qoomon/docker-host 镜像文档

一、镜像概述与主要用途

qoomon/docker-host 是一个用于转发 TCP 和 UDP 流量到 Docker 主机（或指定目标）的 Docker 镜像，同时支持 rootless Podman 环境。本镜像可将容器内的网络流量转发至主机服务，解决容器与主机之间的网络通信问题，适用于需要从容器内部访问主机应用的场景。

二、镜像标签

三、核心功能与特性

3.1 主机地址自动识别

镜像按以下优先级确定目标主机地址（转发目标）：

1. 环境变量指定：若设置 DOCKER_HOST 环境变量，直接使用其IP（支持转发至任意目标，不仅限于Docker主机）；
2. DNS解析：尝试通过DNS解析以下主机名：
   • Docker 环境：host.docker.internal
   • Podman 环境：host.containers.internal（使用 getent ahostsv4 <hostname> 解析）；
3. 默认网关：若以上均失败，默认使用主机默认网关（通过 ip -4 route show default 获取）。

3.2 灵活的端口转发

• 默认转发：默认转发所有端口（1-65535）至目标主机；
• 端口限制：通过 PORTS 环境变量限制转发端口，支持端口列表、端口范围及端口映射（格式见「配置说明」）；
• 协议支持：同时支持 TCP 和 UDP 协议转发。

四、使用场景与适用范围

• 开发环境：容器内应用需访问主机上的数据库、API服务、调试工具等；
• 多容器协作：统一将多个容器的指定端口流量转发至主机，简化网络配置；
• 自定义目标转发：通过 DOCKER_HOST 指定非主机目标，实现跨主机/服务的流量转发；
• Docker/Podman 兼容：同时支持 Docker 和 rootless Podman 环境。

五、配置说明

5.1 环境变量

DOCKER_HOST

• 作用：手动指定目标主机IP，覆盖自动识别逻辑；
• 格式：IP地址（如 192.168.1.100）；
• 示例：-e DOCKER_HOST=10.0.0.5（转发至 10.0.0.5）。

PORTS

• 作用：限制转发端口或配置端口映射；
• 格式：空格/逗号分隔的端口列表、端口范围或端口映射（CONTAINER_PORT:HOST_PORT）；
• 示例：
  • 限制端口：443, 8000-9000（仅转发443及8000-9000端口）；
  • 端口映射：443:8443, 8000-9000:5000-6000（容器443端口→主机8443端口，容器8000-9000→主机5000-6000）。

六、部署与使用示例

6.1 准备工作

在主机启动测试服务（用于验证转发效果）：

• TCP服务：启动netcat监听端口2323（接收消息）：

  sh
  nc -p 2323 -lk
  

• UDP服务：启动netcat监听端口5353（接收消息）：

  sh
  nc -p 5353 -lk -u
  

6.2 Docker Run 基础使用

示例1：默认转发所有端口

sh
docker run -d \
  --name docker-host \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \  # 必需：添加网络管理权限
  --restart on-failure \
  qoomon/docker-host

示例2：限制转发端口（仅443和8000-9000）

sh
docker run -d \
  --name docker-host \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  --restart on-failure \
  -e PORTS='443, 8000-9000' \  # 限制端口为443及8000-9000
  qoomon/docker-host

示例3：端口映射（容器443→主机8443，容器8000-9000→主机5000-6000）

sh
docker run -d \
  --name docker-host \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  --restart on-failure \
  -e PORTS='443:8443, 8000-9000:5000-6000' \  # 端口映射配置
  qoomon/docker-host

6.3 Docker Network 部署

通过自定义网络实现容器间通信，指定 docker-host 为网络别名。

步骤1：创建自定义网络

sh
network_name="docker-host-network"
docker network create "$network_name"

步骤2：启动 docker-host 容器（加入自定义网络）

sh
docker run --name "${network_name}-docker-host" \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  --restart on-failure \
  --net="$network_name" --network-alias 'docker-host' \  # 网络别名便于其他容器访问
  qoomon/docker-host

步骤3：应用容器访问（以netcat测试为例）

• TCP测试（发送消息至主机2323端口）：

  sh
  docker run --rm \
    --net="$network_name" \  # 加入同一网络
    -it alpine nc 'docker-host' 2323 -v  # 通过网络别名访问docker-host
  

• UDP测试（发送消息至主机5353端口）：

  sh
  docker run --rm \
    --net="$network_name" \
    -it alpine nc 'docker-host' 5353 -u -v
  

6.4 Docker Compose 部署

通过 docker-compose.yml 配置服务，自动管理容器依赖。

yaml
version: '2'

services:
  docker-host:
    image: qoomon/docker-host
    cap_add: [ 'NET_ADMIN', 'NET_RAW' ]  # 必需的网络权限
    mem_limit: 8M  # 限制内存使用
    restart: on-failure  # 失败时自动重启

  # 示例：TCP消息发送器（每秒发送当前时间至主机2323端口）
  tcp_message_emitter:
    depends_on: [ docker-host ]  # 依赖docker-host启动
    image: alpine
    command: [ "sh", "-c", "while :; do date; sleep 1; done | nc 'docker-host' 2323 -v" ]

  # 示例：UDP消息发送器（每秒发送当前时间至主机5353端口）
  udp_message_emitter:
    depends_on: [ docker-host ]
    image: alpine
    command: [ "sh", "-c", "while :; do date; sleep 1; done | nc 'docker-host' 5353 -u -v" ]

启动服务：

sh
docker-compose up -d

七、Linux系统注意事项 ⚠️

7.1 主机应用绑定地址

Linux系统中，主机应用需绑定至 0.0.0.0 或桥接网络网关IP，而非仅 127.0.0.1（否则容器无法访问）。
获取桥接网络网关IP的命令：

sh
docker network inspect bridge --format='{{( index .IPAM.Config 0).Gateway}}'

注意：rootless Podman环境下，应用绑定 127.0.0.1 即可（默认安装配置支持）。

7.2 防火墙配置

需确保主机防火墙允许 docker-host 容器访问目标端口。例如，开放主机2323端口（TCP）：

sh
sudo ufw allow 2323/tcp  # 具体命令取决于防火墙工具（ufw/iptables等）

（参考 GitHub Issue #21）

八、外部参考

• Connecting to Docker Host MySQL from Docker Container (Linux/Ubuntu)