Files
2026-06-01 13:54:52 +08:00

387 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 配置选项
<cite>
**本文引用的文件**
- [config.yml](file://config.yml)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构与配置来源](#项目结构与配置来源)
3. [核心配置组件](#核心配置组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向反向代理服务的配置系统,聚焦于 PingoraConfig 结构体及其在代理服务中的作用系统性说明监听地址、超时设置、缓冲区大小、TLS 配置等参数的含义与影响;阐述“命令行 > 环境变量 > 配置文件”的优先级链在代理服务中的具体实现;结合 config.yml 示例解释如何定制化代理行为以适配不同部署环境;并提供性能调优建议与安全配置最佳实践。
## 项目结构与配置来源
- 代理库提供 PingoraConfig 结构体与启动能力,负责解析命令行参数、配置文件与运行时环境变量,形成最终的代理配置。
- 应用层rcoder/agent_runner在启动时加载配置若启用代理则将应用配置中的代理段落转换为 PingoraConfig 并启动 Pingora 服务。
- 配置文件 config.yml 作为应用层的默认配置来源包含代理、Docker 等多类配置项。
```mermaid
graph TB
subgraph "应用层"
RC["rcoder 主服务<br/>加载配置并启动代理"]
AR["agent_runner 服务<br/>加载配置并启动代理"]
end
subgraph "代理库"
PLib["pingora-proxy 库<br/>提供 ProxyConfig/PingoraServerManager"]
end
subgraph "配置来源"
YML["config.yml<br/>默认配置文件"]
ENV["环境变量<br/>RCODER_*"]
CLI["命令行参数<br/>--port/--proxy-port 等"]
end
CLI --> RC
CLI --> AR
ENV --> RC
ENV --> AR
YML --> RC
YML --> AR
RC --> PLib
AR --> PLib
```
图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L66-L70)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L66-L70)
## 核心配置组件
本节围绕 PingoraConfig 结构体展开,说明其在代理服务中的关键参数及默认值来源。
- 监听端口
- 字段listen_port
- 作用:代理服务对外监听的 TCP 端口
- 默认值来自代理库默认常量8080应用层也可通过命令行或配置文件覆盖
- 参考路径:
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L11-L12)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L115-L120)
- 默认后端端口
- 字段default_backend_port
- 作用:当请求未携带端口参数时,代理默认转发到的后端端口
- 默认值来自代理库默认常量3000应用层可通过命令行或配置文件覆盖
- 参考路径:
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L15-L16)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L115-L120)
- 后端主机地址
- 字段backend_host
- 作用:代理转发的目标主机地址(通常为 127.0.0.1
- 默认值来自代理库默认常量127.0.0.1
- 参考路径:
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L19-L20)
- URL 端口参数名
- 字段port_param
- 作用:从查询参数中提取目标端口的参数名,默认为 "port"
- 默认值:来自代理库默认常量("port"
- 参考路径:
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L23-L24)
- 配置文件路径
- 字段config_file
- 作用:指向代理库的配置文件路径(如需启用配置文件支持)
- 参考路径:
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L27-L29)
- 详细日志开关
- 字段verbose
- 作用:启用更详细的日志输出
- 参考路径:
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L31-L33)
- 健康检查配置(应用层代理段落)
- 字段health_check.enabled/interval_seconds/timeout_seconds/healthy_threshold/unhealthy_threshold
- 作用:控制代理服务对后端健康检查的启用、周期、超时与阈值
- 参考路径:
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
章节来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
## 架构总览
下图展示配置在应用层与代理库之间的流转过程,以及优先级链的执行顺序。
```mermaid
sequenceDiagram
participant CLI as "命令行参数"
participant ENV as "环境变量"
participant FILE as "配置文件 config.yml"
participant APP as "应用层配置加载"
participant LIB as "代理库配置(PingoraConfig)"
participant SRV as "代理服务(PingoraServer)"
CLI->>APP : 解析 --port/--proxy-port 等
ENV->>APP : RCODER_PORT/RCODER_PROJECTS_DIR 等
FILE->>APP : 读取并解析 config.yml
APP->>LIB : 将代理段落转换为 PingoraConfig
APP->>SRV : 启动代理服务(可选)
SRV-->>APP : 健康检查循环(按配置)
```
图表来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
## 详细组件分析
### 组件一PingoraConfig 结构体与默认值
- 结构体定义与默认值来源
- 监听端口、默认后端端口、后端主机、端口参数名均来自代理库默认常量
- 代理库提供便捷构造方法(如 with_listen_port、with_backend_host、with_port_param
- 校验规则
- 监听端口与默认后端端口不可为 0
- 后端主机与端口参数名不可为空
- 参考路径:
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L68)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L99-L126)
```mermaid
classDiagram
class ProxyConfig {
+u16 listen_port
+u16 default_backend_port
+string backend_host
+string port_param
+Option~string~ config_file
+bool verbose
+validate() Result
+new() ProxyConfig
+with_listen_port(u16) ProxyConfig
+with_backend_host(string) ProxyConfig
+with_port_param(string) ProxyConfig
}
```
图表来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L94)
章节来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L94)
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
### 组件二:配置优先级链(命令行 > 环境变量 > 配置文件)
- 应用层rcoder/agent_runner的优先级链
- 命令行参数优先级最高,覆盖配置文件与环境变量
- 环境变量次之,覆盖配置文件
- 配置文件再次之,作为默认来源
- rcoder 的优先级链实现
- 若存在配置文件,先加载;否则创建默认配置文件
- 命令行参数覆盖配置文件中的端口与项目目录
- 环境变量 RCODER_PORT、RCODER_PROJECTS_DIR 覆盖应用层配置
- 启用代理时,命令行 --proxy-port、--backend-port 覆盖代理段落
- Docker 配置支持环境变量覆盖RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL
- agent_runner 的优先级链实现
- 首先加载默认配置,尝试从配置文件读取,失败则创建默认配置文件
- 环境变量 RCODER_PORT 覆盖端口
- 启用代理时,命令行参数决定代理监听端口与默认后端端口
- 命令行参数优先级最高,覆盖配置文件与环境变量
- 参考路径:
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
```mermaid
flowchart TD
Start(["开始"]) --> LoadFile["读取配置文件 config.yml"]
LoadFile --> HasFile{"文件存在?"}
HasFile --> |否| CreateDefault["创建默认配置文件"]
HasFile --> |是| ParseYAML["解析 YAML 为应用配置"]
ParseYAML --> ApplyCLI["应用命令行参数覆盖"]
ApplyCLI --> ApplyENV["应用环境变量覆盖"]
ApplyENV --> ApplyDockerEnv["应用 Docker 环境变量覆盖"]
ApplyDockerEnv --> Validate["配置验证"]
Validate --> Done(["结束"])
```
图表来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L347-L403)
章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
### 组件三:代理服务启动与健康检查
- 应用层启动代理服务
- 若配置中启用代理,将应用层代理段落转换为 PingoraConfig 并启动 PingoraServerManager
- 启动健康检查循环(按配置的 interval_seconds 与 timeout_seconds
- 参考路径:
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L104-L108)
```mermaid
sequenceDiagram
participant APP as "应用层"
participant CFG as "应用配置(AppConfig.ProxyConfig)"
participant PCONF as "PingoraConfig"
participant MGR as "PingoraServerManager"
participant HC as "健康检查循环"
APP->>CFG : 读取代理配置
APP->>PCONF : 构造 PingoraConfig
APP->>MGR : new(PCONF)
APP->>HC : start_health_check_loop(interval, timeout_ms)
MGR-->>APP : 后台启动服务
```
图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L104-L108)
### 组件四:配置文件 config.yml 的定制化
- 代理段落proxy_config
- listen_port代理服务监听端口
- default_backend_port默认后端端口
- backend_host后端主机地址
- port_paramURL 中端口参数名
- health_check健康检查开关、间隔、超时、健康/不健康阈值
- Docker 配置docker_config
- multi_image_config多镜像配置服务镜像、环境变量、挂载、资源限制、工作目录、网络模式等
- network_mode/work_dir/auto_cleanup/container_ttl_secondsDocker 运行时通用配置
- 参考路径:
- [config.yml](file://config.yml#L1-L161)
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L314-L401)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L360-L401)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
章节来源
- [config.yml](file://config.yml#L1-L161)
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L314-L401)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L360-L401)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
## 依赖关系分析
- 应用层依赖代理库提供的 PingoraServerManager 与 ProxyConfig
- 应用层配置AppConfig.ProxyConfig与代理库配置ProxyConfig字段一一对应
- Docker 配置通过共享类型模块提供多镜像配置与资源限制等能力
```mermaid
graph LR
RC["rcoder/src/config.rs"] --> PC["pingora-proxy/src/config.rs"]
AR["agent_runner/src/config.rs"] --> PC
RC --> SC["shared_types/src/service_config.rs"]
AR --> SC
SC --> MIC["shared_types/src/multi_image_config.rs"]
```
图表来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L37-L81)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L74)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L37-L81)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L74)
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
## 性能考量
- 监听端口与默认后端端口
- 将代理监听端口与后端端口设置为不同值,避免端口冲突
- 默认后端端口应与主服务端口一致,便于统一路由
- 健康检查
- 合理设置 interval_seconds 与 timeout_seconds避免过于频繁导致额外开销
- healthy_threshold 与 unhealthy_threshold 用于平滑波动,建议根据后端稳定性调整
- 端口参数名
- 使用较短且稳定的参数名(默认 "port"),减少路径长度与解析成本
- 环境变量覆盖
- 在容器编排中通过环境变量快速切换端口与目录,避免频繁修改配置文件
- Docker 配置
- 合理设置资源限制内存、CPU、交换避免容器争抢导致抖动
- 启用 auto_cleanup 与合理的 container_ttl_seconds降低长期运行的资源占用
[本节为通用指导,无需列出具体文件来源]
## 故障排查指南
- 常见配置错误
- 监听端口或默认后端端口为 0校验失败需修正为有效端口
- 后端主机或端口参数名为空:校验失败,需提供有效值
- 代理无法启动
- 检查代理监听端口是否被占用
- 确认后端主机可达且端口开放
- 健康检查异常
- 调整 interval_seconds 与 timeout_seconds避免过于敏感
- 检查后端服务健康状态与响应时间
- 环境变量覆盖无效
- 确认环境变量命名正确RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL
- 确认命令行参数未覆盖环境变量(命令行优先级最高)
章节来源
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L68)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
## 结论
- PingoraConfig 为代理服务的核心配置载体,提供监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与详细日志等关键参数。
- 配置优先级链清晰明确:命令行 > 环境变量 > 配置文件,应用层在启动时严格遵循该顺序,确保部署灵活性与可控性。
- 通过 config.yml 可定制代理行为与 Docker 运行参数,满足不同部署环境需求。
- 建议在生产环境中合理设置健康检查与资源限制,并通过环境变量实现快速切换与运维。
[本节为总结性内容,无需列出具体文件来源]
## 附录
- 关键字段对照表
- 监听端口listen_port
- 默认后端端口default_backend_port
- 后端主机backend_host
- 端口参数名port_param
- 配置文件路径config_file
- 详细日志verbose
- 健康检查enabled/interval_seconds/timeout_seconds/healthy_threshold/unhealthy_threshold
- 参考路径:
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
- [config.yml](file://config.yml#L1-L161)
[本节为参考性内容,无需列出具体文件来源]