socket-proxy

最新镜像

• wollomatic/socket-proxy:1.10.0 / ghcr.io/wollomatic/socket-proxy:1.10.0
• wollomatic/socket-proxy:1 / ghcr.io/wollomatic/socket-proxy:1

关于

socket-proxy 是一款轻量级、默认安全的Unix socket代理。尽管最初设计用于将Docker socket代理给Traefik，但也可用于其他场景。其设计深受 tecnativa/docker-socket-proxy 启发。

额外优势在于，socket-proxy可用于检查客户端应用的API调用。与其他解决方案相比，其优势在于极小的容器镜像（from-scratch镜像），无任何外部依赖（无操作系统、无软件包，仅包含Go标准库）。设计以安全为核心，提供安全默认配置及额外安全层（基于IP地址的访问控制）。

允许列表按HTTP方法单独配置，使用Go正则表达式语法，支持细粒度控制允许的HTTP方法。

源代码托管于 GitHub: wollomatic/socket-proxy。

[!NOTE] 从1.6.0版本开始，socket-proxy容器镜像也可在GHCR获取。

快速开始

示例可在 wiki 及仓库的examples目录中找到。

警告

使用前需了解其工作原理。切勿将socket-proxy暴露到公网，仅用于安全环境。

安装

容器镜像可在 Docker Hub (wollomatic/socket-proxy) 和 GitHub Container Registry (ghcr.io/wollomatic/socket-proxy) 获取。

如需固定版本，使用版本标签（如 wollomatic/socket-proxy:1.10.0 或 ghcr.io/wollomatic/socket-proxy:1.10.0）。如需始终使用最新版本，使用1标签（wollomatic/socket-proxy:1 或 ghcr.io/wollomatic/socket-proxy:1），该标签在无部署破坏性变更时保持有效。

可能存在带有testing标签的镜像，仅用于测试，其文档可能仅在GitHub提交消息中提供，不建议用于生产环境。

所有socket-proxy发布镜像均使用Cosign签名。公钥可在 GitHub: wollomatic/socket-proxy/main/cosign.pub 和 [***] 获取。详情参见 安全策略。自1.6版本起，所有多架构镜像均已签名。

配置访问权限

由于默认安全设计，需显式允许所有访问。这是额外安全层，不能替代防火墙、网络分段等其他安全措施。切勿将socket-proxy暴露到公网。

配置TCP监听器

默认情况下，socket-proxy仅监听127.0.0.1。根据需求，可通过-listenip参数设置其他监听地址。在Docker镜像中使用时，几乎所有场景下-listenip=0.0.0.0为正确配置。

使用Unix socket替代TCP监听器

如需将Unix socket代理/过滤到新的Unix socket（而非TCP监听器），需通过-proxysocketendpoint参数或SP_PROXYSOCKETENDPOINT环境变量设置新Unix socket的路径，这将同时禁用TCP监听器。例如：-proxysocketendpoint=/tmp/filtered-socket.sock

[!NOTE] 1.10.0版本之前的socket-proxy将Unix socket的默认文件权限设为0400，而非文档中所述的0600。

配置IP地址或主机名允许列表

默认仅允许127.0.0.1/32连接到socket-proxy。可根据需求通过-allowfrom参数设置其他允许列表。除IP网络外，还可配置主机名，例如-allowfrom=traefik或-allowfrom=traefik,dozzle，以显式允许特定主机名连接。

配置请求允许列表

必须为客户端应用所需的每个HTTP方法配置正则表达式允许列表。参数名称为-allow后接HTTP方法（如-allowGET）。若设置该参数且入站请求匹配方法和路径正则表达式，则允许请求；未设置则禁止对应HTTP方法。

也可通过环境变量配置，变量名为SP_ALLOW_后接HTTP方法（如SP_ALLOW_GET）。若同时配置命令行参数和环境变量，环境变量将被忽略。

使用Go的正则表达式语法，字符串开头自动添加^，结尾自动添加$。无效正则表达式将导致程序终止。

命令行示例：

• '-allowGET=/v1\..{1,2}/(version|containers/.*|events.*)' 可用于允许Traefik v2访问Docker socket
• '-allowHEAD=.* 允许所有HEAD请求

环境变量示例：

• 'SP_ALLOW_GET="/v1\..{1,2}/(version|containers/.*|events.*)"' 可用于允许Traefik v2访问Docker socket
• 'SP_ALLOW_HEAD=".*" 允许所有HEAD请求

更多信息参见 Go正则表达式文档，在线测试工具推荐 regex101.com。

如需确定客户端应用使用的HTTP请求，可在安全环境中将socket-proxy日志级别设为debug并允许所有请求，然后查看日志输出。

配置绑定挂载限制

默认不限制绑定挂载。如需通过限制绑定挂载源目录增强安全性，可使用-allowbindmountfrom参数或SP_ALLOWBINDMOUNTFROM环境变量。配置后，仅允许从指定目录及其子目录进行绑定挂载，目录需以/开头，多个目录用逗号分隔。

