Docker Compose 常用命令详解

3. 依赖与启动控制

4. 扩缩容（替代废弃的 scale 命令）

5. 其他实用选项

四、核心使用场景与示例

1. 基础启动（开发环境）

# 前台启动所有服务（日志实时输出，按 Ctrl+C 停止）
docker compose up
# 后台启动所有服务（生产/测试环境常用）
docker compose up -d

2. 指定配置文件 + 项目名启动（多环境隔离）

# 生产环境配置 + 自定义项目名
docker compose -f docker-compose.prod.yml -p myapp-prod up -d

3. 强制构建镜像并启动

# 重新构建镜像 + 后台启动，确保使用最新代码
docker compose up -d --build

4. 扩缩容服务（无端口冲突前提）

# 将 web 服务扩到 4 实例，清理孤立容器
docker compose up -d --scale web=4 --remove-orphans
# 缩容到 2 实例
docker compose up -d --scale web=2 --remove-orphans

5. 仅启动单个服务（不启动依赖）

# 仅启动 web 服务，不启动 db/redis 等依赖
docker compose up -d --no-deps web

6. 强制重建容器（配置修改后生效）

# 修改配置后，强制重建所有容器，确保配置生效
docker compose up -d --force-recreate

7. 等待服务就绪（集成测试）

# 启动服务并等待健康检查通过，用于自动化测试
docker compose up --wait --wait-timeout 120

五、关键注意事项

1. 端口冲突问题

• 扩缩容时若服务配置了固定宿主机端口（如 8080:80），会因端口冲突失败，需改为随机端口（如 80）；
• 解决方案：使用随机端口 + 前端负载均衡（如 Nginx/Traefik）统一入口。

2. 依赖启动顺序

• depends_on 仅保证「启动顺序」，不保证「服务就绪」；
• 需配合 healthcheck + depends_on.condition: service_healthy 实现「就绪后启动」（Compose 3.9+ 支持）。

3. 数据持久化

• --renew-anon-volumes 会删除匿名卷数据，生产环境慎用；
• 持久化数据优先使用「命名卷」，避免匿名卷数据丢失。

4. 资源限制

• 单机 Compose 中，服务的资源限制（deploy.resources）仅对 Swarm 生效，单机需通过 --memory/--cpus 等 Docker 原生参数（需在 command 中配置）。

5. 与 docker compose down 联动

• docker compose up 会复用之前创建的网络 / 卷（除非用 down -v 删除）；
• 如需完全重置环境，先执行 docker compose down -v（删除容器 / 网络 / 卷），再执行 up。

六、常见问题排查

1. 容器启动失败（日志无输出）

# 方式 1：前台启动，查看实时日志
docker compose up <服务名>
# 方式 2：查看已创建容器的日志
docker compose logs <服务名>

2. 镜像拉取失败

# 强制拉取最新镜像
docker compose up -d --pull always
# 检查镜像名称/仓库是否正确
docker compose config

3. 依赖服务未启动

# 检查依赖配置
docker compose config | grep depends_on
# 手动启动依赖服务
docker compose up -d <依赖服务名>

4. 扩缩容后容器未删除

# 加 --remove-orphans 清理孤立容器
docker compose up -d --scale <服务名>=<目标数> --remove-orphans
# 手动删除孤立容器
docker compose rm -f <孤立容器名>

七、最佳实践

1. 开发环境

• 前台启动：docker compose up（实时查看日志，便于调试）；
• 代码更新后重建：docker compose up -d --build（快速更新镜像）。

2. 测试环境

• 后台启动 + 等待就绪：docker compose up -d --wait；
• 测试完成后清理：docker compose down -v（删除容器 / 网络 / 卷）。

3. 生产环境

• 后台启动 + 不重建已有容器：docker compose up -d --no-recreate；
• 更新服务：docker compose up -d --pull always --no-recreate <服务名>；
• 扩缩容：docker compose up -d --scale <服务名>=<实例数> --remove-orphans；
• 强制更新配置：docker compose up -d --force-recreate --no-build <服务名>。

4. 配置验证

