Docker Compose profiles与depends_on组合时为什么依赖服务没有启动

Docker Compose 中，profiles 决定服务是否进入当前配置模型，depends_on 决定服务之间的启动与移除关系。依赖服务没有出现时，先不要只盯着启动命令：沿着 services.*.profiles 和 depends_on 检查两边的 profile 边界，再区分“依赖服务默认可用”“依赖服务被另一个 profile 限制”和“只显式点名了目标服务”这三种情况。

官方地址：https://docs.docker.com/compose/how-tos/profiles/

先给结论：如果目标服务属于某个 profile，而它的依赖服务没有 profile，显式运行目标时 Compose 可以带起这个依赖；如果依赖服务也被 profile 限制，就要让两个服务共享可用 profile、先单独启动依赖，或把依赖服务改成默认服务。需要启动同 profile 的其他服务时，则要显式使用 --profile 或 COMPOSE_PROFILES。

第 1 步：先确认 profile 与依赖写在哪里

操作入口是“项目目录 → compose.yaml → services”。先把目标服务、依赖服务和 profile 分别记下来，避免把服务名当成 profile 名。下面的配置把数据库设为默认服务，把迁移任务放入 tools profile：

# db 没有 profiles，属于默认服务集合
services:
  db:
    image: postgres:18

  # 迁移任务只在 tools profile 下作为可选服务
  db-migrations:
    image: demo-backend
    command: ./app migrate
    profiles: [tools]
    # 目标服务依赖 db，但这里仍要继续检查 db 是否被别的 profile 限制
    depends_on:
      - db

  # 同一个 tools profile 的其他服务不会因显式运行迁移任务而自动全部启动
  adminer:
    image: adminer
    profiles: [tools]

这个例子有三个重要事实：tools 是 profile，db-migrations 和 adminer 是服务；db 没有 profile，所以默认参与配置；db-migrations 的依赖只指向 db，并不等于“自动启动 tools 组内所有服务”。

第 2 步：分别查看声明过的 profile 和当前服务模型

在“项目目录 → Compose 配置 → 配置检查命令”路径执行下面的命令。第一条只查看配置文件里出现过的 profile，第二条查看没有额外启用 profile 时的服务集合：

# 列出 compose.yaml 声明过的 profile 名称
docker compose config --profiles

# 查看当前参数下进入 Compose 模型的服务
docker compose config --services

对上面的示例，config --profiles 应能列出 tools；默认执行 config --services 时，重点是确认 db 是否在集合中，以及 db-migrations 和 adminer 是否仍被 profile 过滤。这里的两个命令回答的是不同问题：前者查声明，后者查当前解析结果。

第 3 步：区分显式目标与整组 profile

当用户只想执行一次迁移任务时，可以显式指定目标服务；当用户想把 tools 组内的可选服务一起纳入模型，则应显式启用 profile。不要把这两个入口混为一谈：

# 显式运行带 tools profile 的目标服务，Compose 会处理它和可解析的 db 依赖
docker compose run db-migrations

# 显式启用整个 tools profile，再查看该参数下的服务集合
docker compose --profile tools config --services

# 脚本中也可以用环境变量表达同一个 profile 选择
COMPOSE_PROFILES=tools docker compose config --services

检查时可以按下面的表格记录结果：

第 4 步：处理依赖服务也被 profile 限制的情况

最容易误判的场景是依赖服务也写了 profiles，但 profile 名与目标服务不一致。例如把数据库放到 data，把迁移任务放到 tools，只启用 tools 就无法得到一个完整的可解析依赖边界。此时有三种配置方向：

services:
  # 方案一：核心依赖不设 profile，让它始终属于默认服务
  db:
    image: postgres:18

  # 目标服务与核心依赖的关系保持明确
  db-migrations:
    image: demo-backend
    profiles: [tools]
    depends_on:
      - db

  # 方案二：如果依赖也必须可选，就让双方共享能同时启用的 profile
  # db:
  #   profiles: [tools]
  # db-migrations:
  #   profiles: [tools]

第三种方向是先单独启动依赖，再运行目标任务，但这会把依赖生命周期交给运维命令管理。选择哪种方式取决于数据库是否属于所有环境的核心服务。不要只通过增加一个 profile 名来“碰运气”，要让目标服务与依赖服务在同一份配置解析结果中同时存在。

第 5 步：不要把启动顺序当成健康检查

即使 db 已经进入服务模型，depends_on 的短语法也只保证依赖服务先启动，不保证数据库已经完成初始化并可以接受连接。如果问题从“依赖服务没有启动”变成“应用启动后连接失败”，应把排查重点转到 healthcheck 和长语法条件：

services:
  db:
    image: postgres:18
    # 用健康检查表达“可接受连接”，而不只是容器已运行
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    image: demo-web
    # 只有健康状态满足后，Compose 才继续处理 web
    depends_on:
      db:
        condition: service_healthy

常见问题

为什么 config --profiles 有 tools，但 db-migrations 仍不在服务列表？

因为前者只列出声明，后者按当前启用参数解析。补上 --profile tools 或 COMPOSE_PROFILES=tools 后再比较；如果显式执行的是 docker compose run db-migrations，则应另外检查它的 depends_on 依赖。

目标服务和依赖服务属于不同 profile，应该怎么改？

让依赖服务成为默认服务、让两者共享同一个可启用 profile，或者先单独启动依赖。核心判断是：同一次配置解析中，目标与依赖必须都能进入 Compose 模型。

depends_on 已经写了，为什么数据库仍然连接失败？

短语法只表达启动顺序，不代表数据库已经健康。为数据库补充 healthcheck，再用 condition: service_healthy 表达应用真正需要的就绪条件。

最后复查这三项

完成修改后，沿“compose.yaml → services.*.profiles → depends_on → config --profiles → config --services”复查一遍。确认 profile 名是声明过的、目标服务与依赖服务能同时进入模型，并且没有把同 profile 的其他服务误认为依赖。这样就能把“没启动”拆成配置过滤、profile 未启用、显式目标范围和健康状态四类问题。