AI Agent Engineering · Week 11
11-02|Docker、Environment、Deployment 与 CI/CD
用可重复镜像、分离环境和受保护流水线,把同一版本从本地送到 Staging 与 Production。
“在我电脑上能跑”缺少可复现条件
本地机器拥有特定 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
Image 是只读构建产物,Container 是 Image 的运行实例。多阶段构建可以把编译工具留在 Build Stage,只把生产所需文件放入 Runtime Stage。API Key 不应通过 ARG、普通 ENV 或复制文件进入镜像层;构建期 Secret 使用受控 secret mount,运行期 Secret 由部署平台注入。
一条最小 CI/CD 路径
TypeScript · Lint · Unit · Eval · Security
固定依赖,生成不可变 Image
依赖 / Secret / Image 基础检查
部署、迁移、Health、Smoke
报告、风险和版本签字
渐进流量、监控、可回滚
参考路径可以采用 GitHub Repository → GitHub Actions → Container Registry → 支持容器的云平台/VM。Staging 与 Production 使用独立数据库、凭据和域名。云账号、付费实例、DNS、TLS、外部模型 Key 和真实 Shopify/ERP 授权都属于前置条件;没有这些条件时,使用 Docker Compose + Mock 业务 API 完成等价本地演示。
环境差异应该在哪里
公开端点、Feature Flag、Log Level、限额
Model Key、DB credential、Webhook secret;独立存储与轮换
Local fake / Staging synthetic / Production authorized
Tool allowlist、审批阈值、租户与地区规则
commit SHA、image digest、migration、report、deploy ID
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 替代路径。
- ☐ 流水线保存可回滚的上一版本标识。
主动回忆
- Image 和 Container 分别是什么?
- 为什么最好在 Staging 与 Production 使用同一个 Image digest?
- Build Secret 与 Runtime Secret 的暴露边界有何不同?
- Docker build 成功以后还缺哪些生产证据?
下一课执行参考部署,验证 Health、监控、回滚和上线验收。
延伸阅读 / Sources
核查日期:2026-10-18。
- Docker Docs:Multi-stage builds。用于核对构建阶段与运行阶段分离。
- Docker Docs:Build secrets。用于核对构建参数、环境变量与 secret mount 的边界。
- GitHub Docs:Deployment environments。用于核对环境保护规则、审批和环境级 Secrets。
长期有效的原理: 构建产物应可复现、不可变,并与环境配置和 Secret 分离。当前实现方式: CI/CD 与容器平台可以替换,版本证据和发布门禁应保持一致。