Docker Compose profiles怎么配置或排查

Docker Compose profiles 适合把“默认必需服务”和“按需使用的工具”放进同一个 Compose 文件。例如数据库和 API 每次都启动，Adminer、调试代理或一次性迁移工具只有排查问题时才打开。关键规则是：没有 profiles 的服务始终启用；写了 profiles 的服务，只有对应 profile 被激活时才参与默认操作。

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

先把可选服务放进 profiles

在项目目录打开 compose.yaml，沿着“services → 服务名 → profiles”添加配置。下面把 api 和 db 作为默认服务，把 adminer 放到 debug profile。示例中的镜像名只用于演示配置位置，实际项目替换成自己的镜像。

services:
  api:
    image: example/api:dev
    depends_on:
      - db

  db:
    image: postgres:16

  adminer:
    image: adminer:4
    profiles: [debug]
    depends_on:
      - db

注意不要把 db 一起放进 debug，否则普通执行时数据库也会消失。保存后，未启用 profile 的预期集合是 api、db；adminer 应暂时不在其中。

用 config 预览，再启动指定 profile

先不要急着启动，打开项目目录的终端执行：

# 先查看默认服务集合，确认可选服务没有误加入
docker compose config --services

# 激活 debug 后预览最终服务集合
docker compose --profile debug config --services

# 确认集合正确后，在后台启动核心与调试服务
docker compose --profile debug up -d

第二次输出应该比第一次多出 adminer。随后执行 docker compose ps，如果核心服务和 adminer 都显示为运行或健康状态，就完成了这次配置。多个 profile 可以重复写 --profile，例如 --profile debug --profile test。

profile 不生效时按三处检查

第一处看激活方式。命令行方式是 docker compose --profile debug up -d；环境变量方式是：

# 环境变量只在当前命令前生效，适合脚本或 CI
COMPOSE_PROFILES=debug docker compose up -d

# 用最终模型确认变量确实被 Compose 读取
COMPOSE_PROFILES=debug docker compose config --services

# 查看容器是否真的创建并运行
docker compose ps

第二处看 profile 名称。名称必须与服务上的值完全一致，debug 和 Debug 不是同一个选择。第三处看依赖关系：显式运行某个带 profile 的服务时，Compose 可以自动启动它的依赖；但如果依赖本身也被另一个不匹配的 profile 限制，就需要把两个 profile 同时启用，或让基础依赖不配置 profile。排查时优先看 config --services，不要只凭容器列表猜配置是否生效。

停止与验收：只保留你需要的服务

调试完成后，可以用相同的 profile 停止并移除这一组资源：

# 关闭默认服务与 debug 服务，避免调试工具长期暴露
docker compose --profile debug down

# 只停止某个可选服务时，直接指定服务名
docker compose stop adminer

最后复核三件事：compose.yaml 中核心服务没有误写 profile；启用 profile 后 config --services 能列出目标工具；ps 的状态与预期一致。这样配置既保留了单文件协作，又不会让调试组件在每次启动时占用端口。

常见问题

不写 --profile 时为什么看不到 adminer？

这是正常行为。adminer 被标记为 debug，默认操作只处理没有 profile 的服务；加上 --profile debug 或设置 COMPOSE_PROFILES=debug 即可。

可以一次启用所有 profiles 吗？

可以使用 docker compose --profile "*" up。但生产环境不建议把测试、调试工具全部打开，应按用途选择 profile。

为什么显式运行服务时 profile 看起来被绕过了？

直接指定某个服务名时，Compose 会把该服务视为明确目标并运行它；这不代表同 profile 的其他服务也会自动启动，依赖关系仍需单独检查。