Docker Compose v2 完全实战指南：从单容器到多服务编排 | 2026最新最佳实践

1
# Step 1: 定义各服务的 Dockerfile（可选，也可直接用现成镜像）
2
FROM node:20-alpine
3
WORKDIR /app
4
COPY . .
5
RUN npm install --production
6
CMD ["node", "server.js"]

1
# Step 2: 编写 docker-compose.yml，定义服务间关系
2
services:
3
  web:
4
    build: .
5
    ports:
6
      - "3000:3000"
7
  redis:
8
    image: "redis:alpine"

1
services:
2
  # 1. Nginx 反向代理
3
  nginx:
4
    image: nginx:1.27-alpine
5
    container_name: app-nginx
6
    ports:
7
      - "80:80"
8
      - "443:443"
9
    volumes:
10
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
11
      - ./nginx/ssl:/etc/nginx/ssl:ro
12
      - ./static:/var/www/static:ro
13
      - nginx-logs:/var/log/nginx
14
    depends_on:
15
      api:
16
        condition: service_healthy
17
    networks:
18
      - frontend
19
    restart: unless-stopped
20
    healthcheck:
21
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
22
      interval: 30s
23
      timeout: 5s
24
      retries: 3
25
      start_period: 10s
26

27
  # 2. Node.js API 服务
28
  api:
29
    build:
30
      context: ./api
31
      dockerfile: Dockerfile
32
      args:
33
        NODE_VERSION: 20
34
    container_name: app-api
35
    environment:
36
      - NODE_ENV=production
37
      - PORT=3000
38
      - DB_HOST=mysql
39
      - DB_PORT=3306
40
      - DB_USER=${DB_USER}
41
      - DB_PASSWORD=${DB_PASSWORD}
42
      - REDIS_HOST=redis
43
      - REDIS_PORT=6379
44
    volumes:
45
      - ./api:/app:ro
46
      - /app/node_modules
47
    expose:
48
      - "3000"
49
    depends_on:
50
      mysql:
51
        condition: service_healthy
52
      redis:
53
        condition: service_healthy
54
    networks:
55
      - frontend
56
      - backend
57
    restart: unless-stopped
58
    healthcheck:
59
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1))"]
60
      interval: 30s
61
      timeout: 10s
62
      retries: 3
63
      start_period: 30s
64
    deploy:
65
      resources:
66
        limits:
67
          cpus: "1.0"
68
          memory: 512M
69
        reservations:
70
          cpus: "0.25"
71
          memory: 128M
72

73
  # 3. MySQL 数据库
74
  mysql:
75
    image: mysql:8.4
76
    container_name: app-mysql
77
    environment:
78
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
79
      MYSQL_DATABASE: ${DB_NAME}
80
      MYSQL_USER: ${DB_USER}
81
      MYSQL_PASSWORD: ${DB_PASSWORD}
82
    volumes:
83
      - mysql-data:/var/lib/mysql
84
      - ./mysql/init:/docker-entrypoint-initdb.d:ro
85
    expose:
86
      - "3306"
87
    networks:
88
      - backend
89
    restart: unless-stopped
90
    command:
91
      - --character-set-server=utf8mb4
92
      - --collation-server=utf8mb4_unicode_ci
93
      - --default-authentication-plugin=mysql_native_password
94
    healthcheck:
95
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u${DB_USER}", "-p${DB_PASSWORD}"]
96
      interval: 10s
97
      timeout: 5s
98
      retries: 10
99
      start_period: 60s
100

101
  # 4. Redis 缓存
102
  redis:
103
    image: redis:7.2-alpine
104
    container_name: app-redis
105
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
106
    volumes:
107
      - redis-data:/data
108
    expose:
109
      - "6379"
110
    networks:
111
      - backend
112
    restart: unless-stopped
113
    healthcheck:
114
      test: ["CMD", "redis-cli", "ping"]
115
      interval: 10s
116
      timeout: 5s
117
      retries: 5
118

119
# 网络配置
120
networks:
121
  frontend:
122
    driver: bridge
123
    ipam:
124
      config:
125
        - subnet: 172.20.1.0/24
126
  backend:
127
    driver: bridge
128
    internal: true  # 内部网络，不可访问外网
