SkillHub部署完全指南：Docker Compose、Helm与K8s三条路径及多架构镜像实战

SkillHub部署完全指南Docker Compose、Helm与K8s三条路径及多架构镜像实战【免费下载链接】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/skillhubSkillHub 是一个自托管的开源 AI Agent 技能注册中心支持技能包发布与版本管理、RBAC 权限治理、审计日志可通过 Docker 或 Kubernetes 私有化部署。本文将带你完整走通SkillHub 部署的三条路径Docker Compose 单机交付、Kubernetes Kustomize 原生部署、Helm Chart 企业级部署并实战验证多架构镜像amd64 / arm64 / riscv64的使用方式。 1分钟选对部署路径你的场景推荐路径核心文件单台服务器、快速上线、对外演示Docker Composecompose.release.yml已有 K8s 集群想用最简单的 YAML 部署Kustomizedeploy/k8s/README.md生产级集群需要 HA、HPA、GitOpsHelm Chartcharts/skillhub/README.md无论哪条路径SkillHub 的运行模型一致WebNginx 前端→ ServerSpring Boot 后端→ PostgreSQL Redis外加可选的安全扫描器 Scanner。✅ 部署前置条件三条路径通用Docker 路径Docker Engine Compose 插件若使用 GHCR 私有镜像需先docker login ghcr.ioK8s 路径Kubernetes 1.24、已配置kubectl、默认 StorageClassHelm 路径额外需要 Helm 3.8网络只开放80/443公网入口避免直接暴露5432PostgreSQL和6379Redis先获取源码git clone https://gitcode.com/gh_mirrors/sk/skillhub cd skillhub 路径一Docker Compose 单机部署最快上手这是最省心的路径一条命令拉起全部容器PostgreSQL 与 Redis 默认只绑定127.0.0.1安全性有保障。三步完成 SkillHub 部署第 1 步准备环境变量文件cp .env.release.example .env.release.env.release.example 是运行时变量模板包含镜像名、镜像版本、端口、数据库凭证、外部 S3 对象存储参数和首登管理员参数。重点关注这几项变量说明SKILLHUB_VERSION镜像版本标签latest/edge/vX.Y.Z三选一POSTGRES_PASSWORD务必改为非默认强密码BOOTSTRAP_ADMIN_PASSWORD首登管理员密码默认值会被校验脚本拒绝SKILLHUB_PUBLIC_BASE_URL最终 HTTPS 域名不带尾部/影响 OAuth 回调与 CookieSKILLHUB_STORAGE_S3_*对象存储接入参数推荐生产使用外部 S3/OSS第 2 步启动前校验配置make validate-release-config该脚本由 scripts/validate-release-config.sh 实现可提前拦截replace-me占位值、URL 格式错误、缺失的 OSS 凭据和危险明文默认值——上线前的体检步骤强烈建议每次都跑。第 3 步一键启动docker compose --env-file .env.release -f compose.release.yml up -d启动拓扑见 docs/09-deployment.mdWeb 容器提供静态资源并把/api/*、/oauth2/*反代到后端后端运行dockerprofile所有服务都带健康检查和depends_on依赖编排启动顺序自动保证。开发模式彩蛋如果只是本地开发make dev-all会基于 docker-compose.yml 只拉起 PostgreSQL / Redis / MinIO / Scanner前后端跑在宿主机上热更新更友好。☸️ 路径二Kubernetes Kustomize 部署适合已经熟悉 K8s、希望用纯 YAML kustomize管理部署的团队。目录结构在 deploy/k8s/base/基础配置Deployment、Service、ConfigMap、Ingressoverlays/with-infra/完整部署内置 PostgreSQL Redis StatefulSetoverlays/external/外部数据库模式复用已有 PG/Redis一键部署内置数据库版kubectl create namespace skillhub # 1. 配置敏感信息 cd deploy/k8s/base cp secret.yaml.example secret.yaml # 编辑数据库连接、管理员密码 # 2. 一键部署含内置 PG Redis kubectl apply -k overlays/with-infra/ # 3. 验证 kubectl get pods -n skillhub kubectl wait --forconditionready pod --all -n skillhub --timeout300s本地测试可用端口转发访问kubectl port-forward svc/skillhub-web -n skillhub 8080:80已有数据库修改base/configmap.yaml的 Redis 地址与secret.yaml的数据库凭据后执行kubectl apply -k overlays/external/即可SkillHub 还支持外部 Redis Cluster / Sentinel 接入详见 deploy/k8s/README.md。⚓ 路径三Helm Chart 企业级部署charts/skillhub/ 是功能最全的方案内置 Bitnami PostgreSQL / Redis 子 Chart支持主从复制、哨兵模式、HPA 自动扩缩容、PDB Pod 中断预算、TLS 证书管理、Prometheus 指标导出并内置values.schema.json交叉校验。生产安装标准流程第 1 步准备受保护的 values 文件secrets: allowAutoGenerated: false # 禁止随机生成保证 GitOps 可复现 bootstrapAdminPassword: 固定管理员密码 downloadAnonCookieSecret: 至少32字符的固定随机值 postgresql: auth: postgresPassword: 固定管理员密码 password: 固定业务密码 redis: auth: password: 固定Redis密码第 2 步构建依赖并安装helm dependency build ./charts/skillhub kubectl create namespace skillhub helm -n skillhub upgrade -i skillhub ./charts/skillhub \ -f values-production.yaml \ --set publicBaseUrlhttps://skills.example.com所有 values 在安装前会先经过 schema 校验无效的组件 / Ingress / HPA / 存储组合会直接失败不会留下半成品部署。进阶玩法速查完整参数见 charts/skillhub/values.yaml# 高可用模式PG 主从 Redis 哨兵 --set postgresql.architecturereplication \ --set redis.architecturereplication # 多副本Server 扩到 3 副本本地存储需 RWX否则建议 S3 --set server.replicaCount3 --set server.storage.accessModeReadWriteMany # 外部数据库模式 --set postgresql.enabledfalse --set redis.enabledfalse \ --set externalDatabase.hostpostgres.example.com \ --set externalRedis.hostredis.example.com # 复用已有 Secret避免明文密码 --set existingSecretmy-custom-secretGitOps 用户注意Argo CD 等工具使用离线helm template无法读取集群已有 Secret。因此 Chart 默认allowAutoGeneratedfalse——缺失固定密码时会明确报错指出具体配置项而不是静默随机生成导致漂移。️ 多架构镜像实战AMD / ARM / RISC-V 通吃SkillHub 通过 GitHub Actions 发布多架构 manifest这是私有化部署在国产化环境中的重要能力组件支持架构skillhub-server后端linux/amd64、linux/arm64、linux/riscv64skillhub-web前端linux/amd64、linux/arm64、linux/riscv64skillhub-scanner扫描器linux/amd64、linux/arm64镜像标签怎么选标签含义推荐场景latest仅在语义化版本 tag 发布时更新默认快速启动edgemain 分支最新构建团队内部持续验证vX.Y.Z对应 Git tag对外演示 / 严格可复现环境在.env.release中通过SKILLHUB_VERSIONv1.2.3固定版本即可同一份 Compose 文件在 x86 服务器和 ARM 服务器如 Apple 芯片、国产飞腾/鲲鹏上都能正确拉取对应架构镜像无需任何修改。RISC-V 平台的支持细节构建方式、运行时限制见 docs/RISCV64.md私有化离线环境可参考 deploy/runtime-mirror-images.txt 做镜像源映射。 部署验证与避坑清单健康检查三件套# 后端健康检查 curl -i http://127.0.0.1:8080/actuator/health # Compose 服务状态 docker compose --env-file .env.release -f compose.release.yml ps # K8s Pod 状态 kubectl get pods -n skillhub全部就绪后浏览器打开SKILLHUB_PUBLIC_BASE_URL即可看到 SkillHub 首页——搜索、技能详情、命名空间与审核列表一览无余。高频避坑要点首登后立即改密码bootstrap admin默认用户名admin完成首次登录后应立刻修改密码完全走 OAuth 的场景可将BOOTSTRAP_ADMIN_ENABLED设为false公网 URL 别忘填SKILLHUB_PUBLIC_BASE_URL必须是最终 HTTPS 域名否则 OAuth 回调、设备码链接、Cookie 安全判断都会异常子路径部署三件套网关部署在/skillhub/时需同时设置SKILLHUB_WEB_BASE_PATH/skillhub/、SKILLHUB_WEB_API_BASE_URL/skillhub和公网 URL 前缀K8s Pod 一直 Pending先查 PVC 是否绑定kubectl get pvc -n skillhub再查节点资源镜像拉取失败私有镜像需创建docker-registry类型的拉取凭证 Secret数据迁移无感Flyway 在应用启动时自动执行 schema 迁移server/skillhub-app/ 是唯一 schema 变更入口升级无需手工动库 延伸阅读资料路径部署架构与运维总纲docs/09-deployment.mdK8s 部署指南含故障排查deploy/k8s/README.mdHelm Chart 完整配置参考charts/skillhub/README.mdRISC-V 多架构支持说明docs/RISCV64.md官方文档站点部署/治理/CLIdocs/skillhub/guide/开发工作流入口Make 命令大全Makefile三条路径一套镜像体系——从一台裸金属服务器到一个多副本 HA 集群SkillHub 都能以相同的心智模型完成部署。建议先用 Docker Compose 路径跑通全链路熟悉核心变量后再平滑迁移到 Helm 生产部署。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考