Docker Compose profiles 列出可用配置并核对当前启用状态的排查方法

Docker Compose 排查 profiles 时，先别急着改 compose.yaml。最稳妥的顺序是：先列出文件里声明过的 profile，再用同一组启用参数解析服务集合，最后对照命令中显式指定的服务。这样可以区分“profile 根本不存在”“profile 没有激活”和“服务被显式点名启动”这三种看起来相似的现象。

官方地址：https://docs.docker.com/reference/cli/docker/compose/config/

第 1 步：沿文件路径确认 profile 的声明位置

操作路径可以固定为“Compose 工作区 → 文件树 → compose.yaml → services.*.profiles”。没有 profiles 字段的服务属于默认集合；写了 profiles: [debug] 的服务，只有对应 profile 生效时才会进入普通的服务解析结果。

# 无 profiles 的服务默认参与解析
services:
  backend:
    image: demo-backend
  db:
    image: mysql
  # debug profile 只在启用 debug 时进入普通服务集合
  phpmyadmin:
    image: phpmyadmin
    profiles: [debug]
  # tools profile 用于一次性迁移任务
  db-migrations:
    image: demo-backend
    profiles: [tools]
    depends_on:
      - db

这里先记下三个实体：profile 名是 debug、tools，服务名是 phpmyadmin、db-migrations。服务名和 profile 名不是一回事，后面的命令核对必须分别记录。

第 2 步：列出文件中可用的 profile

在“项目目录 → Compose 配置 → 配置检查命令”路径执行下面的命令。它只回答“文件里定义过哪些 profile”，不会替你启用服务。

# 在包含 compose.yaml 的项目目录执行，先查看声明过的 profile
docker compose config --profiles

# 用配置解析服务清单，但不启动容器
docker compose config --services

按上面的示例，第一条命令应能看到 debug 和 tools；第二条命令默认只包含 backend 与 db。如果 profile 名没有出现在第一条结果中，继续修改启动参数没有意义，应先回到 services.*.profiles 检查拼写和缩进。

第 3 步：用同一参数核对实际服务集合

操作路径是“配置检查命令 → 启用 profile 字段 → 服务集合结果”。不要只看 docker compose ps，因为它反映的是容器状态；排查 profiles 时更适合先看配置解析结果。

# 只启用 debug，核对默认服务和 debug 服务是否一起出现
docker compose --profile debug config --services

# 用环境变量表达同一个选择，避免脚本和手工命令不一致
COMPOSE_PROFILES=debug docker compose config --services

# 同时启用 debug 与 tools，逗号分隔多个 profile
COMPOSE_PROFILES=debug,tools docker compose config --services

可以把结果整理成一张小清单：

第 4 步：处理“看不到服务”与“多出服务”

如果命令行只指定了一个带 profile 的服务，Compose 会按显式目标处理它，并带上声明的 depends_on 依赖；同一个 profile 下的其他服务不会因为“同组”就自动全部启动。反过来，使用 --profile debug 或 COMPOSE_PROFILES=debug，才是启用整组服务的表达方式。

# 只检查 tools profile 中的迁移服务及其依赖边界
docker compose run db-migrations

# 需要整组 debug 服务时，显式启用 profile
docker compose --profile debug up -d

# 需要把所有 profile 都纳入解析时使用星号，避免漏掉可选服务
docker compose --profile "*" config --services

修正后再执行一次 config --profiles 和 config --services，把“profile 列表、启用方式、服务集合”一起记录到部署说明中。只记录容器是否 Running，无法解释为什么某个服务根本没有进入 Compose 模型。

常见问题

为什么 config --profiles 有结果，但 config --services 没有对应服务？

前者列出声明，后者按当前启用参数解析服务。补上 --profile 名称 或 COMPOSE_PROFILES 后再比较。

显式运行一个 profile 服务会不会启动同组服务？

不会自动启动同 profile 的全部服务，通常只处理目标服务和它的依赖；要启动整组，请显式启用 profile。

怎样判断是 profile 拼写错误还是服务被过滤？

先看 config --profiles 是否存在该名称，再看启用参数下的 config --services，两步能把问题拆开。