uds-proxy

Appearance

API 文档 ​

uds-proxy 提供简洁的 RESTful API 接口。

端点概览 ​

端点方法说明
/GET服务信息
/healthGET健康检查
/proxyALL代理请求

服务信息 ​

GET / ​

返回服务基本信息和使用说明。

响应示例：

json
{
  "service": "uds-proxy",
  "version": "0.1.0",
  "usage": {
    "endpoint": "/proxy",
    "params": {
      "path": "Unix socket 文件路径（必需）",
      "url": "目标 URL 路径（默认: /）",
      "method": "覆盖 HTTP 方法（可选）"
    },
    "example": "/proxy?path=/var/run/docker.sock&url=/version"
  }
}

健康检查 ​

GET /health ​

用于服务健康检查，适用于负载均衡器或监控系统。

响应：

json
{
  "status": "ok"
}

状态码： 200 OK

代理请求 ​

[ALL] /proxy ​

核心代理端点，支持所有 HTTP 方法。

请求参数 ​

参数类型必需说明
pathstring是Unix socket 文件路径
urlstring否目标 URL 路径，默认 /
methodstring否覆盖 HTTP 方法
*any否其他参数将转发到目标服务

请求头转发 ​

所有请求头将自动转发到目标服务，以下头部除外：

  • Host（将被替换为 localhost）

请求体转发 ​

对于 POST、PUT、PATCH 等方法，请求体将完整转发。

响应 ​

代理成功时，返回目标服务的原始响应，包括：

  • 状态码
  • 响应头
  • 响应体

错误响应 ​

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

状态码说明响应体
2xx/4xx/5xx透传目标服务响应目标服务响应体
400缺少 path 参数无
502Socket 不存在或连接失败无
504请求超时无

设计原则：调用方通过状态码区分是目标服务响应还是网关错误。网关错误无 body，目标服务响应原样透传。

使用示例 ​

基本 GET 请求 ​

bash
curl "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/version"

带查询参数的请求 ​

bash
# 额外参数自动转发
curl "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/containers/json&all=true&limit=10"

POST 请求 ​

bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"Image": "nginx"}' \
  "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/containers/create"

覆盖 HTTP 方法 ​

bash
# 使用 method 参数覆盖实际请求方法
curl "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/containers/abc123&method=DELETE"

自定义请求头 ​

bash
curl -H "X-Custom-Header: value" \
  "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/info"

调试技巧 ​

查看详细请求信息 ​

bash
curl -v "http://localhost:8080/proxy?path=/var/run/docker.sock&url=/version"

启用访问日志 ​

默认情况下访问日志已启用，可在终端查看请求详情：

2024/01/15 10:30:45 GET /proxy?path=/var/run/docker.sock&url=/version 200 150ms

禁用访问日志 ​

bash
./uds-proxy --no-access-log