From 4aee3a64cdda8eb4960f141855c55613169ba4e4 Mon Sep 17 00:00:00 2001 From: FenjuFu Date: Tue, 16 Jun 2026 01:30:38 +0800 Subject: [PATCH 1/3] docs(faq): supplement FAQ (zh & en) with community-sourced Q&A Add questions frequently raised in the user community that were not yet covered in the SkillHub FAQ, for both Chinese and English pages: - Recommended deployment via the one-line script vs manual image pulls - Redirected back to login page after deploying (manual deployment) - Changing the admin password / why env changes need a restart - Password change/reset requires email code (SMTP setup) - Skill naming (English only; Chinese names error in OpenClaw) - Whether unreviewed skills can be downloaded - Hiding/removing GitHub & GitLab SSO login options - Built-in Skill Scanner: iFLYTEK integration over Cisco's scanner (Apache-2.0) - Which cisco-ai-skill-scanner version is used (unpinned in Dockerfile) - Note that upgrades preserve registered skills; online docs link Signed-off-by: FenjuFu --- docs/skillhub/en/faq.md | 53 ++++++++++++++++++++++++++++++++++++++++- docs/skillhub/faq.md | 53 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 104 insertions(+), 2 deletions(-) diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index ac5326e4..2d350fee 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -122,7 +122,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 ``` -> **Note**: It is recommended to back up the database and object storage before upgrading. Database migrations are handled automatically by Flyway. +> **Note**: It is recommended to back up the database and object storage before upgrading. Database migrations are handled automatically by Flyway. Upgrading does not wipe the database, so already-registered skill packages will not be lost. ## Q: Why can't administrators (admin) and regular users create namespaces? @@ -136,11 +136,62 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u A: When using the OpenClaw CLI, you can specify the namespace using the `--` format for operations like search or installation. If you encounter issues finding it on the web interface, you can also manage it by exporting the skill package and importing it into your target namespace. +## Q: What is the recommended deployment method? Can I pull the images and deploy manually? + +A: We recommend the official one-line deployment script. Pulling images and deploying manually is not recommended (manual deployment is prone to initialization issues such as being redirected back to the login page after logging in): + +```bash +curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest +``` + +The script performs a series of initialization steps. The generated runtime configuration is located at `/tmp/skillhub-runtime/` by default (containing `.env.release` and the docker-compose file). + +## Q: After deployment, I enter the correct username and password but get redirected back to the login page? + +A: This is most commonly seen with **manual deployment** (caused by API errors or incomplete initialization). Suggestions: + +1. Switch to the one-line script above for deployment. +2. If necessary, clear and recreate the PostgreSQL data volume, then log in again. +3. If a reverse proxy is in front, verify that it forwards requests correctly. + +## 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. + +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. +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? + +A: Yes. By default, passwords are changed or reset via an email verification code, so SMTP must be configured first. See [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Administrators can also reset it via `.env.release`. + +## Q: Can a skill have a Chinese name? + +A: Skill names are generally in English; Chinese names are not currently supported (using a Chinese skill name in OpenClaw will cause an error). + +## Q: Can unreviewed skills be downloaded? + +A: As long as you have permission to view it, it can generally be downloaded. + +## Q: How do I hide or remove the GitHub / GitLab SSO login options on the login page? + +A: Edit `application.yml` and comment out or delete the `github` and `gitlab` blocks under `spring.security.oauth2.client.registration`, along with their corresponding `provider` sections. Spring Boot then won't create these registrations at startup, and the login page won't show those entries. + +## Q: Is SkillHub's security scanning (Skill Scanner) developed in-house by iFLYTEK? What license does it use? + +A: SkillHub has built-in security scanning. The scanner integration, task orchestration, audit persistence, and deployment integration are implemented by the iFLYTEK team; the underlying scanning service uses Cisco's [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) (Apache License 2.0, copyright Cisco). + +## Q: Which version of cisco-ai-skill-scanner does SkillHub use? + +A: `scanner/Dockerfile` runs `pip install cisco-ai-skill-scanner` directly without pinning a version, so the latest version on PyPI is pulled when the image is built. To pin a version, do so yourself when customizing the build. + ## Q: What should I do if I encounter issues? A: You can get help through the following channels: - **GitHub Issues**: https://github.com/iflytek/skillhub/issues +- **Online Docs**: https://www.astron-skillhub.org/ - **Documentation**: Refer to the project README.md - **Community Discussions**: https://github.com/iflytek/skillhub/discussions diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index a29d6d85..f27253b0 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -122,7 +122,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 ``` -> **注意**：升级前建议先备份数据库和对象存储。数据库迁移由 Flyway 自动执行。 +> **注意**：升级前建议先备份数据库和对象存储。数据库迁移由 Flyway 自动执行。升级不会清空数据库，已录入的技能包不会丢失。 ## Q: 为什么管理员（admin）和普通用户都无法创建命名空间？ @@ -136,11 +136,62 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u A: 使用 OpenClaw CLI 命令行工具时，可以通过 `--` 的格式来指定命名空间进行操作（例如搜索、安装）。如果在网页端搜索遇到问题，也可以尝试通过先导出技能、再导入到目标命名空间的方式来完成跨空间操作。 +## Q: 推荐的部署方式是什么？可以自己拉镜像手动部署吗？ + +A: 推荐使用官方一键部署脚本，不建议自己拉取镜像手动部署（手动部署容易出现登录后跳回登录页等初始化问题）： + +```bash +curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest +``` + +脚本会执行一系列初始化操作，生成的运行时配置默认位于 `/tmp/skillhub-runtime/`（包含 `.env.release` 和 docker-compose 文件）。 + +## Q: 部署后输入正确的账号密码，却又跳回登录页？ + +A: 该现象多见于「手动部署」场景（接口异常或初始化未完成导致）。建议： + +1. 改用上面的一键脚本部署。 +2. 必要时清空 PostgreSQL 数据卷后重建再登录。 +3. 若前置了反向代理，检查代理配置是否正确转发。 + +## Q: 如何修改 admin 密码？修改配置后不生效？ + +A: 环境变量在容器启动时读取，修改后必须重启容器才会生效。 + +1. 修改运行时目录下的 `/tmp/skillhub-runtime/.env.release`（参考仓库 [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example)）。 +2. 重启相关容器。 +3. 若此前密码已写入数据库导致仍不生效，可能需要清理对应数据后重新初始化。 + +## Q: 修改 / 找回密码必须使用邮箱验证码吗？ + +A: 是的，默认通过邮箱验证码修改或找回密码，因此需要先配置 SMTP。配置方法参考 [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。管理员也可在 `.env.release` 中进行重置。 + +## Q: skill 可以起中文名吗？ + +A: skill name 一般使用英文，目前不支持中文名（在 OpenClaw 中使用中文 skill 名会报错）。 + +## Q: 未审核的 skill 可以下载吗？ + +A: 只要拥有可查看的权限，一般都可以下载。 + +## Q: 如何隐藏或删除登录页的 GitHub / GitLab SSO 登录方式？ + +A: 修改 `application.yml`，注释或删除 `spring.security.oauth2.client.registration` 下的 `github` 和 `gitlab` 两块，并删除对应的 `provider` 段。Spring Boot 启动时便不会创建这两个注册，登录页也不会再显示对应入口。 + +## Q: SkillHub 的安全扫描（Skill Scanner）是讯飞自研的吗？使用什么协议？ + +A: SkillHub 内置安全扫描能力。其中扫描接入、任务编排、审计落库和部署集成由讯飞团队实现；底层扫描服务使用 Cisco 的 [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner)（Apache License 2.0，版权归 Cisco）。 + +## Q: SkillHub 使用的 cisco-ai-skill-scanner 是哪个版本？ + +A: `scanner/Dockerfile` 中直接执行 `pip install cisco-ai-skill-scanner`，未锁定版本，因此构建镜像时会拉取 PyPI 上的最新版本。如需固定版本，可在二次开发时自行锁定。 + ## Q: 遇到问题怎么办？ A: 可以通过以下方式获取帮助： - **GitHub Issues**: https://github.com/iflytek/skillhub/issues +- **在线文档**: https://www.astron-skillhub.org/ - **文档**: 参考项目 README.md - **社区讨论**: https://github.com/iflytek/skillhub/discussions From e3f84b074f98b2c20c1364f732b14ff32e9c9437 Mon Sep 17 00:00:00 2001 From: FenjuFu Date: Tue, 16 Jun 2026 01:37:01 +0800 Subject: [PATCH 2/3] docs(faq): use github.io docs URL for online docs link Signed-off-by: FenjuFu --- docs/skillhub/en/faq.md | 2 +- docs/skillhub/faq.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 2d350fee..e65541f6 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -191,7 +191,7 @@ A: `scanner/Dockerfile` runs `pip install cisco-ai-skill-scanner` directly witho A: You can get help through the following channels: - **GitHub Issues**: https://github.com/iflytek/skillhub/issues -- **Online Docs**: https://www.astron-skillhub.org/ +- **Online Docs**: https://iflytek.github.io/skillhub/ - **Documentation**: Refer to the project README.md - **Community Discussions**: https://github.com/iflytek/skillhub/discussions diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index f27253b0..4d9715fc 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -191,7 +191,7 @@ A: `scanner/Dockerfile` 中直接执行 `pip install cisco-ai-skill-scanner`， A: 可以通过以下方式获取帮助： - **GitHub Issues**: https://github.com/iflytek/skillhub/issues -- **在线文档**: https://www.astron-skillhub.org/ +- **在线文档**: https://iflytek.github.io/skillhub/ - **文档**: 参考项目 README.md - **社区讨论**: https://github.com/iflytek/skillhub/discussions From e57667ae60069890ccb040fbafd4944ea7d94483 Mon Sep 17 00:00:00 2001 From: FenjuFu Date: Tue, 16 Jun 2026 10:15:36 +0800 Subject: [PATCH 3/3] docs(faq): add CLI publish & deployment Q&A (zh & en) Add more community-sourced questions (both Chinese and English): - Troubleshooting CLI `skillhub publish` returning 400 (name conflict, SKILL.md location/frontmatter, namespace membership, etc.) - Required skill package structure (SKILL.md in root) - "malformed input" on publish caused by non-UTF-8 / Chinese-path zips - Per-package file-count limit and how to raise it - Minimum server version for CLI features (v0.2.7+) - PostgreSQL-only (no MySQL); plugins not distributable yet - How to check server/CLI versions and customize via secondary dev Signed-off-by: FenjuFu --- docs/skillhub/en/faq.md | 60 +++++++++++++++++++++++++++++++++++++++++ docs/skillhub/faq.md | 60 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index e65541f6..9cf6d556 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -186,6 +186,66 @@ A: SkillHub has built-in security scanning. The scanner integration, task orches A: `scanner/Dockerfile` runs `pip install cisco-ai-skill-scanner` directly without pinning a version, so the latest version on PyPI is pulled when the image is built. To pin a version, do so yourself when customizing the build. +## Q: How do I troubleshoot a `registry returned 400` error from `skillhub publish` (CLI)? + +A: A 400 usually means backend validation failed. Common causes: + +- `SKILL.md` is not in the package root directory; +- `SKILL.md` frontmatter is missing `name` / `description` or is malformed; +- name or version conflict (e.g. `error.skill.publish.nameConflict`, meaning a skill with the same name is already published in that namespace) — change `name` in `SKILL.md`, use another namespace, or have an admin handle the existing skill; +- the namespace does not exist, or you are not a member of it; +- the package contains suspected tokens/secrets that the CLI cannot confirm skipping; +- file type / size / path is not allowed. + +You can inspect the server logs to locate the cause: + +```bash +docker logs --tail=300 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest' +``` + +## Q: What directory structure does a skill package require? + +A: The package root directory must contain a `SKILL.md` file, whose frontmatter must include fields such as `name` and `description`. + +## Q: Publishing fails with "package validation failed / malformed input" — what do I do? + +A: This error occurs while unzipping and reading file names, usually because the archive is not UTF-8 encoded (e.g. created with the built-in Windows compression tool) or contains Chinese/non-ASCII paths. Repackage using UTF-8 encoding and avoid Chinese / special-character paths. + +## Q: How many files can a skill package contain? What if I hit the file-count limit? + +A: The default limit is **100 files** (this is separate from the 100MB size limit). To raise it, change the `skillhub.publish.max-file-count` setting, or override it via an environment variable at deploy time: + +```bash +SKILLHUB_PUBLISH_MAX_FILE_COUNT=500 +``` + +Restart the containers for the change to take effect. Note that `compose.release.yml` must also reference this variable; older versions (e.g. v0.2.6) may hard-code the value, so upgrading to the latest version is recommended. + +## Q: Is there a server version requirement for using the CLI (publish / download, etc.)? + +A: A SkillHub server image of **v0.2.7 or later** is required for CLI features. + +## Q: Does SkillHub support MySQL? + +A: Currently only PostgreSQL is supported; MySQL is not supported. + +## Q: Can SkillHub be used to distribute Plugins? + +A: Not supported for now. + +## Q: How do I check the SkillHub version? How do I customize it (e.g. change the logo)? + +A: + +- Check the server image version: + +```bash +docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}' +``` + +- 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: 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 4d9715fc..2aac0a54 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -186,6 +186,66 @@ A: SkillHub 内置安全扫描能力。其中扫描接入、任务编排、审 A: `scanner/Dockerfile` 中直接执行 `pip install cisco-ai-skill-scanner`，未锁定版本，因此构建镜像时会拉取 PyPI 上的最新版本。如需固定版本，可在二次开发时自行锁定。 +## Q: 使用 CLI `skillhub publish` 报错 `registry returned 400` 怎么排查？ + +A: 400 通常是后端校验未通过。常见原因： + +- `SKILL.md` 不在技能包根目录； +- `SKILL.md` 的 frontmatter 缺少 `name` / `description` 或格式错误； +- 名称或版本冲突（如 `error.skill.publish.nameConflict`，表示该 namespace 下已存在同名的已发布技能）——可改 `SKILL.md` 里的 `name`、换一个 namespace，或让管理员处理已有同名技能； +- namespace 不存在，或你不是该 namespace 的成员； +- 包内含疑似 token/secret，CLI 无法确认跳过； +- 文件类型 / 大小 / 路径不合规。 + +可用以下命令查看服务端日志定位： + +```bash +docker logs --tail=300 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest' +``` + +## Q: 技能包的目录结构有什么要求？ + +A: 技能包根目录必须包含一个 `SKILL.md` 文件，且其 frontmatter 需包含 `name`、`description` 等字段。 + +## Q: 发布时报“技能包校验失败 / malformed input”怎么办？ + +A: 该错误发生在 zip 解包读取文件名阶段，通常是压缩包不是 UTF-8 编码（例如用 Windows 自带压缩工具生成）或包内含中文路径导致。请使用 UTF-8 编码重新打包，并避免中文 / 特殊字符路径。 + +## Q: 技能包能包含多少个文件？提示文件数超限怎么办？ + +A: 默认上限为 **100 个文件**（这与 100MB 的大小限制是两回事）。如需放宽，修改配置项 `skillhub.publish.max-file-count`，或在部署时用环境变量覆盖： + +```bash +SKILLHUB_PUBLISH_MAX_FILE_COUNT=500 +``` + +修改后需重启容器生效。注意 `compose.release.yml` 中也需引用该变量；较旧版本（如 v0.2.6）可能将该值写死，建议升级到最新版本。 + +## Q: 使用 CLI（发布 / 下载等）对服务端版本有要求吗？ + +A: 需要 SkillHub 服务端镜像 **v0.2.7 及以上** 才支持 CLI 功能。 + +## Q: SkillHub 支持 MySQL 数据库吗？ + +A: 目前仅支持 PostgreSQL，暂不支持 MySQL。 + +## Q: SkillHub 可以用来分发 Plugin 吗？ + +A: 暂不支持。 + +## Q: 如何查看 SkillHub 的版本？想做定制（如修改 logo）怎么办？ + +A: + +- 查看服务端镜像版本： + +```bash +docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}' +``` + +- 查看 CLI 版本：`skillhub version`。 +- 如需定制（如修改 logo 等），建议基于最新代码进行二次开发并自行构建 docker 镜像。 + ## Q: 遇到问题怎么办？ A: 可以通过以下方式获取帮助：