Docker容器访问宿主机服务笔记

核心原理

Docker容器默认拥有独立的网络命名空间，localhost或 127.0.0.1指向容器自身而非宿主机，因此容器无法直接通过 localhost访问宿主机服务。

解决方案

1. 使用 host.docker.internal（推荐，跨平台）

适用场景：Docker Desktop（Windows/macOS）或 Docker Engine 18.03+（Linux）
原理：Docker提供的特殊主机名，自动解析为宿主机IP

# 在容器内直接访问
http://host.docker.internal:8080

注意：Linux原生不支持，需手动配置

2. Host网络模式（仅Linux）

适用场景：Linux环境
原理：容器与宿主机共享网络命名空间

docker run --network="host" <image_name>

在容器内使用 localhost:8080即可访问宿主机服务

注意：Windows/macOS不支持，可能产生端口冲突

3. 宿主机IP地址（通用方法）

适用场景：所有操作系统
步骤：

# 获取宿主机IP
# Linux/macOS
ifconfig
# Windows
ipconfig

# 在容器内访问
http://<宿主机IP>:8080

注意：需确保防火墙允许访问，建议使用静态IP

4. 自定义Docker网络

适用场景：需要网络隔离的场景

# 创建自定义网络
docker network create my_network

# 启动容器加入网络
docker run --network my_network <image_name>

5. --add-host参数

适用场景：手动指定宿主机IP

docker run --add-host host:192.168.1.100 <image_name>
# 在容器内访问 http://host:8080

6. Docker Compose配置

version: '3'
services:
  my_service:
    image: <image_name>
    extra_hosts:
      - "host:192.168.1.100"

推荐方案

• Windows/macOS：host.docker.internal
• Linux：--network="host" 或配置 host.docker.internal
• 通用方案：宿主机IP地址

host.docker.internal 是一个 Docker 提供的特殊 DNS 名称，主要用于在 Docker Desktop 环境（Windows 和 macOS）中，让容器内部能够访问宿主机（即运行 Docker 的机器）上的服务。

在 Linux 环境下，Docker Desktop 并不常用，因此 host.docker.internal 默认不可用，需要手动配置。

下面分别介绍如何在 docker run 和 docker-compose.yml 中配置 host.docker.internal：

1. 使用 docker run 命令

在运行容器时，通过 --add-host 参数添加 host.docker.internal 指向宿主机的 IP。

语法：

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

示例：

docker run -d \
  --name myapp \
  --add-host=host.docker.internal:host-gateway \
  -p 8080:8080 \
  myimage:latest

说明：

• host-gateway 是 Docker 20.10+ 引入的一个特殊值，代表宿主机的网关地址（通常是 172.17.0.1 或类似）。
• 该方式适用于 Docker Desktop（Windows/macOS）和 Linux（需 Docker 版本支持）。

2. 使用 docker-compose.yml

在 docker-compose.yml 文件中，使用 extra_hosts 字段来添加主机映射。

示例 docker-compose.yml：

version: '3.8'

services:
  app:
    image: myimage:latest
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    # 其他配置...

启动服务：

docker-compose up -d

说明：

• extra_hosts 的作用等同于 --add-host。
• host-gateway 会被 Docker 自动解析为宿主机的内部 IP。

3. Linux 环境下没有 host-gateway？手动指定 IP

如果你的 Docker 版本较旧，不支持 host-gateway，可以手动指定宿主机的 IP。

查看宿主机 Docker 网桥 IP：

ip addr show docker0
# 或
docker network inspect bridge | grep Gateway

通常为 172.17.0.1。

手动指定 IP：

# docker run
docker run --add-host=host.docker.internal:172.17.0.1 ...

# docker-compose.yml
extra_hosts:
  - "host.docker.internal:172.17.0.1"

4. 注意事项

• ✅ Docker Desktop (Windows/macOS)：host.docker.internal 默认支持，无需额外配置（但显式添加更稳妥）。
• ✅ Linux + Docker Engine：必须使用 --add-host 或 extra_hosts 配置 host-gateway 或手动 IP。
• ⚠️ 确保宿主机上的服务监听在 0.0.0.0 或 172.17.0.1，而不是 localhost（127.0.0.1），否则容器无法访问。

总结

推荐使用 host-gateway，因为它具有更好的可移植性和兼容性。