# 反向代理服务

<cite>
**本文引用的文件**
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
- [Cargo.toml](file://Cargo.toml)
- [docker/Dockerfile](file://docker/Dockerfile)
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
- [config.yml](file://config.yml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“反向代理服务”的架构文档，聚焦于基于 Cloudflare Pingora 的高性能反向代理子系统，涵盖其高阶设计、架构模式、系统边界、组件交互、数据流与集成模式。文档解释技术决策、权衡与约束，并给出基础设施要求、可扩展性考虑、部署拓扑、安全与监控、灾难恢复等横切关注点。目标读者既包括工程实践者，也包括对系统架构感兴趣的非技术读者。

## 项目结构
该仓库采用多 Crate 的工作区组织，反向代理能力主要集中在 crates/pingora-proxy 中，而业务服务（如 rcoder、agent_runner）在启动时可按需启用 Pingora 代理服务，并通过统一的路由对外暴露代理状态与统计信息。

```mermaid
graph TB
subgraph "工作区"
A["crates/pingora-proxy<br/>反向代理库"]
B["crates/rcoder<br/>主服务"]
C["crates/agent_runner<br/>代理运行器"]
D["crates/shared_types<br/>共享类型"]
E["crates/docker_manager<br/>Docker 管理"]
F["crates/acp_adapter<br/>ACP 适配"]
G["crates/claude-code-agent<br/>Claude 代码代理"]
H["crates/codex-acp-agent<br/>Codex ACP 代理"]
end
subgraph "基础设施"
I["docker/Dockerfile<br/>镜像构建"]
J["docker/docker-compose.yml<br/>编排"]
K["config.yml<br/>服务配置"]
end
B --> A
C --> A
A --> D
B --> E
C --> E
B --> F
C --> G
C --> H
I --> J
J --> B
J --> C
K --> B
K --> C
```

图表来源
- [Cargo.toml](file://Cargo.toml#L1-L205)
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
- [config.yml](file://config.yml#L1-L161)

章节来源
- [Cargo.toml](file://Cargo.toml#L1-L205)
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
- [config.yml](file://config.yml#L1-L161)

## 核心组件
- Pingora 代理库（crates/pingora-proxy）
  - 提供基于 Cloudflare Pingora 的高性能反向代理能力，支持路径与查询参数两种端口提取方式、动态后端管理、负载均衡、健康检查与指标统计。
- Pingora 服务器管理器（PingoraServerManager）
  - 负责启动/停止 Pingora 服务器，绑定监听端口，注入代理服务，处理优雅关闭。
- 代理服务与代理实现（PingoraProxyService / PortProxy）
  - 实现 Pingora 的 ProxyHttp trait，负责上游请求过滤、路径重写、端口提取、后端选择、响应过滤与指标统计。
- 配置模块（ProxyConfig）
  - 定义监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与日志开关等。
- 业务服务（rcoder / agent_runner）
  - 在启动时根据配置决定是否启用 Pingora 代理服务；通过统一路由暴露代理状态、统计与配置查询接口；并提供健康检查与优雅关闭。

章节来源
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L250)
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L372)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)

## 架构总览
反向代理服务采用“库+管理器+业务服务”的分层架构：
- 库层：提供代理能力与指标统计，支持动态后端与健康检查。
- 管理器层：封装 Pingora 服务器生命周期，负责监听、服务注册与优雅关闭。
- 业务层：在 rcoder/agent_runner 中按需启用代理服务，提供统一的代理 API 与健康检查。

```mermaid
graph TB
subgraph "业务服务"
RC["rcoder 主服务"]
AR["agent_runner 服务"]
end
subgraph "反向代理子系统"
PM["PingoraServerManager<br/>服务器管理器"]
PS["PingoraProxyService<br/>代理服务"]
PP["PortProxy<br/>代理实现"]
PC["ProxyConfig<br/>配置"]
end
subgraph "外部系统"
U["客户端/浏览器"]
BE["后端服务<br/>任意端口"]
end
U --> PM
PM --> PS
PS --> PP
PP --> BE
RC --> PM
AR --> PM
RC --> PC
AR --> PC
```

图表来源
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)

## 详细组件分析

### 组件一：Pingora 服务器管理器（PingoraServerManager）
- 职责
  - 创建并启动 Pingora 服务器，绑定监听端口，注入代理服务。
  - 提供优雅关闭机制，通过 oneshot 通道接收关闭信号并终止服务器。
- 关键行为
  - 通过 Server::new 与 bootstrap 初始化服务器。
  - 使用 http_proxy_service 注册代理服务，add_tcp 绑定监听地址。
  - 通过 ProxyServiceWrapper 实现 Pingora 的 ProxyHttp trait，委托给 PortProxy。
- 与业务服务集成
  - rcoder/agent_runner 在启动时创建 PingoraServerManager 并在后台任务中运行，同时将服务引用注入 AppState，用于读取代理指标。

```mermaid
classDiagram
class PingoraServerManager {
-config : ProxyConfig
-service : Arc<PingoraProxyService>
-shutdown_tx : Option<oneshot : : Sender>
+new(config) PingoraServerManager
+start() Result
+stop() Result
+service() Arc<PingoraProxyService>
}
class ProxyServiceWrapper {
-inner : Arc<PortProxy>
+upstream_peer(...)
+upstream_request_filter(...)
+response_filter(...)
}
PingoraServerManager --> ProxyServiceWrapper : "注册代理服务"
ProxyServiceWrapper --> PortProxy : "委托实现"
```

图表来源
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)

章节来源
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)

### 组件二：代理服务与代理实现（PingoraProxyService / PortProxy）
- 职责
  - PingoraProxyService：维护后端映射、负载均衡算法、指标与健康状态缓存；提供后端增删查、健康检查循环与指标快照。
  - PortProxy：实现 Pingora 的 ProxyHttp trait，完成请求过滤、路径重写、端口提取、后端选择与响应过滤。
- 数据流
  - 请求进入：从请求头提取端口（路径优先，其次查询参数），若端口不在映射中则动态添加默认主机。
  - 上游请求：重写 Host 与 X-Forwarded-Proto，移除 /proxy/{port} 前缀，保留查询参数。
  - 上游响应：记录指标（总请求数、成功率、平均响应时间、每端口统计、活跃连接数）。
- 指标与健康检查
  - 指标：原子计数器与每端口快照；健康检查：基于 TCP 连接超时的周期性检查，支持轮询与一致性哈希（Ketama）负载均衡。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Manager as "PingoraServerManager"
participant Service as "PingoraProxyService"
participant Proxy as "PortProxy"
participant Backend as "后端服务"
Client->>Manager : "HTTP 请求 /proxy/{port}/..."
Manager->>Service : "创建/获取代理服务"
Service->>Proxy : "委托处理请求"
Proxy->>Proxy : "提取端口/重写路径/设置头部"
Proxy->>Service : "记录请求/活跃连接+1"
Proxy->>Backend : "转发请求"
Backend-->>Proxy : "返回响应"
Proxy->>Service : "记录响应/活跃连接-1"
Proxy-->>Client : "返回响应"
```

图表来源
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)

章节来源
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)

### 组件三：配置与启动（ProxyConfig、业务服务 main）
- ProxyConfig
  - 定义监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与日志开关；提供默认值与校验。
- 业务服务启动流程
  - 解析 CLI 与配置文件，按需创建 PingoraServerManager 并启动后台任务。
  - 将 Pingora 服务引用注入 AppState，以便路由层读取代理状态与统计。
  - 提供健康检查端点与优雅关闭信号处理。

```mermaid
flowchart TD
Start(["启动业务服务"]) --> Parse["解析 CLI 与配置"]
Parse --> CheckProxy{"是否启用代理?"}
CheckProxy --> |否| InitAPI["初始化 API 服务"]
CheckProxy --> |是| BuildConfig["构建 ProxyConfig"]
BuildConfig --> NewManager["创建 PingoraServerManager"]
NewManager --> StartProxy["后台启动代理服务"]
StartProxy --> InjectState["注入 AppState含代理服务"]
InjectState --> InitAPI
InitAPI --> Listen["绑定监听端口并启动服务"]
Listen --> End(["运行中"])
```

图表来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)

章节来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)

### 组件四：路由与代理 API（rcoder/agent_runner 路由）
- 路由组织
  - 系统路由：/health、聊天与代理会话管理等。
  - 代理 API：/proxy/status、/proxy/stats、/proxy/config、/proxy/{port}、/proxy/{port}/{*path} 等。
- 与代理服务的协作
  - 路由层通过 AppState 获取 PingoraProxyService，读取健康状态、统计快照与配置信息，用于对外展示。

章节来源
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)

## 依赖关系分析
- 语言与运行时
  - Rust 2024 edition，Tokio 异步运行时，Axum HTTP 服务器，Pingora 负载均衡特性。
- 外部依赖
  - Cloudflare Pingora（lb 特性）、OpenTelemetry（遥测）、Tracing（日志与链路传播）。
- 工作区依赖
  - shared_types 提供共享模型与 gRPC 类型；docker_manager 提供容器管理能力；acp_adapter/claude-code-agent/codex-acp-agent 提供代理生态集成。

```mermaid
graph LR
P["pingora-proxy"] --> L["pingora"]
P --> T["tokio/async-trait"]
P --> O["opentelemetry/tracing"]
RC["rcoder"] --> P
AR["agent_runner"] --> P
RC --> DM["docker_manager"]
AR --> DM
RC --> ST["shared_types"]
AR --> ST
RC --> AC["acp_adapter"]
AR --> CA["claude-code-agent"]
AR --> CO["codex-acp-agent"]
```

图表来源
- [Cargo.toml](file://Cargo.toml#L1-L205)

章节来源
- [Cargo.toml](file://Cargo.toml#L1-L205)

## 性能考量
- 异步 I/O 与事件循环
  - 基于 Tokio 与 Pingora 的异步事件驱动，避免阻塞，提升吞吐。
- 负载均衡与健康检查
  - 支持轮询与一致性哈希（Ketama）；内置 TCP 健康检查，周期性探测后端可用性。
- 指标与可观测性
  - 原子计数器与每端口快照，支持平均响应时间、成功率、活跃连接数等关键指标。
- 路径重写与头部处理
  - 在上游请求过滤阶段重写 Host 与 X-Forwarded-Proto，减少后端复杂度。
- 可扩展性
  - 动态后端管理：按需添加/删除后端，无需重启；支持多端口并行代理。

[本节为通用性能讨论，不直接分析具体文件]

## 故障排查指南
- 启动与健康检查
  - 业务服务提供 /health 健康检查端点；Pingora 代理服务可通过 /proxy/status 与 /proxy/stats 查询状态与统计。
- 日志与遥测
  - 业务服务初始化 Tracing 与 OpenTelemetry，支持 trace_id 传播；日志按天滚动，便于定位问题。
- Docker 环境问题
  - rcoder 在启动时进行宿主机路径解析与 Docker 管理器初始化，若失败会输出详细帮助信息与排障步骤。
- 代理端口提取失败
  - 当请求未携带端口参数或路径不匹配时，将回退到默认后端端口；可在 /proxy/config 查看配置。

章节来源
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)

## 结论
该反向代理服务以 Pingora 为核心，结合动态后端管理、负载均衡与健康检查，提供了高性能、可观测且易于扩展的端口代理能力。业务服务通过统一路由与 AppState 注入，实现了代理状态与统计的可视化与可控性。配合 Docker 编排与日志/遥测体系，满足生产环境的安全、可运维与可扩展需求。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 系统上下文图（概念性）
```mermaid
graph TB
subgraph "外部系统"
Browser["浏览器/客户端"]
Agents["AI 代理容器"]
end
subgraph "RCoder 平台"
API["业务 API 服务"]
Proxy["Pingora 反向代理"]
Stats["指标与健康检查"]
end
Browser --> API
Browser --> Proxy
API --> Stats
Proxy --> Agents
```

[本图为概念性示意，不对应具体代码文件]

### 部署拓扑与基础设施要求
- 容器化
  - 使用 docker-compose 编排，挂载 Docker socket 以支持宿主机路径解析与容器管理。
  - 端口映射：业务服务端口与代理服务端口可分离，默认分别为 8087/8088。
- 镜像与健康检查
  - Dockerfile 提供增强调试镜像，包含性能分析工具与健康检查指令。
- 配置
  - config.yml 定义代理监听端口、默认后端端口、后端主机、端口参数名与健康检查参数。

章节来源
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
- [config.yml](file://config.yml#L1-L161)

### 安全性、监控与灾难恢复
- 安全性
  - 代理在上游请求过滤阶段重写 Host 与 X-Forwarded-Proto，便于后端识别真实来源。
  - 通过健康检查与负载均衡降低单点风险。
- 监控
  - 指标：总请求数、成功/失败数、平均响应时间、每端口统计、活跃连接数。
  - 健康检查：周期性 TCP 探测，支持阈值配置。
- 灾难恢复
  - 业务服务支持优雅关闭，清理动态容器与资源；代理服务支持优雅停止。

章节来源
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)