• 启动前模拟执行：docker compose up --dry-run（检查配置语法、端口冲突等）；
• 验证最终配置：docker compose config（确认变量、依赖等生效）。

总结

docker compose up 是 Compose 服务启动的「一站式命令」，核心能力覆盖「构建→创建→启动→扩缩容」全流程。掌握其核心参数（如 -d、--scale、--force-recreate、--build），并结合不同环境的需求选择参数组合，可高效实现单机多服务的部署与更新。

docker compose logs

docker compose logs 是 Docker Compose 中用于查看容器化服务日志的核心命令，支持实时跟踪、筛选、格式化等操作，是排查服务运行异常的关键工具。

一、核心语法

# 基础用法：查看所有服务的日志
docker compose logs
# 查看指定单个/多个服务的日志（最常用）
docker compose logs <服务名 1>[服务名 2]
# 示例（compose 中有 web、db、redis 服务）
docker compose logs web
# 仅查看 web 服务日志
docker compose logs web db
# 查看 web + db 服务日志

二、核心参数（按使用频率 / 重要性排序）

三、高频组合用法（覆盖 90% 场景）

1. 实时跟踪单个服务日志（带时间戳）

docker compose logs -f -t web # 最常用：实时看 + 时间戳，便于定位问题时间点

2. 查看服务最近 N 行日志（带时间戳）

docker compose logs -t --tail 200 db # 查看数据库最后 200 行日志（带时间）

3. 筛选指定时间段的日志

# 查看今天 10 点到 11 点的 web 日志
docker compose logs --since 2025-12-16 10:00:00 --until 2025-12-16 11:00:00 web
# 查看最近 30 分钟的 redis 日志（相对时间）
docker compose logs --since 30m redis

4. 隐藏前缀 + 实时跟踪（精简日志输出）

docker compose logs -f --no-log-prefix web # 仅显示日志内容，无服务/容器前缀

5. 组合筛选 + 实时跟踪

# 实时查看 web 服务最近 100 行、带时间戳的日志
docker compose logs -f -t --tail 100 web

四、关键特性与注意事项

1. 日志前缀规则

默认日志每行前缀格式：[服务名] [容器 ID 前 12 位] [日志内容]，示例：

web_1 | 2025-12-16 10:05:23 [INFO] Server started on port 8080
db_1 | 2025-12-16 10:05:25 [Note] mysqld: ready for connections.

使用 --no-log-prefix 可移除前缀，仅保留日志内容。

2. 日志驱动兼容性

• docker compose logs 仅支持 Docker 日志驱动为 json-file（默认）、journald 的场景；
• 若日志驱动为 syslog、fluentd 等，需通过对应驱动的工具查看日志（如 journalctl 查看 journald 日志）。

3. 日志编码与乱码解决

若日志包含中文乱码，可通过管道转码：

# Linux/macOS
docker compose logs web | iconv -f GBK -t UTF-8
# Windows（PowerShell）
docker compose logs web | Out-File -Encoding utf8 web-logs.txt

4. 日志大小与清理

清理过大的日志（谨慎操作，Linux）：

truncate -s 0 $(docker inspect --format='{{.LogPath}}'<容器 ID>)

查看单个服务日志文件路径：

# 先获取服务对应的容器 ID
docker compose ps -q web
# 查看日志文件路径
docker inspect --format='{{.LogPath}}'<容器 ID>

5. 新旧命令兼容

• 新版 Docker Compose（v2+）：docker compose logs（无短横线）；
• 旧版 Docker Compose（v1）：docker-compose logs（有短横线）；
• 可通过 docker compose version 查看版本。

6. 日志排序

默认日志按时间正序输出，若需倒序（最新日志在前），可结合系统命令：

# Linux/macOS
docker compose logs --tail 100 web | tac

五、排障常见问题

1. 日志无输出：
   • 检查服务是否运行：docker compose ps <服务名>；
   • 检查容器是否正常启动：docker compose up -d <服务名>；
   • 确认日志驱动为 json-file：docker inspect --format='{{.HostConfig.LogConfig.Type}}' <容器 ID>。
2. 实时跟踪中断：
   • 容器重启会导致 --follow 中断，需重新执行命令；
   • 网络异常或 Docker 守护进程重启也会中断，检查 Docker 状态：systemctl status docker（Linux）。
