6.5 KiB
Kubernetes / Helm 部署说明
1. 交付范围
DEPLOY-002 提供单一 Helm Chart,将以下运行角色部署到已有 Kubernetes 集群:
- API/Admin:默认两个副本,提供
/healthz、/admin/*和/api/v1/*; - MCP Gateway:默认两个副本,提供经 Bearer Token 保护的
/mcp; - Async Worker:默认两个副本,只消费
ingestion队列; - Recovery Scheduler:固定单副本,以
Recreate策略运行 Celery Beat; - Migration Job:每次安装/升级前串行执行
alembic upgrade head; - 可选 RabbitMQ:只供开发/演示集群显式启用,生产默认使用外部 Broker。
OceanBase MySQL、BOS、Embedding/Reranker 服务继续使用集群外已有资源。Chart 不创建数据库、 BOS Bucket、域名、证书或云账号,也没有扩大公共知识库阶段的业务范围。
2. 前置条件
操作者需要提前准备:
- 可用的 Kubernetes Namespace 和对应
kubectl上下文; - Helm 3/4 与 Kubernetes 客户端;
- 已推送到目标 Registry 的 API、MCP、Worker 不可变 tag 或 digest;
- Namespace 内的运行时 Secret、TLS Secret,以及私有 Registry 所需的 ImagePullSecret;
- 集群到 OceanBase、BOS、RabbitMQ 和模型服务的网络连通性。
Chart 默认引用 knowledge-platform-runtime,但不会创建它。该 Secret 至少包含以下键:
DATABASE_URL
RABBITMQ_URL
BOS_ACCESS_KEY_ID
BOS_SECRET_ACCESS_KEY
BAIDU_QIANFAN_API_KEY
OCEANBASE_VECTOR_PASSWORD
MCP_AUTH_TOKEN
RERANKER_API_KEY 可单独提供;未提供时应用按既有契约复用
BAIDU_QIANFAN_API_KEY。MCP_AUTH_TOKEN 至少 32 个字符,只具备
knowledge:search 服务范围。不要使用 kubectl --from-literal、Shell 参数或 Helm
--set 传递以上值;应由受控 Secret 管理系统或运维流程预先写入 Namespace。
3. 环境 Values
复制 values.example.yaml 到仓库外的受控
路径,填写以下非敏感信息:
- 三个镜像的 Registry 路径与不可变 tag/digest;
existingSecret和imagePullSecrets的资源名称;- OceanBase/BOS 的非敏感 Endpoint、数据库标识和 Bucket;
- Admin/API 与 MCP 的 Ingress Host、TLS Secret 名称;
- 与外部地址一致的 MCP Public URL、Issuer、Allowed Host/Origin;
- 副本、资源、超时和批量上传限制。
values.schema.json 拒绝未知顶层字段、latest tag、无效 digest、单副本 API/MCP、错误类型和
空的关键引用;模板还会校验 Chunk、检索和入库限制之间的大小关系。Values 只允许非敏感配置,
模板逐项生成 ConfigMap,不提供任意 extraEnv 入口,避免把凭据误写进渲染产物。
4. 安装与幂等升级
先做离线校验和清单检查:
make deploy-lint VALUES=/secure/path/environment-values.yaml
make deploy-render VALUES=/secure/path/environment-values.yaml
安装或升级:
NAMESPACE=knowledge-platform \
RELEASE=knowledge-platform \
make deploy VALUES=/secure/path/environment-values.yaml
make deploy 只接收 Values 文件路径。脚本会先验证 Chart、Namespace、运行时 Secret 及必需
键名、可选 RabbitMQ Secret 键名,以及启用 Ingress 时的两个 TLS Secret 引用,然后执行带失败
回滚和等待语义的 helm upgrade --install;脚本对 Helm 3 使用 --atomic,对 Helm 4 使用等价
的 --rollback-on-failure。它只验证 Secret 资源和键是否存在,不读取或输出 Secret 值。
Migration 是 pre-install,pre-upgrade Hook,固定名称配合
before-hook-creation 保证同一 Release 内不会并发执行。Helm 等待 Migration 成功后才更新业务
工作负载;失败时 Helm 保留上一版本。完成的 Job 最长保留一天供日志追查,并在下次升级前删除。
安装命令可以重复执行;数据库迁移必须保持 forward-only 与幂等。
5. Ingress、探针与 Pod 安全
生产环境启用 Ingress 后,Admin/API 与 MCP 使用独立稳定 HTTPS Host,也可由同一 Ingress Controller 托管。证书只通过预建 TLS Secret 引用,不进入 Values。
- API 的 startup/readiness/liveness 调用无凭据
/healthz; - MCP 的三类探针使用 TCP 端口,不发送或记录 Token;
- Worker/Scheduler 使用 PID 1 存活探针,业务恢复正确性由持久化 Job/Attempt 保证;
- 全部应用容器固定 UID/GID
10001、禁止提权、丢弃 Linux capabilities、使用RuntimeDefaultseccomp 和只读根文件系统; /tmp使用有大小上限的emptyDir,ServiceAccount 不挂载 API Token;- API/MCP 滚动更新使用
maxUnavailable: 0,未 Ready Pod 不进入 Service Endpoint。
/healthz 当前只表示 API 进程存活,不探测所有外部 Provider;真实依赖故障、滚动重启和
Worker 恢复行为由 DEPLOY-003 在目标集群验收。
6. 可选 Demo RabbitMQ
生产默认 rabbitmq.enabled=false,RABBITMQ_URL 指向外部受管 Broker。仅开发/演示时可开启
本地子 Chart;它使用单节点 StatefulSet 和 PVC,并要求预建 Secret 包含:
username
password
erlang-cookie
同时必须让运行时 Secret 中的 RABBITMQ_URL 指向该 Service。子 Chart 使用固定
rabbitmq:4.1.4-alpine tag 与 multi-architecture manifest digest;它不具备生产 RabbitMQ 的
高可用、备份或升级保证,禁止作为生产默认值。卸载 Release 时 StatefulSet PVC 默认保留,
删除前必须由数据责任人确认。
7. 回滚、卸载与 Secret 轮换
查看历史并回滚时不要输出 Pod 环境变量:
helm -n knowledge-platform history knowledge-platform
helm -n knowledge-platform rollback knowledge-platform <revision> --wait
更新外部 Secret 后,Secret 名称不变;用户和 WorkBuddy 配置无需重新注入。当前应通过受控 滚动重启让 Pod 读取新值,目标集群的无中断验证属于 DEPLOY-003。
卸载只删除本 Release 管理的 Kubernetes 对象:
helm -n knowledge-platform uninstall knowledge-platform
外部 OceanBase、BOS、RabbitMQ、TLS/运行时 Secret 和可选 RabbitMQ PVC 不由卸载命令删除。
8. DEPLOY-002 验收边界
本任务完成 Chart lint、双路径渲染、严格 Kubernetes Schema、Values 失败关闭、Secret 泄漏扫描
以及本地集群两次安装/升级验证。目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实
Provider 和远程 WorkBuddy 验收统一属于后续 DEPLOY-003,不得提前宣称完成。