先看一个我踩过的坑

周三下午，我把一个 PHP 8.3 项目的日志级别从 info 改成 debug。配置文件躺在 API 容器里，我改了之后需要重启让 env 生效。这个项目一共 8 个容器：Nginx、两个 PHP-FPM、MySQL、Redis、Redis Commander、一个 Node 写的 Cron 服务、一个队列 Worker。

我的第一反应是 docker restart api。结果 API 起来了，Nginx 的 upstream 缓存还指着旧 IP。于是我又重启 Nginx。Nginx 起来了，Redis 连接池又崩了。我干脆把 8 个容器全删了，按启动顺序一个个 docker run，该等 MySQL 初始化完成，该等 Redis 写入健康检查。整个过程花了 11 分钟，期间还有两个容器因为依赖服务没就绪直接退出。

这事的根子出在：我用一堆 shell 脚本做编排。docker run 每一个都是独立命令，没有依赖关系、没有健康检查、没有配置漂移管控。改一次配置等于做一次手工运维。这就是我要写这篇文章的原因。

问题拆解：手工编排到底痛苦在哪

上面那个场景，本质上暴露了四个问题：

• 容器启动顺序不可控：MySQL 没起来，PHP-FPM 先跑，连库失败直接退出
• 服务间通信靠 IP：容器重建后 IP 变了，写死在配置文件里的地址全部失效
• 配置改动无法追踪：一个 env 变量散落在三个启动脚本里，改了找不到记录
• 缺乏健康检查机制：没有任何一个脚本能判断服务是否真正可用，只看进程在不在

我的方案很简单：把 8 个容器的启动配置写进一个 docker-compose.yml，用 Docker Compose v2 管理生命周期。所有服务之间通过服务名互相访问，Compose 内置 DNS 解析搞定 IP 变化。启动顺序用 depends_on 加 condition 控制，服务就绪用 healthcheck 判定。

方案对比：bash 启动脚本 vs Docker Compose

动手之前，我实际写了两个版本做对比。第一个版本是纯 bash 部署脚本，137 行，支持 start / stop / restart。第二个版本是 Docker Compose，25 行 yaml。

结论不复杂：规模超过 5 个容器，脚本方案的时间成本会指数级上升。Compose 的声明式语法，让基础设施的变更像代码一样可以被 review。

完整代码实现：从零编排一个微服务项目

项目结构和版本清单

我用的环境是 Docker 24.0.7 + Docker Compose v2.23.0，宿主机 Ubuntu 22.04。项目结构如下：

microservice-project/
├── docker-compose.yml
├── docker-compose.override.yml
├── .env
├── nginx/
│   └── conf.d/
│       └── default.conf
├── api/          # PHP 8.3-FPM 主 API
├── cron/         # Node 18 定时任务
├── sql/
│   └── init.sql
└── scripts/
    └── healthcheck.sh

核心编排文件 docker-compose.yml

主文件定义了 6 个服务，覆盖一个典型 Web 项目的完整链路。注释里写了每个配置项的作用，这些参数都是压测调过的。

version: "3.8"  # Compose v2 已废弃，不留兼容性的话可以直接删掉这行

services:
  nginx:
    image: nginx:1.25.3-alpine
    ports:
      - "8080:80"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./api:/var/www/html:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - frontend
      - backend

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    image: microservice-api:latest
    environment:
      - APP_ENV=production
      - DB_HOST=mysql
      - DB_PORT=3306
      - REDIS_HOST=redis
    expose:
      - "9000"
    healthcheck:
      test: ["CMD", "php", "/var/www/html/healthcheck.php"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - backend

  cron:
    image: node:18.17.1-alpine
    volumes:
      - ./cron:/app
    working_dir: /app
    command: node scheduler.js
    depends_on:
      mysql:
        condition: service_healthy
    networks:
      - backend

  mysql:
    image: mysql:8.0.35
    environment:
      - MYSQL_ROOT_PASSWORD=rootpwd
      - MYSQL_DATABASE=app
      - MYSQL_USER=app
      - MYSQL_PASSWORD=apppwd
    volumes:
      - db_data:/var/lib/mysql
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-prootpwd"]
      interval: 3s
      timeout: 2s
      retries: 20
      start_period: 20s
    networks:
      - backend

  redis:
    image: redis:7.2.1-alpine
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 2s
      retries: 10
      start_period: 5s
    networks:
      - backend

  redis-commander:
    image: rediscommander/redis-commander:latest
    environment:
      - REDIS_HOSTS=local:redis:6379
    ports:
      - "8081:8081"
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - backend

volumes:
  db_data:
  redis_data:

networks:
  frontend:
  backend:

开发环境覆盖配置

生产环境和本地开发最重要的区别是端口冲突和调试工具。我用 override 文件解决，不需要改主文件。Compose 读取顺序是 docker-compose.yml 先读，再读 docker-compose.override.yml，同名 key 用覆盖值。

# docker-compose.override.yml - 仅本地开发使用
services:
  api:
    environment:
      - APP_ENV=development
      - XDEBUG_MODE=debug
    volumes:
      - ./api:/var/www/html:cached  # 覆盖为可写挂载，改动即时生效
    ports:
      - "9000:9000"

  nginx:
    ports:
      - "80:80"    # 本地用 80，避免和线上 8080 混淆

  mysql:
    ports:
      - "3307:3306"  # 本地 3306 可能被宿主机 MySQL 占用，错开

使用方式和主文件一样：docker compose up -d。override 文件在 CI/CD 环境不参与构建，部署服务器上只保留 docker-compose.yml。

Nginx 配置：服务发现的关键细节

容器间通信不走端口映射，直接用 Compose 网络内部的 DNS 解析。Nginx 配置文件里 upstream 指向的是服务名 api，不是 IP。

upstream microservice_api {
    # 这里写的是 docker compose 服务名，Compose DNS 会自动解析到对应容器 IP
    server api:9000;
    keepalive 32;
}

server {
    listen 80;
    server_name _;

    root /var/www/html/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass microservice_api;
        fastcgi_keep_conn on;
        fastcgi_buffers 16 16k;
        fastcgi_buffer_size 32k;
    }

    # 静态文件直接本机返回，不经过 PHP-FPM，压测数据里的 RPS 提升靠这个
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 30d;
        access_log off;
        try_files $uri =404;
    }
}