3. 时间戳时区错误：
   • 日志时间戳默认使用 Docker 守护进程的时区；
   • 解决：启动容器时挂载时区文件，或在 Dockerfile 中设置时区。

总结

docker compose logs 是 Compose 服务日志排查的核心工具，核心掌握 -f（实时）、-t（时间戳）、--tail（行数）、--since/--until（时间筛选）四个参数，可覆盖绝大多数日志查看场景。结合日志驱动、编码、清理等细节，能高效定位服务运行中的问题。

docker compose build

docker compose build 是 Docker Compose 中用于构建 / 重新构建 Compose 配置中定义的服务镜像的核心命令，适用于自定义镜像（基于 Dockerfile）的场景。

一、核心语法

# 基础用法：构建所有服务的镜像
docker compose build
# 构建指定单个/多个服务的镜像（常用）
docker compose build <服务名 1>[服务名 2]
# 示例（compose 中有 web、db、redis 服务）
docker compose build web
# 仅构建 web 服务
docker compose build web db
# 构建 web + db 服务

二、关键参数（按使用频率排序）

三、高频使用场景与示例

1. 强制重新构建（忽略缓存）

适用于依赖更新、Dockerfile 逻辑修改后，避免缓存导致的构建不生效：

docker compose build --no-cache --pull web # 无缓存 + 拉取最新基础镜像

2. 传递构建参数

假设 Dockerfile 中有 ARG APP_PORT，compose.yml 中未定义，可通过命令行传递：

docker compose build --build-arg APP_PORT=8080 --build-arg ENV=prod web

3. 调试构建过程（显示完整日志）

默认构建日志会简化，用 --progress plain 可查看每一步的详细执行过程：

docker compose build --progress plain web

4. 并行构建多服务

多服务项目中加速构建（需确保服务间无构建依赖）：

docker compose build --parallel --pull web db redis

四、核心特性与注意事项

1. 构建上下文（Context）

• Compose 中每个服务的构建上下文由 compose.yml 中 build.context 定义（默认是 Compose 文件所在目录）；
• 构建时会将上下文目录下的所有文件（除 .dockerignore 排除的）发送给 Docker 守护进程，因此上下文目录尽量精简（避免传递大文件）。

示例 compose.yml 中的构建配置：

version: '3.8'
services:
  web:
    build:
      context: ./web-app # 构建上下文：当前目录下的 web-app 文件夹
      dockerfile: Dockerfile.prod # 自定义 Dockerfile 名称（默认 Dockerfile）
      args:
        VERSION: 1.0 # 预设构建参数（也可通过 --build-arg 覆盖）

2. 缓存机制

• Docker 构建默认使用缓存：只有当 Dockerfile 步骤、上下文文件或基础镜像变化时，才会重新执行对应步骤；
• --no-cache 会完全禁用缓存，适合调试或依赖强更新的场景（但会增加构建时间）。

3. 与 docker compose up 的联动

• docker compose up 会自动检测镜像是否存在，若不存在则触发构建；
• 若需强制重新构建后启动，可使用：

docker compose up --build web # 构建 web 并启动
docker compose up --build --force-recreate web # 构建 + 强制重建容器

4. 镜像命名规则

• Compose 构建的镜像默认命名规则：<项目名>_<服务名>:<标签>（标签默认 latest）；
• 项目名默认是 Compose 文件所在目录名，可通过 --project-name（或 -p）指定：

docker compose -p my-project build web # 镜像名：my-project_web:latest

5. 常见问题排查

• 构建上下文过大：检查 .dockerignore 文件，排除无关文件（如 node_modules/、logs/、.git/）；
• 缓存导致修改不生效：使用 --no-cache 强制重建，或修改 Dockerfile 中对应步骤的内容（如添加 RUN echo $(date) 打破缓存）；
• 构建参数传递失败：确保 Dockerfile 中用 ARG 定义参数（而非 ENV），且命令行 --build-arg 拼写正确；
• 基础镜像拉取失败：检查网络，或手动拉取基础镜像（如 docker pull nginx:alpine）后再构建。

