在 Docker Compose 中实现容器到宿主机通信——host.docker.internal 与 host-gateway 的实战指南

3 天 ago

木它

1 minute

一、前言

在容器化开发过程中，常常遇到容器需要访问宿主机上的服务，比如数据库、API 或其他本地应用。对于 macOS 和 Windows 用户来说，Docker 官方提供了 host.docker.internal 这个 DNS 名称，方便容器自动识别宿主机。然而，Linux 用户则需要额外配置。自 Docker 20.10 起，host-gateway 关键字极大简化了这一过程。本篇将详细介绍如何在 Docker Compose 中实现容器访问宿主机的最佳实践，并结合实战案例帮助理解。

二、容器访问宿主机的常见方式

在 Linux 环境下，容器默认无法通过 host.docker.internal 访问宿主机上的服务。常见的几种做法包括：

手动指定宿主机 IP：在 extra_hosts 或命令行中写死宿主机 IP，缺点是 IP 可能变化，维护不便。
使用 network_mode: host：容器与宿主机共享网络栈，虽然简单，但会牺牲隔离性，且端口暴露风险增加。
利用 host-gateway：结合 Docker 20.10+ 的新特性，自动将 host.docker.internal 映射到宿主机网关 IP，推荐使用。

三、Docker 命令行与 Compose 的实现方式

1. 命令行方式

直接运行容器时，可以用如下参数：

docker run \
  --add-host=host.docker.internal:host-gateway \
  <其他参数> \
  <镜像名>

这样容器内部的 /etc/hosts 会新增一条，把 host.docker.internal 指向宿主机网关 IP。

2. Docker Compose 配置

在 Compose 文件中，使用 extra_hosts 字段实现同样功能：

version: '3.9'
services:
  app:
    image: <镜像名>
    extra_hosts:
      - "host.docker.internal:host-gateway"

Compose 会自动查找 bridge 网络的网关地址，并注入到容器 hosts 文件中，跨平台兼容性极强。

四、实战案例：容器访问宿主机 HTTP 服务

1. 宿主机启动 HTTP 服务

在宿主机上运行如下 Python 命令：

python3 -m http.server 8080

确保服务监听在 0.0.0.0，方便容器访问。

2. 编写 docker-compose.yml

创建如下 Compose 文件，实现容器内 curl 访问宿主机服务：

version: '3.9'
services:
  curltest:
    image: curlimages/curl
    command: ["curl", "http://host.docker.internal:8080"]
    extra_hosts:
      - "host.docker.internal:host-gateway"

3. 启动并验证

执行：

docker-compose up

如能看到 HTTP 服务返回内容，说明配置成功。

五、常见问题与排查技巧

1. host-gateway 报错

报错信息：invalid IP address in add-host: host-gateway
原因：Docker 版本过低。请升级至 20.10 或以上。

2. 无法访问宿主机服务

检查服务监听地址必须为 0.0.0.0，否则只在本地回环可用。
查看防火墙设置是否允许 Docker 网络访问指定端口。
确认 Compose 文件 extra_hosts 配置无误。

六、适用场景与注意事项

适用场景

容器需要调用本地数据库或 API
开发环境下调试本地服务
跨平台项目需要兼容性配置

不推荐做法

使用 network_mode: host，丧失网络隔离
手动硬编码宿主机 IP，难以维护

七、结语

通过 extra_hosts 配合 host-gateway，Docker Compose 能方便地实现容器到宿主机的通信，无需关心平台差异，配置简洁且易于迁移。无论是本地开发还是自动化测试，这一技巧都能显著提升开发效率与体验。

参考资料