一、问题背景

上个月接手一个内部管理系统,架构是典型的前后端分离:Nginx做静态资源服务和反向代理,Spring Boot提供API,MySQL存业务数据,Redis做缓存和会话。之前部署靠一套手写的shell脚本,每次上线都是一场灾难——脚本里sleep 30等待MySQL就绪,网络不好时应用启动时数据库还没准备好,直接抛Connection refused退出;数据库数据目录用bind mount挂到宿主机,换台机器路径对不上就起不来;四个容器全用默认bridge网络,靠--link(早已废弃)互相访问,端口冲突排查半天。

痛定思痛,把这套部署彻底迁移到Docker Compose。这篇文章把最终的配置和踩过的坑完整记录下来,配置在Docker Engine 25.0.3、Docker Compose v2.24.5、Ubuntu 22.04 LTS上验证通过,可以直接拿去改。

二、环境与版本

先把版本钉死,避免读者照着抄出现行为差异:

组件 版本
Docker Engine 25.0.3
Docker Compose v2.24.5(插件形式,docker compose 而非 docker-compose)
宿主机 Ubuntu 22.04 LTS,4C8G
Nginx 1.25.4-alpine
OpenJDK 17(eclipse-temurin:17-jre-jammy)
MySQL 8.0.36
Redis 7.2.4-alpine

注意Compose v2的depends_on支持condition: service_healthy,这是v1的docker-compose(Python版)在较老版本里没有的能力,也是本文启动顺序方案的基础。

三、方案设计

设计上定了几条原则:

  1. 网络隔离:建两个自定义bridge网络。frontend网络只挂Nginx和app,backend网络挂app、MySQL、Redis。MySQL和Redis完全不暴露到frontend,减少攻击面。
  2. 数据持久化:MySQL数据、Redis的AOF文件、Nginx日志全部用命名卷(named volume),不用bind mount,避免宿主机路径依赖。
  3. 启动顺序:MySQL和Redis配healthcheck,app用depends_on的service_healthy条件等待;Nginx再等app健康。链式依赖,杜绝"启动即退出"。
  4. 配置外置:数据库密码、JVM参数走.env文件,compose文件里用${VAR}引用,不把敏感信息写进版本库。
  5. 资源限制:给每个服务加deploy.resources.limits,防止某个服务吃满内存把宿主机拖垮。

目录结构:

project/
├── docker-compose.yml
├── .env
├── nginx/
│   └── conf.d/default.conf
└── app/
    └── app.jar

四、核心实现

4.1 完整docker-compose.yml

version: "3.9"

services:
  mysql:
    image: mysql:8.0.36
    container_name: app-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      TZ: Asia/Shanghai
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --max_connections=500
      - --innodb-buffer-pool-size=512M
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - backend
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
    deploy:
      resources:
        limits:
          memory: 1G

  redis:
    image: redis:7.2.4-alpine
    container_name: app-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD}"]
    volumes:
      - redis-data:/data
    networks:
      - backend
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 256M

  app:
    image: eclipse-temurin:17-jre-jammy
    container_name: app-server
    restart: unless-stopped
    working_dir: /opt/app
    command: >
      java -Xms512m -Xmx1024m
      -Dspring.profiles.active=prod
      -jar app.jar
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/${MYSQL_DATABASE}?useSSL=false&serverTimezone=Asia/Shanghai
      SPRING_DATASOURCE_USERNAME: ${MYSQL_USER}
      SPRING_DATASOURCE_PASSWORD: ${MYSQL_PASSWORD}
      SPRING_REDIS_HOST: redis
      SPRING_REDIS_PORT: 6379
      SPRING_REDIS_PASSWORD: ${REDIS_PASSWORD}
      TZ: Asia/Shanghai
    volumes:
      - ./app/app.jar:/opt/app/app.jar:ro
      - app-logs:/opt/app/logs
    networks:
      - frontend
      - backend
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8080/actuator/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
    deploy:
      resources:
        limits:
          memory: 1536M

  nginx:
    image: nginx:1.25.4-alpine
    container_name: app-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - nginx-logs:/var/log/nginx
    networks:
      - frontend
    depends_on:
      app:
        condition: service_healthy
    deploy:
      resources:
        limits:
          memory: 128M

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