六、完整示例（结合 Compose 配置）

1. 编写 docker-compose.yml

version: '3.8'
services:
  app:
    build:
      context: ./app # 构建上下文：app 目录
      dockerfile: Dockerfile # 自定义 Dockerfile（默认可省略）
      args:
        NODE_ENV: production # 预设构建参数
    ports:
      - "3000:3000"
  db:
    image: mysql:8.0 # 无需构建（直接使用官方镜像）
    environment:
      - MYSQL_ROOT_PASSWORD=123456

2. 构建 app 服务镜像

# 基础构建
docker compose build app
# 强制重新构建（无缓存 + 拉取最新基础镜像）
docker compose build --no-cache --pull app
# 传递自定义构建参数（覆盖预设的 NODE_ENV）
docker compose build --build-arg NODE_ENV=development app

总结

docker compose build 是自定义镜像场景的核心命令，核心价值是统一管理多服务的构建流程，结合参数可灵活控制构建行为（缓存、参数、并行等）。日常使用中，优先掌握 --no-cache、--pull、--build-arg 三个参数，可解决 90% 以上的构建需求。

docker compose config

docker compose config 是 Docker Compose 中用于验证、解析并输出最终生效的 Compose 配置的核心命令，核心价值是排查配置语法错误、查看变量 / 扩展后的最终配置、确认多文件合并结果，是调试 Compose 配置的必备工具。

一、核心语法

# 基础用法：验证并输出当前目录下 compose.yml 的最终配置
docker compose config
# 指定自定义 Compose 文件（覆盖默认的 compose.yml/compose.yaml）
docker compose -f <文件 1> -f <文件 2> config
# 仅验证配置（不输出内容）
docker compose config --quiet
# 示例
docker compose -f docker-compose.yml -f docker-compose.override.yml config
# 合并多文件并输出
docker compose config --services
# 仅列出所有服务名

二、核心参数（按使用频率 / 重要性排序）

三、高频使用场景与示例

1. 验证配置语法（最常用）

编写 Compose 配置后，先通过 config 验证是否有语法错误（如缩进、关键字拼写、变量未定义等），避免启动时报错：

# 验证并输出错误（如有）
docker compose config
# 仅验证，无输出（脚本中常用，通过返回值判断）
if docker compose config -q; then
  echo "配置合法"
else
  echo "配置错误"
  exit 1
fi

2. 查看变量插值后的最终配置

Compose 配置中常使用 ${ENV_VAR} 环境变量或 .env 文件中的变量，config 会输出变量替换后的最终配置，便于确认变量是否生效：

# 示例：.env 文件中有 APP_PORT=8080，compose.yml 中 ports: ["${APP_PORT}:80"]
docker compose config
# 输出中会显示 ports: ["8080:80"]

3. 查看多文件合并后的最终配置

Compose 支持多文件合并（如 docker-compose.yml + docker-compose.override.yml），config 会输出合并后的完整配置，排查覆盖逻辑问题：

# 合并主配置和覆盖配置并输出
docker compose -f docker-compose.yml -f docker-compose.prod.yml config

4. 仅提取关键信息（服务名 / 镜像 / 卷 / 网络）

快速获取配置中的核心元素，避免翻阅冗长配置文件：

# 列出所有服务名
docker compose config --services
# 输出：web db redis
# 列出所有镜像
docker compose config --images
# 输出：nginx:alpine mysql:8.0 redis:latest
# 列出所有卷
docker compose config --volumes
# 输出：data-volume app-cache
# 列出所有网络
docker compose config --networks
# 输出：default app-network

5. 解析镜像标签为摘要（确保镜像版本唯一）

将镜像标签解析为不可变的摘要，避免因标签更新导致镜像不一致：

docker compose config --resolve-image-digests
# 输出示例：image: nginx@sha256:abc123...（而非 nginx:alpine）

6. 禁用变量插值（查看原始配置）

如需确认配置中未替换的变量原始写法，使用 --no-interpolate：

docker compose config --no-interpolate
# 输出示例：ports: ["${APP_PORT}:80"]（保留变量，不替换）

