第 2.11.2 节：用 Nginx、环境变量和密钥管理守住部署入口
Nginx 入口、环境变量与密钥只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够按顺序说明 Nginx 入口、环境变量与密钥的触发、处理、复核、记录和兜底步骤。
核心概念四层解释法
这一节用四层解释法把部署概念讲清楚：先说人话，再放到客服工作台的位置，然后说明工程动作，最后给出面试说法。
Docker（容器工具）
| 层级 | 解释 |
|---|---|
| 人话解释 | Docker（容器工具）把应用和它需要的运行环境打包在一起，减少“我电脑能跑，服务器不能跑”的问题。 |
| 项目位置 | 在客服 Agent（智能体）工作台里，前端构建产物、后端 API（应用程序接口）、worker（后台任务）都可以分别做成镜像，通过镜像版本追踪上线内容。 |
| 工程动作 | 明确每个服务的镜像版本、启动入口、运行用户、端口、健康检查、资源限制和日志输出。 |
| 面试说法 | Docker（容器工具）不是为了炫技术，而是为了让部署产物可复制、可标记、可回滚。上线时我会记录 image_version（镜像版本）和 rollback_version（回滚版本）。 |
Docker（容器工具）不应该承载所有状态。业务数据库、向量数据库数据、上传文件、备份文件和密钥不能被当成随容器销毁的临时内容。容器可以换，业务状态不能随便丢。
Nginx（反向代理服务器）与 reverse proxy（反向代理）
| 层级 | 解释 |
|---|---|
| 人话解释 | Nginx（反向代理服务器）像一个门卫。用户只访问一个公开入口，门卫再把不同请求转给前端、后端或文件服务。 |
| 项目位置 | 客服工作台的 public_url（公开地址）进入 Nginx（反向代理服务器），再转发到内部前端、API 和上传下载服务。 |
| 工程动作 | 设计域名、TLS（传输层安全协议）、路径路由、请求大小、超时、错误页、内部服务地址和访问日志。 |
| 面试说法 | 我不会把后端服务端口直接暴露给公网，而是通过 Nginx（反向代理服务器）统一入口，处理 TLS（传输层安全协议）、路由、限流和超时。 |
AI Agent 服务和普通网页不同：它可能有长回答、文件上传、知识库导入和流式输出。如果 Nginx（反向代理服务器）的超时太短，模型还在生成，用户连接已经断了；如果上传大小太小，客户知识库文件无法导入；如果路径路由混乱，前端看似正常，API 却跨域失败。
environment variables（环境变量）与 secret（密钥）
| 层级 | 解释 |
|---|---|
| 人话解释 | 环境变量是不同环境下可替换的配置；secret（密钥）是必须保护的敏感配置。 |
| 项目位置 | 客服工作台用环境变量区分本地、测试、生产，用密钥保存模型供应商 API Key（接口密钥）、数据库密码和第三方系统凭证。 |
| 工程动作 | 为每个环境定义 env_profile（环境配置），把普通配置和 secret_ref（密钥引用）分开，禁止在日志和文档里暴露真实密钥。 |
| 面试说法 | 我会把配置外置，把密钥引用化，保证同一个镜像可以部署到不同环境，同时避免密钥进入代码仓库、镜像和日志。 |
环境变量不是一个随手填写的清单，而是部署契约的一部分。生产环境和测试环境可以使用同一个 image_version（镜像版本），但它们必须有不同的 environment（环境）、env_profile（环境配置）、secret_ref（密钥引用）、public_url（公开地址）和数据库连接。
health check（健康检查）
| 层级 | 解释 |
|---|---|
| 人话解释 | 健康检查是系统自己回答“我现在能不能提供服务”。 |
| 项目位置 | 客服工作台不仅要检查 API 服务是否活着，还要检查数据库、向量数据库、模型配置、worker（后台任务）和关键队列是否可用。 |
| 工程动作 | 设计 health_status（健康状态）、检查范围、检查频率、失败阈值、展示位置和告警规则。 |
| 面试说法 | 我不会只用页面能打开判断上线成功。健康检查要覆盖核心依赖，并把状态写入部署记录和告警。 |
健康检查要分层。浅层检查回答“进程是否存活”；深层检查回答“关键依赖是否可用”；业务检查回答“客服 Agent 是否能完成一次最小链路”。三者不能混为一谈。
database（数据库）与 vector database（向量数据库）
| 层级 | 解释 |
|---|---|
| 人话解释 | 数据库保存业务状态，向量数据库保存知识库检索索引。它们都是部署里最不能随便丢的部分。 |
| 项目位置 | 客服工作台的用户、会话、工单、权限、部署记录通常在业务数据库里；知识库分块和 Embedding（嵌入向量）索引通常在向量数据库里。 |
| 工程动作 | 管理连接配置、迁移状态、备份状态、恢复演练、索引版本和数据权限。 |
| 面试说法 | 我会把应用容器和持久化数据分开管理，上线前检查 migration_status（迁移状态）和 backup_status（备份状态），避免升级时破坏业务数据。 |
数据库迁移是部署中最容易被低估的环节。应用回滚不一定等于数据库能回滚。如果新版本迁移已经改变了表结构或索引结构，简单切回旧镜像可能仍然失败。因此上线前要明确迁移是否可逆、是否做过备份、是否有恢复路径。
worker（后台任务）
| 层级 | 解释 |
|---|---|
| 人话解释 | worker（后台任务）负责处理不适合在用户请求里等待的工作，例如文档解析、知识库重建、批量同步和通知发送。 |
| 项目位置 | 客服工作台上传知识库后，不应该让用户页面一直等到所有文档索引完成，而应该交给 worker（后台任务）异步处理。 |
| 工程动作 | 为 worker（后台任务）设计队列、重试、任务状态、资源限制、死信处理、日志和健康检查。 |
| 面试说法 | 我会把在线 API 和长耗时后台任务分开部署，避免知识库索引拖垮客服对话。 |
AI Agent 项目里，后台任务非常常见。文档转文本、切分、Embedding（嵌入向量）、重排索引、批量质检、生成报表，都不应该挤在用户请求链路里。
backup（备份）与 rollback（回滚）
| 层级 | 解释 |
|---|---|
| 人话解释 | backup（备份）是出事后能恢复数据；rollback（回滚）是新版本有问题时能退回稳定版本。 |
| 项目位置 | 客服工作台升级前要备份业务数据库、关键配置和知识库索引，部署记录里要保存 rollback_version（回滚版本）。 |
| 工程动作 | 定义备份范围、备份频率、恢复演练、回滚触发条件、回滚负责人和回滚验收清单。 |
| 面试说法 | 我会在上线前确认备份可用、迁移状态明确、旧版本镜像可部署，并把回滚作为上线流程的一部分，而不是事故后的临时动作。 |
备份如果从来没有恢复演练，只能叫“心理安慰”。回滚如果没有写明版本、配置、迁移边界和验收方式，也不能算真正可用。
本章在客服 Agent（智能体）工作台中的位置
客服 Agent 工作台可以分成 8 层：
| 层级 | 作用 | 本章关注点 |
|---|---|---|
| 用户入口层 | 客服、管理员和客户访问系统 | public_url（公开地址）、TLS（传输层安全协议）、Nginx（反向代理服务器）。 |
| 前端工作台层 | 会话、知识库、工单和管理页面 | 静态资源、版本发布、缓存和错误页。 |
| API 层 | 提供会话、工单、知识库和配置接口 | 镜像版本、健康检查、内部地址、日志。 |
| Agent 运行层 | 调模型、调工具、组织回答 | 模型环境变量、密钥引用、超时、Trace ID（追踪编号）。 |
| worker（后台任务）层 | 处理知识库索引、批量任务和通知 | 队列、重试、任务日志、资源隔离。 |
| 数据层 | 业务数据库、向量数据库、文件存储 | 迁移、备份、恢复、容量和权限。 |
| 可观测层 | 日志、Tracing（调用链追踪）、告警、成本 | trace_id（追踪编号）、health_status（健康状态）、部署事件。 |
| 运维治理层 | 上线、回滚、密钥轮换、权限审计 | deployment_id（部署编号）、rollback_version（回滚版本）、上线检查。 |
本章位于“功能开发完成”和“系统上线运营”之间。前面章节让工作台会回答、会检索、会调用工具；本章让这些能力在服务器上长期稳定运行。下一章可观测性会继续展开日志、Tracing（调用链追踪）、成本、限流和告警，本章则先把部署时必须预留的入口讲清楚。
系统流程图
这张图要表达三件事：
读图重点：先读运行层：公网请求只到 Nginx，内部 API、Agent、RAG、队列、Worker 和数据服务各守边界；再读治理层：deployment_id 把可部署产物与所有恢复条件固定下来。
- 用户只应该看到 public_url（公开地址），内部服务通过 internal_url（内部地址）互相访问。
- Agent 回答链路会经过模型、RAG（检索增强生成）、向量数据库、业务数据库和 worker（后台任务），部署检查必须覆盖这些依赖。
- 每次上线都要形成 deployment_id（部署编号），把镜像、环境配置、密钥引用、健康状态、备份、迁移和回滚串起来。
模块拆分
部署前必须先拆模块。模块拆不清，后面环境变量、健康检查、日志和回滚都会混在一起。
| 模块 | 主要职责 | 部署关注点 |
|---|---|---|
| 前端工作台 | 展示会话、知识库、工单和管理页面 | 静态资源版本、public_url（公开地址）、缓存策略、错误页。 |
| 后端 API | 提供登录、会话、工单、知识库和配置接口 | internal_url（内部地址）、健康检查、模型配置、数据库连接。 |
| Agent 运行层 | 编排模型、RAG、工具调用和回答生成 | 模型供应商、超时、密钥引用、trace_id（追踪编号）。 |
| worker（后台任务） | 文档解析、Embedding（嵌入向量）、索引重建、批量任务 | 队列、重试、资源限制、任务状态、死信兜底。 |
| 业务数据库 | 用户、权限、会话、工单、部署记录 | 迁移、备份、连接池、恢复演练、权限隔离。 |
| 向量数据库 | 知识库分块向量、索引、检索元数据 | 索引版本、容量、备份、重建策略、检索健康检查。 |
| 文件存储 | 上传文档、附件、导出文件 | 存储路径、访问权限、备份、病毒或格式检查。 |
| Nginx（反向代理服务器） | 统一入口、TLS（传输层安全协议）、路由、超时 | 公开域名、证书、上传大小、长请求、访问日志。 |
| 日志与监控 | 请求日志、部署日志、错误日志、成本和告警 | trace_id（追踪编号）、日志脱敏、告警阈值、保留周期。 |
| 部署控制 | 上线记录、回滚、备份、迁移状态 | deployment_id（部署编号）、image_version（镜像版本）、rollback_version（回滚版本）。 |
最小可交付版本不一定要上复杂平台，但这些模块的责任要先分清。哪怕所有服务都部署在一台服务器上，你也应该知道哪些是无状态应用，哪些是持久化数据，哪些是公开入口，哪些只能内部访问。