llm-worker-proxy：反向连接架构的LLM推理代理，实现私有GPU集群的统一调度

一个采用反向连接架构的中央HTTP代理，通过WebSocket将推理请求路由到认证的远程工作节点，支持队列管理、流式传输和请求取消，专为私有化GPU集群设计。

问题背景：传统LLM部署的痛点\n\n在管理多台GPU服务器进行大语言模型推理时，开发者通常面临以下困境：\n\n直接暴露方案需要为每台服务器配置端口转发、DNS解析和防火墙规则，不仅配置繁琐，还存在安全隐患。当GPU节点位于家庭网络或内网环境时，公网访问的配置更是复杂。\n\n传统负载均衡方案如nginx或HAProxy虽然能统一入口，但它们不理解LLM特有的流式传输语义，也无法处理请求取消、队列管理等场景。当某个工作节点繁忙时，请求可能被错误地转发过去，导致用户体验下降。\n\n云端路由服务如LiteLLM或OpenRouter虽然功能完善，但主要面向公有云场景设计，并非为私有硬件的"回连"模式优化。\n\n## 架构革新：反向连接模式\n\nllm-worker-proxy采用了一种巧妙的反向连接架构，彻底改变了GPU集群的接入方式：\n\n\n客户端 (curl, Claude Code, LiteLLM, Open WebUI...)\n │\n │ POST /v1/chat/completions\n ▼\n┌──────────────────┐\n│ proxy-server │◄─── 工作节点通过WebSocket主动连接\n│ (单一稳定端点) │ GPU服务器无需开放入站端口\n└──────────────────┘\n │ 将请求路由到最佳可用工作节点\n ▼\n┌────────┐ ┌────────┐ ┌────────┐\n│worker-1│ │worker-2│ │worker-3│\n│ llama │ │ ollama │ │ vllm │ ← 你的GPU服务器，\n│ server │ │ │ │ │ 位于任何网络的任何位置\n└────────┘ └────────┘ └────────┘\n\n\n这种架构的核心优势在于：工作节点主动连接到中央代理，而非等待客户端直接访问。这意味着GPU服务器可以位于NAT后面、家庭网络中，或者任何只有出站连接的环境中，无需配置端口转发或暴露公网IP。\n\n## 核心功能详解\n\n### 队列管理与负载均衡\n\n代理服务器内置了智能队列系统：\n\n- 可配置队列深度：当所有工作节点繁忙时，请求进入队列等待（默认最大100个）\n- 超时控制：队列中的请求可设置超时时间（默认30秒），避免无限等待\n- 负载感知路由：工作节点上报当前负载，代理优先将请求分配给空闲节点\n\n### 流式传输支持\n\n与不理解SSE（Server-Sent Events）的传统代理不同，llm-worker-proxy完整支持流式响应：\n\n- 透传SSE块：从后端到客户端的流式数据保持顺序和终止信号\n- 端到端取消：客户端断开连接时，取消信号会逐级传播到工作节点再到后端，避免资源浪费\n\n### 高可用与容错\n\n- 自动重队列：如果工作节点在处理请求时宕机，请求会自动重新进入队列分配给其他节点\n- 心跳检测：代理通过心跳机制识别失效节点并清理\n- 优雅退出：工作节点可以安全关闭，新节点会自动接管队列中的工作\n\n### 认证与安全\n\n- 工作节点认证：通过共享密钥验证工作节点身份，防止未授权接入\n- 认证冷却恢复：工作节点在认证失败后会优雅地进入退避重试，避免风暴请求\n\n## 部署与使用\n\n### Docker快速启动\n\n项目提供了预构建的容器镜像，托管于GitHub Container Registry：\n\nbash\n# 拉取最新镜像\ndocker pull ghcr.io/ericflo/llm-worker-proxy/proxy-server:latest\ndocker pull ghcr.io/ericflo/llm-worker-proxy/worker-daemon:latest\n\n# 启动代理\ndocker run -p 8080:8080 \\\n -e WORKER_SECRET=mysecret \\\n -e LISTEN_ADDR=0.0.0.0:8080 \\\n ghcr.io/ericflo/llm-worker-proxy/proxy-server:latest\n\n# 启动工作节点（在GPU服务器上）\ndocker run \\\n -e PROXY_URL=http://<proxy-host>:8080 \\\n -e WORKER_SECRET=mysecret \\\n -e BACKEND_URL=http://host.docker.internal:8000 \\\n -e MODELS=llama3.2:3b \\\n ghcr.io/ericflo/llm-worker-proxy/worker-daemon:latest\n\n\n### Docker Compose一键部署\n\n项目包含完整的docker-compose配置，适合本地快速验证：\n\nbash\ngit clone https://github.com/ericflo/llm-worker-proxy.git\ncd llm-worker-proxy\ndocker compose up\n\n\n这会自动启动代理服务器和一个连接到本地llama-server（假设运行在8081端口）的工作节点。\n\n### 从源码构建\n\n对于需要定制或贡献代码的开发者，可以使用Rust工具链从源码构建：\n\nbash\ncargo build --release\n\n# 启动代理\n./target/release/proxy-server \\\n --listen 0.0.0.0:8080 \\\n --worker-secret mysecret\n\n# 启动工作节点\n./target/release/worker-daemon \\\n --proxy-url http://<proxy-host>:8080 \\\n --worker-secret mysecret \\\n --backend-url http://127.0.0.1:8000 \\\n --models llama3.2:3b,llama3.2:1b\n\n\n## API兼容性\n\n代理服务器提供与OpenAI和Anthropic兼容的API端点：\n\n- POST /v1/chat/completions - 标准对话补全\n- POST /v1/responses - Anthropic风格响应\n- POST /v1/messages - 消息接口\n- GET /v1/models - 模型列表\n\n这意味着现有客户端（如Claude Code、Open WebUI、LiteLLM）可以零改动接入。\n\n## 配置参数\n\n### 代理服务器配置\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| --listen | LISTEN_ADDR | 127.0.0.1:8080 | 监听地址 |\n| --worker-secret | WORKER_SECRET | (必需) | 工作节点认证密钥 |\n| --max-queue-len | MAX_QUEUE_LEN | 100 | 最大队列长度 |\n| --queue-timeout | QUEUE_TIMEOUT_SECS | 30 | 队列超时时间 |\n| --request-timeout | REQUEST_TIMEOUT_SECS | 300 | 请求超时时间 |\n\n### 工作节点配置\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| --proxy-url | PROXY_URL | http://127.0.0.1:8080 | 代理服务器地址 |\n| --backend-url | BACKEND_URL | http://127.0.0.1:8000 | 本地模型后端地址 |\n| --models | MODELS | default | 支持的模型列表 |\n| --max-concurrency | MAX_CONCURRENCY | 1 | 最大并发请求数 |\n| --worker-name | WORKER_NAME | worker | 工作节点名称 |\n\n## 适用场景\n\n### 家庭GPU用户\n\n拥有多台带GPU的电脑（如游戏PC、工作站、MacBook Pro）的用户，可以通过llm-worker-proxy统一API入口，无需关心请求实际由哪台设备处理。\n\n### 企业私有化部署\n\n对于需要在内部网络部署LLM服务的企业，该方案避免了复杂的网络配置。GPU服务器可以分布在不同机房或办公室，只要能够访问中央代理即可。\n\n### 研究环境\n\n研究人员经常需要在不同模型和硬件配置间切换。llm-worker-proxy允许动态添加或移除工作节点，无需更新客户端配置。工作节点甚至可以动态更新支持的模型列表而无需重连。\n\n## 质量保证\n\n项目采用Rust编写，具有内存安全和并发安全优势。测试覆盖三个层次：\n\n- 黑盒契约测试：验证代理、队列、流式传输和取消语义的规范符合性\n- HTTP集成测试：代理服务器的实时HTTP接口测试\n- 端到端测试：工作节点与真实后端的完整链路测试\n\nCI流水线包含代码格式化检查（cargo fmt）、静态分析（cargo clippy）和完整测试套件。\n\n## 总结\n\nllm-worker-proxy通过反向连接架构解决了私有GPU集群管理的核心痛点。它不仅简化了网络配置，还提供了生产级的队列管理、流式传输和容错能力。对于希望统一管理分散GPU资源的个人用户和团队，这是一个轻量但功能完整的解决方案。\n\n项目的MIT许可证和清晰的架构文档（包括行为契约和架构草图）也为社区贡献和二次开发提供了良好基础。