示例：

• -allowbindmountfrom=/home,/var/log 允许从/home、/var/log及其子目录（如/home/user/data或/var/log/app）进行绑定挂载
• SP_ALLOWBINDMOUNTFROM="/app/data,/tmp" 允许从/app/data和/tmp目录进行绑定挂载

绑定挂载限制适用于相关Docker API端点，支持传统绑定挂载语法（-v /host/path:/container/path）和现代挂载语法。

注意：该功能仅限制绑定挂载，不影响其他挂载类型（卷、tmpfs等）。

容器健康检查

默认禁用健康检查。由于socket-proxy容器可能不暴露到公网，镜像中包含独立健康检查二进制文件。如需启用，需设置-allowhealthcheck参数或SP_ALLOWHEALTHCHECK=true环境变量。然后可通过如下docker-compose片段配置健康检查：

compose
# [...]
    healthcheck:
      test: ["CMD", "./healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 2
# [...]

Socket监控

在某些情况下（如Docker引擎更新后），socket连接可能中断导致客户端应用故障。可配置socket-proxy定期检查socket可用性，若不可用则停止，以便容器编排工具重启。默认禁用该功能。如需启用，设置-watchdoginterval参数（或SP_WATCHDOGINTERVAL环境变量）为检查间隔（秒），并设置-stoponwatchdog参数（或SP_STOPONWATCHDOG=true）。若未设置-stoponwatchdog，监控仅记录错误日志并继续运行（问题仍存在）。

代理Docker socket到Traefik的示例

需了解如何在此环境中安装Traefik，示例参见 wollomatic/traefik2-hardened。

可通过docker compose部署：

compose
services:
  dockerproxy:
    image: wollomatic/socket-proxy:<<version>> # 选择最新镜像
    restart: unless-stopped
    user: "65534:<<你的Docker组ID>>"
    mem_limit: 64M
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges
    command:
      - '-loglevel=info'
      - '-listenip=0.0.0.0'
      - '-allowfrom=traefik' # 仅允许主机名"traefik"连接
      - '-allowGET=/v1\..{1,2}/(version|containers/.*|events.*)'
      - '-allowbindmountfrom=/var/log,/tmp' # 限制绑定挂载到特定目录
      - '-watchdoginterval=3600' # 每小时检查一次socket可用性
      - '-stoponwatchdog' # 出错时停止程序，让compose重启
      - '-shutdowngracetime=5' # 关闭前等待5秒
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - docker-proxynet    # 切勿暴露到公网！
                           # 这是仅Traefik和socket-proxy使用的私有网络
                           # 不同于traefik-servicenet

  traefik:
    # [...] 完整示例参见github.com/wollomatic/traefik-hardened
    depends_on:
      - dockerproxy
    networks:
      - traefik-servicenet # Traefik公共网络
      - docker-proxynet    # 仅限制Traefik和socket-proxy使用
  
networks:
  traefik-servicenet:
    external: true
  docker-proxynet:
    driver: bridge
    internal: true

检查客户端应用的API调用

如需记录客户端应用的API调用，将日志级别设为DEBUG并允许所有请求，然后查看日志输出。允许所有请求的参数配置如下：

- '-loglevel=debug'
- '-allowGET=.*'
- '-allowHEAD=.*'
- '-allowPOST=.*'
- '-allowPUT=.*'
- '-allowPATCH=.*'
- '-allowDELETE=.*'
- '-allowCONNECT=.*'
- '-allowTRACE=.*'
- '-allowOPTIONS=.*'

所有参数和环境变量

socket-proxy可通过命令行参数或环境变量配置，若同时设置，环境变量将被忽略。

变更日志

1.0 - 初始版本

1.1 - 为-allowfrom参数添加主机名支持

1.2 - 重新格式化程序启动时允许列表的日志输出

1.3 - 允许在-allowfrom参数中使用逗号分隔的多个主机名（感谢@ildyria）

1.4 - 允许通过环境变量配置

1.5 - 允许将Unix socket作为代理/过滤端点

1.6 - Cosign：签名多架构容器镜像及所有关联的独立镜像。镜像也在GHCR提供。

1.7 - 允许在-allowfrom中使用逗号分隔的CIDR（不仅是1.3+版本中的主机名）

1.8 - 添加可选的绑定挂载限制（感谢@powerman、@C4tWithShell）

1.9 - 为-listenip添加IPv6支持（感谢@op3）

1.10 - 修复socket文件权限（感谢@amanda-wee），优化构建操作（感谢@reneleonhardt）

许可证

本项目采用MIT许可证 - 详见LICENSE文件。

文件cmd/internal/bindmount.go的部分内容采用Apache 2.0许可证。详见该文件注释和LICENSE文件。

致谢

• Chris Wiegman: Protecting Your Docker Socket With Traefik 2 @ChrisWiegman
• tecnativa/docker-socket-proxy
• @justsomescripts 修复环境变量解析以配置Unix socket

替代方案

• ***/cetusguard
• 11notes/docker-socket-proxy