本站支持搜索的镜像仓库：Docker Hub、gcr.io、ghcr.io、quay.io、k8s.gcr.io、registry.gcr.io、elastic.co、mcr.microsoft.com

wollomatic/socket-proxy

轻量级、安全优先的Unix socket代理，设计用于代理Docker socket（如给Traefik使用），支持细粒度访问控制，镜像极小且无外部依赖。

7 收藏0 次下载activewollomatic镜像

🚀轩辕镜像专业版更稳定💎一键安装 Docker 配置镜像源

中文简介版本下载

🚀轩辕镜像专业版更稳定💎一键安装 Docker 配置镜像源

socket-proxy

关于

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片段配置健康检查：

# [...]
    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部署：

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可通过命令行参数或环境变量配置，若同时设置，环境变量将被忽略。

参数	环境变量	默认值	描述
`-allowfrom`	`SP_ALLOWFROM`	`127.0.0.1/32`	指定允许连接代理的客户端IP地址或主机名（逗号分隔）。默认仅允许本地连接，这是默认安全设计。允许所有IPv4地址可设为`-allowfrom=0.0.0.0/0`；也可设主机名，如`-allowfrom=traefik`或`-allowfrom=traefik,dozzle`。无论如何，切勿将socket-proxy暴露到公网。
`-allowbindmountfrom`	`SP_ALLOWBINDMOUNTFROM`	（未设置）	指定允许作为绑定挂载源的目录（逗号分隔）。未设置则不限制；设置后仅允许从指定目录及其子目录进行绑定挂载，目录需以`/`开头。例如`-allowbindmountfrom=/home,/var/log`允许从`/home`、`/var/log`及其子目录挂载。
`-allowhealthcheck`	`SP_ALLOWHEALTHCHECK`	（未设置/false）	若设置，允许内置健康检查二进制文件通过TCP端口55555（`127.0.0.1:55555/health`）检查socket连接。
`-listenip`	`SP_LISTENIP`	`127.0.0.1`	指定服务器绑定的IP地址。
`-logjson`	`SP_LOGJSON`	（未设置/false）	若设置，启用JSON格式日志；否则为纯文本格式。
`-loglevel`	`SP_LOGLEVEL`	`INFO`	设置日志级别，可选值：`DEBUG`、`INFO`、`WARN`、`ERROR`。
`-proxyport`	`SP_PROXYPORT`	`2375`	定义代理监听的TCP端口。
`-shutdowngracetime`	`SP_SHUTDOWNGRACETIME`	`10`	收到sigterm或sigint后，等待优雅关闭TCP服务器的时间（秒）。
`-socketpath`	`SP_SOCKETPATH`	`/var/run/docker.sock`	指定要连接的Unix socket路径，默认连接Docker守护进程socket。
`-stoponwatchdog`	`SP_STOPONWATCHDOG`	（未设置/false）	若设置，监控检测到Unix socket不可用时将停止socket-proxy。
`-watchdoginterval`	`SP_WATCHDOGINTERVAL`	`0`	检查socket可用性的间隔（秒），0或未设置则禁用检查。
`-proxysocketendpoint`	`SP_PROXYSOCKETENDPOINT`	（未设置）	代理到指定Unix socket，而非TCP端口。
`-proxysocketendpointfilemode`	`SP_PROXYSOCKETENDPOINTFILEMODE`	`0600`	为过滤后的Unix socket端点显式设置文件权限（仅与`-proxysocketendpoint`一起使用）。