跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 11

11-02|Docker、Environment、Deployment 与 CI/CD

用可重复镜像、分离环境和受保护流水线,把同一版本从本地送到 Staging 与 Production。

Docker · CI/CD · Environment · Deployment

“在我电脑上能跑”缺少可复现条件

本地机器拥有特定 Node/Python 版本、缓存文件、环境变量和手工启动顺序。另一台机器出现差异时,团队很难判断是代码、依赖还是环境问题。Docker 把应用和运行依赖打包成可重复 Image;部署仍要另外处理配置、Secrets、数据、网络、健康检查和流量。

Image、Container 与 Environment

Source + Lockfile + Dockerfile
↓ build once
Immutable Image:support-agent@sha256…
↓ run with environment-specific config
Local / Staging / Production Containers
↓
External Database · Secret Store · Model / Business APIs

图 1|同一 Image 跨环境运行;配置和 Secret 在运行时注入,持久数据位于容器之外。

Image 是只读构建产物,Container 是 Image 的运行实例。多阶段构建可以把编译工具留在 Build Stage,只把生产所需文件放入 Runtime Stage。API Key 不应通过 ARG、普通 ENV 或复制文件进入镜像层;构建期 Secret 使用受控 secret mount,运行期 Secret 由部署平台注入。

一条最小 CI/CD 路径

1 Verify

TypeScript · Lint · Unit · Eval · Security

2 Build

固定依赖,生成不可变 Image

3 Inspect

依赖 / Secret / Image 基础检查

4 Staging

部署、迁移、Health、Smoke

5 Approval

报告、风险和版本签字

6 Production

渐进流量、监控、可回滚

图 2|CI 证明候选构建满足门禁;CD 把同一产物安全推进到目标环境。

参考路径可以采用 GitHub Repository → GitHub Actions → Container Registry → 支持容器的云平台/VM。Staging 与 Production 使用独立数据库、凭据和域名。云账号、付费实例、DNS、TLS、外部模型 Key 和真实 Shopify/ERP 授权都属于前置条件;没有这些条件时,使用 Docker Compose + Mock 业务 API 完成等价本地演示。

环境差异应该在哪里

Config
公开端点、Feature Flag、Log Level、限额
Secrets
Model Key、DB credential、Webhook secret;独立存储与轮换
Data
Local fake / Staging synthetic / Production authorized
Policy
Tool allowlist、审批阈值、租户与地区规则
Evidence
commit SHA、image digest、migration、report、deploy ID
图 3|环境差异显式配置;不能靠手改容器或在代码中切换生产分支。

Failure Lab

Docker build 成功就宣布可上线

为什么诱人: Image 已经可启动,交付物看起来完整。

为什么失败: 构建没有证明数据库持久化、授权、迁移、健康检查、告警和回滚有效。

更合理设计: 把 Image 作为候选产物,继续通过 Staging Smoke、Eval、安全门禁与生产验收。

把 .env 复制进 Image

为什么诱人: 容器启动时不再缺少配置。

为什么失败: Secret 会进入镜像层、缓存、Registry 和拥有镜像权限的环境。

更合理设计: 提交 .env.example 记录变量名;真实值由本地安全存储或部署平台运行时注入。

每个环境重新 Build

为什么诱人: 可以直接烘焙不同 API 地址和开关。

为什么失败: Staging 验证的产物与 Production 不同,难以证明版本一致。

更合理设计: Build once,按 digest 提升同一 Image,环境差异走外部 Config 和 Secret。

实践:设计 Reference Deployment Pipeline

写出触发条件、验证命令、Image 标识、Staging 门禁、Production Approval、Secret 来源、数据库迁移、Smoke Test、监控窗口和 Rollback Target。另写一条完全本地的 Docker Compose 路径。

Acceptance Criteria

  • ☐ Image 可由干净环境重复构建,并绑定 commit SHA 与 digest。
  • ☐ Build Stage 与 Runtime Stage 分离,生产镜像不含开发工具。
  • ☐ Secret 不进入代码、构建参数、镜像层、日志或测试报告。
  • ☐ Local、Staging、Production 使用独立配置、凭据和数据。
  • ☐ CI 运行功能、Eval 与 Security 门禁;失败阻止部署。
  • ☐ Staging 通过 Health 与 Smoke 后才允许 Production。
  • ☐ 云端前置条件和付费资源已列明,并提供本地 Mock 替代路径。
  • ☐ 流水线保存可回滚的上一版本标识。

主动回忆

  1. Image 和 Container 分别是什么?
  2. 为什么最好在 Staging 与 Production 使用同一个 Image digest?
  3. Build Secret 与 Runtime Secret 的暴露边界有何不同?
  4. Docker build 成功以后还缺哪些生产证据?

下一课执行参考部署,验证 Health、监控、回滚和上线验收。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 构建产物应可复现、不可变,并与环境配置和 Secret 分离。当前实现方式: CI/CD 与容器平台可以替换,版本证据和发布门禁应保持一致。