PAYATHON 2026

docker compose build 使用 network: host 的授权方法

技术问小赵

不要在 docker compose up 后面加 --allow。--allow 是 Buildx 构建阶段用的权限参数;在 Compose 文件里,应该把 network.host 放进 build.entitlements,并确认 docker-compose-plugin 的版本会把这个字段传给 Buildx。如果当前 Compose 版本还不支持,或者没有转发这个字段,可以临时先用 docker buildx build --allow=network.host 预构建镜像,再让 Compose 使用这个镜像。

原因

build.network: host 会让 BuildKit 在构建阶段请求 network.host 权限。从 Buildx 0.37.2 开始,这项 entitlement 检查不再被跳过,所以会提示:

additional privileges requested: pass "--allow=network.host" to grant requested privileges

之前能构建,只是因为旧版 Buildx 有跳过检查的 bug,并不代表 Compose 配置正确。运行容器时的 host 网络模式不受影响,报错发生在构建阶段。

推荐做法

确保 entitlements 放在 build 下面,并且是数组:

services:
  caddy:
    build:
      context: caddy
      dockerfile: Dockerfile
      network: host
      entitlements:
        - network.host

然后检查并升级 Compose/Buildx 插件。Debian 上如果用 Docker 官方 apt 源,可以这样更新:

sudo apt update
sudo apt install --only-upgrade docker-compose-plugin docker-buildx-plugin
docker compose version
docker buildx version

再重新构建:

docker compose build caddy
docker compose up

如果用 docker compose up --build,也不要加 --allow;构建权限应该来自 Compose 文件里的 build.entitlements。

仍然报错时

如果 docker compose build 还是报同样的错,通常说明当前 docker-compose-plugin 还没有把 build.entitlements 转成 Buildx 的 --allow=network.host,或者 Compose 和 Buildx 的版本组合不匹配。这时可以先用 Buildx 直接构建:

docker buildx build --allow=network.host --network=host -t caddy:local -f caddy/Dockerfile caddy

然后让 Compose 使用这个镜像,例如把服务改成:

services:
  caddy:
    image: caddy:local

并避免这次启动触发构建:

docker compose up --no-build

注意:--no-build 只保证本次不构建,镜像必须已经存在;如果 Compose 文件里还保留 build,后面带 --build 的命令仍可能触发构建。需要长期固定时,建议用覆盖文件,或者去掉该服务的 build 段。

注意事项

network: host 会让构建步骤访问宿主机网络,只应对可信的 Dockerfile 开启;不需要时保持默认构建网络。只写 entitlements: network.host 或把 entitlements 放到 service 顶层都不会生效。

备注:内容仅供参考。