Compose profiles 怎样按 profile 启停服务

Compose profiles 适合把一份 Compose 配置里的核心服务和可选服务分开管理：不写 profiles 的服务默认参与启动，写了 profile 的服务只有在对应 profile 被激活时才参与。最常用的启动方式是 docker compose --profile debug up -d，也可以通过 COMPOSE_PROFILES=debug 激活同名 profile。

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

先记住一个范围规则：profile 只作用于声明它的 service，不会让整个 Compose 项目切换环境。数据库和应用这类核心服务通常不写 profile；调试面板、迁移工具或一次性任务再放入 debug、tools 等 profile。

第一步：给可选服务配置 profiles

先在项目目录创建或整理 compose.yaml。下面让 api 和 db 始终可用，把管理面板和迁移任务分别放入 debug 与 tools。一个 service 可以属于多个 profile，但 profile 名称需要以字母或数字开头，并由字母、数字、下划线、点或短横线组成。

services:
  db:
    image: postgres:16
    # 核心数据库不绑定 profile，默认会参与 Compose 启动

  api:
    image: example/api:dev
    depends_on:
      - db
    # API 同样保持常驻，便于其他可选服务复用

  adminer:
    image: adminer:latest
    profiles: [debug]
    depends_on:
      - db
    # 调试面板只有激活 debug 时才加入项目

  migrate:
    image: example/api:dev
    command: ["./app", "migrate"]
    profiles: [tools]
    depends_on:
      - db
    # 一次性迁移任务归入 tools，避免每次 up 都运行

直接执行 docker compose up -d 时，Compose 会启动 db 和 api，不会启动 adminer 或 migrate。顶层的网络、卷等元素不受 profile 过滤；profile 过滤的是 service 是否进入当前模型。

第二步：用 --profile 启动一个或多个 profile

需要调试面板时，在项目目录执行下面的命令：

# 启动默认服务，并额外启用 debug profile
docker compose --profile debug up -d

# 同时启用 debug 和 tools 两个 profile
docker compose --profile debug --profile tools up -d

# 也可以用环境变量传入逗号分隔的 profile 名称
COMPOSE_PROFILES=debug,tools docker compose up -d

这三种写法的共同点是：没有 profile 的 db、api 仍会启动，匹配 debug 的 adminer 和匹配 tools 的 migrate 才会被加入。命令行显式传入的 --profile 优先级高于对应环境变量，排查脚本时尽量只保留一种来源。

第三步：停止服务时先分清项目范围

启动 profile 时，Compose 管理的是当前项目的服务集合。使用 down 会按项目范围停止并移除当前模型里的容器、网络等资源，所以不要把它误认为“只关闭这个 profile”。例如：

# 关闭 debug profile 对应的项目运行环境；核心服务也会随项目一起处理
docker compose --profile debug down

# 只想暂时停掉调试面板时，按 service 名称处理
docker compose stop adminer

# 只运行 tools 中的迁移任务，显式指定 service 会自动启用它的 profile
docker compose run --rm migrate

显式指定带 profile 的 service 时，Compose 会自动激活这个 service 的 profile，并启动它声明的依赖；同 profile 的其他 service 不会因为它被点名就全部启动。比如运行 migrate 会带上 db，但不会自动启动 adminer。这正适合一次性迁移或调试命令。

第四步：profile 不生效时检查这四个位置

1. 检查归属：确认目标 service 的 profiles 拼写和命令中的 profile 完全一致；未声明 profile 的核心 service 不需要额外激活。
2. 检查依赖：如果被激活的 service 依赖另一个也被 profile 限制的 service，两个 profile 必须能同时激活，否则 Compose 可能因为依赖不在当前模型而报错。
3. 检查命令范围：docker compose up 不会启动带 profile 的 service；docker compose --profile "*" up 才表示启用所有 profile。
4. 检查当前配置：用 docker compose config --profiles 查看 Compose 识别到的 profile 名称，再用 docker compose config --services 对照服务清单。

结论与常见问题

Compose profiles 的最小闭环是：核心 service 不写 profile，可选 service 用 profiles 分类；启动时用 --profile 或 COMPOSE_PROFILES 激活；停止前区分项目级 down 和单 service 的 stop；遇到依赖错误则检查两个 service 是否处在同一组可激活的 profile 中。

不写 profiles 的服务会不会被 profile 命令排除？

不会。没有声明 profiles 的 service 始终处于启用状态，普通 up 和带 --profile 的 up 都会把它纳入当前项目。

可以一次开启多个 profile 吗？

可以。命令行重复传入多个 --profile，或者在 COMPOSE_PROFILES 中使用逗号分隔名称即可；如果只是点名一个带 profile 的 service，则只会自动处理它和声明的依赖。

为什么显式运行工具时，同 profile 的面板没有一起启动？

显式目标只会自动激活目标 service 及其依赖，不会把同 profile 的所有 service 都当作目标。需要一起启动面板时，显式使用 --profile debug。

相关官方资料：https://docs.docker.com/reference/compose-file/profiles/、https://docs.docker.com/reference/cli/docker/compose/。