第 2.11.3 节：把数据库、向量库、Worker 和健康检查纳入部署验收
数据库、向量库、Worker 和健康检查只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够写出数据库、向量库、Worker 和健康检查的验收样例、通过/不通过标准、判断阈值和风险说明。
实现步骤或决策流程
推荐技术流
客服 Agent（智能体）工作台的部署技术流，推荐按“先产物、再配置、再数据、再入口、再验收”的顺序设计。
| 顺序 | 做什么 | 验收重点 |
|---|---|---|
| 1 | 定义部署环境 | 至少区分 local（本地）、staging（预发布）、production（生产）。 |
| 2 | 固化服务镜像 | 前端、后端、worker（后台任务）都有明确 image_version（镜像版本）。 |
| 3 | 设计 env_profile（环境配置） | 同一镜像能通过配置切换模型、数据库、域名和日志级别。 |
| 4 | 管理 secret_ref（密钥引用） | 模型 API Key（接口密钥）、数据库密码、第三方凭证不进入代码、镜像和日志。 |
| 5 | 准备数据库和向量数据库 | migration_status（迁移状态）明确，backup_status（备份状态）可验证。 |
| 6 | 拆分 API（应用程序接口）和 worker（后台任务） | 长任务不会阻塞在线请求，失败可重试。 |
| 7 | 配置 Nginx（反向代理服务器）入口 | public_url（公开地址）、TLS（传输层安全协议）、路径、超时、上传大小符合业务。 |
| 8 | 设计健康检查 | health_status（健康状态）覆盖进程、依赖和最小业务链路。 |
| 9 | 接入日志和 trace_id（追踪编号） | 部署事件、请求链路、模型调用、工具调用、worker（后台任务）能关联。 |
| 10 | 执行上线检查 | 前端、API、模型、RAG（检索增强生成）、工单、备份、回滚都通过。 |
| 11 | 观察灰度窗口 | 新版本上线后观察错误率、延迟、成本、队列积压和用户反馈。 |
| 12 | 保留回滚路径 | rollback_version（回滚版本）、旧配置和恢复步骤明确。 |
这条技术流的核心不是“部署工具选哪一个”，而是“上线状态能不能被描述和验证”。只要你能稳定回答“当前跑的是哪个版本、用了哪套配置、健康状态如何、失败能不能回滚”，部署就开始具备工程可信度。
字段契约
部署也需要字段契约。没有字段契约，团队只能靠聊天记录和记忆判断“现在服务器上到底是什么状态”。
部署记录字段契约
| 字段 | 含义 | 示例含义 | 验收要求 |
|---|---|---|---|
| deployment_id（部署编号） | 一次上线或回滚动作的唯一编号 | 用来追踪某次生产发布 | 能关联部署人、时间、服务、版本、日志和结果。 |
| environment（环境） | 部署目标环境 | local、staging、production | 生产和测试必须明确区分，不能共用敏感配置。 |
| service_name（服务名称） | 被部署的服务 | frontend、api、worker、nginx | 每个服务独立记录，不用一句“系统已部署”带过。 |
| image_version（镜像版本） | 本次部署使用的镜像或构建产物版本 | 某个后端 API 版本 | 必须可追溯到构建产物，不能只写“latest”。 |
| env_profile（环境配置） | 本次部署使用的配置档案 | 生产模型、生产数据库、生产域名组合 | 能看出配置来源和生效范围。 |
| secret_ref（密钥引用） | 密钥的引用名或管理位置 | 模型密钥、数据库密码、第三方凭证引用 | 只能记录引用，不能记录真实密钥。 |
| health_status（健康状态） | 部署后的健康结果 | healthy、degraded、failed | 必须来自健康检查，不靠人工感觉。 |
| public_url（公开地址） | 用户访问入口 | 客服工作台公网域名 | 必须经过 TLS（传输层安全协议）和 Nginx（反向代理服务器）。 |
| internal_url（内部地址） | 服务之间访问的内部地址 | Nginx（反向代理服务器）转发到 API 的地址 | 不应直接暴露给公网用户。 |
| rollback_version（回滚版本） | 出问题时要退回的版本 | 上一个稳定镜像版本 | 上线前就要确认存在且可用。 |
| backup_status（备份状态） | 上线前后的备份结果 | completed、missing、failed | 数据库和关键配置必须能恢复。 |
| migration_status（迁移状态） | 数据库或索引迁移结果 | not_required、pending、completed、failed | 迁移失败不能继续宣称上线成功。 |
| trace_id（追踪编号） | 串联部署动作和运行日志的编号 | 用于追踪上线过程中的错误 | 部署日志、健康检查日志和告警要能关联。 |
服务配置字段契约
| 字段 | 适用服务 | 说明 |
|---|---|---|
| service_name（服务名称） | 全部服务 | 服务名称要稳定，方便日志和告警识别。 |
| environment（环境） | 全部服务 | 本地、预发布、生产不能混用数据库和密钥。 |
| env_profile（环境配置） | API、worker（后台任务）、前端 | 表示当前服务读取哪套配置，不直接暴露密钥值。 |
| secret_ref（密钥引用） | API、worker（后台任务） | 指向模型、数据库、工单系统等敏感凭证。 |
| public_url（公开地址） | 前端、Nginx（反向代理服务器） | 用户和客户可访问的地址。 |
| internal_url（内部地址） | API、数据库、向量数据库、worker（后台任务） | 内部通信地址，不应作为用户入口。 |
| health_status（健康状态） | 全部服务 | 记录服务自身和关键依赖是否可用。 |
| trace_id（追踪编号） | API、Agent、worker（后台任务） | 串联用户请求、工具调用、后台任务和错误。 |
上线事件字段契约
| 字段 | 含义 | 为什么需要 |
|---|---|---|
| deployment_id（部署编号） | 本次上线事件 | 出现问题时能知道是哪次上线引入的。 |
| operator（操作人） | 谁发起上线 | 便于权限审计和责任归属。 |
| approval_status（审批状态） | 是否经过负责人确认 | 生产上线不能完全靠个人随手操作。 |
| precheck_result（上线前检查结果） | 上线前依赖是否满足 | 防止无备份、无密钥、无回滚就上线。 |
| migration_status（迁移状态） | 数据结构或索引是否迁移成功 | 防止应用和数据结构不一致。 |
| health_status（健康状态） | 上线后的服务健康 | 决定是否继续观察、回滚或下线。 |
| rollback_version（回滚版本） | 可退回版本 | 新版本异常时减少决策时间。 |
| trace_id（追踪编号） | 关联部署日志 | 和下一章可观测性衔接。 |
字段契约的意义是把部署从“口头经验”变成“系统事实”。当客户问“昨天晚上的版本为什么创建工单失败”，你应该能从 deployment_id（部署编号）找到 image_version（镜像版本）、env_profile（环境配置）、migration_status（迁移状态）、健康检查结果和相关 trace_id（追踪编号）。
制作步骤
下面是把客服 Agent 工作台部署成可交付系统的制作方法。它不是命令清单，而是工程步骤和验收顺序。
第 1 步：定义环境边界
先定义有哪些环境：
| 环境 | 用途 | 配置原则 |
|---|---|---|
| local（本地） | 开发和调试 | 可以使用 Mock（模拟）模式和本地数据库。 |
| staging（预发布） | 上线前验证 | 尽量接近生产，但使用隔离数据和测试密钥。 |
| production（生产） | 客户真实使用 | 使用生产域名、生产密钥、备份和正式告警。 |
新手常犯的错是测试环境和生产环境混用模型密钥、数据库或向量数据库。这样会导致测试数据污染生产数据，或者生产问题被误判为测试问题。
第 2 步：定义服务清单
列出要部署的服务，而不是只说“部署项目”。
| 服务 | 是否必须独立记录版本 | 原因 |
|---|---|---|
| frontend（前端工作台） | 是 | 页面和接口契约可能变化。 |
| api（后端 API 服务） | 是 | 连接模型、数据库、工单和权限。 |
| worker（后台任务） | 是 | 处理知识库索引和批量任务。 |
| nginx（反向代理入口） | 是 | 影响所有用户访问。 |
| database（业务数据库） | 记录迁移版本 | 数据结构变化影响回滚。 |
| vector_database（向量数据库） | 记录索引版本 | 知识库检索效果依赖索引版本。 |
服务清单确定后，才能设计 service_name（服务名称）、image_version（镜像版本）和 health_status（健康状态）。
第 3 步：制作镜像版本策略
镜像版本要能回答“当前跑的是什么”。不要只依赖一个模糊的默认标签。每次上线至少要知道：
- 哪个服务被更新。
- 使用哪个 image_version（镜像版本）。
- 这个版本来自哪次构建或发布。
- 上一个稳定 rollback_version（回滚版本）是什么。
- 该版本是否需要数据库或向量索引迁移。
版本策略不是为了好看，而是为了回滚。没有明确版本，就无法稳定退回。
第 4 步：设计环境配置和密钥引用
把配置分成普通配置和敏感配置。
| 类型 | 例子 | 管理方式 |
|---|---|---|
| 普通配置 | APP_MODE（应用模式）、MODEL_PROVIDER（模型供应商）、LOG_LEVEL（日志级别）、PUBLIC_URL（公开地址） | 放入 env_profile（环境配置），可审计、可回滚。 |
| 敏感配置 | 模型 API Key（接口密钥）、数据库密码、第三方工单系统凭证 | 只记录 secret_ref（密钥引用），不在文档、镜像和日志中出现真实值。 |
| 环境相关配置 | 数据库地址、向量数据库地址、允许访问的域名 | 按 environment（环境）隔离。 |
同一个镜像可以部署到不同环境，但不能把不同环境的密钥混在一起。
第 5 步：准备数据库和向量数据库
上线前要明确两类数据：
- 业务数据库：用户、会话、工单、权限、部署记录、审计日志。
- 向量数据库：知识库分块、Embedding（嵌入向量）、索引元数据、来源引用。
每次升级前至少检查：
- migration_status（迁移状态）是否为 not_required（不需要）或 completed（已完成）。
- backup_status（备份状态）是否为 completed（已完成）。
- 如果迁移失败，旧版本是否还能继续使用。
- 如果向量索引要重建，旧索引是否保留到新索引验证完成。
向量数据库常被新手当成“可以重新生成的缓存”。这只说对了一半。小项目可以重建，但客户知识库大、Embedding（嵌入向量）成本高、索引时间长时，向量数据库就是关键资产，也要备份和版本管理。
第 6 步：拆分 API（应用程序接口）和 worker（后台任务）
客服对话请求应该尽量保持在线响应；文档处理、批量索引、报表生成和通知重试可以交给 worker（后台任务）。
部署时要检查：
- worker（后台任务）是否和 API 使用相同 env_profile（环境配置）或明确差异。
- worker（后台任务）是否能访问数据库、向量数据库和文件存储。
- 队列积压是否可见。
- 失败任务是否有重试上限和人工处理方式。
- worker（后台任务）异常是否会影响在线客服对话。
一个常见事故是：文档批量索引占满资源，导致客服对话也变慢。拆分 worker（后台任务）就是为了避免长任务和在线请求互相拖累。
第 7 步：设计 Nginx（反向代理服务器）入口
Nginx（反向代理服务器）要处理的不只是转发。
| 能力 | 客服工作台中的验收 |
|---|---|
| 域名入口 | 用户通过 public_url（公开地址）访问，不直接访问内部端口。 |
| TLS（传输层安全协议） | 浏览器显示安全连接，证书域名匹配且未过期。 |
| 路径路由 | 前端页面、API、文件上传下载路径不冲突。 |
| 上传限制 | 知识库文件上传有明确大小限制和错误提示。 |
| 超时控制 | Agent 长回答、流式响应或批量任务不会被入口层误断。 |
| 访问日志 | 能看到请求状态、耗时和错误，但不泄露密钥和敏感内容。 |
AI Agent 系统尤其要关注超时。模型回答、RAG 检索、工具调用和外部接口都可能比普通网页请求更慢。入口层太激进，会让后端还在工作，前端已经失败。
第 8 步：设计健康检查
健康检查至少分 3 层：
| 层级 | 检查什么 | 失败后怎么处理 |
|---|---|---|
| 进程健康 | 服务是否启动、端口是否可访问 | 自动重启或标记失败。 |
| 依赖健康 | 数据库、向量数据库、模型配置、队列是否可用 | 标记 degraded（降级）或 failed（失败）。 |
| 业务健康 | 是否能完成一次最小客服链路 | 阻止上线或触发回滚。 |
最小客服链路可以是：打开工作台、调用后端、读取一条知识库、生成一次 Mock（模拟）回答或真实模型回答、创建一条测试工单。不同环境可以使用不同深度的检查，但生产上线不能只看进程是否存活。
第 9 步：把日志和 trace_id（追踪编号）接进部署流程
每次部署都应该产生 trace_id（追踪编号）或类似的追踪标识。它要能串联：
- 部署事件。
- 服务启动日志。
- 健康检查日志。
- Nginx（反向代理服务器）访问日志。
- API 错误日志。
- Agent 模型调用日志。
- worker（后台任务）日志。
这样当上线后客服反馈“知识库问答变慢”，你可以查到是新版本引入、向量数据库异常、Nginx（反向代理服务器）超时，还是模型供应商延迟。
第 10 步：制定上线检查和回滚条件
上线前就要写清楚什么时候继续、什么时候暂停、什么时候回滚。
| 条件 | 处理 |
|---|---|
| 备份失败 | 不允许生产上线。 |
| 数据库迁移失败 | 不允许继续切换流量。 |
| 核心健康检查失败 | 不标记上线成功。 |
| 非核心依赖异常 | 可降级，但要告警和记录。 |
| 创建工单失败 | 生产上线应暂停或回滚。 |
| RAG 不可用 | 视业务要求降级到人工或回滚。 |
| 错误率明显升高 | 进入观察、修复或回滚。 |
回滚不是失败的耻辱，而是上线流程的一部分。一个能回滚的系统，比一个“只能向前硬修”的系统更可靠。
和后续章节的关系
本章和后续章节的关系非常直接。
| 后续章节 | 和本章的关系 |
|---|---|
| 第 2.12 章可观测性 | 本章预留 trace_id（追踪编号）、日志和 health_status（健康状态），下一章展开日志、Tracing（调用链追踪）、成本、限流和告警。 |
| 安全与权限章节 | 本章先讲密钥、环境变量和部署权限，后续会扩展到用户权限、数据权限和攻击防护。 |
| 多模型适配章节 | 环境变量和 secret_ref（密钥引用）决定模型供应商、模型名称和调用模式如何切换。 |
| RAG 章节 | 向量数据库、索引版本和知识库重建都需要部署层支持。 |
| 测试章节 | 部署验收需要自动化检查和最小业务链路测试。 |
| 作品集项目章节 | 部署记录、上线检查和回滚方案可以直接作为作品集工程亮点。 |
部署不是最后一页附录，而是把前面所有能力放到真实环境里的桥梁。
版本与资料来源
本章不提供完整源码，也不写可复制部署命令，重点讲部署设计、字段契约、上线验收、失败兜底和面试表达。
资料来源以官方文档和稳定工程实践为主：
- Docker（容器工具）官方文档：https://docs.docker.com/
- Docker（容器工具） Compose（多容器应用定义工具）官方文档：https://docs.docker.com/compose/
- Nginx（反向代理服务器）官方文档：https://nginx.org/en/docs/
- PostgreSQL（开源关系型数据库）官方文档：https://www.postgresql.org/docs/
- OpenTelemetry（可观测性标准）官方文档：https://opentelemetry.io/docs/
- Let’s Encrypt（证书签发服务）文档：https://letsencrypt.org/docs/
过时风险：具体部署命令、平台功能、证书申请方式、容器运行时和云厂商能力会变化。进入真实项目交付前，应重新核对客户服务器环境、Docker（容器工具）版本、Nginx（反向代理服务器）版本、数据库版本、向量数据库版本、模型供应商要求和公司安全规范。