2.1 利用构建缓存：指令顺序就是性能#

Docker 构建是逐层缓存的，某条指令的输入没变就复用缓存，一旦某层失效，它之后的所有层都会重建。这条规则决定了 Dockerfile 的指令顺序。

一个常见错误是过早复制全部源码：

1
# 不推荐：源码任何改动都导致 npm ci 重新执行
2
FROM node:20-alpine
3
WORKDIR /app
4
COPY . .
5
RUN npm ci
6
CMD ["node", "server.js"]

COPY . . 把整个项目复制进去，只要你改了一行业务代码，npm ci 这一层就失效，依赖重新安装。正确的做法是先把依赖描述文件复制进去，安装依赖单独成层，再复制业务代码：

1
# 推荐：依赖层只随 package.json 变化
2
FROM node:20-alpine
3
WORKDIR /app
4
COPY package*.json ./
5
RUN npm ci --only=production
6
COPY . .
7
CMD ["node", "server.js"]

这样改业务代码时，依赖安装层命中缓存，构建从 COPY . . 开始，几秒完成。对 Go 项目同理，先 COPY go.* ./ 再 go mod download，最后才 COPY . .。

配合 .dockerignore 排除 node_modules、.git、日志文件，避免无关变更使缓存失效，也避免把本地调试产物打进镜像。

2.2 合并 RUN 指令：少一层是一层#

每条 RUN 产生一层，层数越多镜像越大。把相关的安装命令用 && 串起来，并在结尾清理缓存：

1
# 不推荐：四层，且 apt 缓存留在镜像里
2
RUN apt-get update
3
RUN apt-get install -y curl
4
RUN apt-get install -y vim
5
RUN apt-get clean
6

7
# 推荐：一层完成，清理缓存
8
RUN apt-get update && \
9
    apt-get install -y --no-install-recommends \
10
      curl \
11
      vim && \
12
    apt-get clean && \