7. 输出 JSON 格式配置（便于脚本解析）

通过 --format json 将配置转为 JSON 格式，方便用 jq 等工具解析：

# 输出 JSON 格式配置
docker compose config --format json
# 结合 jq 提取 web 服务的端口
docker compose config --format json | jq '.services.web.ports'

四、核心特性与注意事项

1. 配置解析规则

docker compose config 会严格按照 Compose 的优先级规则解析最终配置，优先级从高到低：

1. 命令行参数（如 -f 指定的文件、--env-file）；
2. 环境变量（如 COMPOSE_PROFILES、COMPOSE_PROJECT_NAME）；
3. .env 文件中的变量；
4. Compose 文件中的 environment 字段；
5. 内置默认值（如默认网络、默认项目名）。

通过 config 可直观看到这些规则生效后的最终结果。

2. 配置验证范围

• 验证语法：YAML 格式、关键字拼写（如 port 误写为 ports）；
• 验证逻辑：如端口格式、镜像名合法性、依赖关系（depends_on）；
• 不验证：镜像是否存在、网络 / 卷是否已创建、容器能否正常启动（仅验证配置本身）。

3. 多文件合并逻辑

当通过 -f 指定多个 Compose 文件时，config 会按后指定的文件覆盖先指定的文件的规则合并：

• 相同服务的相同字段：后文件覆盖前文件；
• 相同服务的不同字段：合并保留；
• 不同服务：全部保留。

示例：

# docker-compose.yml 中 web 服务 ports: ["80:80"]
# docker-compose.prod.yml 中 web 服务 ports: ["8080:80"]
docker compose -f docker-compose.yml -f docker-compose.prod.yml config
# 最终 web 服务 ports 为 ["8080:80"]（后文件覆盖）

4. 项目名与配置作用域

• 默认项目名是 Compose 文件所在目录名；
• 可通过 -p/--project-name 指定项目名，config 会输出该项目名下的配置：

docker compose -p my-project config # 输出 my-project 项目的配置

5. 支持的 Compose 版本

config 兼容所有 Compose 文件版本（如 2.x、3.x），会自动适配不同版本的语法规则，输出符合当前 Docker 版本支持的最终配置。

五、排障常见问题

1. 配置验证失败（返回非 0）：
   • 检查 YAML 缩进（必须用 2 个空格，禁止 tab）；
   • 检查变量是否定义（如 ${VAR} 未在 .env 或环境变量中定义）；
   • 检查关键字拼写（如 restart: always 误写为 restart: alway）。
2. 变量插值不符合预期：
   • 使用 --no-interpolate 查看原始变量，确认变量名拼写；
   • 检查 .env 文件路径（默认在 Compose 文件同级目录，可通过 --env-file 指定）；
   • 确认环境变量优先级：命令行环境变量 > .env 文件。
3. 多文件合并后配置异常：
   • 按 -f 指定顺序逐一验证：先单独查看第一个文件 docker compose -f 文件 1 config，再查看合并后的；
   • 确认覆盖规则：后文件的相同字段会覆盖前文件，而非追加。
4. 服务名 / 卷名重复：
   • config 会提示重复定义的错误，需检查多文件中是否有重复的服务 / 卷 / 网络名称。

总结

docker compose config 是 Compose 配置调试的'瑞士军刀'，核心场景包括：验证配置语法、查看变量 / 多文件合并后的最终配置、提取服务 / 镜像 / 卷等关键信息。掌握 --quiet（验证）、--services（列服务）、--format json（脚本解析）三个核心参数，可高效解决 Compose 配置的绝大多数调试问题。

docker compose exec

docker compose exec 是 Docker Compose 中用于在运行中的服务容器内执行命令的核心命令，相当于 docker exec 的 Compose 封装，支持直接通过「服务名」定位容器（无需记容器 ID），是日常运维、调试容器的高频工具。

一、核心语法

# 基础用法：在指定服务的容器内执行命令
docker compose exec <服务名><命令>[命令参数]
# 示例（compose 中有 web、db、redis 服务）
docker compose exec web ls /app # 在 web 容器内执行 ls /app
docker compose exec db mysql -uroot -p # 在 db 容器内登录 mysql
docker compose exec redis redis-cli # 在 redis 容器内执行 redis-cli