问题背景：传统LLM部署的痛点\n\n在管理多台GPU服务器进行大语言模型推理时，开发者通常面临以下困境：\n\n直接暴露方案需要为每台服务器配置端口转发、DNS解析和防火墙规则，不仅配置繁琐，还存在安全隐患。当GPU节点位于家庭网络或内网环境时，公网访问的配置更是复杂。\n\n传统负载均衡方案如nginx或HAProxy虽然能统一入口，但它们不理解LLM特有的流式传输语义，也无法处理请求取消、队列管理等场景。当某个工作节点繁忙时，请求可能被错误地转发过去，导致用户体验下降。\n\n云端路由服务如LiteLLM或OpenRouter虽然功能完善，但主要面向公有云场景设计，并非为私有硬件的"回连"模式优化。\n\n架构革新：反向连接模式\n\nllm-worker-proxy采用了一种巧妙的反向连接架构，彻底改变了GPU集群的接入方式：\n\n\n客户端 (curl, Claude Code, LiteLLM, Open WebUI...)\n │\n │ POST /v1/chat/completions\n ▼\n┌──────────────────┐\n│ proxy-server │◄─── 工作节点通过WebSocket主动连接\n│ (单一稳定端点) │ GPU服务器无需开放入站端口\n└──────────────────┘\n │ 将请求路由到最佳可用工作节点\n ▼\n┌────────┐ ┌────────┐ ┌────────┐\n│worker-1│ │worker-2│ │worker-3│\n│ llama │ │ ollama │ │ vllm │ ← 你的GPU服务器，\n│ server │ │ │ │ │ 位于任何网络的任何位置\n└────────┘ └────────┘ └────────┘\n\n\n这种架构的核心优势在于：工作节点主动连接到中央代理，而非等待客户端直接访问。这意味着GPU服务器可以位于NAT后面、家庭网络中，或者任何只有出站连接的环境中，无需配置端口转发或暴露公网IP。\n\n核心功能详解\n\n队列管理与负载均衡\n\n代理服务器内置了智能队列系统：\n\n- 可配置队列深度：当所有工作节点繁忙时，请求进入队列等待（默认最大100个）\n- 超时控制：队列中的请求可设置超时时间（默认30秒），避免无限等待\n- 负载感知路由：工作节点上报当前负载，代理优先将请求分配给空闲节点\n\n流式传输支持\n\n与不理解SSE（Server-Sent Events）的传统代理不同，llm-worker-proxy完整支持流式响应：\n\n- 透传SSE块：从后端到客户端的流式数据保持顺序和终止信号\n- 端到端取消：客户端断开连接时，取消信号会逐级传播到工作节点再到后端，避免资源浪费\n\n高可用与容错\n\n- 自动重队列：如果工作节点在处理请求时宕机，请求会自动重新进入队列分配给其他节点\n- 心跳检测：代理通过心跳机制识别失效节点并清理\n- 优雅退出：工作节点可以安全关闭，新节点会自动接管队列中的工作\n\n认证与安全\n\n- 工作节点认证：通过共享密钥验证工作节点身份，防止未授权接入\n- 认证冷却恢复：工作节点在认证失败后会优雅地进入退避重试，避免风暴请求\n\n部署与使用\n\nDocker快速启动\n\n项目提供了预构建的容器镜像，托管于GitHub Container Registry：\n\nbash\n拉取最新镜像\ndocker pull ghcr.io/ericflo/llm-worker-proxy/proxy-server:latest\ndocker pull ghcr.io/ericflo/llm-worker-proxy/worker-daemon:latest\n\n启动代理\ndocker run -p 8080:8080 \\\n -e WORKER_SECRET=mysecret \\\n -e LISTEN_ADDR=0.0.0.0:8080 \\\n ghcr.io/ericflo/llm-worker-proxy/proxy-server:latest\n\n启动工作节点（在GPU服务器上）\ndocker run \\\n -e PROXY_URL=http://<proxy-host>:8080 \\\n -e WORKER_SECRET=mysecret \\\n -e BACKEND_URL=http://host.docker.internal:8000 \\\n -e MODELS=llama3.2:3b \\\n ghcr.io/ericflo/llm-worker-proxy/worker-daemon:latest\n\n\nDocker Compose一键部署\n\n项目包含完整的docker-compose配置，适合本地快速验证：\n\nbash\ngit clone https://github.com/ericflo/llm-worker-proxy.git\ncd llm-worker-proxy\ndocker compose up\n\n\n这会自动启动代理服务器和一个连接到本地llama-server（假设运行在8081端口）的工作节点。\n\n从源码构建\n\n对于需要定制或贡献代码的开发者，可以使用Rust工具链从源码构建：\n\nbash\ncargo build --release\n\n启动代理\n./target/release/proxy-server \\\n --listen 0.0.0.0:8080 \\\n --worker-secret mysecret\n\n启动工作节点\n./target/release/worker-daemon \\\n --proxy-url http://<proxy-host>:8080 \\\n --worker-secret mysecret \\\n --backend-url http://127.0.0.1:8000 \\\n --models llama3.2:3b,llama3.2:1b\n\n\nAPI兼容性\n\n代理服务器提供与OpenAI和Anthropic兼容的API端点：\n\n- POST /v1/chat/completions - 标准对话补全\n- POST /v1/responses - Anthropic风格响应\n- POST /v1/messages - 消息接口\n- GET /v1/models - 模型列表\n\n这意味着现有客户端（如Claude Code、Open WebUI、LiteLLM）可以零改动接入。\n\n配置参数\n\n代理服务器配置\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| --listen | LISTEN_ADDR | 127.0.0.1:8080 | 监听地址 |\n| --worker-secret | WORKER_SECRET | (必需) | 工作节点认证密钥 |\n| --max-queue-len | MAX_QUEUE_LEN | 100 | 最大队列长度 |\n| --queue-timeout | QUEUE_TIMEOUT_SECS | 30 | 队列超时时间 |\n| --request-timeout | REQUEST_TIMEOUT_SECS | 300 | 请求超时时间 |\n\n工作节点配置\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| --proxy-url | PROXY_URL | http://127.0.0.1:8080 | 代理服务器地址 |\n| --backend-url | BACKEND_URL | http://127.0.0.1:8000 | 本地模型后端地址 |\n| --models | MODELS | default | 支持的模型列表 |\n| --max-concurrency | MAX_CONCURRENCY | 1 | 最大并发请求数 |\n| --worker-name | WORKER_NAME | worker | 工作节点名称 |\n\n适用场景\n\n家庭GPU用户\n\n拥有多台带GPU的电脑（如游戏PC、工作站、MacBook Pro）的用户，可以通过llm-worker-proxy统一API入口，无需关心请求实际由哪台设备处理。\n\n企业私有化部署\n\n对于需要在内部网络部署LLM服务的企业，该方案避免了复杂的网络配置。GPU服务器可以分布在不同机房或办公室，只要能够访问中央代理即可。\n\n研究环境\n\n研究人员经常需要在不同模型和硬件配置间切换。llm-worker-proxy允许动态添加或移除工作节点，无需更新客户端配置。工作节点甚至可以动态更新支持的模型列表而无需重连。\n\n质量保证\n\n项目采用Rust编写，具有内存安全和并发安全优势。测试覆盖三个层次：\n\n- 黑盒契约测试：验证代理、队列、流式传输和取消语义的规范符合性\n- HTTP集成测试：代理服务器的实时HTTP接口测试\n- 端到端测试：工作节点与真实后端的完整链路测试\n\nCI流水线包含代码格式化检查（cargo fmt）、静态分析（cargo clippy）和完整测试套件。\n\n总结\n\nllm-worker-proxy通过反向连接架构解决了私有GPU集群管理的核心痛点。它不仅简化了网络配置，还提供了生产级的队列管理、流式传输和容错能力。对于希望统一管理分散GPU资源的个人用户和团队，这是一个轻量但功能完整的解决方案。\n\n项目的MIT许可证和清晰的架构文档（包括行为契约和架构草图）也为社区贡献和二次开发提供了良好基础。