MacOS下Docker容器如何通过IPv4访问宿主机localhost服务

问题场景 #

我有如下定义了多个服务的docker-compose配置文件：

version: "3.8"

services:
  app:
    container_name: mobile_app_api
    env_file:
      - .env.development
    command: npm run watch:dev
    build:
      context: .
      target: development
      dockerfile: ./Dockerfile
    restart: always
    volumes:
      - /usr/src/app/node_modules
      - ./:/usr/src/app
    depends_on:
      - postgres
      - redis
    extra_hosts:
      - host-machine:host-gateway
    network_mode: host

  redis:
    image: "redis:alpine"
    container_name: mobile_app_cache

  postgres:
    image: postgres
    container_name: mobile_app_database
    restart: "unless-stopped"
    environment:
      TZ: 'GMT'
      PGTZ: 'GMT'
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mobile_app_database
    volumes:
      - /:/data/postgres
    network_mode: host

预期API服务运行在localhost:3333地址，但执行docker-compose up --build启动后，得到如下输出：

mobile_app_api | server running on http://[::1]:3333

现有两个疑问：

1. 为何宿主机已关闭IPv6的情况下，服务仍运行在IPv6地址上？
2. 如何修改配置让服务正常绑定IPv4协议的localhost地址运行？

备注： 宿主机为MacOS系统，已在系统设置中关闭IPv6。曾尝试在compose文件中配置host.docker.internal（以及gateway.docker.internal）指向host-gateway的映射，如下所示，但未生效：

extra_hosts:
      - host.docker.internal:host-gateway

原因说明 #

• MacOS下Docker的host网络模式实现和Linux不一致：Docker Desktop for Mac是运行在内置的轻量Linux虚拟机上的，network_mode: host指的是容器共享这个内部虚拟机的网络栈，而非直接共享Mac宿主机的网络栈。你在Mac系统层面关闭IPv6，不会影响Docker内置Linux虚拟机的网络配置，该虚拟机默认是开启IPv6回环地址::1的。
• Node服务默认监听行为导致：大部分Node框架默认会优先绑定::（IPv6双栈地址，同时支持IPv4/IPv6连接），所以启动日志会显示服务运行在[::1]:3333。
• 之前的extra_hosts配置无效是逻辑问题：这个配置只是给容器内部/etc/hosts加域名和IP的映射关系，完全不会影响服务本身的监听地址选择，自然解决不了问题。

解决方法 #

方法1：显式指定服务监听IPv4地址（最直接） #

从启动命令和默认3333端口判断，你用的大概率是AdonisJS框架，直接修改.env.development文件中的HOST配置即可：

HOST=0.0.0.0
PORT=3333

如果是Express/Fastify等其他Node框架，在启动服务的代码里显式传入IPv4监听地址：

// Express 示例
app.listen(3333, '0.0.0.0')

// Fastify 示例
fastify.listen({ port: 3333, host: '0.0.0.0' })

修改后重启容器，服务就会绑定IPv4地址，在宿主机直接访问localhost:3333即可正常连通。

方法2：放弃host网络模式，改用标准端口映射（推荐Mac环境使用） #

MacOS下network_mode: host本身存在大量兼容性问题，性能也没有优势，完全不推荐使用。直接删除app和postgres服务下的network_mode: host配置，通过ports字段显式做IPv4端口映射即可，修改后的核心配置如下：

services:
  app:
    container_name: mobile_app_api
    env_file:
      - .env.development
    command: npm run watch:dev
    build:
      context: .
      target: development
      dockerfile: ./Dockerfile
    restart: always
    volumes:
      - /usr/src/app/node_modules
      - ./:/usr/src/app
    depends_on:
      - postgres
      - redis
    extra_hosts:
      - host-machine:host-gateway
    ports:
      - "127.0.0.1:3333:3333" # 绑定宿主机IPv4回环的3333端口到容器

  redis:
    image: "redis:alpine"
    container_name: mobile_app_cache

  postgres:
    image: postgres
    container_name: mobile_app_database
    restart: "unless-stopped"
    environment:
      TZ: 'GMT'
      PGTZ: 'GMT'
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mobile_app_database
    volumes:
      - /:/data/postgres
    ports:
      - "127.0.0.1:5432:5432" # 按需映射Postgres端口

这种模式下Docker会自动处理IPv4端口转发，只要容器内服务监听0.0.0.0，就可以通过宿主机的IPv4地址正常访问，不需要关心容器内部的IPv6配置。

内容的提问来源于stack exchange，提问作者dokichan