添加qiming-rcoder模块
This commit is contained in:
Codex
380
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
Normal file
380
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 反向代理服务
|
||||
|
||||
<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)
|
||||
Reference in New Issue
Block a user