tecnativa/whitelist

Docker白名单代理

概述

Docker白名单代理（tecnativa/whitelist）是一个基于socat的网络代理工具，用于实现网络连接的白名单控制。它允许将传入连接重定向到指定目标，同时限制容器的网络访问范围，解决Docker内部网络中完全隔离或完全开放的局限性。

使用场景与价值

该镜像主要用于解决Docker网络隔离中的灵活性问题，具体场景包括：

• 仅允许容器连接特定API服务，阻止访问其他外部网络
• 在暴露容器端口的同时，限制容器对外部网络的访问权限
• 实现精细化的网络访问控制，平衡安全性与功能性

核心价值在于提供了一种中间状态的网络隔离方案，既避免了完全隔离导致的功能限制，又防止了完全开放带来的安全风险。

使用方法与配置说明

环境变量

通过以下环境变量配置代理行为：

TARGET

• 必填项
• 描述：传入连接将被重定向到的目标主机名

MODE

• 默认值：tcp
• 描述：代理模式，设置为udp可启用UDP代理模式

MAX_CONNECTIONS

• 默认值：100
• 描述：限制每个端口同时接受的最大连接数

设置"无限制"连接数

每个端口和连接会生成一个子进程，过高的数值可能导致主机无响应。典型Linux系统可处理约32768个进程，若需大量连接，需调整主机系统参数（参考：https://stackoverflow.com/questions/6294133/maximum-pid-in-linux%EF%BC%89%EF%BC%8C%E5%B9%B6%E6%8C%89%E9%80%9A%E8%BF%87%E8%AF%A5%E4%BB%A3%E7%90%86%E7%9A%84%E7%AB%AF%E5%8F%A3%E6%95%B0%E9%87%8F%E5%88%86%E6%91%8A%E6%AD%A4%E6%95%B0%E5%80%BC%E3%80%82

连接数达到限制时的行为

• UDP模式：客户端无明显差异，但新连接的数据包将停止转发，直至连接数减少
• TCP模式：代理停止接受新连接，客户端连接将等待直至连接数减少，可能超时

NAMESERVERS

• 默认值：208.67.222.222 8.8.8.8 208.67.220.220 8.8.4.4（OpenDNS和Google DNS服务器）
• 描述：仅在启用预解析（PRE_RESOLVE）时使用的DNS服务器列表

PORT

• 默认值：80 443
• 描述：代理服务监听的端口，同时也是目标服务预期监听的端口（HTTP/S服务无需额外指定）

PRE_RESOLVE

• 默认值：0
• 描述：设置为1时，使用指定的NAMESERVERS预先解析TARGET主机名，特别适用于通过网络别名白名单外部API的场景

UDP_ANSWERS

• 默认值：1
• 描述：1表示进程等待服务器响应后才终止子进程（此时连接计入连接限制）；设置为0则不等待响应，防止子进程无限等待（推荐用于连接syslog服务器如graylog的场景）

VERBOSE

• 默认值：0
• 描述：设置为1时记录所有连接日志

使用示例

以下示例展示如何在staging环境中使用该镜像解决应用无法访问外部字体服务的问题。

问题场景

生产环境中的coolapp应用需要访问fonts.googleapis.com和fonts.gstatic.com加载字体，但在staging环境中，为避免邮件发送等外部网络行为，应用被部署在内部网络（internal: true），导致无法加载字体。

解决方案

通过tecnativa/whitelist为字体服务创建代理，允许应用访问特定域名，同时保持其他网络隔离。

docker-compose配置示例

yaml
# Staging部署配置
version: "2.0"
services:
    # 代理fonts.googleapis.com
    fonts_googleapis_proxy:
        image: docker.xuanyuan.run/tecnativa/whitelist
        environment:
            TARGET: fonts.googleapis.com  # 目标主机
            PRE_RESOLVE: 1  # 启用预解析，避免解析到本地
        networks:
            default:  # 内部网络，供应用访问
                aliases:
                    - fonts.googleapis.com  # 网络别名，使应用认为此代理即目标主机
            public:  # 公共网络，提供外部访问能力

    # 代理fonts.gstatic.com
    fonts_gstatic_proxy:
        image: docker.xuanyuan.run/tecnativa/whitelist
        networks:
            default:
                aliases:
                    - fonts.gstatic.com
            public:
        environment:
            TARGET: fonts.gstatic.com
            PRE_RESOLVE: 1

    # 入口代理（如traefik）
    proxy:
        image: docker.xuanyuan.run/traefik
        networks:
            default:
            public:
        ports:
            - "8080:8080"  # 暴露访问端口
        volumes:
            - /etc/traefik/traefik.toml  # traefik配置文件

    # 应用服务
    app:
        image: docker.xuanyuan.run/Tecnativa/coolapp
        environment:
            DB_HOST: db  # 数据库连接
        depends_on:
            - db

    # 数据库服务   
    db:
        image: docker.xuanyuan.run/postgres:alpine

networks:
    default:
        internal: true  # 内部网络，默认隔离外部访问 except通过代理
    public:  # 公共网络，用于代理对外连接

配置说明

• 两个代理服务分别为两个字体域名创建，通过aliases在内部网络中模拟目标域名
• PRE_RESOLVE: 1确保代理正确解析外部域名，而非内部网络中的本地地址
• 代理同时连接内部网络（供应用访问）和公共网络（实现外部连接），实现特定域名的访问控制

通过此配置，应用可正常加载字体，同时保持其他外部网络隔离，解决了网络隔离与功能可用性的矛盾。