docker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker

Overview

概述

Docker packages applications into isolated containers that run consistently across environments. A Dockerfile defines the image build steps, Compose orchestrates multi-container services, and production patterns ensure small, secure, performant images.

When to use: Containerizing applications, creating reproducible dev environments, orchestrating multi-service stacks, deploying to container platforms (ECS, Kubernetes, Fly.io, Railway, Coolify).

When NOT to use: Simple static sites with no backend (use CDN deploy), single-binary CLI tools (distribute the binary), or when the target platform has native buildpacks (Heroku, Vercel) and you don't need container control.

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

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

不适用场景：无后端的简单静态站点（使用CDN部署）、单二进制CLI工具（直接分发二进制文件）、目标平台提供原生buildpacks（Heroku、Vercel）且无需容器控制权的场景。

Quick Reference

快速参考

Pattern	Approach	Key Points
Multi-stage build	Separate `builder` and `production` stages	80%+ image size reduction, no dev deps in production
Layer caching	Copy lockfile first, install, then copy source	Dependency layer cached across builds
Non-root user	`RUN adduser` + `USER` in final stage	Never run production containers as root
Health check	`HEALTHCHECK CMD curl` or node/python check	Enables orchestrator restart on failure
`.dockerignore`	Exclude `node_modules` , `.git` , `.env`	Smaller build context, faster builds
Compose services	`compose.yaml` with service definitions	Dev environment in one command
Compose override	`compose.prod.yaml` with production settings	Environment-specific config without duplication
Named volumes	`volumes:` in Compose for persistent data	Survives container recreation
Build cache mount	`RUN --mount=type=cache,target=/root/.npm`	Persistent cache across builds
Secrets in build	`RUN --mount=type=secret,id=token`	Never bake secrets into image layers
Image pinning	Pin to major.minor or digest	Reproducible builds, avoid surprise breakage
Container networking	Custom bridge networks with service discovery	Containers resolve each other by service name
Compose watch	`develop.watch` with sync/rebuild actions	Live reload without volume mounts
Init process	`--init` flag or `tini` entrypoint	Proper signal handling and zombie reaping
Multi-platform	`docker buildx build --platform`	ARM (Apple Silicon, Graviton) + x86 in one image
Monorepo prune	`turbo prune app --docker`	Minimal build context from workspace dependencies
CI layer caching	`cache-from` / `cache-to` with GHA or registry	Avoid full rebuilds in CI pipelines
Debug containers	`docker exec` , `docker logs` , `dive`	Inspect running containers and image layers

模式	实现方式	核心要点
多阶段构建	分离 `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架构
单仓多包裁剪	`turbo prune app --docker`	从工作区依赖中提取最小构建上下文
CI层缓存	结合GHA或镜像仓库使用 `cache-from` / `cache-to`	避免CI流水线中完全重建镜像
容器调试	`docker exec` 、 `docker logs` 、 `dive` 工具	检查运行中容器和镜像层

Common Mistakes

常见错误

Mistake	Correct Pattern
Installing dev dependencies in production image	Multi-stage build: install in builder, copy artifacts to runtime
Copying source before installing dependencies	Copy lockfile first, `npm ci` , then copy source for cache reuse
Running as root in production	Create non-root user, `USER` directive in final stage
Hardcoding secrets in Dockerfile or ENV	Use build secrets ( `--mount=type=secret` ) or runtime env
Using `latest` tag for base images	Pin to specific version ( `node:24-alpine` )
No `.dockerignore` file	Exclude `node_modules` , `.git` , `.env` , build artifacts
Using `npm install` instead of `npm ci`	`npm ci` for deterministic, lockfile-based installs
HEALTHCHECK missing	Add health check for orchestrator integration
Large base images ( `node:24` )	Use alpine variants ( `node:24-alpine` ) for smaller images
Ignoring `.env` file precedence in Compose	`environment:` in Compose overrides `.env` file values
Building entire monorepo for one service	Use `turbo prune --docker` for minimal build context
No layer caching in CI	Use `cache-from` / `cache-to` with GHA or registry backend
Building only for x86 when deploying to ARM	Use `docker buildx` with `--platform linux/amd64,linux/arm64`

错误做法	正确实践
在生产镜像中安装开发依赖	多阶段构建：在builder阶段安装依赖，仅将产物复制到运行时阶段
先复制源码再安装依赖	先复制锁文件，执行 `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` 实现基于锁文件的确定性安装
未配置健康检查	添加健康检查以集成编排器功能
使用大型基础镜像（如 `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`

Delegation

任务委托

Dockerfile review: Use
```
Task
```
agent to audit Dockerfiles for size, security, and caching
Compose exploration: Use
```
Explore
```
agent to discover existing Docker configurations
Architecture decisions: Use
```
Plan
```
agent for container orchestration strategy

If the
ci-cd-architecture
skill is available, delegate CI/CD pipeline and deployment strategy to it. If the
application-security
skill is available, delegate container security scanning and hardening review to it.

Dockerfile审核：使用
```
Task
```
代理审核Dockerfile的体积、安全性和缓存策略
Compose配置探索：使用
```
Explore
```
代理发现现有Docker配置
架构决策：使用
```
Plan
```
代理制定容器编排策略

若
ci-cd-architecture
技能可用，将CI/CD流水线和部署策略委托给该技能处理。若
application-security
技能可用，将容器安全扫描和加固审核委托给该技能处理。

References

参考资料

Dockerfile patterns: multi-stage builds, layer caching, and image optimization
Compose: services, networking, volumes, and environment management
Security: non-root users, secrets, scanning, and production hardening
Buildx: multi-platform builds for ARM and x86
CI: GitHub Actions caching, registry push, and automated builds
Monorepo: Turborepo prune, pnpm workspaces, and selective builds
Debugging: logs, exec, inspect, layer analysis, and network troubleshooting

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