knowledge-platform/docs/development/CLUSTER_OPERATIONS.md

7.6 KiB
Raw Blame History

公共知识库集群运行与验收手册

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:

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。部署前执行:

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. 安装、幂等升级与只读验收

首次安装或普通升级使用同一入口:

NAMESPACE=knowledge-platform RELEASE=knowledge-platform \
  make deploy VALUES=/secure/path/environment-values.yaml

只读验收不会触发安装、重启或故障注入,但强制 context 与操作者声明完全一致:

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 执行:

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 通过静默输入进入 当前进程环境,不写入命令参数或配置文件:

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,只通过客户端安全环境注入 EKP_MCP_URL 和 EKP_MCP_TOKEN。验收必须确认:连接状态正常、只发现 search_knowledge、真实问题返回至少一个带来源字段的结果。记录客户端版本、时间、网络区域、 Tool 名和成功/失败即可,禁止复制 Token、正文或内部 Provider 信息。

7. 日志、指标与最小告警

应用事件为单行 JSON,允许字段包括 event、request_id、job_id、attempt_number、stage、 job_status 和耗时;异常正文不会被格式化器写出。常用检查:

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 记录非敏感结果。 只有完整自动化验收、真实 MCP 协议调用和远程 WorkBuddy 三部分全部通过,DEPLOY-003 才能 标记完成并合并到 main。