如何把 Multica 部署到 KubernetesHelm chart、Secret 与 Ingress【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multicaMultica 的自托管方式默认是 Docker Compose但如果你已经有一个 Kubernetes 集群官方提供了 Helm chart 来替代。这篇文章的目标是把一个能运行的 MulticaPostgreSQL 17 Go 后端 Next.js 前端部署到你的集群里配好域名解析、Secret 和 Ingress通过健康检查确认后端迁移完成最后把本地 CLI 指向集群完成登录。Chart 来源有两个已发布的 OCI chartoci://ghcr.io/multica-ai/charts/multica或仓库内的源码 chart deploy/helm/multica/。它面向典型的 k3s / k8s 环境——带 Ingress controller、默认ReadWriteOnceStorageClass作者基于 k3s Traefik local-path编写其他集群做少量调整即可。前置条件按 SELF_HOSTING.md 的说明部署前需要kubectl和helm使用--take-ownership需要 v3.13或 v4已配置好目标集群集群里有 Ingress controllerTraefik / NGINX 均可集群有默认 StorageClass。Chart 会在目标 namespace 中创建这些资源multica-postgres—pgvector/pgvector:pg17默认挂 10Gi PVCmultica-backend— Go API/WS 服务默认挂 5GiReadWriteOnceuploads PVC如果你已配置 S3backend.config.s3Bucket可以设backend.uploads.persistence.enabledfalse让 chart 完全不声明这个 PVCmultica-frontend— Next.js standalone server两个Ingress资源web 主机和 backend 主机各一个multica-configConfigMap从values.yaml渲染。注意一点multica-secrets这个 Secret不由 chart 管理需要你用kubectl提前创建一次这样真实密钥不需要进 git。chart 只是按名字引用它见 values.yaml 中的existingSecret: multica-secrets。第一步让域名能解析到集群Chart 默认主机名是multica.dev.lanweb和api.multica.dev.lanbackend。任选一种方式让访问方开发机 跑 daemon 的机器能解析这两个名字在每台需要访问的机器上改/etc/hosts192.168.1.206 multica.dev.lan api.multica.dev.lan其中192.168.1.206换成你的 Ingress controller Service 可达的任意节点 IP文档示例。或者在本地 DNSPi-hole、Unbound 等里给两个主机名各加一条 A 记录指向集群 Ingress IP。如果不想用默认主机名在 install 时覆盖对应值即可ingress.frontend.host、ingress.backend.host以及backend.config.appUrl、backend.config.frontendOrigin、backend.config.localUploadBaseUrl、backend.config.googleRedirectUri。第二步创建 namespace 和 Secretkubectl create namespace multicaSecret 的 key 是 chart 约定的固定集合。内置 postgres默认时用下面的命令JWT_SECRET和POSTGRES_PASSWORD用随机值可选项先留空kubectl -n multica create secret generic multica-secrets \ --from-literalJWT_SECRET$(openssl rand -hex 32) \ --from-literalPOSTGRES_PASSWORD$(openssl rand -hex 16) \ --from-literalRESEND_API_KEY \ --from-literalGOOGLE_CLIENT_SECRET \ --from-literalCLOUDFRONT_PRIVATE_KEY \ --from-literalMULTICA_DEV_VERIFICATION_CODE如果你不用内置 postgresvalues 里postgres.external.enabledtruechart 会跳过 postgres Deployment/PVC/Service此时把POSTGRES_PASSWORD换成DATABASE_URL指向外部库例如postgres://user:passhost:5432/multica?sslmoderequire这是 values.yaml 注释中的示例格式其中的user:passhost替换为你自己的连接信息。第三步安装 chart发布版的 chart version 会去掉 Git tag 的前导v例如 release tagv0.3.5对应 chart version0.3.5且 chart 默认把前后端镜像 tag 设为对应的v0.3.5。helm install multica oci://ghcr.io/multica-ai/charts/multica \ --version chart-version \ -n multicachart-version替换为你要安装的具体 chart 版本号。要覆盖默认值先把 values 导出再编辑用-f传回helm show values oci://ghcr.io/multica-ai/charts/multica \ --version chart-version my-values.yaml # 编辑 my-values.yaml例如改 ingress hosts、镜像 tag、资源限制 helm install multica oci://ghcr.io/multica-ai/charts/multica \ --version chart-version \ -n multica \ -f my-values.yaml开发场景下直接从仓库检出安装用本地 chart 路径代替 OCI 地址helm install multica deploy/helm/multica -n multica验证Pod 就绪与健康检查kubectl -n multica get pods -w冷集群上 backend 可能先Running但不Ready因为它在等 PostgreSQL 并执行迁移——startupProbe 会吸收这段等待Pod 不应重启。等 backend 报Ready时迁移已完成、/healthz返回 OKcurl -H Host: api.multica.dev.lan http://ingress-ip/healthz # 文档示例输出 # {status:ok,checks:{db:ok,migrations:ok}}ingress-ip替换为你集群 Ingress 的 IP。上面带引号的 JSON 是文档给出的示例输出用于判断检查项是否齐全。最后浏览器打开http://multica.dev.lan应能看到前端。第四步登录Chart 默认APP_ENVproductionvalues.yaml中backend.config.appEnv且默认没有固定验证码。三种登录方式与 Docker 版相同推荐生产给 Secret 补上真实 Resend key然后重启 backend。真实验证码会发到你在登录页填写的邮箱kubectl -n multica patch secret multica-secrets --typemerge \ -p {stringData:{RESEND_API_KEY:re_xxx}} kubectl -n multica rollout restart deploy/multica-backendre_xxx替换为你自己的 Resend API key。邮件变量细节RESEND_API_KEY、RESEND_FROM_EMAIL或改用SMTP_HOST走 SMTP relay见 SELF_HOSTING_ADVANCED.md 的 Email 一节。未配置邮件时验证码在服务端生成并打到 backend 日志从中复制即可适合一次性测试kubectl -n multica logs -f deploy/multica-backend | grep Verification code本地/私有环境的确定性测试在 values 里设backend.config.appEnv: development并在 Secret 里设MULTICA_DEV_VERIFICATION_CODE888888然后helm upgrade并重启 backend。注意这个固定码在APP_ENVproduction下会被忽略helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \ --version chart-version \ -n multica \ -f my-values.yaml --set backend.config.appEnvdevelopment kubectl -n multica patch secret multica-secrets --typemerge \ -p {stringData:{MULTICA_DEV_VERIFICATION_CODE:888888}} kubectl -n multica rollout restart deploy/multica-backend警告不要在任何公网可达的实例上设置MULTICA_DEV_VERIFICATION_CODE——知道邮箱地址的人就能用这个固定码登录。ALLOW_SIGNUP、DISABLE_WORKSPACE_CREATION、GOOGLE_CLIENT_ID同样位于values.yaml的backend.config.*下键名allowSignup、disableWorkspaceCreation、googleClientId。helm upgrade之后 ConfigMap hash 变化会让 backend Pod 自动滚动web 端这三个值从/api/config运行时读取无需重建前端。第五步安装 CLI 并指向集群daemon 跑在你自己的机器上不在集群里。装好 CLI 和一个 AI agent CLI 之后把 CLI 指到 Ingress 主机名multica setup self-host \ --server-url http://api.multica.dev.lan \ --app-url http://multica.dev.lan跑 daemon 的机器必须有第一步配好的/etc/hosts或 DNS条目否则解析不到这两个主机名。升级、回滚与拆除拉取最新镜像values 里用的是可变latesttag 时kubectl -n multica rollout restart deploy/multica-backend deploy/multica-frontend升级到指定版本就升级对应 chart versionchart 默认把应用镜像指向匹配的 Git tag需要独立覆盖应用镜像时在 values 里设置images.backend.tag/images.frontend.tag。升级出问题可回滚helm -n multica rollback multica一个已知的升级坑从v0.3.4升到v0.3.5报refusing to drop legacy daily rollups: ...时自 MUL-2957 起migrate up会在应用迁移103之前自动跑幂等的月度分片 backfill干净的升级就是单次helm upgrade backend 滚动如果二进制早于 MUL-2957 或自动钩子失败按 SELF_HOSTING_ADVANCED.md 中 Usage Dashboard Rollup 一节的恢复流程手动补跑backfill_task_usage_hourly。拆除时两条命令行为不同# 删除工作负载保留 PVC 和 Secret helm -n multica uninstall multica # 删除 namespace连 PostgreSQL 数据和 uploads 一并清空 kubectl delete namespace multica第二条kubectl delete namespace multica会不可逆地清掉数据库和上传文件执行前确认你不再需要这些数据。Ingress 的细节两个 Ingress 的定义在 templates/ingress.yamlfrontend Ingress 把ingress.frontend.host的/前缀路径转发到 frontend Service 的 3000 端口backend Ingress 把ingress.backend.host转发到 backend Service 的 8080 端口。ingress.className默认traefikNGINX 集群要在 values 里改成对应类名ingress.annotations是空的需要给某个 Ingress 加注解时在这里填。TLS 块在默认 values 里被注释掉需要时在 values 里放开ingress.tls。另外当前multica-web镜像在运行时读取REMOTE_API_URL和DOCS_URL改 API/docs 上游不需要重新构建 web 镜像chart 默认把REMOTE_API_URL指向本版本 backend Service。frontend.compatibility.backendAlias只服务于在构建期烘焙了REMOTE_API_URLhttp://backend:8080的旧镜像用当前镜像保持false即可。参考文件SELF_HOSTING.md — Kubernetes 部署章节的完整说明deploy/helm/multica/values.yaml — 全部可覆盖项及 Secret 创建示例deploy/helm/multica/Chart.yaml — chart 元信息deploy/helm/multica/templates/ingress.yaml — 两个 Ingress 的模板SELF_HOSTING_ADVANCED.md — 邮件、注册控制、Usage Dashboard Rollup 等高级配置【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考