# 公共知识库集群运行与验收手册 ## 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`。