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/skillhub

SkillHub 是一个自托管的开源 AI Agent 技能注册中心，支持技能包发布与版本管理、RBAC 权限治理、审计日志，可通过 Docker 或 Kubernetes 私有化部署。本文将带你完整走通SkillHub 部署的三条路径：Docker Compose 单机交付、Kubernetes Kustomize 原生部署、Helm Chart 企业级部署，并实战验证多架构镜像（amd64 / arm64 / riscv64）的使用方式。

🧭 1分钟选对部署路径

无论哪条路径，SkillHub 的运行模型一致：Web（Nginx 前端）→ Server（Spring Boot 后端）→ PostgreSQL + Redis，外加可选的安全扫描器 Scanner。

✅ 部署前置条件（三条路径通用）

• Docker 路径：Docker Engine + Compose 插件；若使用 GHCR 私有镜像需先docker login ghcr.io
• K8s 路径：Kubernetes 1.24+、已配置kubectl、默认 StorageClass；Helm 路径额外需要 Helm 3.8+
• 网络：只开放80/443公网入口，避免直接暴露5432（PostgreSQL）和6379（Redis）
• 先获取源码：

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 对象存储参数和首登管理员参数。重点关注这几项：

第 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.md：Web 容器提供静态资源并把/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、Ingress）
• overlays/with-infra/：完整部署，内置 PostgreSQL + Redis StatefulSet
• overlays/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 --for=condition=ready pod --all -n skillhub --timeout=300s

本地测试可用端口转发访问：

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 publicBaseUrl=https://skills.example.com

所有 values 在安装前会先经过 schema 校验，无效的组件 / Ingress / HPA / 存储组合会直接失败，不会留下半成品部署。

进阶玩法速查（完整参数见 charts/skillhub/values.yaml）：

# 高可用模式：PG 主从 + Redis 哨兵 --set postgresql.architecture=replication \ --set redis.architecture=replication # 多副本：Server 扩到 3 副本（本地存储需 RWX，否则建议 S3） --set server.replicaCount=3 --set server.storage.accessMode=ReadWriteMany # 外部数据库模式 --set postgresql.enabled=false --set redis.enabled=false \ --set externalDatabase.host=postgres.example.com \ --set externalRedis.host=redis.example.com # 复用已有 Secret，避免明文密码 --set existingSecret=my-custom-secret

🔐GitOps 用户注意：Argo CD 等工具使用离线helm template，无法读取集群已有 Secret。因此 Chart 默认allowAutoGenerated=false——缺失固定密码时会明确报错指出具体配置项，而不是静默随机生成导致漂移。

🖥️ 多架构镜像实战：AMD / ARM / RISC-V 通吃

SkillHub 通过 GitHub Actions 发布多架构 manifest，这是私有化部署在国产化环境中的重要能力：

镜像标签怎么选？

在.env.release中通过SKILLHUB_VERSION=v1.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 首页——搜索、技能详情、命名空间与审核列表一览无余。

高频避坑要点：

1. 首登后立即改密码：bootstrap admin（默认用户名admin）完成首次登录后应立刻修改密码；完全走 OAuth 的场景可将BOOTSTRAP_ADMIN_ENABLED设为false
2. 公网 URL 别忘填：SKILLHUB_PUBLIC_BASE_URL必须是最终 HTTPS 域名，否则 OAuth 回调、设备码链接、Cookie 安全判断都会异常
3. 子路径部署三件套：网关部署在/skillhub/时，需同时设置SKILLHUB_WEB_BASE_PATH=/skillhub/、SKILLHUB_WEB_API_BASE_URL=/skillhub和公网 URL 前缀
4. K8s Pod 一直 Pending：先查 PVC 是否绑定（kubectl get pvc -n skillhub），再查节点资源
5. 镜像拉取失败：私有镜像需创建docker-registry类型的拉取凭证 Secret
6. 数据迁移无感：Flyway 在应用启动时自动执行 schema 迁移，server/skillhub-app/ 是唯一 schema 变更入口，升级无需手工动库

📚 延伸阅读

三条路径，一套镜像体系——从一台裸金属服务器到一个多副本 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