knowledge-platform/docs/development/CLUSTER_OPERATIONS.md

148 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 公共知识库集群运行与验收手册
## 1. 范围与安全边界
本手册覆盖 DEPLOY-003 的目标集群安装、幂等升级、滚动恢复、Worker 故障恢复、最小日志/指标、
备份责任和远程 MCP/WorkBuddy 验收。当前仍是企业受控网络内的单一公共知识库,不增加用户、
租户或 Document ACL,也不提供完整 Observability 平台和跨区域灾备。
所有敏感值必须由 Secret 管理系统写入 Kubernetes Secret。Values、Git、镜像、命令行参数、
验收记录和日志中不得出现数据库 URL、RabbitMQ URL、云密钥、Provider Key 或 MCP Token。
## 2. 交付责任边界
| 资源 | 平台仓库负责 | 环境/运维负责 |
|---|---|---|
| 应用镜像 | 可重复构建的 API、MCP、Worker target | 目标 Registry、不可变 tag/digest、镜像扫描和保留策略 |
| Kubernetes | Helm Chart、Migration、探针、PDB、资源和 Pod 安全默认值 | 集群、Namespace、Ingress Controller、配额和网络策略 |
| 敏感配置 | Secret 引用和必需键名预检 | Secret 创建、轮换、审计和访问控制 |
| HTTPS | Ingress Host/TLS Secret 引用 | DNS、证书签发/续期与 TLS Secret |
| 数据 | canonical/可重建边界和恢复顺序 | OceanBase、BOS、RabbitMQ 的备份、容量、HA 和恢复演练 |
| 监控 | JSON 事件、API `/metrics`、验收检查 | 日志/指标采集、留存、查询、告警和 On-call |
## 3. 部署前检查
操作者需要准备仓库外的环境 Values、Namespace、运行时 Secret、TLS Secret、ImagePullSecret,
并确认集群可访问 OceanBase、BOS、RabbitMQ、Embedding 和 Reranker。先显式选择并核对 context:
```bash
kubectl config current-context
kubectl auth can-i get deployments -n knowledge-platform
kubectl auth can-i patch deployments -n knowledge-platform
```
镜像必须使用 Registry 中已存在的不可变 tag 或 digest,禁止 `latest`。部署前执行:
```bash
make deploy-lint VALUES=/secure/path/environment-values.yaml
make deploy-render VALUES=/secure/path/environment-values.yaml >/tmp/ekp-rendered.yaml
```
渲染文件只能包含非敏感 ConfigMap 和 Secret 引用;完成检查后应删除临时文件。
## 4. 安装、幂等升级与只读验收
首次安装或普通升级使用同一入口:
```bash
NAMESPACE=knowledge-platform RELEASE=knowledge-platform \
make deploy VALUES=/secure/path/environment-values.yaml
```
只读验收不会触发安装、重启或故障注入,但强制 context 与操作者声明完全一致:
```bash
ACCEPTANCE_KUBE_CONTEXT="$(kubectl config current-context)" \
NAMESPACE=knowledge-platform RELEASE=knowledge-platform \
make cluster-acceptance VALUES=/secure/path/environment-values.yaml
```
## 5. 完整可用性验收
完整模式会连续执行两次相同 Helm 入口、滚动重启 API/MCP,并在一个合成入库 Job 运行时强制
删除一个明确选中的 Worker Pod。只能在已批准的验收 Namespace 执行:
```bash
context="$(kubectl config current-context)"
ACCEPTANCE_MODE=full \
ACCEPTANCE_KUBE_CONTEXT="${context}" \
ACCEPTANCE_CONFIRM="DEPLOY-003:${context}:knowledge-platform:knowledge-platform" \
NAMESPACE=knowledge-platform RELEASE=knowledge-platform \
make cluster-acceptance VALUES=/secure/path/environment-values.yaml
```
脚本验证以下内容:
- 相同 Values 的安装/升级可以重复成功,Migration Hook 先于工作负载更新完成;
- API/MCP 至少两个副本全部 Ready/Available,PDB 存在;
- Admin、健康检查、指标和 MCP 均通过稳定 HTTPS Host 到达;
- API/MCP 滚动期间连续健康探测无中断;
- Worker 被非优雅中断后,同一 canonical Job 经租约到期和恢复调度器完成,不要求重新上传;
- 合成文档验收完成后调用公开删除 API 清理,脚本不访问 Secret 值。
若合成文档处理过快,脚本会失败而不是虚报 Worker 中断已验证。可在受控验收环境调整 Provider
延迟或使用批准的非敏感验收文件重跑,不得加入测试后门。
## 6. 远程 MCP 与 WorkBuddy
先用官方 MCP Python Client 验证远程协议、唯一 Tool 和一次真实检索。Token 通过静默输入进入
当前进程环境,不写入命令参数或配置文件:
```bash
export EKP_MCP_URL=https://mcp.example.internal/mcp
export EKP_MCP_ACCEPTANCE_QUERY='已批准的公共知识验收问题'
read -rsp 'MCP token: ' EKP_MCP_TOKEN && export EKP_MCP_TOKEN && echo
make mcp-remote-acceptance
unset EKP_MCP_TOKEN
```
随后在与最终用户相同网络路径的 WorkBuddy 客户端加载
[`workbuddy-mcp.example.json`](../../deploy/workbuddy-mcp.example.json),只通过客户端安全环境注入
`EKP_MCP_URL` 和 `EKP_MCP_TOKEN`。验收必须确认:连接状态正常、只发现
`search_knowledge`、真实问题返回至少一个带来源字段的结果。记录客户端版本、时间、网络区域、
Tool 名和成功/失败即可,禁止复制 Token、正文或内部 Provider 信息。
## 7. 日志、指标与最小告警
应用事件为单行 JSON,允许字段包括 `event`、`request_id`、`job_id`、`attempt_number`、`stage`、
`job_status` 和耗时;异常正文不会被格式化器写出。常用检查:
```bash
kubectl -n knowledge-platform logs deployment/knowledge-platform-api --since=15m
kubectl -n knowledge-platform logs deployment/knowledge-platform-worker --since=15m
curl --fail https://knowledge.example.internal/metrics
kubectl -n knowledge-platform get deployments,pods,poddisruptionbudgets
```
环境监控至少采集并告警:API/MCP Ready 副本不足、Pod 重启持续增加、HTTP 5xx、P95 请求耗时、
Worker 无 Ready 副本、`ingestion_attempt_failed`/`ingestion_retry_cleanup_failed`、恢复扫描持续
失败、Migration Job 失败,以及 OceanBase/BOS/RabbitMQ/模型服务在应用日志中的安全失败事件。
阈值由真实流量基线确定,不在本任务中固化完整监控平台。
## 8. 故障处置
API/MCP 不可用时先检查 Deployment/Endpoint/Ingress/TLS,再按单个 Deployment 滚动重启;禁止
直接打印 Pod 环境变量。Job 卡住时使用 Admin/API 的 Job ID 查询状态,再按相同 Job ID 搜索
Worker JSON 事件。处于有效租约的 Job 不应手工重复提交;租约到期后恢复调度器会重投递。
更新同名 Secret 不会自动改变已运行进程。由运维完成 Secret 轮换后,依次滚动重启 API、MCP、
Worker 和 Scheduler,并复跑只读验收。稳定 Host 和客户端 Token 未轮换时,Admin/WorkBuddy
无需重新配置;MCP Token 轮换时必须通过客户端 Secret 分发流程更新。
## 9. 备份与恢复顺序
OceanBase 关系表和 BOS 不可变源文件共同构成事实数据,必须由资源所有者执行一致性备份策略。
OceanBase 向量表是可重建索引,不得代替 canonical 备份。RabbitMQ 消息只提供执行提示,
canonical Job/Attempt 才是恢复依据,但生产 Broker 仍应按其 SLA 做持久化和 HA。
恢复顺序为:恢复/验证 OceanBase canonical 表 → 恢复并核对 BOS 对象 → 部署相同或兼容应用版本
并执行 forward-only Migration → 恢复 RabbitMQ 连通 → 启动 Worker/Scheduler → 按 active Index
Profile 重建缺失向量 → 验证来源追踪和真实检索。Helm 回滚只能回退兼容的应用清单,不能反向
撤销数据库 Migration。完整灾备演练仍是后置任务。
## 10. 验收记录
每次目标集群验收按 [`DEPLOY_003_ACCEPTANCE.md`](DEPLOY_003_ACCEPTANCE.md) 记录非敏感结果。
只有完整自动化验收、真实 MCP 协议调用和远程 WorkBuddy 三部分全部通过,DEPLOY-003 才能
标记完成并合并到 `main`。