129
    ipam:
130
      config:
131
        - subnet: 172.20.2.0/24
132

133
# 命名数据卷（持久化）
134
volumes:
135
  mysql-data:
136
    driver: local
137
  redis-data:
138
    driver: local
139
  nginx-logs:
140
    driver: local

1
# 形式 1: CMD - 在容器内执行命令（最常用）
2
healthcheck:
3
  test: ["CMD", "curl", "-f", "http://localhost"]
4
  interval: 30s        # 检查间隔
5
  timeout: 10s          # 单次超时时间
6
  retries: 3            # 失败重试次数
7
  start_period: 40s     # 启动宽限期（服务启动需要时间）
8

9
# 形式 2: CMD-SHELL - 使用 shell 执行
10
healthcheck:
11
  test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
12
  # 或简写为字符串:
13
  # test: curl -f http://localhost || exit 1
14

15
# 形式 3: NONE - 禁用健康检查
16
healthcheck:
17
  disable: true

1
# Nginx
2
healthcheck:
3
  test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
4
  interval: 30s
5
  timeout: 5s
6
  retries: 3
7

8
# MySQL
9
healthcheck:
10
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uuser", "-ppass"]
11
  interval: 10s
12
  timeout: 5s
13
  retries: 10
14
  start_period: 60s
15

16
# PostgreSQL
17
healthcheck:
18
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
19
  interval: 10s
20
  timeout: 5s
21
  retries: 5
22

23
# Redis
24
healthcheck:
25
  test: ["CMD", "redis-cli", "ping"]
26
  interval: 10s
27
  timeout: 5s
28
  retries: 5
29

30
# Node.js / Express
31
healthcheck:
32
  test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
33
  interval: 20s
34
  timeout: 5s
35
  retries: 3
36
  start_period: 30s
37

38
# Elasticsearch
39
healthcheck:
40
  test: ["CMD-SHELL", "curl -s http://localhost:9200/_cluster/health | grep -q 'green\\|yellow'"]
41
  interval: 30s
42
  timeout: 10s
43
  retries: 5
44
  start_period: 120s

1
services:
2
  api:
3
    depends_on:
4
      mysql:
5
        condition: service_healthy  # 等 mysql 健康后再启动 api
6
      redis:
7
        condition: service_healthy
8
      rabbitmq:
9
        condition: service_started  # 只要启动就行

1
services:
2
  app:
3
    image: myapp:latest
4
    volumes:
5
      # 命名卷 - 最简形式
6
      - mydata:/data
7

8
      # 命名卷 - 长格式
9
      - type: volume
10
        source: mydata
11
        target: /data
12
        volume:
13
          nocopy: true
14

15
      # Bind Mount - 长格式
16
      - type: bind
17
        source: ./config
18
        target: /etc/config
19
        read_only: true
20

21
      # tmpfs - 临时文件系统
22
      - type: tmpfs
23
        target: /tmp/cache
24
        tmpfs:
25
          size: 100m
26

27
volumes:
28
  mydata:

1
services:
2
  api:
3
    image: node:20
4
    # api 服务可以通过 mysql:3306 访问数据库
5
  mysql:
6
    image: mysql:8.4
7
    # mysql 服务名即它的 DNS 名称

1
services:
2
  nginx:
3
    networks:
4
      - frontend        # 可被外部访问
5

6
  api:
7
    networks:
8
      - frontend        # 与 nginx 通信
9
      - backend         # 与数据库通信
10

11
  mysql:
12
    networks:
13
      - backend         # 仅内部网络，外网不可达
14

15
  redis:
16
    networks:
17
      - backend         # 仅内部网络
18

19
networks:
20
  frontend:
21
    driver: bridge
22

23
  backend:
24
    driver: bridge
25
    internal: true      # 标记为内部网络

1
services:
2
  web:
3
    ports:
4
      - "3000"                      # 随机主机端口映射到 3000
5
      - "3000:3000"                 # 主机 3000 → 容器 3000（所有IP）
6
      - "127.0.0.1:3000:3000"       # 仅本机访问（推荐用于调试）
7
      - "8080:80/tcp"               # 指定协议
8
      - "6379:6379/udp"             # UDP 端口

