# 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 至少包含以下键: ```text 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`](../../deploy/helm/environments/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. 安装与幂等升级 先做离线校验和清单检查: ```bash make deploy-lint VALUES=/secure/path/environment-values.yaml make deploy-render VALUES=/secure/path/environment-values.yaml ``` 安装或升级: ```bash 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 包含: ```text 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 环境变量: ```bash helm -n knowledge-platform history knowledge-platform helm -n knowledge-platform rollback knowledge-platform --wait ``` 更新外部 Secret 后,Secret 名称不变;用户和 WorkBuddy 配置无需重新注入。当前应通过受控 滚动重启让 Pod 读取新值,目标集群的无中断验证属于 DEPLOY-003。 卸载只删除本 Release 管理的 Kubernetes 对象: ```bash 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`,不得提前宣称完成。