关键扩展语法（处理特殊场景）

# 执行交互式命令（如 bash/sh，最常用）
docker compose exec <服务名> bash # 进入容器的 bash 终端
docker compose exec <服务名> sh # 轻量容器（如 alpine）用 sh
# 指定用户执行命令（避免 root 权限）
docker compose exec -u <用户名/UID><服务名><命令>
# 针对多实例服务（scale 部署），指定具体容器实例
docker compose exec --index <实例序号><服务名><命令>

二、核心参数（按使用频率 / 重要性排序）

三、高频使用场景与示例

1. 进入容器交互式终端（最常用）

# 进入 web 容器的 bash（带伪终端 + 交互）
docker compose exec -it web bash
# 轻量镜像（如 alpine）无 bash，用 sh
docker compose exec -it web sh

2. 指定用户执行命令（非 root 权限）

# 以 www-data 用户执行命令
docker compose exec -u www-data web touch /var/www/html/test.txt
# 以 UID=1000、GID=1000 执行（避免用户名不存在）
docker compose exec -u 1000:1000 web id
# 输出 uid=1000 gid=1000

3. 指定工作目录执行命令

# 不进入容器，直接在 /app 目录执行 npm 安装
docker compose exec -w /app web npm install
# 对比：默认工作目录执行 vs 指定目录
docker compose exec web pwd
# 输出容器默认工作目录（如 /）
docker compose exec -w /app web pwd
# 输出 /app

4. 临时设置环境变量执行命令

# 临时设置数据库密码，执行查询
docker compose exec -e MYSQL_PWD=123456 db mysql -uroot -e "show databases;"
# 多环境变量
docker compose exec -e ENV=prod -e PORT=8080 web node server.js

5. 处理多实例服务（scale 部署）

# 先启动 3 个 web 实例
docker compose up -d --scale web=3
# 进入第二个 web 实例
docker compose exec --index 2 web bash
# 查看每个实例的 IP
for i in {1..3}; do
  docker compose exec --index $i web hostname -I
done

6. 后台执行耗时命令（不阻塞终端）

# 后台执行数据备份
docker compose exec -d db sh -c "mysqldump -uroot -p123456 app_db > /backup/db_$(date +%Y%m%d).sql"
# 查看后台命令的进程（进入容器后）
docker compose exec db ps aux | grep mysqldump

7. 从本地向容器传输内容（无文件拷贝）

# 本地创建文件内容，写入容器的 /app/test.txt
cat local-file.txt | docker compose exec -i web sh -c "cat > /app/test.txt"
# 交互式输入内容到容器文件
docker compose exec -i web sh -c "cat > /app/input.txt"
# 此时输入内容，按 Ctrl+D 结束输入

四、核心特性与注意事项

1. 与 docker exec 的区别

2. 命令执行的前提

• 目标服务的容器必须处于运行状态（docker compose ps <服务名> 查看状态为 Up）；
• 若服务有多个实例，默认执行第一个实例（--index=1）；
• 容器内必须存在要执行的命令（如 bash、mysql 等），否则报错 exec: "bash": executable file not found in $PATH。

3. 权限与安全

• --privileged 会赋予命令主机级别的权限，可能带来安全风险，仅在必要时使用；
• 避免用 root 用户执行非必要命令，优先用 -u 指定普通用户；
• 交互式终端中修改容器内文件会直接生效，但重启容器后（无卷挂载）会丢失。

4. 常见坑点

• 环境变量解析顺序：-e 指定的变量 > 容器原有环境变量 > Compose 配置的 environment；
• 命令参数含特殊字符：需用引号包裹，避免被宿主机 Shell 解析：

# 正确：容器内执行 `echo $PATH`（$PATH 由容器解析）
docker compose exec web sh -c "echo \$PATH"
# 错误：$PATH 被宿主机 Shell 解析，而非容器
docker compose exec web echo $PATH

• 伪终端导致脚本输出乱码：脚本中执行命令时，禁用 -t 或用 --no-TTY：

