144 lines
6.5 KiB
Markdown
144 lines
6.5 KiB
Markdown
# 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 <revision> --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`,不得提前宣称完成。
|