docker

Docker

概述

Docker 将应用打包到隔离容器中，使其在不同环境中都能一致运行。Dockerfile 定义镜像构建步骤，Compose 编排多容器服务，而生产环境模式可确保镜像体积小、安全且性能出色。

适用场景： 将应用容器化、创建可复现的开发环境、编排多服务技术栈、部署到容器平台（ECS、Kubernetes、Fly.io、Railway、Coolify）。

不适用场景： 没有后端的简单静态网站（使用 CDN 部署）、单二进制文件的 CLI 工具（分发二进制文件），或目标平台支持原生 buildpack（Heroku、Vercel）且你不需要控制容器时。

快速参考

模式	方法	要点
多阶段构建	分离 builder 和 production 阶段	镜像体积减少 80% 以上，生产环境不包含开发依赖
层缓存	先复制锁文件、安装依赖，再复制源代码	依赖层可在多次构建间缓存
非 root 用户	在最终阶段使用 RUN adduser + USER	生产容器绝不能以 root 身份运行
健康检查	使用 HEALTHCHECK CMD curl 或 node/python 检查	失败时可触发编排器重启
.dockerignore	排除 node_modules、.git、.env	缩小构建上下文，加快构建
Compose 服务	使用包含服务定义的 compose.yaml	一条命令即可启动开发环境
Compose 覆盖配置	使用包含生产环境设置的 compose.prod.yaml	无需重复配置即可实现环境专属设置
命名卷	在 Compose 中使用 volumes: 保存持久化数据	容器重建后数据仍会保留
构建缓存挂载	使用 RUN --mount=type=cache,target=/root/.npm	在多次构建间持久保留缓存
构建过程中的密钥	使用 RUN --mount=type=secret,id=token	绝不将密钥烘焙到镜像层中
固定镜像版本	固定到主版本号、次版本号或摘要	确保构建可复现，避免意外故障
容器网络	使用支持服务发现的自定义桥接网络	容器可通过服务名称相互解析
Compose 监视	使用 develop.watch 配置同步/重建操作	无需挂载卷即可实时重新加载
初始化进程	使用 --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	检查运行中的容器和镜像层

常见错误

错误	正确做法
在生产镜像中安装开发依赖	多阶段构建：在构建阶段安装，将产物复制到运行阶段
安装依赖前复制源代码	先复制锁文件，运行 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 进行确定性、基于锁文件的安装
缺少 HEALTHCHECK	添加健康检查以集成编排工具
基础镜像体积过大（node:24）	使用 Alpine 变体（node:24-alpine）以缩小镜像体积
忽略 Compose 中 .env 文件的优先级	Compose 中的 environment: 会覆盖 .env 文件中的值
为一个服务构建整个单体仓库	使用 turbo prune --docker 以创建精简的构建上下文
CI 中没有层缓存	使用 GHA 或注册表后端的 cache-from/cache-to
部署到 ARM 时只为 x86 构建	使用 docker buildx 和 --platform linux/amd64,linux/arm64

委派

• Dockerfile 审查：使用 Task Agent 审查 Dockerfile 的镜像体积、安全性和缓存
• Compose 配置探索：使用 Explore Agent 查找现有 Docker 配置
• 架构决策：使用 Plan Agent 制定容器编排策略

如果有 ci-cd-architecture 技能，请将 CI/CD 流水线和部署策略委派给它。 如果有 application-security 技能，请将容器安全扫描和加固审查委派给它。

参考资料

• Dockerfile 模式：多阶段构建、层缓存和镜像优化
• Compose：服务、网络、卷和环境管理
• 安全：非 root 用户、密钥、扫描和生产环境加固
• Buildx：适用于 ARM 和 x86 的多平台构建
• CI：GitHub Actions 缓存、推送到注册表和自动化构建
• 单体仓库：Turborepo prune、pnpm 工作区和选择性构建
• 调试：日志、exec、inspect、层分析和网络故障排查