# 错误示例（脚本中用 -t 导致输出乱码）
docker compose exec -t web sh -c "echo hello"
# 正确示例（禁用伪终端）
docker compose exec --no-TTY web sh -c "echo hello"

5. 新旧命令兼容

• 新版 Docker Compose（v2+）：docker compose exec（无短横线）；
• 旧版 Docker Compose（v1）：docker-compose exec（有短横线）；
• 可通过 docker compose version 查看版本。

五、排障常见问题

1. 报错「container not running」
   • 原因：目标服务的容器未启动；
   • 解决：先启动服务 docker compose up -d <服务名>，再执行 exec。
2. 报错「executable file not found in $PATH」
   • 原因：容器内无该命令（如 alpine 镜像无 bash）；
   • 解决：换容器内存在的命令（如 sh 替代 bash），或安装对应工具（apk add bash）。
3. 交互式终端无颜色 / 光标异常
   • 原因：未加 -t 参数，未分配伪终端；
   • 解决：使用 docker compose exec -it <服务名> bash。
4. 多实例服务执行命令无响应
   • 原因：默认选第一个实例，但第一个实例可能异常；
   • 解决：用 --index 指定健康的实例，或重启服务 docker compose restart <服务名>。
5. 权限不足（Permission denied）
   • 原因：执行命令的用户无对应权限；
   • 解决：加 -u root 用 root 执行（临时），或调整容器内文件权限。

总结

docker compose exec 是 Compose 容器运维的核心命令，核心掌握 -it（交互式终端）、-u（指定用户）、-w（工作目录）、--index（多实例）四个参数，可覆盖 90% 以上的容器内命令执行场景。注意区分与 docker exec 的差异、避免伪终端在脚本中的坑，能高效完成容器内的调试和操作。

docker compose scale

docker compose scale 是 Docker Compose 中用于调整运行中服务的容器实例数量的命令，核心作用是快速扩缩容单个 / 多个服务（如把 web 服务从 1 个实例扩到 5 个）。需要注意的是：该命令在 Compose V2 中已被 docker compose up --scale 替代（标记为废弃），但仍兼容旧版用法。

一、核心语法（含新旧版对比）

1. 旧版（Compose V1 / 兼容写法）

# 基础用法：指定单个服务的实例数
docker compose scale <服务名>=<实例数>
# 扩缩容多个服务
docker compose scale <服务名 1>=<实例数 1><服务名 2>=<实例数 2>
# 示例：将 web 服务扩到 3 个实例，db 服务保持 1 个
docker compose scale web=3 db=1

2. 新版（Compose V2 推荐写法）

scale 命令已废弃，官方推荐用 up --scale（支持更多参数，如 -d 后台运行）：

# 扩缩容服务（需加 -d 避免阻塞终端）
docker compose up -d --scale <服务名>=<实例数>
# 示例：扩 web 到 3 个实例，不重启其他服务
docker compose up -d --scale web=3

二、关键参数（新版 up --scale 为主）

三、核心使用场景与示例

1. 基础扩缩容（最常用）

# 旧版：扩 web 服务到 5 个实例
docker compose scale web=5
# 新版（推荐）：后台扩 web 到 5 个实例，不重启现有容器
docker compose up -d --scale web=5 --no-recreate

2. 缩容（减少实例数）

# 旧版：将 web 从 5 个实例缩到 2 个
docker compose scale web=2
# 新版：缩容并清理多余容器（--remove-orphans 确保删除多余实例）
docker compose up -d --scale web=2 --remove-orphans

3. 多服务同时扩缩容

# 旧版：web 扩到 3 个，redis 扩到 2 个
docker compose scale web=3 redis=2
# 新版：多服务扩缩容（后台运行 + 不重建现有容器）
docker compose up -d --scale web=3 --scale redis=2 --no-recreate

4. 扩缩容同时强制重启（适用于配置更新）

# 扩 web 到 4 个实例，且强制重启所有 web 容器（加载新配置）
docker compose up -d --scale web=4 --force-recreate

四、核心特性与注意事项

1. 扩缩容的核心规则

