mirror of
https://github.com/iflytek/skillhub.git
synced 2026-10-10 03:27:54 +00:00
docs(faq): move entries to the published docs source and fix inaccuracies
Move the new FAQ entries from document/ (a generated tree that the docs build does not read) to docs/skillhub/, which is what make docs-build and the Pages deploy actually publish. Also address review feedback: - drop the SKILLHUB_BUILTIN_SKILLS_ENABLED tip; compose.release.yml does not pass that variable through, so setting it has no effect - correct the dependency list: object storage defaults to local, S3 is recommended for production - soften the 502 wording, since upstream/DNS/network can also cause it - state the 32-character minimum for the cookie secret - give a real bulk-install example and qualify v0.2.12 as a server version - drop entries already covered by existing upgrade/MySQL/version questions Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
This commit is contained in:
FenjuFu
parent
f74d2066ba
commit
aff866f4b3
4 changed files with 146 additions and 226 deletions
|
|
@ -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=<your own random string, at least 32 characters>
|
||||
```
|
||||
|
||||
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 <skill-slug> --dir <target-path>
|
||||
```
|
||||
|
||||
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:
|
||||
|
|
|
|||
|
|
@ -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 <skill-slug> --dir <target-path>
|
||||
```
|
||||
|
||||
自 **SkillHub Server v0.2.12** 起，公开技能支持匿名搜索与安装；如果配置了无效的 Bearer Token，命令会直接失败而不再回退匿名访问，遇到这种情况请更新凭据或先移除无效 Token。
|
||||
|
||||
## Q: 遇到问题怎么办？
|
||||
|
||||
A: 可以通过以下方式获取帮助：
|
||||
|
|
|
|||
|
|
@ -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 <skill-slug> --dir <target-path>
|
||||
```
|
||||
|
||||
自 `v0.2.12` 起，公开技能支持匿名搜索与安装；如果配置了无效的 Bearer Token，命令会直接失败而不再回退匿名访问，
|
||||
遇到这种情况请更新凭据或先移除无效 Token。
|
||||
|
||||
## 开发相关
|
||||
|
||||
### 如何扩展 OAuth Provider？
|
||||
|
|
|
|||
|
|
@ -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=<replace-with-your-own-long-random-string>
|
||||
```
|
||||
|
||||
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 <skill-slug> --dir <target-path>
|
||||
```
|
||||
|
||||
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?
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue