文档

English · Polski · 简体中文

Docker Compose

Container Desktop 在 Apple 的 container CLI 之上运行 docker-compose.yml 定义的 stack —— 而该 CLI 本身并不支持 compose。应用会解析你的 YAML，并把每个服务翻译成普通的 container run 调用：没有额外的守护进程，也没有隐藏状态。通过 容器 → Compose… 打开，粘贴 YAML 然后点击运行。

对于每个项目，应用会：

创建以项目命名的 项目网络（取自顶层 name: 或对话框中的字段），
按 depends_on 的顺序启动服务，并实时流式显示每个服务的输出，
为容器打上 compose.project / compose.service 标签，因此它们会在容器列表中分组显示，可批量启动 / 停止 / 删除。

支持的服务键

键	说明
`image`	必填。不支持 `build:` —— 请指向一个现成的镜像。
`container_name`	覆盖默认的 `<项目>-<服务>` 名称。
`command` / `entrypoint`	字符串或列表。多段 entrypoint（例如 `["dotnet", "dbmgr.dll"]`）会被正确翻译。
`environment`	支持映射和列表两种写法。
`ports`	短语法（`"8080:80"`，可加 `/udp`）和长语法。
`volumes`	`源:目标[:ro]`；命名卷必须已经存在。
`mem_limit` / `cpus`	虚拟机资源限制（也支持 `deploy.resources.limits`）。默认为 1 GB —— 吃内存的初始化任务（例如数据库初始化）通常需要 `mem_limit: 4g`。
`depends_on`	列表或映射（除 service_started 之外的条件会被忽略并给出警告）。
`x-init`	Container Desktop 的扩展 —— 参见 x-init 任务。

host.containers.internal

在 environment 的值或 command 中的任意位置使用主机名 host.containers.internal，即可从容器内部访问 你的 Mac（相当于 Docker 的 host.docker.internal）。

environment:
  DB_SERVER: "host.containers.internal,1433"   # 运行在宿主机上的 SQL Server

为什么用别名而不是 IP：每个 compose 项目都会得到 自己的 vmnet 网络和 自己的 子网，因此宿主机网关地址在不同项目间各不相同，甚至会在重启 container 服务后变化（例如 192.168.64.1 与 192.168.65.1）。应用会在创建项目网络后立即 inspect 它，并把别名替换为真实的网关 IP —— 该映射会打印在进度日志中。

宿主机上的服务必须监听所有网络接口（0.0.0.0），而不是只监听 127.0.0.1，否则无法从 vmnet 子网访问。其他 Container Desktop 项目、或宿主机上 Docker Desktop 发布的端口，也可以用同样的方式访问。

服务主机名（/etc/hosts 互写）

服务之间通过 容器名 互相访问 —— 例如在默认命名下，项目 shop 中的服务 server 就是 shop-server：

environment:
  API_URL: "http://shop-server:22000"

container 1.0.0 自带一个用于容器名的 DNS 解析器，但它从来匹配不上：注册名称时不带 FQDN 结尾的点，而 DNS 查询到达时已经被规范化，于是每次查询都以 SERVFAIL 失败。Container Desktop 绕开了这一点：每个服务启动后，应用会读取它的 IP，并在项目内所有服务之间互相写入 /etc/hosts 条目（进度日志会显示每一条映射）。

这些条目写在容器内部，因此只在容器被 重新创建 之前有效。如果你手动停止再启动某个容器、而它的 IP 变了，请用"替换已有容器"重新运行 compose 以刷新这些条目。

x-init 任务

给某个服务加上 x-init: true，它就会作为 一次性初始化任务 运行 —— 例如用同一个镜像、但不同的 entrypoint 来创建数据库。初始化任务会先于所有常规服务、按顺序执行到结束；只有当每个初始化任务都成功退出后，常规服务才会启动。

services:
  dbinit:
    image: registry.example.com/server:1.0
    x-init: true
    entrypoint: ["dotnet", "dbmgr.dll"]
    command: create mydb --sqlserver "host.containers.internal,1433" --recreate

  server:
    image: registry.example.com/server:1.0
    # 只有在 dbinit 以退出码 0 结束后才启动

初始化任务失败会中止整次运行；它的容器会被保留，方便你查看日志（成功的初始化容器会自动清理）。
"跳过初始化任务" 开关让你重新运行 stack 而不必重复初始化 —— 数据库已经存在时很实用。
初始化任务之间可以互相依赖，但不能依赖常规服务（它们总是先执行）。

限制

不支持 build: —— 请先构建镜像（应用的构建对话框可以做到），然后用 tag 引用它。
healthcheck、restart、profiles 及其他不支持的键会被忽略 —— 但每一个都会在解析阶段以警告形式提示，绝不静默跳过。
depends_on 只等待依赖启动，而不是等它变为健康状态。如果某个服务在启动时就去连接依赖且没有重试逻辑，请用 ↻ 按钮重启它一次。
顶层的 volumes: 声明不会自动创建 —— 请先在"卷"标签页中创建命名卷。

故障排查

服务访问不到宿主机 —— 确认宿主机进程监听在 0.0.0.0，并且你用的是 host.containers.internal 而不是 localhost（在容器内部，localhost 指的是容器自己）。
重启容器后名称解析失效 —— 用"替换已有容器"重新运行 compose，以刷新 /etc/hosts 条目。
绑定 1024 以下端口时报 Permission denied —— 以非 root 用户运行的镜像无法绑定特权端口；请监听高位端口（例如 8080）并发布为 60000:8080。
项目网络上的一切都超时 —— vmnet 辅助进程可能在容器运行期间重启过；请重新创建该 stack（替换已有容器），如果仍不行，就在"系统"标签页中重启服务。
服务日志 —— "系统"标签页内置了 container 服务日志查看器（5 分钟 / 30 分钟 / 1 小时窗口）。

← Container Desktop · GitHub · MIT