knowledge-platform/docs/development/KUBERNETES_DEPLOYMENT.md
2026-09-03 12:21:54 +08:00

6.5 KiB
Raw Blame History

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. 前置条件

操作者需要提前准备:

  1. 可用的 Kubernetes Namespace 和对应 kubectl 上下文;
  2. Helm 3/4 与 Kubernetes 客户端;
  3. 已推送到目标 Registry 的 API、MCP、Worker 不可变 tag 或 digest;
  4. Namespace 内的运行时 Secret、TLS Secret,以及私有 Registry 所需的 ImagePullSecret;
  5. 集群到 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、使用 RuntimeDefault seccomp 和只读根文件系统;
  • /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,不得提前宣称完成。