15.8.9 生产部署注意事项与故障排查

在生产环境使用 Docker Compose 需要保证一致性、可观测性与可回滚性。本节给出一套可执行的部署与排错流程，包含示例配置、命令解释、架构草图与练习。

生产部署原理草图（配置与镜像可追溯、日志可观测、数据持久化）：

1. 生产级 Compose 示例（含资源限制、健康检查、日志与数据卷）#

文件：/opt/apps/myapp/docker-compose.yml

version: "3.8"

services:
  web:
    image: registry.example.com/myapp/web:1.4.2
    ports:
      - "8080:8080"
    env_file:
      - /opt/apps/myapp/env/prod.env
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"
    restart: always
    networks:
      - appnet

  api:
    image: registry.example.com/myapp/api:1.4.2
    env_file:
      - /opt/apps/myapp/env/prod.env
    volumes:
      - /opt/apps/myapp/data/uploads:/data/uploads
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:9000/health || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 1G
    restart: always
    networks:
      - appnet

networks:
  appnet:
    driver: bridge

环境变量文件示例：/opt/apps/myapp/env/prod.env

APP_ENV=prod
DB_HOST=10.0.10.11
DB_PORT=3306
DB_USER=app
DB_PASS=strong_password
REDIS_HOST=10.0.10.12
REDIS_PORT=6379

关键点说明：
- 固定镜像标签，避免 latest 漂移；镜像从私有仓库拉取。
- healthcheck + depends_on 保障依赖健康后再启动。
- logging 控制容器日志滚动，避免磁盘爆满。
- volumes 明确持久化目录，防止容器重建数据丢失。
- deploy.resources.limits 做资源上限，避免单服务抢占。

2. 发布流程与命令（含解释）#

发布目录与命令建议：

# 1) 检查版本与环境
docker compose version

# 2) 拉取指定版本镜像，确保可回滚
docker compose -f /opt/apps/myapp/docker-compose.yml pull

# 3) 生产启动（后台）
docker compose -f /opt/apps/myapp/docker-compose.yml up -d

# 4) 查看容器状态与健康检查
docker compose -f /opt/apps/myapp/docker-compose.yml ps

命令解释：
- pull：提前拉取镜像，避免上线时卡在下载。
- up -d：后台启动服务。
- ps：查看运行状态与健康检查结果。

3. 常见故障排查流程（配置→镜像→网络→资源→依赖）#

3.1 配置问题#

# 检查环境变量是否加载
docker compose -f /opt/apps/myapp/docker-compose.yml config

# 查看容器内实际环境
docker exec -it myapp_api_1 env | grep DB_

3.2 镜像问题#

# 查看镜像是否存在/拉取成功
docker images | grep myapp

# 若拉取失败，检查仓库与登录
docker login registry.example.com
docker pull registry.example.com/myapp/api:1.4.2

3.3 网络问题#

# 查看网络是否创建
docker network ls

# 检查服务网络配置
docker inspect myapp_api_1 | grep -A5 Networks

3.4 资源与 OOM#

# 观察资源占用
docker stats

# 查看容器退出原因
docker inspect myapp_api_1 --format '{{.State.OOMKilled}} {{.State.ExitCode}}'

3.5 依赖不可达#

# 进入容器检查依赖连通
docker exec -it myapp_api_1 bash
curl -v http://db:3306  # 示例，实际需要 DB 地址

4. 日志与回滚#

# 按服务查看日志
docker compose -f /opt/apps/myapp/docker-compose.yml logs -f api

# 回滚思路：切换至上一版本镜像标签后重启
# 修改 docker-compose.yml 中 image 标签为 1.4.1
docker compose -f /opt/apps/myapp/docker-compose.yml up -d

5. 生产部署注意事项清单#

配置集中管理，敏感信息分离（env_file/外部密钥系统）。
数据服务优先外部托管或独立集群，Compose 仅部署业务服务。
明确端口暴露策略，仅对外暴露必要端口。
启用健康检查与重启策略，配合告警。

6. 练习#

将示例中的 api 服务镜像标签改为不存在的版本，观察 docker compose up 的错误信息并记录排错步骤。
将 web 的 healthcheck URL 改为无效地址，观察 depends_on 行为与容器状态变化。
设置 logging.max-size 为 1m，持续访问服务并查看日志滚动效果。