volumes:
  mysql-data:
  redis-data:
  app-logs:
  nginx-logs:

4.2 .env文件与Nginx配置

.env放在项目根目录,Compose会自动加载:

MYSQL_ROOT_PASSWORD=Root@2024!Change
MYSQL_DATABASE=appdb
MYSQL_USER=appuser
MYSQL_PASSWORD=App@2024!Change
REDIS_PASSWORD=Redis@2024!Change

Nginx的default.conf里,proxy_pass直接用服务名app,因为两者都在frontend网络,Docker内置DNS会解析容器名:

server {
    listen 80;
    server_name _;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://app:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 60s;
    }
}

启动命令就一句:

docker compose up -d

五、踩坑与优化

坑1:MySQL healthcheck一直unhealthy。 一开始test写的是mysqladmin ping -h localhost,容器内localhost走socket,而初始化阶段socket尚未就绪,健康检查失败。改成-h 127.0.0.1强制走TCP,并加start_period: 30s给初始化留时间,问题解决。另外密码里有!和@,在test数组里要确保不被shell解析,用JSON数组形式(["CMD", ...])而非CMD-SHELL更稳妥。

坑2:app的healthcheck依赖curl,但temurin镜像里没有curl。 报exec: "curl": executable file not found。两个选择:换wget --spider,或者镜像里装curl。我选了后者,在Dockerfile里apt-get install -y curl,因为actuator健康端点用curl排查也方便。如果不想改镜像,可以写个纯Java的健康检查,但没必要。

坑3:卷挂载jar包后应用无法热更新。 ./app/app.jar:/opt/app/app.jar:ro是文件挂载,宿主机的inode变了(比如用cp覆盖),容器里看到的还是旧文件。改用docker compose cp app.jar app-server:/opt/app/再docker compose restart app,或者把挂载改成目录挂载。这个坑排查了两小时,血泪教训。

坑4:内存限制过紧导致OOM Kill。 最初app只给1G,-Xmx1024m加上Metaspace、线程栈、堆外内存,实际RSS超过1G,容器被内核OOM Killer干掉,docker inspect里OOMKilled: true。把limit调到1536M、Xmx保持1024m,留出约500M给非堆内存,稳定了。

优化点:MySQL的innodb-buffer-pool-size按宿主机内存的25%左右设置(8G机器给512M偏保守,可给1G),max_connections按实际并发调;Redis开了AOF但没配appendfsync,默认everysec足够,追求极致可靠可改always但会牺牲写性能。

六、效果数据

迁移前后对比(同一台4C8G机器,连续部署10次取平均):

指标 shell脚本方案 Docker Compose方案
全量冷启动耗时 约8分钟(含人工sleep) 92秒(MySQL初始化占大头)
因启动顺序失败次数 10次里3次 0次
换机部署耗时 需改路径、装依赖,约30分钟 拷贝目录 + docker compose up -d,约3分钟
单服务重启影响 需手动确认依赖 docker compose restart app,Nginx不受影响

健康检查生效后,docker compose ps能直接看到每个服务的health状态,排查问题从"看日志猜"变成"看状态定位"。

七、总结

这套配置的核心就三件事:自定义网络划清边界、命名卷管住数据、healthcheck + depends_on管住顺序。Compose v2的condition: service_healthy是启动顺序的关键,别再用sleep了。另外提醒两点:.env记得加进.gitignore;deploy.resources.limits在非Swarm模式下Compose v2也支持,别以为只有docker stack deploy能用。配置不复杂,但每个参数背后都是踩出来的坑,希望对正在做容器化部署的同行有点用。