13
    rm -rf /var/lib/apt/lists/*

--no-install-recommends 跳过推荐包，rm -rf /var/lib/apt/lists/* 清掉包索引，这两个动作对镜像体积的影响往往比想象中大。

2.3 多阶段构建：把编译器和源码挡在镜像之外#

把编译环境和运行环境塞进同一个镜像，是镜像体积失控的主因。多阶段构建用 AS 给阶段命名，运行阶段只 COPY --from 拷贝编译产物：

1
# 构建阶段：完整的 Go SDK，数百 MB
2
FROM golang:1.21-alpine AS builder
3
WORKDIR /app
4
COPY go.* ./
5
RUN go mod download
6
COPY . .
7
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server .
8

9
# 运行阶段：只有二进制和必要证书
10
FROM alpine:3.19
11
RUN apk --no-cache add ca-certificates tzdata
12
WORKDIR /app
13
COPY --from=builder /server .
14
USER nobody
15
ENTRYPOINT ["/server"]

单阶段构建出的镜像可能 800MB，多阶段后能压到 15MB 左右。体积小的意义不只是省带宽，更在于攻击面：运行镜像里没有编译器、没有源码、没有构建工具，攻击者能利用的东西少得多。

-ldflags="-s -w" 去掉调试符号和 DWARF 信息，对 Go 二进制度数级别的缩减。CGO_ENABLED=0 生成静态二进制，运行阶段甚至可以用 FROM scratch 这种空镜像。

2.4 CMD 与 ENTRYPOINT 的配合#

这两个指令容易混淆，关键在于 docker run 后面跟的参数如何处理：

• CMD：可被 docker run 参数整体覆盖
• ENTRYPOINT：docker run 参数作为追加参数拼在后面

1
FROM alpine
2
CMD ["echo", "hello"]
3
# docker run myimage           → echo hello
4
# docker run myimage echo world → echo world（CMD 被覆盖）

1
FROM alpine
2
ENTRYPOINT ["echo"]
3
CMD ["hello"]
4
# docker run myimage           → echo hello
5
# docker run myimage world     → echo hello world（world 追加）

实战中更常用的是 ENTRYPOINT 定命令、CMD 定默认参数的组合：把容器设计成”带默认行为的可执行程序”，调用方既可以直接跑，也可以传参覆盖默认行为。注意都用 JSON 数组格式（exec 形式），不要用 shell 形式（CMD echo hello），后者会经 shell 解析，信号传递和参数处理都更难控制。

2.5 安全基线#

生产镜像至少做到三条：非 root 运行、最小基础镜像、只读根文件系统。

1
FROM node:20-alpine
2
RUN addgroup -g 1000 -S appgroup && \
3
    adduser -u 1000 -S appuser -G appgroup
4
WORKDIR /app
5
COPY --chown=appuser:appgroup . .
6
USER appuser
7
CMD ["node", "server.js"]

1
# 运行时配合只读根文件系统和权限收敛
2
docker run -d \
3
  --read-only \
4
  --tmpfs /tmp \
5
  --cap-drop ALL --cap-add CHOWN \
6
  my-app:latest

USER appuser 确保即使容器被入侵，攻击者也没有 root 权限。--read-only 让根文件系统不可写，攻击者无法写入后门或篡改二进制，需要写的临时目录用 --tmpfs 单独挂载。--cap-drop ALL 收回所有 Linux capabilities，只按需加回。

最小基础镜像（alpine、distroless）的意义不只是体积，更少的包意味着更少的 CVE。可以用 docker scout cves <image> 扫描镜像漏洞。

3.1 用 depends_on 表达启动顺序#

一个典型的 Web 应用通常由 Web、App、数据库、缓存组成，App 依赖数据库就绪。depends_on 可以声明这种依赖：

1
services:
2
  app:
3
    build: ./app
4
    depends_on:
5
      db:
6
        condition: service_healthy
7
      cache:
8
        condition: service_started
9
    environment:
10
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
11
      - REDIS_URL=redis://cache:6379
12

13
  db:
14
    image: postgres:15-alpine
15
    environment:
16
      POSTGRES_USER: user
17
      POSTGRES_PASSWORD: pass
18
      POSTGRES_DB: mydb
19
    volumes:
20
      - postgres-data:/var/lib/postgresql/data
21
    healthcheck:
22
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
23
      interval: 10s
24
      timeout: 5s
25
      retries: 5
26

27
  cache:
28
    image: redis:7-alpine
29
    volumes:
30
      - redis-data:/data
31

32
volumes:
33
  postgres-data:
34
  redis-data:

这里有个坑值得单独说：depends_on 只控制启动顺序，不等于就绪。service_started 只表示容器进程拉起来了，不代表应用能接收请求。数据库容器启动后，PostgreSQL 进程还需要几秒完成初始化，这段时间 App 去连库会失败。

解决办法是给被依赖服务配 healthcheck，依赖方用 condition: service_healthy，Compose 会等健康检查通过才启动依赖方。上面的 pg_isready 就是 PostgreSQL 自带的就绪探测命令。

3.2 多环境配置：override 与 -f 组合#

Compose 支持多文件叠加。默认会自动加载 docker-compose.yml 和 docker-compose.override.yml，后者常用于开发环境的本地覆盖。生产环境用 -f 显式指定多个文件叠加：

1
# 开发环境（自动合并 docker-compose.yml 和 override）
2
docker compose up -d
3

4
# 生产环境
5
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
6

7
# 只启动部分服务
8
docker compose up -d db cache

基础文件放通用配置，环境文件只放差异：

1
# docker-compose.prod.yml：只覆盖生产相关的部分
2
services:
3
  app:
4
    image: registry.example.com/app:${VERSION:-latest}
5
    deploy:
6
      replicas: 3
7
      resources:
8
        limits:
9
          cpus: "1"
10
          memory: 512M
11
    healthcheck:
12
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
13
      interval: 30s
14
      timeout: 10s
15
      retries: 3

注意生产文件里 app 用 image 拉取已构建镜像而非 build 本地构建，配合 ${VERSION:-latest} 注入版本号，保证运行的是 CI 产出的那个镜像而不是本地随手构建的。

3.3 环境变量与 .env#

敏感信息不要硬编码进 YAML。用 .env 文件管理，Compose 启动时自动读取同目录下的 .env：

1
DB_URL=postgres://user:pass@db:5432/mydb
2
REDIS_URL=redis://cache:6379
3
VERSION=1.2.3

1
services:
2
  app:
3
    image: my-app:${VERSION}
4
    environment:
5
      - DATABASE_URL=${DB_URL}

.env 必须加入 .gitignore，仓库里只提交 .env.example 作为模板。命令行也能临时覆盖：VERSION=1.2.4 docker compose up -d。

4.1 前后端一体镜像#

一个前端 SPA 加 Nginx 的典型场景：构建阶段编译前端，运行阶段只放静态文件和 Nginx 配置。

1
# app/Dockerfile
2
FROM node:20-alpine AS builder
3
WORKDIR /app
4
COPY package*.json ./
5
RUN npm ci
6
COPY . .
7
RUN npm run build
8

9
FROM nginx:1.25-alpine
10
COPY --from=builder /app/dist /usr/share/nginx/html
11
COPY nginx/nginx.conf /etc/nginx/nginx.conf
12
EXPOSE 80
13
CMD ["nginx", "-g", "daemon off;"]

1
services:
2
  web:
3
    build:
4
      context: .
5
      dockerfile: app/Dockerfile
6
    ports:
7
      - "80:80"
8
    restart: unless-stopped

要点是构建产物（/app/dist）从 builder 阶段拷出，运行镜像里没有 Node.js、没有源码、没有 node_modules，只有 Nginx 和编译后的静态文件。

4.2 本地开发环境#

本地开发讲究的是”改代码即时生效”，这和生产的”构建一次跑到底”是两套逻辑。用卷挂载源码 + 覆盖启动命令实现热重载：

1
services:
2
  app:
3
    build:
4
      context: .
5
      target: development
6
    volumes:
7
      - .:/app              # 源码挂载进容器，改代码即时生效
8
      - /app/node_modules   # 屏蔽宿主机的 node_modules，用容器内的
9
    ports:
10
      - "3000:3000"
11
    environment:
12
      - NODE_ENV=development
13
      - CHOKIDAR_USEPOLLING=true   # WSL2/macOS 下文件监听需要轮询
14
    command: npm run dev
15

16
  db:
17
    image: postgres:15-alpine
18
    ports:
19
      - "5432:5432"
20
    environment:
21
      POSTGRES_USER: dev
22
      POSTGRES_PASSWORD: dev
23
      POSTGRES_DB: myapp
24
    volumes:
25
      - dev-db:/var/lib/postgresql/data
26

27
  redis:
28
    image: redis:7-alpine
29
    ports:
30
      - "6379:6379"
31

32
volumes:
33
  dev-db:

- .:/app 把当前目录挂进容器，编辑器改的代码立刻反映到容器里，配合 npm run dev 的热重载实现不用重启就生效。/app/node_modules 这个匿名卷是个技巧：它遮蔽了挂载进来的宿主机 node_modules，保证容器用的是自己 npm install 装的版本，避免宿主机和容器 Node 版本不一致导致的原生模块不兼容。

CHOKIDAR_USEPOLLING=true 是 WSL2 和 macOS 卷挂载场景下文件监听经常失效的 workaround，不开启会出现在容器里改了代码但不触发热重载的问题。

4.3 CI/CD 流水线#

GitLab CI 里用 Docker-in-Docker 构建并推送镜像的典型片段：

1
stages:
2
  - build
3
  - test
4
  - deploy
5

6
variables:
7
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
8

9
build:
10
  stage: build
11
  image: docker:24
12
  services:
13
    - docker:24-dind
14
  script:
15
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
16
    - docker build -t $IMAGE_TAG .
17
    - docker push $IMAGE_TAG
18

19
test:
20
  stage: test
21
  image: $IMAGE_TAG
22
  script:
23
    - npm test
24

25
deploy:
26
  stage: deploy
27
  image: docker:24
28
  script:
29
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
30
    - docker pull $IMAGE_TAG
31
    - docker tag $IMAGE_TAG $CI_REGISTRY_IMAGE:latest
32
    - docker push $CI_REGISTRY_IMAGE:latest
33
  only:
34
    - main

用 commit SHA 作为镜像 tag，保证每次提交对应一个不可变镜像，测试阶段直接用这个镜像跑，部署阶段再额外打一个 latest tag 供生产拉取。only: - main 限制只有主分支才部署，避免特性分支误发生产。

5.1 容器退出码的含义#

docker ps -a 看到容器退出了，先查退出码：

1
docker inspect <container_id> --format '{{.State.ExitCode}}'
2
docker logs <container_id>

常见退出码：

137 是最需要警惕的。如果容器没设内存限制或设得太小，宿主机内存紧张时内核的 OOM Killer 会杀掉容器进程，退出码就是 137。确认是不是 OOM：

1
# 查看宿主机最近的 OOM 记录
2
dmesg | grep -i "killed process"

看到对应进程被 OOM Kill，就需要调大 --memory 或排查应用内存泄漏。

5.2 网络不通的排查路径#

容器间网络不通，按从内到外的顺序排查：

1
# 1. 进容器测 DNS（自定义网络才支持容器名解析）
2
docker exec -it <container> sh
3
nslookup db            # 解析不了说明不在同一自定义网络
4

5
# 2. 测连通性
6
ping -c 3 <对端IP>
7
curl -v http://<对端>:<端口>
8

9
# 3. 查 NAT 规则（bridge 模式对外通信靠 NAT）
10
iptables -t nat -L -n
11

12
# 4. 重建异常的网络
13
docker network prune

最常见的根因是两个容器不在同一个自定义网络。默认 bridge 网络里容器之间只能用 IP 通信，不支持容器名解析；自定义 bridge 网络才内置 DNS，能用 ping db 这种名字访问。所以微服务场景一律用自定义网络而非默认 bridge。

5.3 磁盘被镜像和日志撑满#

Docker 用久了磁盘报警，多半是镜像层、停止的容器、无主卷和容器日志累积。先看占用分布：

1
docker system df -v

清理未使用的资源：

1
# 清理停止的容器、无主网络、悬空镜像、构建缓存
2
docker system prune
3

4
# 连未使用的镜像一起清（确认无误后）
5
docker system prune -a
6

7
# 连无主卷一起清（危险，确认无数据卷在用）
8
docker system prune -a --volumes

容器日志是另一个隐形杀手。默认的 json-file 日志驱动不限制大小，一个跑很久的服务日志能写到几十 GB。治本的办法是在 /etc/docker/daemon.json 里限制日志大小：

1
{
2
  "log-driver": "json-file",
3
  "log-opts": {
4
    "max-size": "100m",
5
    "max-file": "3"
6
  }
7
}

这样每个容器最多保留 3 个 100MB 的日志文件，轮转覆盖。改完 systemctl restart docker 生效，已运行的容器需要重建才会应用新配置。

如果数据目录所在的盘本身就小，可以把整个 Docker 数据目录迁到大盘：

1
sudo systemctl stop docker
2

3
# 修改 /etc/docker/daemon.json
4
# { "data-root": "/mnt/docker-data" }
5

6
sudo rsync -aP /var/lib/docker/ /mnt/docker-data/
7
sudo systemctl start docker

迁移完确认 docker info 里的 Docker Root Dir 已指向新路径，且容器都正常起来后，再删除旧的 /var/lib/docker。