diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 9cf6d556..fa78d120 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -246,6 +246,79 @@ docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .C - Check the CLI version: `skillhub version`. - For customization (e.g. changing the logo), it is recommended to fork the latest code, modify it, and build your own Docker image. +## Q: The page loads, but the login / register APIs return 502? + +A: The page is served by the `web` container, while login, register and other APIs are proxied by `web` to `server` (default `SKILLHUB_API_UPSTREAM=http://server:8080`). When the page works but the API returns 502, check whether `server` started correctly first; a wrong upstream, DNS, or container-network problem can also produce a 502. + +Troubleshooting order: + +```bash +# 1. Check whether server is running +docker compose --env-file .env.release -f compose.release.yml ps + +# 2. Look at the first error in the server startup log +docker compose --env-file .env.release -f compose.release.yml logs server | head -50 +``` + +One common startup failure is: + +``` +SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET must not use the default placeholder +``` + +This means `server` still reads the placeholder from the template. Replace it in `.env.release` with your own random string (**at least 32 characters**) and recreate the containers: + +```bash +SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET= +``` + +Running `make validate-release-config` before startup validates `.env.release` and surfaces placeholders and missing values early. + +## Q: Why doesn't my configuration change take effect? + +A: Two common causes: + +1. **Edited the wrong file**: `.env.release.example` is only a template; Compose reads the file passed via `--env-file`, i.e. `.env.release`. Run `cp .env.release.example .env.release` first, then edit `.env.release`. +2. **Restarted instead of recreated**: environment variables are injected when the container is created, and `restart` does not re-inject them. Recreate the containers after a config change: + +```bash +docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate +``` + +## 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. + +The release Compose file already bundles PostgreSQL and Redis, bound to `127.0.0.1` by default. + +## Q: How does an account created through OAuth (GitHub / GitLab, etc.) get admin rights? + +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`. + +## 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: + +```bash +# install one by one +for skill in skill-a skill-b skill-c; do + skillhub install "$skill" +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 --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. + ## Q: What should I do if I encounter issues? A: You can get help through the following channels: diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index 2aac0a54..a26278df 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -246,6 +246,79 @@ docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .C - 查看 CLI 版本：`skillhub version`。 - 如需定制（如修改 logo 等），建议基于最新代码进行二次开发并自行构建 docker 镜像。 +## Q: 页面能打开，但登录 / 注册接口返回 502？ + +A: 页面由 `web` 容器提供，登录、注册等接口由 `web` 转发给 `server`（默认 `SKILLHUB_API_UPSTREAM=http://server:8080`）。出现「页面正常但 API 502」时，通常先检查 `server` 是否正常启动；upstream 配置、DNS 或容器网络异常也可能返回 502。 + +排查顺序： + +```bash +# 1. 看 server 是否处于运行状态 +docker compose --env-file .env.release -f compose.release.yml ps + +# 2. 看 server 启动日志中的第一条错误 +docker compose --env-file .env.release -f compose.release.yml logs server | head -50 +``` + +一条常见的启动失败日志是： + +``` +SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET must not use the default placeholder +``` + +说明 `server` 读到的仍是模板里的占位值。在 `.env.release` 中改成自己的随机字符串（**至少 32 个字符**）后重建容器即可： + +```bash +SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET=<替换成你自己的随机字符串，至少 32 个字符> +``` + +启动前可以先执行 `make validate-release-config`，它会校验 `.env.release`，提前暴露这类占位值和缺失项。 + +## Q: 改了配置为什么不生效？ + +A: 两个高频原因： + +1. **改错了文件**：`.env.release.example` 只是模板，Compose 实际读取的是 `--env-file` 指定的 `.env.release`。请先 `cp .env.release.example .env.release`，然后修改 `.env.release`。 +2. **只重启没重建**：环境变量在容器创建时注入，`restart` 不会重新注入。改完配置需要重建容器： + +```bash +docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate +``` + +## Q: SkillHub 运行时需要哪些外部依赖？ + +A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式，由 `SKILLHUB_STORAGE_PROVIDER` 控制，默认为 `local`，生产环境推荐使用 S3（通过 `SKILLHUB_STORAGE_S3_*` 配置）。数据库仅支持 PostgreSQL，暂不支持 MySQL。 + +发布版 Compose 已内置 PostgreSQL 与 Redis，默认只绑定在 `127.0.0.1`。 + +## Q: 通过 OAuth（GitHub / GitLab 等）登录的账号，如何取得管理员权限？ + +A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`（例如初始化时的 bootstrap admin）在后台将其提升为管理员。 + +注意：`USER_ADMIN` 只能管理普通用户，**不能**授予 `SUPER_ADMIN` 角色；只有 `SUPER_ADMIN` 能授予 `SUPER_ADMIN`。 + +## Q: 如何批量安装多个技能包？ + +A: CLI 的 `install` 一次处理一个技能包，批量安装用 shell 循环即可： + +```bash +# 逐个安装 +for skill in skill-a skill-b skill-c; do + skillhub install "$skill" +done + +# 或从清单文件读取（每行一个技能名） +xargs -a skills.txt -n 1 skillhub install +``` + +`install` 也支持 `--dir` 指定安装目录，便于在内网环境中脚本化部署： + +```bash +skillhub install --dir +``` + +自 **SkillHub Server v0.2.12** 起，公开技能支持匿名搜索与安装；如果配置了无效的 Bearer Token，命令会直接失败而不再回退匿名访问，遇到这种情况请更新凭据或先移除无效 Token。 + ## Q: 遇到问题怎么办？ A: 可以通过以下方式获取帮助： diff --git a/document/docs/05-reference/faq.md b/document/docs/05-reference/faq.md index c70c80fa..eb2d352c 100644 --- a/document/docs/05-reference/faq.md +++ b/document/docs/05-reference/faq.md @@ -20,95 +20,12 @@ description: 常见问题解答 使用 PostgreSQL 标准备份工具（pg_dump）。 -### 页面能打开，但登录/注册接口返回 502？ - -页面由 `web` 容器提供，登录、注册等接口由 `web` 转发给 `server`（默认 `SKILLHUB_API_UPSTREAM=http://server:8080`）。 -因此「页面正常但 API 502」基本都是 `server` 没有正常启动，而不是前端镜像的问题。 - -排查顺序： - -```bash -# 1. 看 server 是否处于运行状态 -docker compose --env-file .env.release -f compose.release.yml ps - -# 2. 看 server 启动日志中的第一条错误 -docker compose --env-file .env.release -f compose.release.yml logs server | head -50 -``` - -最常见的一条启动失败日志是： - -``` -SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET must not use the default placeholder -``` - -说明 `server` 读到的仍是模板里的占位值。在 `.env.release` 中改成自己的随机长字符串后重建容器即可： - -```bash -SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET=<替换成你自己的随机长字符串> -``` - -启动前可以先执行 `make validate-release-config`，它会在启动前校验 `.env.release`，提前暴露这类占位值和缺失项。 - -### 改了配置为什么不生效？ - -两个高频原因： - -1. **改错了文件**：`.env.release.example` 只是模板，Compose 实际读取的是 `--env-file` 指定的 `.env.release`。请先 `cp .env.release.example .env.release`，然后改 `.env.release`。 -2. **只重启没重建**：环境变量在容器创建时注入，`restart` 不会重新注入。改完配置需要重建容器： - -```bash -docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate -``` - -### 离线 / 内网环境启动时内置技能同步失败怎么办？ - -日志出现 `published=0 ... failed=N` 之类的内置技能同步告警时，说明容器访问不到云端 manifest 对应的 CDN 域名， -但**服务本身通常已经起来了**。两种处理方式： - -- 能联网：放通日志中提示的 CDN 域名。 -- 不能联网：在 `.env.release` 中关闭内置技能同步，先让服务正常启动。 - -```bash -SKILLHUB_BUILTIN_SKILLS_ENABLED=false -``` - -### 如何升级到新版本？数据库结构需要手工改吗？ - -按发布版 Compose 部署时，升级只需要换镜像标签并重建容器；数据库结构由 Flyway 在新镜像启动时自动迁移，**不需要手工改表**， -前提是**保留原有数据卷**。 - -```bash -# 1. 在 .env.release 中修改版本 -SKILLHUB_VERSION=vX.Y.Z - -# 2. 拉取新镜像并重建 -docker compose --env-file .env.release -f compose.release.yml pull -docker compose --env-file .env.release -f compose.release.yml up -d -``` - -升级前建议先备份数据库（`pg_dump`），并阅读目标版本 Release Notes 中的 Breaking Changes 一节。 - -### 需要哪些外部依赖？支持 MySQL 吗？ - -运行时依赖 PostgreSQL、Redis 和 S3 兼容对象存储，目前**不支持 MySQL**。 -发布版 Compose 已经内置 PostgreSQL 与 Redis，默认只绑定在 `127.0.0.1`。 - ## 使用相关 ### 如何重置管理员密码？ 如果忘记管理员密码，可通过环境变量重新设置首登管理员，或直接操作数据库。 -### 通过 OAuth（GitHub / GitLab 等）登录的账号，如何取得管理员权限？ - -OAuth 首次登录的账号默认是普通用户，需要由一个已有管理员为其授予平台角色： - -1. 启用首登管理员：`.env.release` 中设置 `BOOTSTRAP_ADMIN_ENABLED=true`，并确认 `BOOTSTRAP_ADMIN_USERNAME`（默认 `admin`）、`BOOTSTRAP_ADMIN_PASSWORD`（默认 `ChangeMe!2026`，生产环境必须改）。 -2. 用首登管理员登录，在用户管理中给你的 OAuth 账号授予 `SUPER_ADMIN`。 -3. 权限体系完成交接后，可将 `BOOTSTRAP_ADMIN_ENABLED` 改回 `false`。 - -注意：`USER_ADMIN` 只能分配普通角色，**不能分配或改写 `SUPER_ADMIN`**，这是刻意的权限边界，避免越权提升。 - ### 技能包上传失败怎么办？ 检查： @@ -117,31 +34,6 @@ OAuth 首次登录的账号默认是普通用户，需要由一个已有管理 3. 是否包含必需的 SKILL.md 4. SKILL.md frontmatter 格式是否正确 -### 如何区分 CLI 版本和服务端版本？ - -两者独立发布，排查问题时建议同时提供： - -```bash -# CLI 版本 -skillhub version - -# 服务端版本（看实际运行的镜像标签） -docker compose --env-file .env.release -f compose.release.yml images -``` - -CLI 的新增能力通常要求服务端不低于对应版本，出现「CLI 有这个命令但服务端报错」时，优先确认服务端镜像标签。 - -### 内网环境如何把技能批量安装到指定目录？ - -`install` 命令支持 `--dir` 指定安装目录，可脚本化批量执行： - -```bash -skillhub install --dir -``` - -自 `v0.2.12` 起，公开技能支持匿名搜索与安装；如果配置了无效的 Bearer Token，命令会直接失败而不再回退匿名访问， -遇到这种情况请更新凭据或先移除无效 Token。 - ## 开发相关 ### 如何扩展 OAuth Provider？ diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md index c63d0821..137a90e7 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md @@ -20,104 +20,12 @@ Recommended to use reverse proxy (Nginx/Ingress) for TLS termination. Use PostgreSQL standard backup tools (pg_dump). -### The page loads, but login/register APIs return 502? - -The page is served by the `web` container, while login, register and other APIs are proxied from `web` to `server` -(default `SKILLHUB_API_UPSTREAM=http://server:8080`). So "page works but API returns 502" almost always means -`server` failed to start — it is rarely a frontend image problem. - -Check in this order: - -```bash -# 1. Is server actually running? -docker compose --env-file .env.release -f compose.release.yml ps - -# 2. Read the first error in the server startup log -docker compose --env-file .env.release -f compose.release.yml logs server | head -50 -``` - -The most common startup failure is: - -``` -SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET must not use the default placeholder -``` - -It means `server` still reads the placeholder value from the template. Set your own long random string in -`.env.release` and recreate the container: - -```bash -SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET= -``` - -Running `make validate-release-config` before startup validates `.env.release` and surfaces placeholder or -missing values early. - -### Why do my configuration changes have no effect? - -Two frequent causes: - -1. **Edited the wrong file**: `.env.release.example` is only a template. Compose reads the file passed via - `--env-file`, which is `.env.release`. Run `cp .env.release.example .env.release` first, then edit `.env.release`. -2. **Restarted instead of recreated**: environment variables are injected when the container is created, so - `restart` does not pick up new values. Recreate the containers after changing configuration: - -```bash -docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate -``` - -### Built-in skill sync fails in an offline / intranet environment? - -A warning such as `published=0 ... failed=N` means the container cannot reach the CDN domain behind the cloud -manifest, but **the service itself is usually up**. Two options: - -- With network access: allow the CDN domain shown in the log. -- Without network access: disable built-in skill sync in `.env.release` so the service starts cleanly. - -```bash -SKILLHUB_BUILTIN_SKILLS_ENABLED=false -``` - -### How to upgrade to a new version? Does the database schema need manual changes? - -With the release Compose setup, upgrading only means switching the image tag and recreating the containers. -The database schema is migrated automatically by Flyway when the new image starts — **no manual DDL is needed** — -as long as you **keep the existing data volume**. - -```bash -# 1. Change the version in .env.release -SKILLHUB_VERSION=vX.Y.Z - -# 2. Pull the new images and recreate -docker compose --env-file .env.release -f compose.release.yml pull -docker compose --env-file .env.release -f compose.release.yml up -d -``` - -Back up the database (`pg_dump`) before upgrading, and read the Breaking Changes section of the target release notes. - -### Which external dependencies are required? Is MySQL supported? - -The runtime depends on PostgreSQL, Redis and S3-compatible object storage. **MySQL is not supported.** -The release Compose file already ships PostgreSQL and Redis, bound to `127.0.0.1` by default. - ## Usage Related ### How to reset admin password? If you forgot admin password, you can reconfigure bootstrap admin via environment variables or directly operate the database. -### How does an OAuth (GitHub / GitLab) account become an administrator? - -An account created by a first OAuth login is a regular user; an existing administrator must grant it a platform role: - -1. Enable the bootstrap admin: set `BOOTSTRAP_ADMIN_ENABLED=true` in `.env.release` and check - `BOOTSTRAP_ADMIN_USERNAME` (default `admin`) and `BOOTSTRAP_ADMIN_PASSWORD` (default `ChangeMe!2026`, - must be changed in production). -2. Sign in as the bootstrap admin and grant `SUPER_ADMIN` to your OAuth account in user management. -3. Once the role handover is done, you can set `BOOTSTRAP_ADMIN_ENABLED` back to `false`. - -Note: `USER_ADMIN` can only assign regular roles and **cannot assign or overwrite `SUPER_ADMIN`**. This is an -intentional boundary that prevents privilege escalation. - ### Skill package upload failed? Check: @@ -126,32 +34,6 @@ Check: 3. Whether required SKILL.md is included 4. Whether SKILL.md frontmatter format is correct -### How to tell the CLI version from the server version? - -They are released independently — please report both when filing an issue: - -```bash -# CLI version -skillhub version - -# Server version (the image tag actually running) -docker compose --env-file .env.release -f compose.release.yml images -``` - -New CLI capabilities usually require a server at or above the matching version. If a CLI command exists but the -server rejects it, check the server image tag first. - -### How to install skills into a specific directory on an intranet? - -The `install` command accepts `--dir` for the target directory, which can be scripted for batch installs: - -```bash -skillhub install --dir -``` - -Since `v0.2.12`, public skills support anonymous search and install. Note that an invalid bearer token now fails -closed instead of falling back to anonymous access — refresh the credential or drop the invalid token. - ## Development Related ### How to extend OAuth Provider?