Docker Compose profiles怎样按环境启用不同服务

同一份 Compose 配置既要服务本地开发，又要容纳调试面板、迁移任务或测试容器时，profiles 是比复制多份 compose.yaml 更稳妥的切分方式。核心服务不写 profiles，始终启动；可选服务绑定到 debug、tools 等 profile，需要哪组再显式启用。

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

步骤一：准备一份带 profiles 的 Compose 文件

先在项目根目录打开 compose.yaml，保留真正的应用依赖为默认服务，把只在特定环境出现的组件标记出来。下面的例子中，backend 和 db 是基础运行单元，phpmyadmin 只在调试环境出现，db-migrations 只给一次性工具任务使用。

services:
  backend:
    image: example/backend:1.0
    # 核心服务不绑定 profile，所有环境都能启动
    depends_on:
      - db

  db:
    image: mysql:8.4
    # 数据库是核心依赖，保持默认启用

  phpmyadmin:
    image: example/phpmyadmin:1.0
    # 只有调试环境才需要数据库管理界面
    profiles: [debug]
    depends_on:
      - db

  db-migrations:
    image: example/backend:1.0
    command: ["./app", "migrate"]
    # 一次性迁移任务放进 tools，避免常规 up 自动运行
    profiles: [tools]
    depends_on:
      - db

保存后，重点看三处：profiles 的值必须是服务级数组；核心依赖不要误绑到 debug；一次性任务不要写成默认服务，否则每次启动都会带上它。

步骤二：用命令行按环境启用 profile

在项目目录打开命令行，执行基础启动命令时不附加 profile：

# 基础环境只启动没有 profile 的服务
docker compose up -d

# 调试环境额外启用 debug 服务
docker compose --profile debug up -d

# 同时启用多个可选服务组
docker compose --profile debug --profile tools up -d

基础命令预期只处理 backend 和 db；增加 debug 后才会把 phpmyadmin 纳入应用。需要所有 profile 时可以使用 docker compose --profile "*" up -d，但不建议把它当作生产默认入口，因为它会把测试或维护工具一并启动。

关闭时也要保持同样的边界。例如只关闭调试环境，可以执行：

# 按同一个 profile 清理可选服务与默认服务
docker compose --profile debug down

如果你的目标只是移除一个调试容器，优先写出服务名：docker compose down phpmyadmin。这样比无条件清理整个项目更容易控制影响面。

步骤三：用 COMPOSE_PROFILES 固化环境入口

脚本、Makefile 或 CI 环境通常不适合到处拼接 --profile。在启动命令前设置 COMPOSE_PROFILES 即可，多个 profile 用逗号分隔：

# 本地调试入口：启用 debug，其余默认服务仍会启动
COMPOSE_PROFILES=debug docker compose up -d

# 集成检查入口：同时启用调试界面和工具服务
COMPOSE_PROFILES=debug,tools docker compose up -d

环境变量只决定本次 Compose 模型中哪些 profile 有效，不会自动改变镜像、网络或数据卷。环境切换后仍应检查服务名和卷是否复用，避免把“服务未启动”误判成“数据被清理”。

步骤四：检查显式服务与依赖边界

有一个容易忽略的例外：直接指定可选服务时，不必先写 --profile。例如：

# 直接执行 tools 中的迁移任务；Compose 会按目标服务处理它
docker compose run --rm db-migrations

# 显式运行后移除一次性容器
docker compose rm -f db-migrations

上面的命令会针对 db-migrations 启动它声明的 db 依赖，但不会因为它和其他工具共用 profile 就把所有 tools 服务一起拉起。若依赖服务本身也绑定了另一个不匹配的 profile，就可能无法解析。最简单的规则是：核心依赖保持无 profile，或者让依赖与目标服务共享同一个 profile，并在修改后先执行配置展开检查。

最终确认时，基础环境应只看到核心服务；启用 debug 后应出现 phpmyadmin；单独运行迁移任务时，应能看到 db 被满足而不是整组工具被误启动。

常见问题

不写 profiles 的服务会被 profile 过滤掉吗？

不会。没有 profiles 的服务始终处于启用集合中，profile 只控制被标记服务的加入条件。

为什么设置了 COMPOSE_PROFILES 仍然没有启动某个服务？

先确认变量值是否用逗号分隔，再检查服务上的 profile 名称是否完全一致；最后用 docker compose config --profiles 查看 Compose 识别到的 profile。

能不能给数据库也加 debug profile？

只有在数据库确实是可选依赖时才这样做。多数项目的数据库是 backend 和调试工具的共同基础，保持默认启用更不容易造成依赖无法解析。

把核心服务和可选服务分开，Compose 文件就能同时承担开发、调试与维护入口。日常只用默认启动，临时任务通过显式 profile 或目标服务调用，环境边界会更清楚。