用途:在 compose.yaml 中定义顶层 networks、volumes、configs、secrets 资源,避免网络驱动误配、卷数据丢失和密钥挂载错误。
主要能力:
- networks:支持 bridge(默认,单主机隔离)、host、overlay(多主机 Swarm)、macvlan、none 驱动;可配置 ipam(subnet、ip_range、gateway、aux_addresses)、internal、attachable、enable_ipv6、labels、name、driver_opts;支持 external 引用外部网络;可自定义 default 网络;服务级可设 aliases、ipv4_address、ipv6_address、priority。
- volumes:支持命名卷、driver、driver_opts(如 NFS)、labels、name、external。
- configs:来源支持 file、environment、content(Compose 2.23.1+)、external;默认挂载到 /<config-name>,权限 0444。
- secrets:来源支持 file、environment、external;默认挂载到 /run/secrets/<secret-name>,权限 0444。
- 服务中挂载 configs/secrets 可自定义 target、uid、gid、mode。
关键限制与警告:
- 持久数据必须用命名卷,匿名卷在 docker compose down 后会被重建并丢失数据。
- 服务引用的卷、config、secret 必须在顶层声明,否则 Compose 校验报错。
- external: true 的资源 Compose 不会创建,缺失会立即报错;且不能与 driver、driver_opts、file、content 等创建属性同时使用,只能搭配 name。
- 资源标签建议使用反向 DNS 记法(如 com.example.description)避免冲突。
典型用法:网络隔离模式中,proxy 仅接 frontend,db 仅接 backend 且 backend 设 internal: true,app 同时接两者作为桥梁,使 proxy 无法直接访问 db。
参考:https://docs.docker.com/compose/compose-file/06-networks/ 、07-volumes/、08-configs/、09-secrets/