Docker 用于将应用打包为隔离容器，使其在不同环境中保持一致运行。Dockerfile 定义镜像构建步骤，Compose 编排多容器服务，生产模式则帮助构建更小、更安全、性能更好的镜像。
适用场景
- 将应用容器化
- 创建可复现的开发环境
- 编排多服务栈
- 部署到容器平台，例如 ECS、Kubernetes、Fly.io、Railway、Coolify
不适用场景
- 没有后端的纯静态站点（应使用 CDN 部署）
- 单二进制 CLI 工具（直接分发二进制文件）
- 目标平台提供原生 buildpack（如 Heroku、Vercel），且你不需要容器控制能力
速查表
- 多阶段构建：将构建阶段与生产阶段分离。要点：镜像体积缩减 80% 以上，生产环境不含开发依赖。
- 层缓存：先复制 lockfile，安装依赖，再复制源码。要点：依赖层可跨多次构建复用缓存。
- 非 root 用户：在最终阶段执行 RUN adduser 并使用 USER 指令。要点：生产容器绝不以 root 运行。
- 健康检查：使用 HEALTHCHECK CMD 执行 curl 或 node/python 检查。要点：使编排器能在失败时重启容器。
- .dockerignore：排除 node_modules、.git、.env。要点：缩小构建上下文，加快构建。
- Compose 服务：用 compose.yaml 定义服务。要点：一条命令启动开发环境。
- Compose override：使用 compose.prod.yaml 存放生产配置。要点：无需重复即可实现环境特定配置。
- 命名卷：在 Compose 中通过 volumes 持久化数据。要点：容器重建后数据仍保留。
- 构建缓存挂载：RUN --mount=type=cache,target=/root/.npm。要点：跨构建保留缓存。
- 构建机密：RUN --mount=type=secret,id=token。要点：绝不把机密固化进镜像层。
- 镜像固定：固定到 major.minor 或 digest。要点：构建可复现，避免意外破坏。
- 容器网络：使用自定义 bridge 网络并启用服务发现。要点：容器可通过服务名互相解析。
- Compose watch：develop.watch 配合 sync/rebuild 动作。要点：无需卷挂载即可实现实时重载。
- Init 进程：使用 --init 标志或 tini 入口。要点：正确处理信号并回收僵尸进程。
- 多平台：docker buildx build --platform。要点：一个镜像同时支持 ARM（Apple Silicon、Graviton）与 x86。
- Monorepo 裁剪：turbo prune app --docker。要点：从工作区依赖生成最小构建上下文。
- CI 层缓存：配合 GHA 或镜像仓库使用 cache-from/cache-to。要点：避免 CI 流水线全量重建。
- 调试容器：docker exec、docker logs、dive。要点：检查运行中的容器与镜像层。
常见错误与正确做法
- 在生产镜像中安装开发依赖 → 多阶段构建：在构建阶段安装，把产物复制到运行时。
- 安装依赖前就复制源码 → 先复制 lockfile，执行 npm ci，再复制源码以复用缓存。
- 生产环境以 root 运行 → 创建非 root 用户，在最终阶段使用 USER 指令。
- 在 Dockerfile 或 ENV 中硬编码机密 → 使用构建机密（--mount=type=secret）或运行时环境变量。
- 基础镜像使用 latest 标签 → 固定到具体版本（如 node:24-alpine）。
- 没有 .dockerignore 文件 → 排除 node_modules、.git、.env、构建产物。
- 使用 npm install 而非 npm ci → 用 npm ci 实现基于 lockfile 的确定性安装。
- 缺少 HEALTHCHECK → 添加健康检查以配合编排器集成。
- 基础镜像过大（node:24）→ 使用 alpine 变体（node:24-alpine）缩小镜像。
- 忽视 Compose 中 .env 文件的优先级 → Compose 中的 environment: 会覆盖 .env 文件的值。
- 为单个服务构建整个 monorepo → 使用 turbo prune --docker 生成最小构建上下文。
- CI 中无层缓存 → 使用 cache-from/cache-to 配合 GHA 或镜像仓库后端。
- 部署到 ARM 却只构建 x86 → 使用 docker buildx 配合 --platform linux/amd64,linux/arm64。
委派
- Dockerfile 审查：使用 Task 代理审计 Dockerfile 的体积、安全性与缓存。
- Compose 探查：使用 Explore 代理发现现有 Docker 配置。
- 架构决策：使用 Plan 代理制定容器编排策略。
- 如果 ci-cd-architecture 技能可用，将 CI/CD 流水线与部署策略委派给它。
- 如果 application-security 技能可用，将容器安全扫描与加固审查委派给它。
参考主题
- Dockerfile 模式：多阶段构建、层缓存与镜像优化
- Compose：服务、网络、卷与环境管理
- 安全：非 root 用户、机密、扫描与生产加固
- Buildx：面向 ARM 与 x86 的多平台构建
- CI：GitHub Actions 缓存、镜像仓库推送与自动化构建
- Monorepo：Turborepo prune、pnpm workspaces 与选择性构建
- 调试：日志、exec、inspect、层分析与网络排障