Docker Compose 报 depends_on 的 required 属性不被允许

执行 docker compose up，还没进入应用启动阶段，配置校验就报：

services.plugin_daemon.depends_on.db_mysql Additional property required is not allowed

错误中的服务名会随项目变化，例如也可能是 services.chain-server.depends_on.nemollm-embedding。关键位置是 depends_on 下某个依赖服务的 required 字段。如果实际使用的是 Compose 2.5.0、2.18.0 或 2.19.1 这类旧版本，需要先处理解析器与配置语法不兼容的问题。

这不是 MySQL 已启动但连接失败，也不表示 YAML 必须补上一项名叫 required 的配置。它表示当前工具不接受已经写在该位置的属性。

确认版本和字段所在位置

在真正执行部署的用户、机器或 CI 环境中查看版本：

docker compose version

如果脚本实际调用的是带连字符的命令，再检查那个入口：

docker-compose version

两个入口可能使用不同程序。只更新交互终端里的插件，不能证明面板或 CI 调用的工具也更新了。Docker Engine、Docker Desktop 和 Compose 的版本号也不是同一套编号，不能把 Engine 的 24.x 当作 Compose 已达到要求。

再看错误指向的配置。下面是依赖关系片段，省略了镜像及其他服务配置，不能当作完整部署文件：

depends_on:
  db_mysql:
    condition: service_healthy
    required: false

required 与 condition 同级，都属于 db_mysql 这一条依赖。若实际写在服务根部、depends_on 根部或另一个不接受它的位置，先修正结构；不能把所有同名错误都归为版本不足。

对于这个字段，Compose 实现应使用 2.20.2 或更新版本，并同时满足应用自己的更高要求。2.20.2 是历史功能边界，不是现在应安装的固定目标版本，也不能推出整套应用在该版本一定可用。env_file 条目里的 required 是另一项功能，不适用这里的版本判断。

升级实际使用的 Compose，保留依赖关系

优先选择当前受支持、符合应用要求的 Compose 版本。升级前记录原版本和安装方式，保存 Compose 文件、环境文件及本地修改；有已有业务时，按部署流程准备数据备份和维护安排。

已经安装 Docker Engine、CLI 并配置 Docker 官方软件仓库的 Ubuntu、Debian，可通过包管理器更新插件：

sudo apt-get update
sudo apt-get install docker-compose-plugin
docker compose version

这组命令不适用于尚未配置对应仓库、由 Docker Desktop 管理或手动安装独立程序的环境。Desktop 和手动安装应分别沿用对应的更新方式，更新后再次确认报错入口的实际版本。

如果旧操作系统无法运行应用所需的工具链，应先评估升级系统或迁移部署环境。不要因为某个安装包装不上，就直接删除项目的依赖条件，也不要仅替换 Docker Engine 来期待 Compose 自动获得新语法。

修改 Compose 文件顶层的 version: "3.8" 同样不能增加解析器能力。当前 Compose 不靠这个值切换到一个支持新字段的程序版本。

删除 required: false 会把可选依赖变成必需依赖

required: false 表示该依赖没有启动或不可用时，Compose 可以给出警告。省略 required 的默认值是 true。因此删掉这一行，会改变依赖是否必须满足的语义。

这种差别在多数据库、按 profile 选择服务的配置中尤其明显。应用可能同时声明对 MySQL 和 PostgreSQL 的可选依赖，再由本次部署的 profile 选择实际数据库。未选中的数据库服务不应因此被强制启用。

例如，Dify 1.12.1 的 plugin_daemon 对多个数据库声明了可选依赖。删掉 required: false 后，原来的字段校验错误可能变为：

service db_mysql is required by plugin_daemon but is disabled. Can be enabled by profiles [mysql]

这说明配置语义已经变了，不是数据库又出现了一个无关故障。把所有 profile 也删除，会让原本按需启用的服务进入默认启动范围，可能同时启动本来不需要的数据库或组件。

也不要把整个长格式依赖改成简单列表来消除字段错误。简单列表不能保留 service_healthy 这类等待条件；容器启动了与应用准备好接收连接是两回事。

确实无法升级时，只能依据该应用支持的部署组合重新整理依赖图：确认保留哪套数据库、哪些服务需要它、应用连接参数是否一致，以及原来的健康检查如何保留。这已超出删除一行的兼容修正。对于没有验证过的替代配置，应保留原稿并先在隔离环境完成验证，不能把“能解析”当作可部署。

用相同配置和 profile 重新校验

更新工具后，先在本机测试环境对原配置做校验。下面以 ./docker-compose.yaml 为例，文件名需要按项目替换：

docker compose -f ./docker-compose.yaml config -q
docker compose -f ./docker-compose.yaml config --services

如果部署使用 PostgreSQL profile，校验也要带相同的 profile；以下名称只是示例，须以项目定义为准：

docker compose -f ./docker-compose.yaml --profile postgresql config -q
docker compose -f ./docker-compose.yaml --profile postgresql config --services

多个 -f、--env-file、项目目录和其他影响模型的参数也应保持一致。config -q 只校验，不打印展开后的完整配置；普通 config 可能显示插值后的敏感信息，不要把它的全部输出公开。config --services 用于核对最终选中的服务，不能替代应用健康检查。

校验成功、不再出现 required 属性错误，且服务清单符合选定部署组合后，再按应用原有流程启动或更新。随后检查容器状态、健康状态和业务入口。若这时出现镜像拉取、数据库认证或初始化失败，应按新错误继续处理，不能继续归因于同一个字段。

这次修复不需要删除数据卷、重建数据库或清空应用目录。如果曾为绕过错误删过 required、profile 或健康条件，应先与保存的原文件逐项比较，恢复需要的语义再验证。回退工具时也要搭配它能解析的已知可用配置；仅降级插件不能撤销应用启动过程中发生的数据迁移。