Container-Compose 是一款为 Apple Container 打造的 Docker Compose 类编排工具，让 Mac 用户用熟悉的docker-compose.yml一键拉起多容器应用。它的两大核心能力——depends_on拓扑排序决定服务启动顺序，profiles画像机制决定哪些服务该被启用——正是本文要讲透的部分。理解它们，你就能精准控制up时谁先启动、谁被跳过、遇到循环依赖如何报错。

🧭 先建立一个直觉：两个问题

当你运行container-compose up时，工具其实要回答两个独立的问题：

1. 启动顺序：多个服务谁先谁后？—— 由depends_on+ 拓扑排序解决。
2. 启动范围：哪些服务该被拉起，哪些该忽略？—— 由profiles+ 服务筛选解决。

这两层逻辑在源码中解耦得非常干净，下面分别拆解。

📊 depends_on 如何决定启动顺序（拓扑排序）

三种depends_on写法都被支持

Container-Compose 解析depends_on时，同时兼容三种常见形式（见 Service.swift）：

映射形式中的条件由 ServiceDependency.swift 定义，支持三种：

• service_started（默认）：依赖服务启动即可
• service_healthy：依赖服务通过 healthcheck
• service_completed_successfully：依赖服务成功跑完

拓扑排序算法

核心实现在topoSortConfiguredServices（Service.swift），采用经典的DFS + 三色标记（visited已完成 /visiting访问中）：

visit(服务): 若处于"访问中" → 说明遇到环，抛出循环依赖错误 先递归处理它 depends_on 的每个依赖 再把自身加入有序列表

结果保证：每个服务一定排在它的所有依赖之后。比如web → app → db，排序结果必然是db, app, web。

⚠️循环依赖会被拦截。一旦web依赖app、app又依赖web，排序会直接抛出Cyclic dependency detected错误（见 ServiceDependencyTests.swift），绝不允许带着环去启动。

一个容易忽略的细节：缺失依赖不报错

如果depends_on写了一个并不存在的服务名（可能是被 profile 排除掉的），工具不会崩溃，而是安全地忽略它。这为 profiles 机制留了口子（下文详述）。

⚡ 并行启动的"波次"模型

光有线性顺序还不够。Container-Compose 还实现了dependencyLevels（Service.swift），把所有服务划分成一个个"波次"（wave）：

• 波次 0：没有任何依赖的服务
• 波次 k：所有依赖都落在更早波次的服务

同一波次内的服务彼此独立，因此可以并发container run拉起，缩短整体启动时间。

以一张"菱形"依赖为例（front依赖web+api，二者都依赖db）：

波次 0: [db] 波次 1: [web, api] ← 两者可同时启动 波次 2: [front]

线性链web → app → db则退化成三波、每波一个服务，无法并行。这套分组逻辑的边界情况（自依赖、环、缺失依赖）都在 ParallelSchedulerTests.swift 里被逐一覆盖。

🎛️ profiles 画像机制：按需裁剪服务

profiles是 Compose 规范里的一个"开关门"，用来把某些默认不启动的服务隔离起来——典型的如调试工具、测试桩、备用后端。

规则很简单

在 Service.swift 的isProfileEligible里：

• 没有profiles的服务：永远 eligible，默认就启动。
• 有profiles的服务：只有当它至少一个画像处于激活状态时才启动。

三种"激活画像"的方式

1. 命令行--profile（可重复）：

   container-compose up --profile debug

2. 环境变量COMPOSE_PROFILES（逗号分隔）：

   COMPOSE_PROFILES=debug,frontend container-compose up

3. 两者合并生效——合并逻辑见 ComposeFileOptions.swift。

两个会绕过画像门槛的特殊情形

这是新手最容易踩坑、也最体现 Compose 规范严谨性的地方（见selectServices，Service.swift）：

换句话说：画像门槛只约束"默认全量"这一条路径。只要你显式点名，或它是别人离不开的依赖，就会被放行。

举例：web（无画像）依赖db（画像debug）。普通up时db因画像未激活本不该启动，但因为它是web的依赖，会被自动带入——保证依赖链完整，避免web启动后找不到db。

🔁 一次up背后的完整流程

把上面所有环节串起来，up的实际执行路径是：

1. 加载并解析docker-compose.yml（见 ComposeProject.swift 的orderedServices）。
2. 校验点名服务：若显式指定的服务名不存在，抛no such service: <name>，而不是静默空转（Errors.swift）。
3. 拓扑排序得到基础顺序。
4. profiles 筛选 + 依赖展开，确定最终启动集合。
5. 按依赖波次逐个拉起，每个服务启动前调用waitForDependencyConditions（ComposeUp.swift）检查依赖是否满足对应 condition。
6. 条件不满足时抛出精确错误，例如service_healthy未达成会提示...is not healthy。

🩺 常见报错速查

完整错误定义见 Errors.swift。

📁 关键源码位置一览

✅ 小结

• depends_on+ 拓扑排序保证"依赖先于被依赖"，并对循环依赖、缺失依赖都有明确、安全的处理。
• 波次分组让独立服务可以并发启动，在正确性的前提下压缩启动时间。
• profiles画像机制用"门槛 + 例外"两把钥匙，实现按需启用，同时保证显式点名和依赖传递永远优先。

掌握这两套机制，你就能在 Mac 上用 Apple Container 从容驾驭复杂的多容器应用编排了 🚀