---
name: docker-deployment
when: 'Docker部署, 容器部署, Dockerfile, docker-compose, 镜像构建, 容器化, 部署发布'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-pattern-docker-deployment
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - Docker部署
  - 容器部署
  - Dockerfile
  - docker-compose
  - 镜像构建
  - 容器化
  - 部署发布
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 每次部署必须从源码全新构建镜像，禁止 docker commit、容器内文件编辑、docker exec 安装依赖
- Bug 修复后必须重新构建镜像并重新部署后再验证，禁止在旧容器中验证修复
- 前端禁止复制预构建的 dist/ 目录，必须在 Dockerfile 内完成构建
- docker compose up 必须能一键启动所有服务并通过健康检查
- 若浏览器验证发现容器未运行当前代码，必须自动重建并重新部署
- Dockerfile 必须使用多阶段构建（build → runtime），禁止在最终镜像中包含构建工具和源码
- 容器必须配置 HEALTHCHECK 指令，编排工具（K8s/Docker Compose）依赖健康检查做流量管理
- 容器必须设置资源限制（memory limit、CPU limit），防止单个容器耗尽主机资源
- 镜像版本禁止使用 :latest 标签部署，必须指定明确版本号（如 :1.2.3）
- 敏感配置（密码、密钥）禁止写入 Dockerfile 或镜像，必须通过环境变量或 Secret 注入
- 容器必须以非 root 用户运行（USER app），禁止默认 root 运行

## 验收项
- [AC-01] 镜像从源码全新构建
- [AC-02] 无 docker commit 或热补丁
- [AC-03] docker compose 一键启动通过健康检查
- [AC-04] 修复后重建镜像再验证
- [AC-05] 多阶段构建
- [AC-06] 有 HEALTHCHECK 配置
- [AC-07] 镜像指定版本号（非 latest）
- [AC-08] 敏感配置通过环境变量/Secret 注入
- [AC-09] 非 root 用户运行
