SkillHub FAQ 实战：企业级技能注册中心的部署、CLI 与安全扫描完整运维指南

人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载本文基于 SkillHub 官方 FAQ 整理成篇覆盖部署升级、认证与账号管理、技能包发布限制、CLI 日常操作、内置 Skill Scanner 安全扫描以及登录跳转、502、PostgreSQL 权限等高频故障的排查路径。读完本文你可以独立完成 SkillHub 的一键部署与升级、通过 CLI 管理技能包、理解扫描器两种工作模式的取舍并在配置不生效、发布报错等场景下快速定位根因。1. 产品定位SkillHub 与 ClawHub 的区别SkillHub 是企业级的自托管self-hostedagent skill 注册中心提供命名空间 RBAC、多级审核与治理能力ClawHub 则是类似 npm 的公共注册中心。两者的核心差异如下特性SkillHubClawHub部署方式自托管公共云权限控制命名空间 RBAC基础权限审核机制多级审核无安全扫描内置 Skill Scanner无数据主权完全自主托管在云端适用场景企业内部公开分享从源码结构看SkillHub 的治理能力审核队列、安全扫描、审计日志集中在server/后端与独立的scanner/扫描服务中这也解释了为什么它定位为企业内部使用数据全程留在自己的基础设施上。2. 部署、升级与外部依赖2.1 推荐部署方式官方一键脚本官方推荐使用仓库内的 scripts/runtime.sh 一键部署脚本不建议自己拉取镜像手动部署——手动部署容易出现数据库初始化、依赖顺序、登录跳转等问题。默认依赖从公共镜像仓库拉取SkillHub 应用镜像来自 GHCR# 标准部署 curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com国内网络无法访问 GHCR 时使用阿里云镜像源--aliyun会切换到预配置的阿里云 ACR 地址见 runtime.sh 中的SKILLHUB_ALIYUN_REGISTRY默认值curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest从 scripts/runtime.sh 的源码可以看到脚本支持--version、--aliyun、--mirror-registry、--home、--ref等参数生成的运行时配置默认位于/tmp/skillhub-runtime/可用--home覆盖其中包含.env.release和 docker-compose 文件脚本会执行一系列初始化操作后再拉起服务。2.2 升级 SkillHub升级采用「拉新镜像 → 停旧实例 → 起新实例」的三步方式# 拉取最新镜像并重启 curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up # 或直接指定版本升级 curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0注意升级前建议先备份数据库和对象存储。数据库迁移由 Flyway 自动执行升级不会清空数据库已录入的技能包不会丢失。一个典型的版本相关问题是「管理员admin和普通用户都无法创建命名空间」——这是较旧版本尚未引入该功能导致的升级到latest即可curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version latest2.3 运行时外部依赖PostgreSQL必需数据库仅支持 PostgreSQL不支持 MySQLRedis必需对象存储支持local与 S3 两种模式由SKILLHUB_STORAGE_PROVIDER控制。这一点在 compose.release.yml 中得到印证server 服务的SKILLHUB_STORAGE_PROVIDER回退默认值是s3第 82 行而 .env.release.example 显式配置为local。因此如果直接用compose.release.yml且完全未设置该变量实际会走 S3 模式——FAQ 建议始终显式设置生产环境推荐 S3通过SKILLHUB_STORAGE_S3_*系列变量配置。发布版 Compose 已内置 PostgreSQL 与 Redis 容器默认只绑定在127.0.0.1POSTGRES_BIND_ADDRESS、REDIS_BIND_ADDRESS默认值均为127.0.0.1对外不暴露数据库端口。3. 认证、账号与 SSO 管理3.1 支持的认证方式OAuth2GitHub、GitLab、飞书feishu、钉钉dingtalk等本地账号用户名/密码登录内置管理员admin/ChangeMe!2026企业 SSO可集成 LDAP、SAML 等。内置管理员凭据可以在 compose.release.yml 中得到验证BOOTSTRAP_ADMIN_USERNAME默认admin、BOOTSTRAP_ADMIN_PASSWORD默认ChangeMe!2026由BOOTSTRAP_ADMIN_ENABLED控制是否启用 bootstrap 管理员。3.2 隐藏登录页的第三方 SSO 入口登录入口是配置驱动的/api/v1/auth/methods只返回配置了真实 client id 的注册项client id 为空或包含placeholder时该入口不会出现在登录页前端在 web/src/api/client.ts 中拉取该接口渲染登录方式。隐藏某个入口有两种方式留空对应环境变量例如不设置OAUTH2_FEISHU_CLIENT_ID无需改动配置文件。从 compose.release.yml 可以看到OAUTH2_GITHUB_CLIENT_ID、OAUTH2_FEISHU_CLIENT_ID、OAUTH2_DINGTALK_CLIENT_ID等的缺省值均为local-placeholder即未配置时登录页不会出现对应入口修改application.yml注释或删除spring.security.oauth2.client.registration下对应的注册块github、gitlab、feishu、dingtalk及其provider段Spring Boot 启动时便不会创建该注册。3.3 修改/找回密码与 SMTP默认必须通过邮箱验证码修改或找回密码因此需要先配置 SMTPCompose 中对应SPRING_MAIL_HOST、SPRING_MAIL_SMTP_AUTH、SPRING_MAIL_SMTP_STARTTLS_ENABLE等变量验证码有效期由SKILLHUB_AUTH_PASSWORD_RESET_CODE_EXPIRY控制默认PT10M。具体配置步骤参见仓库内文档 docs/19-smtp-password-reset-email-setup.md。管理员也可以直接在.env.release中重置密码。3.4 OAuth 账号如何获得管理员权限OAuthGitHub / GitLab 等首次登录创建的是普通用户。需要由已有的SUPER_ADMIN例如初始化时创建的 bootstrap admin在管理后台将其提升为管理员。权限边界USER_ADMIN可以管理用户状态、分配除SUPER_ADMIN之外的平台角色但不能向任何账号授予SUPER_ADMIN也不能修改已有SUPER_ADMIN账号的角色——这两类操作只有SUPER_ADMIN可以执行。4. 数据备份与存储故障4.1 备份策略SkillHub 的数据存储在 PostgreSQL 和对象存储中定期备份这两部分即可。备份 PostgreSQLpg_dump -h localhost -U postgres skillhub backup.sql备份对象存储使用 MinIO 时备份 MinIO 数据目录使用 S3 时使用 AWS CLI 或 S3 备份工具。若使用官方 Compose 的local模式对象存储落在 Docker 命名卷skillhub_storage挂载到容器内/var/lib/skillhub/storage备份该卷即可。4.2 PostgreSQL 报operation not permitted写 postmaster.pid / pg_walSkillHub 默认的 Compose 和runtime.sh使用 Docker named volumepostgres_data见 compose.release.yml 第 28 行与 volumes 段通常不需要手工处理宿主机目录权限。该错误更常见于把 PostgreSQL 数据目录改成宿主机 bind mount例如/data/skillhub/postgres:/var/lib/postgresql/data。按以下顺序排查优先恢复为 Docker named volume或使用官方runtime.sh避免手写 Compose 时漏配权限如果必须使用 bind mount先确认.env.release或runtime.sh参数最终选择的POSTGRES_IMAGECompose 默认postgres:16-alpine导出该值后运行docker run --rm $POSTGRES_IMAGE id postgres再按输出的实际 UID/GID 执行chown -R uid:gid 数据目录。不要固定假设镜像是postgres:16-alpine也不要假设所有环境都是999:999在 RHEL/CentOS 上检查 SELinux使用 AppArmor、rootless Docker、NFS、CIFS 或 NAS 时确认宿主文件系统允许 PostgreSQL 写入、加锁和更改权限不建议把PGDATA放在缺少完整 POSIX 权限语义的网络文件系统上生产环境优先使用本地盘、Docker named volume、块存储或外部 PostgreSQL。5. 技能包限制与发布排错5.1 包大小限制默认大小限制为100MB可通过spring.servlet.multipart调整# application.yml spring: servlet: multipart: max-file-size: 100MB max-request-size: 100MB除 Servlet 层限制外服务端还有技能包发布策略值从 server/skillhub-app/src/main/resources/application.yml 可以看到skillhub.publish段中max-package-size: 104857600100MB、max-single-file-size: 10485760单文件 10MB。这些值由 SkillPublishProperties 绑定并在校验器中生效。5.2 文件数量限制默认上限为100 个文件与 100MB 的大小限制是两回事对应skillhub.publish.max-file-count: 100application.yml 第 236 行。如需放宽修改该配置项或在部署时用环境变量覆盖SKILLHUB_PUBLISH_MAX_FILE_COUNT500修改后需重新创建容器才会生效仅执行restart不会重新注入环境变量。注意 compose.release.yml 中也需引用该变量较旧版本如 v0.2.6可能将该值写死建议升级到最新版本。从源码结构看Java 类 SkillPublishProperties 的代码级兜底默认值是 500实际生效值以配置文件为准。5.3 目录结构要求与命名规则技能包根目录必须包含一个SKILL.md文件其 frontmatter 需包含name、description等字段技能名不支持中文skill name 一般使用英文在 OpenClaw 中使用中文技能名会报错未审核的 skill 可以下载只要拥有可查看的权限一般都可以下载Plugin 分发暂不支持当前 SkillHub 只分发技能包发布时包内文件类型、大小、路径都受校验策略约束允许的文件扩展名可通过SKILLHUB_PUBLISH_ALLOWED_FILE_EXTENSIONS覆盖README 中有示例。5.4 发布报「校验失败 / malformed input」该错误发生在 zip 解包读取文件名阶段通常是压缩包不是 UTF-8 编码例如用 Windows 自带压缩工具生成或包内含中文路径导致。请使用 UTF-8 编码重新打包并避免中文/特殊字符路径。5.5skillhub publish报registry returned 400400 通常意味着后端校验未通过常见原因SKILL.md不在技能包根目录SKILL.md的 frontmatter 缺少name/description或格式错误名称或版本冲突如error.skill.publish.nameConflict表示该 namespace 下已存在同名已发布技能——可改SKILL.md里的name、换 namespace或让管理员处理已有同名技能namespace 不存在或你不是该 namespace 的成员包内含疑似 token/secretCLI 无法确认跳过文件类型 / 大小 / 路径不合规。可用以下命令查看服务端日志定位docker logs --tail300 skillhub-server 容器名 21 | grep -Ei publish|SKILL.md|namespace|400|BadRequest6. CLI 日常操作6.1 搜索、安装与发布SkillHub 兼容 OpenClaw CLI使用npx clawhub命令即可操作# 配置注册中心地址 export CLAWHUB_REGISTRYhttp://your-skillhub-host:8080 # 搜索技能包 npx clawhub search email # 安装技能包 npx clawhub install my-skill # 发布技能包ClawHub CLI 的发布协议不兼容 SkillHub export SKILLHUB_REGISTRYhttp://your-skillhub-host:8080 export SKILLHUB_TOKENYOUR_API_TOKEN npx astron-team/skillhublatest publish ./my-skill操作指定命名空间中的技能包时使用namespace--skill-name格式搜索、安装均适用。如果在网页端搜索遇到问题也可以通过「先导出技能包、再导入到目标命名空间」完成跨空间操作。6.2 版本要求使用 CLI发布/下载等需要 SkillHub 服务端镜像v0.2.7 及以上查看服务端镜像版本docker image inspect ghcr.io/iflytek/skillhub-server:latest --format {{index .Config.Labels org.opencontainers.image.version}}查看 CLI 版本skillhub version如需定制如修改 logo建议基于最新代码 fork 后二次开发并自行构建 Docker 镜像。6.3 批量安装多个技能包CLI 的install一次处理一个技能包。以下示例通过--dir将技能批量安装到同一目标根目录每个技能实际位于$target_dir/skill-slug/target_dir/opt/skillhub-skills # 逐个安装 for skill in skill-a skill-b skill-c; do skillhub install $skill --dir $target_dir done # 或从清单文件读取每行一个技能名 xargs -a skills.txt -I {} skillhub install {} --dir $target_dir自SkillHub Server v0.2.12起公开技能支持匿名搜索与安装。注意配置了无效 Bearer Token 时命令会直接失败而不再回退匿名访问遇到这种情况请更新凭据或先移除无效 Token。7. 安全扫描Skill Scanner7.1 实现构成与许可SkillHub 内置安全扫描能力扫描接入、任务编排、审计落库和部署集成由 iFLYTEK 团队实现底层扫描服务使用 Cisco 的cisco-ai-skill-scannerApache License 2.0版权归 Cisco。scanner/Dockerfile 已固定cisco-ai-skill-scanner2.1.0基于python:3.11-slim-bookworm即 glibc LinuxScanner 镜像支持linux/amd64和linux/arm64监听 8000 端口并内置/health健康检查。7.2 upload mode 还是 local mode官方 Compose 和 Kubernetes 部署使用uploadmode通过POST /scan-upload上传技能包。从 compose.release.yml 可以看到 server 服务固定配置SKILLHUB_SECURITY_SCANNER_MODE: upload、SKILLHUB_SECURITY_SCANNER_URL: http://skill-scanner:8000且 server 的健康检查依赖 scanner 先通过健康检查depends_on的service_healthy条件保证扫描服务就绪前不会接收流量。上传大小上限由SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES控制默认110100480字节105 MiB与 100MB 发布上限留出了余量。localmode 仅适用于 Server 与 Scanner 能在相同路径看到同一目录的部署双方需要共享挂载路径并在 Scanner 中设置允许的根目录使用标准路径时配置SKILL_SCANNER_ALLOWED_ROOTS/tmp/skillhub-scansscanner/Dockerfile 中已预建该目录。7.3 “未发现高风险问题” ≠ 零 findingsScanner 返回is_safetrue、UI 显示「未发现高风险问题」仅表示没有发现高风险问题低等级 findings 仍可能存在findingsCount也可能大于 0。请继续查看 findings 明细不要把该状态理解为无条件安全保证。7.4 滚动升级到 Scanner 2.1.0升级顺序很关键先部署兼容 2.1.0 协议的 Server在旧 Scanner 仍运行时排空并下线所有旧 Server 实例及其进行中的扫描再升级 Scanner验证/health和一次 upload mode 扫描不要让旧 Server 连接 Scanner 2.1.0。混合版本期间upload 和 local mode 都应保持 AI Defense 关闭默认SKILLHUB_SCANNER_USE_AI_DEFENSEfalse。如果升级前必须继续使用 AI Defense应按旧 Scanner 版本支持的环境变量把凭据直接配置到旧 Scanner 环境中不要把 AI Defense key 放入 URL query 参数或请求体。8. HTTPS、监控与多租户8.1 配置 HTTPS生产环境建议使用 Nginx 或 Traefik 作为反向代理并配置 SSL 证书。Nginx 配置示例server { listen 443 ssl; server_name skillhub.example.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:3000; } location /api { proxy_pass http://localhost:8080; } }8.2 监控手段健康检查GET /actuator/healthCompose 中 server 容器健康检查即访问该端点Scanner 健康检查GET http://localhost:8000/health指标监控GET /actuator/metricsPrometheus 格式审计日志所有关键操作都会记录到审计日志应用日志使用 ELK 或 Loki 收集Compose 中SKILLHUB_LOG_FORMAT默认为json便于采集。8.3 多租户SkillHub 通过命名空间实现逻辑上的多租户隔离每个命名空间相当于一个租户拥有独立的成员、权限和技能包。如果需要物理隔离可以为每个租户部署独立的 SkillHub 实例。9. 高频故障排查9.1 登录正确凭据却跳回登录页该现象多见于手动部署场景接口异常或初始化未完成导致。建议改用 2.1 节的一键脚本部署必要时清空 PostgreSQL 数据卷后重建再登录若前置了反向代理检查代理配置是否正确转发。9.2 页面能打开但登录/注册接口 502页面由web容器提供登录、注册等接口由web转发给server默认SKILLHUB_API_UPSTREAMhttp://server:8080见 compose.release.yml 第 171 行。出现「页面正常但 API 502」时先检查server是否正常启动upstream 配置、DNS 或容器网络异常也可能返回 502。排查顺序# 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 个字符后重建容器即可SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET替换成你自己的随机字符串至少 32 个字符Compose 中该变量写作${SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET:?required}必填项启动前可先执行make validate-release-config对应 scripts/validate-release-config.sh它会校验.env.release提前暴露占位值和缺失项。9.3 改了配置为什么不生效两个高频原因改错了文件.env.release.example只是模板Compose 实际读取的是--env-file指定的.env.release。请先cp .env.release.example .env.release再修改.env.release只重启没重建环境变量在容器创建时注入restart不会重新注入。改完配置需要重建容器docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate修改 admin 密码同理编辑/tmp/skillhub-runtime/.env.release参考仓库根目录的 .env.release.example然后执行docker compose \ --env-file /tmp/skillhub-runtime/.env.release \ -f /tmp/skillhub-runtime/compose.release.yml \ up -d --force-recreate若此前密码已写入数据库导致仍不生效可能需要清理对应数据后重新初始化。10. 本地开发启动失败make dev-allMakefile 中的「一键启动本地开发环境」目标依赖 scanner 后端 前端后端启动失败时会显示详细错误提示常见问题如下。10.1 Maven 依赖下载失败网络超时症状后端日志显示Could not transfer artifact或连接超时。解决方案配置阿里云镜像——仓库内置了镜像配置文件可直接复制mkdir -p ~/.m2 cp server/.mvn/settings.xml ~/.m2/settings.xml或手动创建~/.m2/settings.xml?xml version1.0 encodingUTF-8? settings mirrors mirror idaliyun/id urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror /mirrors /settings10.2 Java 版本不匹配症状Unsupported class file major version或java.lang.NoSuchMethodError。解决方案安装 Java 21。server/pom.xml 中java.version、maven.compiler.source、maven.compiler.target均为 21即后端要求 JDK 21。# macOS brew install openjdk21 # 验证版本 java -version10.3 端口被占用症状Port 8080 already in use。解决方案# 查看占用端口的进程 lsof -i :8080 # 终止进程 kill -9 PID10.4 查看详细日志make dev-logs SERVICEbackend # 或直接查看 cat .dev/server.log11. 遇到问题去哪里找答案建议按以下顺序查阅仓库内资料README.md项目总览、快速开始与认证配置说明中文见 README_zh.mddocs/skillhub/en/faq.md 与 docs/skillhub/faq.md官方 FAQ 原始版本docs/security-scanning.md安全扫描专题文档覆盖 Scanner 配置参数与故障影响分析配合 scanner/docs/ 下的配置、自定义规则、监控指南docs/19-smtp-password-reset-email-setup.mdSMTP 与密码重置邮件配置deploy/k8s/ 与 charts/skillhub/Kubernetes 部署的 kustomize 与 Helm Chart 资源CONTRIBUTING.md贡献与协作规范。更多实现细节可结合源码继续深入后端位于 server/多模块 Maven 工程含 skillhub-app、skillhub-domain、skillhub-auth 等CLI 位于 cli/前端位于 web/内置技能目录见 builtin-skills/。赞分享人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载相关推荐SkillHub 企业级智能体技能注册中心实战指南私有化部署、CLI 管理与多智能体生态集成SkillHub 企业级智能体技能注册中心实战指南私有化部署、CLI 管理与多智能体生态集成 SkillHub 是一个面向企业的开源智能体Agent技能注人工智能AI AgentAI 技能后端前端SkillHub CLI 实战指南用官方 skillhub-cli 内置技能连接 Agent 注册表、安装与升级技能SkillHub CLI 实战指南用官方 skillhub cli 内置技能连接 Agent 注册表、安装与升级技能 导读本文以 SkillHub 官方内置人工智能AI AgentAI 技能后端前端OpenSCA-cli完整实战部署指南一键开启开源安全扫描OpenSCA cli完整实战部署指南一键开启开源安全扫描 在当今快速发展的软件开发领域开源组件依赖漏洞检测已成为保障项目安全的重要环节。OpenSCA c供应链安全开源治理开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考