348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
# 反向代理架构
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
|
||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||
- [README.md](file://README.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概述](#架构概述)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障恢复机制](#故障恢复机制)
|
||
9. [结论](#结论)
|
||
|
||
## 引言
|
||
本文档详细描述了基于Cloudflare Pingora构建的高性能反向代理架构。该架构设计用于在Docker容器环境中统一端口访问多个前端应用，通过端口参数实现灵活的请求路由。文档涵盖了端口路由机制、请求转发流程、状态监控和与主应用的集成模式，解释了选择Pingora而非Nginx的技术决策、性能优化策略和资源隔离方案。
|
||
|
||
## 项目结构
|
||
反向代理功能主要由`pingora-proxy` crate实现，该模块提供了完整的基于Pingora的高性能代理服务。主应用通过集成此模块，实现了对多个后端服务的统一访问和管理。
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "主应用"
|
||
A[rcoder]
|
||
B[agent_runner]
|
||
end
|
||
subgraph "反向代理模块"
|
||
C[pingora-proxy]
|
||
D[config]
|
||
E[service]
|
||
F[server]
|
||
G[pingora_server]
|
||
end
|
||
A --> C
|
||
B --> C
|
||
C --> D
|
||
C --> E
|
||
C --> F
|
||
C --> G
|
||
```
|
||
|
||
**图表来源**
|
||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||
|
||
**章节来源**
|
||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||
|
||
## 核心组件
|
||
反向代理的核心组件包括配置管理、服务实现、服务器管理和请求处理。`ProxyConfig`定义了代理服务的配置参数，`PingoraProxyService`实现了核心的代理逻辑，`ProxyServer`提供了服务器的启动和管理功能，而`PingoraServerManager`则负责完整的Pingora服务器生命周期管理。
|
||
|
||
**章节来源**
|
||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||
|
||
## 架构概述
|
||
基于Pingora的反向代理架构采用分层设计，从配置层到服务层再到服务器层，每一层都有明确的职责。该架构支持HTTP/1.1和HTTP/2，利用Pingora的异步I/O能力实现高性能请求处理。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[客户端请求] --> B[端口路由]
|
||
B --> C{路由规则}
|
||
C --> |/proxy/{port}| D[提取目标端口]
|
||
C --> |?port={port}| E[提取查询参数]
|
||
C --> |默认端口| F[使用默认端口]
|
||
D --> G[动态后端管理]
|
||
E --> G
|
||
F --> G
|
||
G --> H[健康检查]
|
||
H --> I[连接池管理]
|
||
I --> J[请求转发]
|
||
J --> K[后端服务]
|
||
K --> L[响应处理]
|
||
L --> M[客户端响应]
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
|
||
## 详细组件分析
|
||
|
||
### 端口路由机制
|
||
端口路由机制支持两种方式：路径方式（/proxy/{port}/{path}）和查询参数方式（?port={port}）。路径方式优先级高于查询参数方式，系统会首先尝试从路径中提取端口号，如果失败则尝试从查询参数中提取，最后使用默认端口。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([开始]) --> CheckPath{"路径是否以<br/>/proxy/开头?"}
|
||
CheckPath --> |是| ExtractPortFromPath["从路径提取端口<br/>(parts[2].parse())"]
|
||
CheckPath --> |否| CheckQuery{"查询参数中<br/>是否有port?"}
|
||
CheckQuery --> |是| ExtractPortFromQuery["从查询参数提取端口<br/>(param.split_once('=')"]
|
||
CheckQuery --> |否| UseDefaultPort["使用默认端口<br/>(3000)"]
|
||
ExtractPortFromPath --> ValidatePort{"端口有效?"}
|
||
ExtractPortFromQuery --> ValidatePort
|
||
ValidatePort --> |是| ReturnPort["返回提取的端口"]
|
||
ValidatePort --> |否| ReturnDefault["返回默认端口"]
|
||
ReturnPort --> End([结束])
|
||
ReturnDefault --> End
|
||
UseDefaultPort --> End
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L358-L375)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L478-L507)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
|
||
### 请求转发流程
|
||
请求转发流程由`PortProxy`实现，该组件实现了Pingora的`ProxyHttp` trait，负责处理请求的完整生命周期，包括请求头过滤、上游服务器选择和响应过滤。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Proxy as "反向代理"
|
||
participant Backend as "后端服务"
|
||
Client->>Proxy : HTTP请求
|
||
Proxy->>Proxy : 提取目标端口
|
||
Proxy->>Proxy : 动态添加后端(如需要)
|
||
Proxy->>Proxy : 重写Host头为127.0.0.1
|
||
Proxy->>Proxy : 添加代理头(X-Forwarded-Proto等)
|
||
Proxy->>Proxy : 重写请求路径
|
||
Proxy->>Backend : 转发请求
|
||
Backend-->>Proxy : 响应
|
||
Proxy->>Proxy : 记录指标(响应时间等)
|
||
Proxy->>Client : 返回响应
|
||
Note over Proxy,Backend : 基于Pingora的异步代理流程
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L247-L353)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L397)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
|
||
### 状态监控与统计
|
||
反向代理提供了全面的状态监控和统计功能，包括请求计数、成功率、响应时间、活跃连接数等指标。这些指标通过`ProxyMetrics`结构体进行管理，并可通过API接口查询。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ProxyMetrics {
|
||
+total_requests : AtomicU64
|
||
+total_responses : AtomicU64
|
||
+successful_responses : AtomicU64
|
||
+failed_responses : AtomicU64
|
||
+total_response_time_ns : AtomicU64
|
||
+active_connections : AtomicU64
|
||
+port_map : RwLock~HashMap<u16, Arc<PerPortMetrics>>~
|
||
+record_request()
|
||
+record_response()
|
||
+avg_response_time_ms()
|
||
+port_snapshots()
|
||
}
|
||
class PerPortMetrics {
|
||
+requests : AtomicU64
|
||
+successes : AtomicU64
|
||
+failures : AtomicU64
|
||
+total_response_time_ns : AtomicU64
|
||
}
|
||
class PortSnapshot {
|
||
+port : u16
|
||
+requests : u64
|
||
+successes : u64
|
||
+failures : u64
|
||
+total_response_time_ns : u64
|
||
}
|
||
ProxyMetrics --> PerPortMetrics : "包含"
|
||
ProxyMetrics --> PortSnapshot : "生成"
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L26-L180)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L598-L607)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
|
||
### 与主应用的集成模式
|
||
反向代理通过`AppState`与主应用集成，主应用在启动时创建`PingoraProxyService`实例并将其注入应用状态，从而实现状态监控API与实际代理服务的数据共享。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class AppState {
|
||
+sessions : DashMap~String, Arc<ProjectAndContainerInfo>~
|
||
+project_and_agent_map : DashMap~String, Arc<ProjectAndContainerInfo>~
|
||
+config : AppConfig
|
||
+pingora_service : Option~Arc<PingoraProxyService>~
|
||
}
|
||
class PingoraProxyService {
|
||
+config : ProxyConfig
|
||
+backends : Arc~RwLock<HashMap<u16, String>>~
|
||
+use_round_robin : bool
|
||
+metrics : Arc~ProxyMetrics~
|
||
+health_map : Arc~RwLock<HashMap<u16, HealthInfo>>~
|
||
+new(config)
|
||
+create_pingora_proxy()
|
||
+add_backend()
|
||
+remove_backend()
|
||
+list_backends()
|
||
+start_health_check_loop()
|
||
}
|
||
class AppConfig {
|
||
+proxy_config : Option~ProxyConfig~
|
||
+projects_dir : String
|
||
+agent : AgentConfig
|
||
}
|
||
AppState --> PingoraProxyService : "引用"
|
||
AppState --> AppConfig : "包含"
|
||
```
|
||
|
||
**图表来源**
|
||
- [router.rs](file://crates/rcoder/src/router.rs#L27-L35)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L224-L233)
|
||
|
||
**章节来源**
|
||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
|
||
## 依赖分析
|
||
反向代理模块依赖于多个关键的Rust库，包括Pingora系列库用于高性能代理，Tokio用于异步运行时，Tracing用于日志记录，以及Axum用于HTTP服务构建。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[pingora-proxy] --> B[pingora]
|
||
A --> C[pingora-core]
|
||
A --> D[pingora-http]
|
||
A --> E[pingora-proxy]
|
||
A --> F[pingora-load-balancing]
|
||
A --> G[tokio]
|
||
A --> H[tracing]
|
||
A --> I[axum]
|
||
A --> J[reqwest]
|
||
A --> K[async-trait]
|
||
B --> L[Cloudflare Pingora]
|
||
C --> L
|
||
D --> L
|
||
E --> L
|
||
F --> L
|
||
G --> M[Tokio Runtime]
|
||
H --> N[Tracing Framework]
|
||
I --> O[Axum Web Framework]
|
||
J --> P[HTTP Client]
|
||
```
|
||
|
||
**图表来源**
|
||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||
|
||
**章节来源**
|
||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||
|
||
## 性能考虑
|
||
基于Pingora的反向代理在性能方面进行了多项优化，包括异步I/O处理、连接池管理、负载均衡和健康检查。与Nginx相比，Pingora作为Rust编写的库，提供了更好的内存安全性和性能表现。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[性能优化策略] --> B[异步I/O]
|
||
A --> C[连接池]
|
||
A --> D[负载均衡]
|
||
A --> E[健康检查]
|
||
A --> F[零拷贝]
|
||
A --> G[内存安全]
|
||
B --> H["基于Tokio的异步运行时<br/>避免线程阻塞"]
|
||
C --> I["复用TCP连接<br/>减少握手开销"]
|
||
D --> J["Round Robin/Ketama算法<br/>均匀分发请求"]
|
||
E --> K["定期TCP健康检查<br/>自动剔除故障节点"]
|
||
F --> L["避免数据复制<br/>提高吞吐量"]
|
||
G --> M["Rust所有权模型<br/>防止内存泄漏"]
|
||
style A fill:#f9f,stroke:#333,stroke-width:2px
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||
|
||
## 故障恢复机制
|
||
反向代理实现了完善的故障恢复机制，包括健康检查、自动故障转移和连接重试。健康检查定期检测后端服务的可用性，并在服务恢复后自动重新加入负载均衡。
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Healthy
|
||
Healthy --> Unhealthy : "健康检查失败"
|
||
Unhealthy --> Healthy : "健康检查通过"
|
||
Unhealthy --> Timeout : "连接超时"
|
||
Timeout --> Unhealthy : "重试失败"
|
||
Timeout --> Healthy : "重试成功"
|
||
state Healthy {
|
||
[*] --> Active
|
||
Active --> Draining : "服务停止"
|
||
Draining --> [*]
|
||
}
|
||
state Unhealthy {
|
||
[*] --> Inactive
|
||
Inactive --> [*]
|
||
}
|
||
state Timeout {
|
||
[*] --> Retrying
|
||
Retrying --> Healthy : "成功"
|
||
Retrying --> Unhealthy : "失败"
|
||
}
|
||
note right of Healthy
|
||
健康状态：可正常处理请求
|
||
定期健康检查：每5秒一次
|
||
end note
|
||
note right of Unhealthy
|
||
不健康状态：从负载均衡中移除
|
||
不再接收新请求
|
||
end note
|
||
note right of Timeout
|
||
超时状态：连接失败
|
||
进行重试机制
|
||
end note
|
||
```
|
||
|
||
**图表来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L556-L591)
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L182-L197)
|
||
|
||
**章节来源**
|
||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||
|
||
## 结论
|
||
基于Pingora的反向代理架构提供了一个高性能、高可靠性的解决方案，特别适合在容器化环境中统一管理多个前端应用的访问。通过端口路由机制，实现了灵活的服务访问；通过健康检查和负载均衡，确保了服务的高可用性；通过详细的指标统计，提供了全面的监控能力。与主应用的紧密集成使得状态监控和配置管理更加便捷，整体架构设计合理，性能优越。 |