uds-proxy

• 功能特性 :37+10
• 快速开始 :47+46
  • 安装 :49+12
  • 运行 :61+16
  • 基本用法 :77+16
• API 端点 :93+51
  • GET / :95+17
  • GET /health :112+13
  • [ALL METHODS] /proxy :125+19
• 使用示例 :144+36
  • Docker API 代理 :146+24
  • 其他 Unix Socket 服务 :170+10
• 命令行参数 :180+14
• 错误处理 :194+13
• 项目结构 :207+21
• 开发 :228+21
  • 初始化开发环境 :230+6
  • 常用命令 :236+13
• 相关链接 :249+6
• 许可证 :255+3

一个高性能的 HTTP 到 Unix Domain Socket 代理服务器，使用 Go 语言构建。

功能特性

• 🚀 高性能异步代理，基于 Go 标准库 net/http
• 🔌 HTTP 请求代理到 Unix Socket（如 Docker API）
• 🔄 支持所有 HTTP 方法（GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS）
• 📊 内置健康检查和服务信息端点
• 🔗 完整的查询参数和请求头转发
• 🌐 连接池管理和自动重连
• 📝 可配置的访问日志

快速开始

安装

# 使用 go install 安装（推荐）
go install github.com/lwmacct/251124-uds-proxy/cmd/uds-proxy@latest

# 或从源码构建
git clone https://github.com/lwmacct/251124-uds-proxy.git
cd 251124-uds-proxy
go build -o bin/uds-proxy ./cmd/uds-proxy

运行

# 使用 go install 安装后直接运行
uds-proxy --port 8080

# 自动分配端口（默认写入 /tmp/uds-proxy.port）
uds-proxy

# 指定端口和主机
uds-proxy --host 127.0.0.1 --port 8080

# 禁用访问日志
uds-proxy --port 8080 --no-access-log

基本用法

# 获取服务端口（如果使用了自动分配）
PORT=$(cat /tmp/uds-proxy.port)

# 代理请求到 Docker socket
curl "http://127.0.0.1:$PORT/proxy?path=/var/run/docker.sock&url=/version"

# 健康检查
curl "http://127.0.0.1:$PORT/health"

# 服务信息
curl "http://127.0.0.1:$PORT/"

API 端点

GET /

返回服务信息和使用示例。

响应示例：

{
  "service": "uds-proxy",
  "version": "v1.0.0",
  "description": "HTTP server that proxies requests to Unix domain sockets",
  "usage": "GET /proxy?path=/var/run/docker.sock&url=/containers/json"
}

版本号通过构建时 -ldflags 注入，未注入时显示 Unknown 或 dev-<commit>。

GET /health

健康检查端点，返回服务状态。

响应示例：

{
  "status": "healthy",
  "service": "uds-proxy"
}

[ALL METHODS] /proxy

核心代理端点，将 HTTP 请求转发到 Unix socket。

必需参数：

参数	说明
path	Unix socket 文件路径

可选参数：

参数	说明	默认值
url	目标 URL 路径	/
method	指定 HTTP 方法	请求方法

其他查询参数会自动转发到目标服务。

使用示例

Docker API 代理

# 获取 Docker 版本信息
curl "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/version"

# 列出所有容器
curl "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/containers/json"

# 列出运行中的容器
curl "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/containers/json&all=false"

# 获取系统信息
curl "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/info"

# 列出镜像
curl "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/images/json"

# POST 请求 - 创建容器
curl -X POST "http://127.0.0.1:8080/proxy?path=/var/run/docker.sock&url=/containers/create" \
  -H "Content-Type: application/json" \
  -d '{"Image":"alpine","Cmd":["echo","hello"]}'

其他 Unix Socket 服务

# 代理到自定义服务
curl "http://127.0.0.1:8080/proxy?path=/tmp/myservice.sock&url=/api/status"

# 带查询参数的请求
curl "http://127.0.0.1:8080/proxy?path=/tmp/service.sock&url=/api/search&q=test&limit=10"

命令行参数

参数	短名	默认值	说明
--host	-H	127.0.0.1	监听主机地址
--port	-p	0	监听端口（0 为自动分配）
--port-file		/tmp/uds-proxy.port	端口号写入文件
--timeout		10000	请求超时（毫秒）
--max-conns		10	每个 socket 最大连接数
--max-idle-conns		5	每个 socket 最大空闲连接数
--no-access-log		false	禁用访问日志
--version	-v		打印版本号
--help	-h		显示帮助信息

错误处理

作为纯网关代理，错误时只返回状态码，无响应体：

状态码	说明
2xx	透传目标服务响应
4xx	透传目标服务响应
5xx	透传目标服务响应
400	缺少 path 参数（代理自身错误）
502	网关错误（Socket 不存在、连接失败等）
504	网关超时（目标服务响应超时）

项目结构

251124-uds-proxy/
├── cmd/
│   └── uds-proxy/
│       └── main.go          # CLI 入口
├── internal/
│   ├── command/
│   │   └── udsproxy/        # CLI 命令定义
│   ├── proxy/
│   │   ├── config.go        # 配置结构体
│   │   ├── server.go        # HTTP 服务器
│   │   ├── handlers.go      # 路由处理器
│   │   └── pool.go          # 连接池管理
│   └── version/
│       └── version.go       # 版本信息（构建时注入）
├── go.mod
└── go.sum

开发

初始化开发环境

pre-commit install

常用命令

# 查看所有可用任务
task -a

# 构建项目
go build -o bin/uds-proxy ./cmd/uds-proxy

# 运行测试
go test ./...

相关链接

• 使用 Taskfile 管理项目 CLI
• 使用 Pre-commit 管理 Git hooks
• 使用 urfave/cli 构建 CLI

许可证

MIT License