第 2.11.1 节：把 Agent 服务打包成可部署的 Docker 镜像
Docker Agent 服务只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够按顺序说明 Docker Agent 服务的触发、处理、复核、记录和兜底步骤。
本章要解决什么问题
很多新手第一次做 AI Agent（人工智能体）项目时，会把“部署”理解成一件很窄的事：把服务放到服务器上，页面能打开，截图发给客户或面试官。这种理解只适合演示，不适合交付。
企业客服知识库与工单 Agent 工作台上线后，用户不是只点一次页面。客服团队会每天使用它处理咨询、查知识库、创建工单、查看历史会话、转人工、做质检复盘。系统也不只依赖一个模型接口，它还依赖前端、后端、数据库、向量数据库、后台任务、模型供应商、文件存储、日志、密钥、域名和证书。只要其中一个环节没有部署边界，系统就会从“能跑”变成“不可维护”。
本章要解决的问题是：如何把客服 Agent 工作台部署成可配置、可恢复、可观测、可回滚的工程系统。
本章以制作方法和验收标准为主线，带你建立可配置、可恢复、可观测的部署方案：
- Docker（容器工具）负责什么，不负责什么。
- Nginx（反向代理服务器）为什么是用户入口，不只是“转发一下”。
- environment variables（环境变量）和 secret（密钥）怎样分层管理。
- health check（健康检查）怎样判断服务真的可用。
- reverse proxy（反向代理）、TLS（传输层安全协议）和公开地址如何影响上线。
- database（数据库）和 vector database（向量数据库）如何迁移、备份和恢复。
- worker（后台任务）为什么要和 API（应用程序接口）服务分开看。
- backup（备份）和 rollback（回滚）如何写进上线流程，而不是出事后再想。
- 面试或作品集里如何证明部署不是“我跑起来了”，而是“我能交付和维护”。
一句话概括：部署的目标不是截图成功，而是让系统在真实使用、故障、升级和回滚中仍然可控。
学习目标
读完本章后，你应该能够：
- 解释本地运行、测试部署和生产部署的差异。
- 说清 Docker（容器工具）、Nginx（反向代理服务器）、环境变量、密钥、健康检查、TLS（传输层安全协议）在部署中的位置。
- 为客服 Agent 工作台拆分前端、后端、worker（后台任务）、数据库、向量数据库、反向代理和日志模块。
- 设计部署字段契约，记录 deployment_id（部署编号）、environment（环境）、service_name（服务名称）、image_version（镜像版本）、env_profile（环境配置）、secret_ref（密钥引用）、health_status（健康状态）、public_url（公开地址）、internal_url（内部地址）、rollback_version（回滚版本）、backup_status（备份状态）、migration_status（迁移状态）和 trace_id（追踪编号）。
- 判断一次上线前是否具备备份、迁移、健康检查、日志、告警和回滚条件。
- 说明哪些场景不适合直接用简单 Docker（容器工具） + Nginx（反向代理服务器）方式交付。
- 把部署能力转化成面试表达和作品集交付物。
贯穿业务场景
本章继续使用“企业客服知识库与工单 Agent 工作台”作为贯穿项目。
这个工作台至少包含 6 类用户动作：
| 用户动作 | 涉及部署能力 | 为什么部署层要关心 |
|---|---|---|
| 客服打开工作台查看会话 | 前端、Nginx（反向代理服务器）、TLS（传输层安全协议） | 页面必须稳定可访问，不能暴露内部端口。 |
| 用户提问后得到 Agent 回答 | 后端 API、模型密钥、日志 | 模型配置和密钥必须可切换、可保护、可追踪。 |
| Agent 检索企业知识库 | 向量数据库、文件存储、索引版本 | 检索服务不可用时，系统要能降级或转人工。 |
| Agent 创建工单 | 业务数据库、权限、幂等、审计日志 | 写入动作必须能追踪，失败不能假装成功。 |
| 后台重新索引知识库文档 | worker（后台任务）、任务队列、资源限制 | 长任务不应该拖垮用户请求。 |
| 管理员上线新版本 | 镜像版本、环境配置、迁移、备份、回滚 | 新版本失败时要能恢复到上一个稳定版本。 |
部署层的价值在这里就很清楚了：它不是业务功能本身，却决定业务功能能不能被稳定使用。
假设你给客户交付了一个客服 Agent 工作台。第一天演示正常，第二天客户上传了大量知识库文档，第三天模型供应商密钥过期，第四天数据库迁移失败，第五天 Nginx（反向代理服务器）超时导致长回答中断。如果你的部署方案只能回答“我本地能跑”，那就不是可交付项目。
本章要训练的是另一种思路：每个服务都要知道它的配置来源、健康状态、日志位置、故障兜底和回滚版本。
新手为什么会卡住
部署章节看起来比工具调用、RAG（检索增强生成）和 LangGraph（智能体状态图框架）更“运维”，但新手真正卡住的地方不是命令，而是边界意识。
| 常见误解 | 问题在哪里 | 正确理解 |
|---|---|---|
| 部署就是把服务跑起来 | 只能证明短时间可访问，不能证明可维护 | 部署要证明服务可配置、可恢复、可观测、可回滚。 |
| Docker（容器工具）能解决所有环境问题 | 它解决运行环境一致性，不解决密钥、备份、迁移和业务兜底 | Docker（容器工具）是封装手段，不是交付方案的全部。 |
| Nginx（反向代理服务器）只是转发流量 | 忽略了 TLS（传输层安全协议）、超时、上传大小、路径路由和错误页 | Nginx（反向代理服务器）是外部访问入口和边界控制层。 |
| 环境变量随便写在服务器上 | 不知道谁改过、哪些环境生效、密钥是否泄露 | 环境配置要分环境、分权限、可审计、可回滚。 |
| 健康检查只要页面能打开 | 页面打开不代表模型、数据库、向量数据库和 worker（后台任务）可用 | 健康检查要覆盖关键依赖和业务链路。 |
| 升级失败再手动修 | 生产问题发生时，临时操作风险很高 | 上线前就要准备备份、迁移状态和回滚版本。 |
| 日志等出错再加 | 没有日志就无法定位错误 | 部署时就要定义 trace_id（追踪编号）、服务日志和部署事件。 |
所以本章不会教你背“某条部署命令”。面试官和客户真正关心的是：系统坏了你怎么知道，数据错了你怎么恢复，新版本有问题你怎么退回。