From be0a928c533ffd57e35c54c056101bb52ca1579f Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:45:02 +0800
Subject: [PATCH] docs(faq): correct deployment and admin guidance

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 docs/skillhub/en/faq.md | 30 +++++++++++++++++-------------
 docs/skillhub/faq.md    | 30 +++++++++++++++++-------------
 2 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md
index fa78d120..8cda4944 100644
--- a/docs/skillhub/en/faq.md
+++ b/docs/skillhub/en/faq.md
@@ -156,10 +156,18 @@ A: This is most commonly seen with **manual deployment** (caused by API errors o
 
 ## Q: How do I change the admin password? Why don't my config changes take effect?
 
-A: Environment variables are read at container startup, so you must restart the containers after changing them.
+A: Environment variables are injected when a container is created, so you must recreate the containers after changing them; `restart` alone does not re-inject environment variables.
 
 1. Edit `/tmp/skillhub-runtime/.env.release` in the runtime directory (refer to [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example)).
-2. Restart the relevant containers.
+2. Recreate the relevant containers:
+
+   ```bash
+   docker compose \
+     --env-file /tmp/skillhub-runtime/.env.release \
+     -f /tmp/skillhub-runtime/compose.release.yml \
+     up -d --force-recreate
+   ```
+
 3. If the password was already persisted to the database and the change still doesn't take effect, you may need to clear the corresponding data and re-initialize.
 
 ## Q: Is an email verification code required to change / reset a password?
@@ -287,7 +295,7 @@ docker compose --env-file .env.release -f compose.release.yml up -d --force-recr
 
 ## Q: What external dependencies does SkillHub require at runtime?
 
-A: PostgreSQL and Redis are required. Object storage supports both `local` and S3, controlled by `SKILLHUB_STORAGE_PROVIDER`, which defaults to `local`; S3 is recommended for production (configured via `SKILLHUB_STORAGE_S3_*`). Only PostgreSQL is supported as the database — MySQL is not.
+A: PostgreSQL and Redis are required. Object storage supports both `local` and S3, controlled by `SKILLHUB_STORAGE_PROVIDER`. `.env.release.example` explicitly selects `local`, but if the variable is completely unset when using `compose.release.yml`, the Compose fallback is `s3`. Set it explicitly; S3 is recommended for production (configured via `SKILLHUB_STORAGE_S3_*`). Only PostgreSQL is supported as the database — MySQL is not.
 
 The release Compose file already bundles PostgreSQL and Redis, bound to `127.0.0.1` by default.
 
@@ -295,26 +303,22 @@ The release Compose file already bundles PostgreSQL and Redis, bound to `127.0.0
 
 A: The first OAuth login creates a regular user. An existing `SUPER_ADMIN` (for example the bootstrap admin created during initialization) has to promote it from the admin console.
 
-Note that `USER_ADMIN` can only manage regular users and **cannot** grant the `SUPER_ADMIN` role; only a `SUPER_ADMIN` can grant `SUPER_ADMIN`.
+A `USER_ADMIN` can manage user status and assign platform roles other than `SUPER_ADMIN`, but cannot grant `SUPER_ADMIN` to any account or change the role of an existing `SUPER_ADMIN`. Only a `SUPER_ADMIN` can perform those two operations.
 
 ## Q: How do I install multiple skills in bulk?
 
-A: The CLI `install` command handles one skill at a time; use a shell loop for bulk installs:
+A: The CLI `install` command handles one skill at a time. Both examples below use `--dir` to install the skills into the same target directory:
 
 ```bash
+target_dir=/opt/skillhub-skills
+
 # install one by one
 for skill in skill-a skill-b skill-c; do
-  skillhub install "$skill"
+  skillhub install "$skill" --dir "$target_dir"
 done
 
 # or read from a manifest file (one skill name per line)
-xargs -a skills.txt -n 1 skillhub install
-```
-
-`install` also accepts `--dir` to choose the installation directory, which helps when scripting deployments in an isolated network:
-
-```bash
-skillhub install <skill-slug> --dir <target-path>
+xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir"
 ```
 
 Since **SkillHub Server v0.2.12**, public skills support anonymous search and install. Note that an invalid bearer token now fails the command instead of falling back to anonymous access — update or remove the stale credential in that case.
diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md
index a26278df..754970e4 100644
--- a/docs/skillhub/faq.md
+++ b/docs/skillhub/faq.md
@@ -156,10 +156,18 @@ A: 该现象多见于「手动部署」场景（接口异常或初始化未完
 
 ## Q: 如何修改 admin 密码？修改配置后不生效？
 
-A: 环境变量在容器启动时读取，修改后必须重启容器才会生效。
+A: 环境变量在容器创建时注入，修改后必须重新创建容器才会生效；仅执行 `restart` 不会重新注入环境变量。
 
 1. 修改运行时目录下的 `/tmp/skillhub-runtime/.env.release`（参考仓库 [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example)）。
-2. 重启相关容器。
+2. 重新创建相关容器：
+
+   ```bash
+   docker compose \
+     --env-file /tmp/skillhub-runtime/.env.release \
+     -f /tmp/skillhub-runtime/compose.release.yml \
+     up -d --force-recreate
+   ```
+
 3. 若此前密码已写入数据库导致仍不生效，可能需要清理对应数据后重新初始化。
 
 ## Q: 修改 / 找回密码必须使用邮箱验证码吗？
@@ -287,7 +295,7 @@ docker compose --env-file .env.release -f compose.release.yml up -d --force-recr
 
 ## Q: SkillHub 运行时需要哪些外部依赖？
 
-A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式，由 `SKILLHUB_STORAGE_PROVIDER` 控制，默认为 `local`，生产环境推荐使用 S3（通过 `SKILLHUB_STORAGE_S3_*` 配置）。数据库仅支持 PostgreSQL，暂不支持 MySQL。
+A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式，由 `SKILLHUB_STORAGE_PROVIDER` 控制。`.env.release.example` 显式配置为 `local`，但如果使用 `compose.release.yml` 时完全没有设置该变量，Compose 的回退值是 `s3`。建议始终显式设置；生产环境推荐使用 S3（通过 `SKILLHUB_STORAGE_S3_*` 配置）。数据库仅支持 PostgreSQL，暂不支持 MySQL。
 
 发布版 Compose 已内置 PostgreSQL 与 Redis，默认只绑定在 `127.0.0.1`。
 
@@ -295,26 +303,22 @@ A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式
 
 A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`（例如初始化时的 bootstrap admin）在后台将其提升为管理员。
 
-注意：`USER_ADMIN` 只能管理普通用户，**不能**授予 `SUPER_ADMIN` 角色；只有 `SUPER_ADMIN` 能授予 `SUPER_ADMIN`。
+`USER_ADMIN` 可以管理用户状态，并分配除 `SUPER_ADMIN` 之外的平台角色；但不能向任何账号授予 `SUPER_ADMIN`，也不能修改已有 `SUPER_ADMIN` 账号的角色。这两类操作只有 `SUPER_ADMIN` 可以执行。
 
 ## Q: 如何批量安装多个技能包？
 
-A: CLI 的 `install` 一次处理一个技能包，批量安装用 shell 循环即可：
+A: CLI 的 `install` 一次处理一个技能包。下面两个示例都通过 `--dir` 将技能批量安装到同一个目标目录：
 
 ```bash
+target_dir=/opt/skillhub-skills
+
 # 逐个安装
 for skill in skill-a skill-b skill-c; do
-  skillhub install "$skill"
+  skillhub install "$skill" --dir "$target_dir"
 done
 
 # 或从清单文件读取（每行一个技能名）
-xargs -a skills.txt -n 1 skillhub install
-```
-
-`install` 也支持 `--dir` 指定安装目录，便于在内网环境中脚本化部署：
-
-```bash
-skillhub install <skill-slug> --dir <target-path>
+xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir"
 ```
 
 自 **SkillHub Server v0.2.12** 起，公开技能支持匿名搜索与安装；如果配置了无效的 Bearer Token，命令会直接失败而不再回退匿名访问，遇到这种情况请更新凭据或先移除无效 Token。