• 扩容：新增的容器实例会继承原服务的所有配置（网络、卷、环境变量等），容器名格式为 <项目名>_<服务名>_<序号>（如 myapp_web_1、myapp_web_2）；
• 缩容：默认按「实例序号从大到小」删除容器（如缩 web 从 5 到 2，会删除 web_5、web_4、web_3）；
• 端口冲突：若服务配置了固定宿主机端口（如 ports: ["8080:80"]），扩容时会因端口冲突失败！需改为「随机端口」（如 ports: ["80"]）或使用负载均衡（如 Nginx/Traefik）。

2. 端口冲突解决（关键！）

扩缩容的核心前提是服务不绑定固定宿主机端口，示例：

# 错误配置（固定端口，扩容失败）
services:
  web:
    image: nginx
    ports: ["8080:80"]
# 多个实例会争抢 8080 端口
# 正确配置（随机宿主机端口，扩容无冲突）
services:
  web:
    image: nginx
    ports: ["80"]
# Docker 会分配随机宿主机端口（如 32768:80、32769:80 等）

3. 数据持久化注意

• 若服务使用「匿名卷 / 绑定挂载」，不同实例的数据不共享（如 web 实例各自有独立的文件目录）；
• 需共享数据时，应使用「命名卷」或外部存储（如 NFS、Redis）：

services:
  web:
    image: nginx
    volumes:
      - app-data:/app # 命名卷，所有实例共享
volumes:
  app-data: # 定义命名卷

4. 与 docker compose ps 联动（验证扩缩容结果）

扩缩容后，可通过 ps 查看所有实例状态：

docker compose ps web
# 列出所有 web 实例
# 输出示例：
# NAME COMMAND STATUS PORTS
# myapp_web_1 "/docker-entrypoint.…' Up 2 minutes 0.0.0.0:32768->80/tcp
# myapp_web_2 "/docker-entrypoint.…' Up 2 minutes 0.0.0.0:32769->80/tcp
# myapp_web_3 "/docker-entrypoint.…' Up 2 minutes 0.0.0.0:32770->80/tcp

5. 废弃说明（重要！）

• Compose V2 中 docker compose scale 已标记为「废弃」，执行时会提示：WARNING: The scale command is deprecated. Use the up command with --scale instead.；
• 原因：scale 仅能调整实例数，而 up --scale 可结合 -d、--no-recreate 等参数，更灵活且兼容 Compose 的完整生命周期管理。

6. 不支持的场景

• 服务配置了 deploy.replicas（Swarm 模式）：scale/--scale 仅适用于单机 Compose，Swarm 需用 docker service scale；
• 服务依赖 depends_on 且依赖服务未启动：需先启动依赖服务；
• 只读容器 / 特权容器：扩缩容会继承这些配置，但需确保权限足够。

五、排障常见问题

1. 扩容失败：端口已被占用
   • 原因：服务配置了固定宿主机端口（如 8080:80）；
   • 解决：改为随机端口（ports: ["80"]），或使用负载均衡器统一入口。
2. 缩容后容器未删除
   • 原因：未加 --remove-orphans（新版），或旧版 scale 未清理孤立容器；
   • 解决：执行 docker compose up -d --scale <服务名>=<目标数> --remove-orphans，或手动删除：docker compose rm -f <多余容器名>。
3. 扩缩容后服务不可用
   • 原因：实例间数据不共享（如未用命名卷），或负载均衡未配置；
   • 解决：使用命名卷共享数据，搭配 Nginx/Traefik 实现实例负载均衡。
4. 报错「scale is deprecated」
   • 原因：使用 Compose V2 执行 scale 命令；
   • 解决：改用 docker compose up -d --scale <服务名>=<实例数>。

总结

docker compose scale 是单机 Compose 扩缩容的快捷命令，但已被新版 up --scale 替代。核心使用要点：

1. 避免固定宿主机端口，防止扩容冲突；
2. 用命名卷实现实例数据共享；
3. 新版优先用 docker compose up -d --scale <服务名>=<实例数>；
4. 缩容时加 --remove-orphans 清理多余容器。

该命令适合单机测试 / 小规模扩缩容，生产环境大规模扩缩容建议使用 Docker Swarm/K8s 等编排工具。