环境变量文件 .env

Compose 会自动读取根目录的 .env 文件，用 ${VAR} 插值到 compose 文件里。这样敏感信息不进 git，也不会散落在多个 shell 脚本里。

# .env - 不要提交到 git，用 .env.example 占位
COMPOSE_PROJECT_NAME=microservice
MYSQL_ROOT_PASSWORD=rootpwd
MYSQL_DATABASE=app
MYSQL_USER=app
MYSQL_PASSWORD=apppwd
REDIS_MAXMEMORY=256mb

对应的 compose 文件里改为引用：

  mysql:
    image: mysql:8.0.35
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}

SQL 初始化脚本

mysql 镜像首次启动会自动执行 /docker-entrypoint-initdb.d/ 目录下的 .sql 文件。这个特性配合数据卷，可以完成空库初始化，只跑一次。

-- sql/init.sql - 仅在数据卷为空时执行
CREATE TABLE IF NOT EXISTS users (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

INSERT INTO users (name, email) VALUES ('benchmark', 'bench@example.com') ON DUPLICATE KEY UPDATE name='benchmark';

健康检查脚本

PHP 的 healthcheck 不能只检测进程存在，要检测应用层真正可响应。我写了一个轻量的 healthcheck.php，放在 API 容器里，检查数据库连接和 Redis 连接。

 true];

try {
    $pdo = new PDO(
        'mysql:host=mysql;dbname=app;charset=utf8mb4',
        'app',
        'apppwd',
        [PDO::ATTR_TIMEOUT => 2]
    );
    $pdo->query('SELECT 1');
} catch (Throwable $e) {
    $status['mysql'] = 'unreachable';
    $status['ok'] = false;
}

try {
    $redis = new Redis();
    $redis->connect('redis', 6379, 2);
    $redis->ping();
} catch (Throwable $e) {
    $status['redis'] = 'unreachable';
    $status['ok'] = false;
}

http_response_code($status['ok'] ? 200 : 503);
header('Content-Type: application/json');
echo json_encode($status);

健康检查通过的标准是退出码为 0。上面代码里没显式 exit，PHP 默认 return 0，检测失败时 http_response_code 设为 503，但进程退出码仍然是 0。这会导致 Docker 误判。快速修正一下：

$ docker compose up -d

[+] Running 10/10
 ✔ Network microservice_backend   Created
 ✔ Network microservice_frontend  Created
 ✔ Volume "microservice_db_data"  Created
 ✔ Container microservice-redis-1     Healthy
 ✔ Container microservice-mysql-1     Healthy
 ✔ Container microservice-api-1       Started
 ✔ Container microservice-nginx-1     Started
 ✔ Container microservice-cron-1      Started
 ✔ Container microservice-redis-commander-1  Started

depends_on:
  mysql:
    condition: service_healthy

$ docker compose up -d --scale api=3
[+] Running 4/4
 ✔ Container microservice-api-1  Already exists
 ✔ Container microservice-api-2  Started
 ✔ Container microservice-api-3  Started

wrk -t8 -c800 -d20s --latency http://localhost:8080/index.php
wrk -t8 -c800 -d20s --latency http://localhost:8080/static/img/logo.png

docker compose run --rm --no-deps --entrypoint "" nginx sh -c "apt update && apt install -y curl && curl http://api:9000/healthcheck.php"

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 30s
  timeout: 5s
  retries: 3

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-prootpwd"]
  interval: 5s
  timeout: 3s
  retries: 20
  start_period: 30s

http_response_code(503);
exit(0);  // 这是错的

docker compose down  # 不带 -v，保留数据卷

docker compose down --volumes  # 或者干脆 docker volume rm 指定名字