1
services:
2
  app:
3
    image: myapp:latest
4

5
    # 方式 1: 直接键值对
6
    environment:
7
      NODE_ENV: production
8
      PORT: 3000
9

10
    # 方式 2: 数组形式（支持 shell 变量替换）
11
    environment:
12
      - NODE_ENV=production
13
      - DB_HOST=mysql
14

15
    # 方式 3: 从主机环境变量读取（不指定值）
16
    environment:
17
      - API_KEY          # 从 docker compose up 执行时的环境读取
18

19
    # 方式 4: 从 .env 文件
20
    env_file:
21
      - .env
22
      - .env.production  # 多个文件，后加载的覆盖先加载的

1
1. docker compose 命令行参数 → 最高优先级
2
2. shell 环境变量
3
3. .env 文件
4
4. Compose 文件中的默认值

1
services:
2
  mysql:
3
    image: mysql:8.4
4
    environment:
5
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
6
      MYSQL_PASSWORD_FILE: /run/secrets/db_password
7
    secrets:
8
      - db_root_password
9
      - db_password
10

11
secrets:
12
  db_root_password:
13
    file: ./secrets/db_root_password.txt  # 文件内容即密码
14
  db_password:
15
    file: ./secrets/db_password.txt
16

17
# secrets/db_password.txt (单独文件，不要提交到 Git!)
18
# ChangeThisSecurePassword2026!

1
# 1. 使用固定版本标签，避免 :latest
2
image: nginx:1.27-alpine
3

4
# 2. 使用多阶段构建减小镜像体积
5
FROM node:20-alpine AS builder
6
WORKDIR /app
7
COPY package*.json .
8
RUN npm ci
9
COPY . .
10
RUN npm run build
11

12
FROM node:20-alpine
13
WORKDIR /app
14
COPY --from=builder /app/dist ./dist
15
COPY --from=builder /app/node_modules ./node_modules
16
CMD ["node", "dist/server.js"]

1
services:
2
  app:
3
    user: "1000:1000"              # 不以 root 运行
4
    read_only: true                # 只读文件系统
5
    tmpfs:                         # 需要写入的位置用 tmpfs
6
      - /tmp
7
      - /var/run
8
    security_opt:
9
      - no-new-privileges:true     # 禁止提升权限
10
    cap_drop:                      # 删除不需要的 Linux capability
11
      - ALL
12
    cap_add:
13
      - NET_BIND_SERVICE           # 只保留需要的 capability

1
services:
2
  app:
3
    logging:
4
      driver: json-file
5
      options:
6
        max-size: "10m"            # 单个日志文件最大 10MB
7
        max-file: "5"              # 最多保留 5 个文件
8
        compress: "true"           # 压缩旧日志

1
services:
2
  api:
3
    deploy:
4
      resources:
5
        limits:
6
          cpus: "1.5"              # 最多使用 1.5 个 CPU 核
7
          memory: 512M             # 最多使用 512MB 内存
8
          pids: 100                # 最多创建 100 个进程
9
        reservations:
10
          cpus: "0.25"             # 预留 0.25 核
11
          memory: 128M             # 预留 128MB 内存

1
services:
2
  app:
3
    restart: unless-stopped        # 除非手动停止，否则自动重启
4
    # 其他选项:
5
    # restart: "no"                # 从不重启
6
    # restart: always              # 任何情况都重启（包括手动停止后再启动）
7
    # restart: on-failure          # 仅在非正常退出时重启

1
Error: getaddrinfo ENOTFOUND mysql

1
services:
2
  api:
3
    depends_on:
4
      mysql:
5
        condition: service_healthy  # 等数据库健康后再启动
6
  mysql:
7
    healthcheck:
8
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u${DB_USER}", "-p${DB_PASSWORD}"]
9
      interval: 10s
10
      retries: 10
11
      start_period: 60s

1
Permission denied: cannot write to /var/lib/mysql

1
services:
2
  mysql:
3
    user: "1001:1001"              # 指定运行用户
4
    # 或者在 Dockerfile 中设置
5
    # RUN usermod -u 1001 mysql

1
Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:80

1
failed to solve with frontend dockerfile.v0: failed to create LLB definition