Docker Compose 使用 host 网络时，ports 不生效或报不兼容

启动 Compose 服务时，容器还没正常运行，就出现下面的错误：

"host" network_mode is incompatible with port_bindings

先检查出错服务是否同时配置了 network_mode: host 和 ports。这两个设置对应不同的联网方式：前者让容器使用宿主机的网络，后者则要求 Docker 将宿主机端口映射到容器端口。在 host 模式下，端口映射不生效。

有些执行路径不会报出这段异常，而是提示 Published ports are discarded when using host network mode 后继续启动。能够启动不代表映射已经生效。尤其是配置了 18080:8080 时，不能因为容器在运行，就认为服务会出现在宿主机的 18080 端口。

下面以 Linux Docker Engine 和现代 docker compose 命令为主要环境。旧版 Python docker-compose 的报错形式可能不同，不能用某一个版本的行为推断所有版本都报错或都忽略。Docker Desktop 的 host 网络需要 4.34 或更新版本并在设置中启用；它只支持 Linux 容器，且有自身的平台限制，不应直接照搬 Linux 主机的全部网络假设。

从实际生效的配置定位冲突

先用与启动时相同的文件、文件顺序、环境变量和项目参数查看配置。例如，原本通过两份文件启动，就检查这两份文件的合并结果：

docker compose -f compose.yaml -f compose.local.yaml config

文件名是示例，需要替换为实际使用的文件。如果平时只用一份配置，也只指定那一份。输出会解析变量并展开配置，可能包含环境变量值；不要直接将整份输出贴到公开场合。

在出错服务下查看 network_mode 和 ports。如果配置检查直接拒绝这组设置，也已经指出了需要消除的冲突。不要只看刚编辑的覆盖文件，端口可能仍来自基础配置。应从提供这些设置的配置文件中修正，再检查最终结果，而不是假定在另一份文件里删掉一行就能覆盖基础值。

下面两种配置代表两种需求，应选其中一种。示例中的 your-app:your-tag 必须替换成已经准备好的真实应用镜像，并假设应用已配置为监听 8080；镜像名字本身不会设置应用端口。应用所需的挂载、环境变量和启动参数仍须保留。

需要宿主机端口映射时，去掉 host 模式

如果需求是从宿主机 18080 访问容器里的 8080，应保留 ports，删除 network_mode: host，使用普通的 Compose 网络：

services:
  app:
    image: your-app:your-tag
    ports:
      - "127.0.0.1:18080:8080"

这里没有显式声明网络，服务会连接 Compose 的默认网络。应用应在容器内可被访问的地址上监听 8080，例如 0.0.0.0:8080，而不是只监听容器自己的回环地址。

127.0.0.1:18080:8080 将发布地址设在宿主机回环接口，适合先从宿主机验证，或由运行在宿主机上的反向代理访问。不要为了消除原报错，顺手省掉 127.0.0.1；省掉后发布范围会变化。如果本来需要其他机器访问，应单独确认发布地址、防火墙和访问控制。Docker Engine 28.0.0 之前的版本还存在同一二层网络中的其他主机能够访问回环发布端口的已知限制，不能把旧版本中的这个地址写法当作完整的隔离保证。

删除 host 模式也会改变容器眼中的 localhost。应用如果原来靠 127.0.0.1 访问宿主机数据库，切回普通容器网络后，这个地址将指向容器自身。此时需要按实际网络重新配置依赖地址，调整后也要检查应用连接。

确实需要 host 网络时，删除端口映射

如果应用确实需要共享 Linux 宿主机网络，应保留 host 模式，并删除该服务的全部 ports：

services:
  app:
    image: your-app:your-tag
    network_mode: host

这个配置没有把 8080 转换为 18080。应用监听 8080，就直接使用宿主机网络中的 8080；若要改成 18080，必须通过应用自己的配置或启动参数调整监听端口。具体参数取决于应用，不能再写一条 ports 来完成转换。

同样，原本端口映射中的 127.0.0.1 不会继续限制访问范围。采用 host 模式后，需要检查应用实际绑定的地址。如果应用监听 0.0.0.0，它会面向宿主机的相应网络接口，不能把删除 ports 理解为“没有暴露端口”。只允许本机访问时，应由应用绑定回环地址，并按环境检查访问控制。

还要确认应用要用的端口没有被其他服务占用。普通网络下可以把多个容器的相同内部端口映射到不同宿主机端口；host 模式没有这层端口转换。保留 host 模式时，也不要再给该服务同时配置 networks，这两种网络声明不能混用。

应用配置后核对真实访问地址

修改前保存 Compose 文件和应用监听配置，确认数据已经持久化并有可用备份。先在本地测试环境检查修改后的配置，再用原有项目参数更新目标服务。单文件项目的示例是：

docker compose -f compose.yaml config

docker compose -f compose.yaml up -d --no-deps app

app 是服务名占位值。多文件项目必须在两条命令中保持同一组 -f 参数。第二条会应用服务配置变化，可能停止并重建容器，产生短暂中断；--no-deps 不会替你启动尚未运行的依赖。不要用普通重启来代替应用配置变更，也不需要为这个冲突删除卷或清理镜像。

对于端口映射方案，从宿主机验证 127.0.0.1:18080，确认返回预期应用内容；对于 host 方案，验证应用实际监听的地址和端口。再检查应用日志和依赖连接，确认没有新的端口占用、数据库不可达或访问范围扩大问题。容器处于运行状态，只能证明进程没有立即退出，不能证明入口和依赖都正确。

如果切换模式后出现回归，恢复原来可用的网络配置和应用监听设置，再用相同项目参数更新该服务。原配置本来就包含冲突时，应恢复到最近一次可用版本，而不是恢复那份无法启动的配置。回退网络设置不会恢复容器可写层中的数据，因此数据持久化和备份应在重建前确认。