19 KiB
19 KiB
故障排除
**本文档引用的文件** - [main.rs](file://crates/rcoder/src/main.rs) - [config.rs](file://crates/rcoder/src/config.rs) - [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs) - [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs) - [manager.rs](file://crates/docker_manager/src/manager.rs) - [container_stop.rs](file://crates/docker_manager/src/container_stop.rs) - [types.rs](file://crates/docker_manager/src/types.rs) - [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs) - [app_error.rs](file://crates/shared_types/src/model/app_error.rs)目录
常见问题及解决方案
Docker连接问题
当服务无法连接到Docker守护进程时，系统会提供详细的错误信息和解决建议。主要问题包括：
- Docker socket路径错误：检查环境变量
DOCKER_SOCKET_PATH是否正确设置 - 权限不足：确保容器有权限访问Docker API
- Docker服务未运行：验证Docker是否正在运行
解决方案：
- 检查
docker-compose.yml中的配置，确保正确挂载Docker socket - 验证Docker socket文件是否存在
- 检查用户是否在docker组中
- 测试Docker API连通性
flowchart TD
Start([启动服务]) --> CheckDockerSocket["检查DOCKER_SOCKET_PATH环境变量"]
CheckDockerSocket --> ValidateSocket["验证Docker socket文件存在"]
ValidateSocket --> TestAPI["测试Docker API连通性"]
TestAPI --> CheckPermissions["检查用户权限"]
CheckPermissions --> Success["服务启动成功"]
CheckDockerSocket --> |路径未设置| UseDefault["使用默认路径: /var/run/docker.sock"]
UseDefault --> ValidateSocket
TestAPI --> |连接失败| ShowHelp["显示详细的配置帮助信息"]
ShowHelp --> Stop["停止服务启动"]
Section sources
容器清理失败
在服务启动和关闭时，系统会尝试清理遗留的容器。可能会遇到以下问题：
- 409冲突错误：容器已在删除过程中，这是正常情况
- 容器不存在：容器已被其他进程清理
- 权限不足：无法访问或删除容器
系统采用智能清理策略，忽略409冲突错误和容器不存在的情况，只记录真正的清理失败。
flowchart TD
Start([启动清理]) --> FindContainers["查找匹配模式的容器"]
FindContainers --> CheckExist["检查容器是否存在"]
CheckExist --> |存在| StopContainer["停止并删除容器"]
CheckExist --> |不存在| Skip["跳过，记录为已清理"]
StopContainer --> CheckError["检查错误类型"]
CheckError --> |409冲突| Skip["跳过，记录为已清理"]
CheckError --> |其他错误| LogError["记录失败，计入失败统计"]
CheckError --> |成功| LogSuccess["记录成功"]
LogSuccess --> NextContainer["处理下一个容器"]
LogError --> NextContainer
Skip --> NextContainer
NextContainer --> |还有容器| CheckExist
NextContainer --> |无容器| Complete["清理完成"]
Section sources
服务启动失败
服务启动时可能遇到多种问题，系统提供了详细的错误处理和恢复机制。
常见问题：
- 配置文件加载失败
- Docker管理器初始化失败
- 端口绑定失败
- 依赖服务未就绪
解决方案：
- 检查配置文件是否存在且格式正确
- 验证Docker服务是否正常运行
- 确认端口未被其他进程占用
- 检查依赖服务的状态
flowchart TD
Start([服务启动]) --> LoadConfig["加载配置文件"]
LoadConfig --> |成功| InitDocker["初始化Docker管理器"]
LoadConfig --> |失败| UseDefault["使用默认配置"]
UseDefault --> InitDocker
InitDocker --> |成功| CheckContainers["检查并清理遗留容器"]
InitDocker --> |失败| Stop["停止服务启动"]
CheckContainers --> |成功| StartProxy["启动代理服务"]
CheckContainers --> |失败| LogWarn["记录警告，继续启动"]
StartProxy --> |成功| StartServer["启动HTTP服务器"]
StartProxy --> |失败| LogError["记录错误"]
StartServer --> Complete["服务启动完成"]
Section sources
日志分析
日志配置
系统使用tracing库进行日志记录，支持多种输出格式和级别。
日志配置特点：
- 按天滚动保存日志文件
- 保留最近5天的日志
- 同时输出到控制台和文件
- 文件日志采用JSON格式，便于后续分析
- 控制台日志采用简洁格式
flowchart TD
Start([日志初始化]) --> CreateDir["创建logs目录"]
CreateDir --> SetupRolling["设置按天滚动的文件appender"]
SetupRolling --> CreateFileLayer["创建文件日志层"]
CreateFileLayer --> CreateConsoleLayer["创建控制台日志层"]
CreateConsoleLayer --> SetPropagator["设置全局文本传播器"]
SetPropagator --> InitSubscriber["初始化tracing subscriber"]
InitSubscriber --> Complete["日志系统初始化成功"]
Section sources
日志级别
系统支持多种日志级别，便于不同场景下的调试和监控。
日志级别：
error：记录错误信息，需要立即关注warn：记录警告信息，可能影响系统稳定性info：记录重要事件和状态变化debug：记录调试信息，用于问题排查trace：记录详细跟踪信息，用于深度分析
日志级别配置：
- 通过环境变量
RUST_LOG设置 - 支持按模块设置不同级别
- 默认级别为
info
flowchart TD
Start([日志级别]) --> Error["error: 记录错误信息"]
Error --> Warn["warn: 记录警告信息"]
Warn --> Info["info: 记录重要事件"]
Info --> Debug["debug: 记录调试信息"]
Debug --> Trace["trace: 记录详细跟踪信息"]
Trace --> Complete["完成"]
Section sources
日志内容
日志记录了系统运行过程中的关键信息，便于问题排查和性能分析。
日志内容包括：
- 服务启动和关闭信息
- 配置加载和应用信息
- 容器创建和销毁信息
- 请求处理信息
- 错误和异常信息
日志字段：
timestamp：时间戳level：日志级别target：日志来源message：日志消息trace_id：请求跟踪IDmethod：HTTP方法uri：请求URI
flowchart TD
Start([日志内容]) --> ServiceInfo["服务信息: 启动、关闭、状态"]
ServiceInfo --> ConfigInfo["配置信息: 加载、应用、验证"]
ConfigInfo --> ContainerInfo["容器信息: 创建、启动、停止、销毁"]
ContainerInfo --> RequestInfo["请求信息: 处理、响应、错误"]
RequestInfo --> ErrorInfo["错误信息: 异常、堆栈跟踪"]
ErrorInfo --> Complete["完成"]
Section sources
性能优化
容器清理优化
系统实现了高效的容器清理机制，避免资源泄漏和性能下降。
清理策略：
- 定时清理闲置容器
- 启动时清理遗留容器
- 关闭时清理所有容器
- 并发清理多个容器
优化措施：
- 使用
force remove避免竞态条件 - 过滤409冲突错误
- 并发处理多个容器
- 添加超时机制
flowchart TD
Start([容器清理]) --> CheckIdle["检查容器是否闲置"]
CheckIdle --> |是| StopContainer["停止并删除容器"]
CheckIdle --> |否| Skip["跳过"]
StopContainer --> CheckError["检查错误类型"]
CheckError --> |409冲突| Skip["跳过"]
CheckError --> |其他错误| LogError["记录错误"]
CheckError --> |成功| LogSuccess["记录成功"]
LogSuccess --> NextContainer["处理下一个容器"]
LogError --> NextContainer
Skip --> NextContainer
NextContainer --> |还有容器| CheckIdle
NextContainer --> |无容器| Complete["清理完成"]
Section sources
请求处理优化
系统使用axum框架处理HTTP请求，具有高性能和低延迟的特点。
优化措施：
- 使用异步处理
- 连接复用
- 批量处理
- 缓存机制
性能指标：
- 请求处理时间
- 并发连接数
- 内存使用
- CPU使用
flowchart TD
Start([请求处理]) --> ReceiveRequest["接收HTTP请求"]
ReceiveRequest --> ParseRequest["解析请求"]
ParseRequest --> ProcessRequest["处理请求"]
ProcessRequest --> GenerateResponse["生成响应"]
GenerateResponse --> SendResponse["发送响应"]
SendResponse --> Complete["完成"]
Section sources
资源管理优化
系统实现了高效的资源管理机制，避免资源泄漏和性能下降。
资源管理：
- 内存管理
- CPU管理
- 网络管理
- 存储管理
优化措施：
- 资源限制
- 资源回收
- 资源监控
- 资源优化
flowchart TD
Start([资源管理]) --> Memory["内存管理: 分配、释放、监控"]
Memory --> CPU["CPU管理: 调度、限制、监控"]
CPU --> Network["网络管理: 连接、带宽、监控"]
Network --> Storage["存储管理: 读写、缓存、监控"]
Storage --> Complete["完成"]
Section sources
安全考虑
容器安全
系统在容器创建和运行时实施了多种安全措施。
安全措施：
- 禁用
NET_RAW和NET_ADMIN能力 - 禁用特权模式
- 使用非root用户运行
- 限制资源使用
- 网络隔离
安全配置：
cap_drop：移除危险能力privileged：禁用特权模式user：指定运行用户memory：限制内存使用nano_cpus：限制CPU使用
flowchart TD
Start([容器安全]) --> DropCapabilities["移除NET_RAW和NET_ADMIN能力"]
DropCapabilities --> DisablePrivileged["禁用特权模式"]
DisablePrivileged --> LimitResources["限制资源使用"]
LimitResources --> NetworkIsolation["网络隔离"]
NetworkIsolation --> Complete["完成"]
Section sources
网络安全
系统在网络安全方面实施了多种措施，防止未授权访问和攻击。
安全措施：
- 使用安全的网络配置
- 限制端口暴露
- 使用防火墙规则
- 监控网络流量
- 防止DDoS攻击
网络配置：
network_mode：设置网络模式port_bindings：限制端口映射host_config：配置主机安全networking_config：配置网络安全
flowchart TD
Start([网络安全]) --> SecureNetwork["使用安全的网络配置"]
SecureNetwork --> LimitPorts["限制端口暴露"]
LimitPorts --> Firewall["使用防火墙规则"]
Firewall --> MonitorTraffic["监控网络流量"]
MonitorTraffic --> PreventDDoS["防止DDoS攻击"]
PreventDDoS --> Complete["完成"]
Section sources
数据安全
系统在数据安全方面实施了多种措施，保护用户数据和系统数据。
安全措施：
- 数据加密
- 访问控制
- 数据备份
- 数据审计
- 数据隔离
数据保护：
encryption：数据加密authentication：身份验证authorization：授权backup：数据备份audit：数据审计
flowchart TD
Start([数据安全]) --> EncryptData["数据加密"]
EncryptData --> AccessControl["访问控制"]
AccessControl --> BackupData["数据备份"]
BackupData --> AuditData["数据审计"]
AuditData --> IsolateData["数据隔离"]
IsolateData --> Complete["完成"]
Section sources
配置选项与参数
主要配置选项
系统提供了多种配置选项，便于用户根据需求进行定制。
配置文件：config.yml
主要配置项：
default_agent：默认使用的AI代理类型projects_dir：项目工作目录port：主服务端口proxy_config：反向代理配置docker_config：Docker配置
flowchart TD
Start([配置选项]) --> DefaultAgent["default_agent: 默认AI代理类型"]
DefaultAgent --> ProjectsDir["projects_dir: 项目工作目录"]
ProjectsDir --> Port["port: 主服务端口"]
Port --> ProxyConfig["proxy_config: 反向代理配置"]
ProxyConfig --> DockerConfig["docker_config: Docker配置"]
DockerConfig --> Complete["完成"]
Section sources
反向代理配置
反向代理配置允许用户自定义代理服务的行为。
配置项：
listen_port：代理服务监听端口default_backend_port：默认后端服务端口backend_host：后端服务主机地址port_param：端口参数名称health_check：健康检查配置
健康检查配置：
enabled：是否启用健康检查interval_seconds：检查间隔（秒）timeout_seconds：超时时间（秒）healthy_threshold：健康阈值unhealthy_threshold：不健康阈值
flowchart TD
Start([代理配置]) --> ListenPort["listen_port: 监听端口"]
ListenPort --> DefaultBackend["default_backend_port: 默认后端端口"]
DefaultBackend --> BackendHost["backend_host: 后端主机"]
BackendHost --> PortParam["port_param: 端口参数"]
PortParam --> HealthCheck["health_check: 健康检查"]
HealthCheck --> Enabled["enabled: 是否启用"]
HealthCheck --> Interval["interval_seconds: 间隔"]
HealthCheck --> Timeout["timeout_seconds: 超时"]
HealthCheck --> Healthy["healthy_threshold: 健康阈值"]
HealthCheck --> Unhealthy["unhealthy_threshold: 不健康阈值"]
Unhealthy --> Complete["完成"]
Section sources
Docker配置
Docker配置允许用户自定义容器的行为。
配置项：
multi_image_config：多镜像配置network_mode：网络模式work_dir：工作目录auto_cleanup：自动清理container_ttl_seconds：容器存活时间（秒）
多镜像配置：
services：服务配置global_defaults：全局默认配置selection_strategy：选择策略cache_config：缓存配置
flowchart TD
Start([Docker配置]) --> MultiImage["multi_image_config: 多镜像配置"]
MultiImage --> NetworkMode["network_mode: 网络模式"]
NetworkMode --> WorkDir["work_dir: 工作目录"]
WorkDir --> AutoCleanup["auto_cleanup: 自动清理"]
AutoCleanup --> ContainerTTL["container_ttl_seconds: 容器存活时间"]
ContainerTTL --> Complete["完成"]
Section sources
组件关系
核心组件关系
系统由多个核心组件组成，它们之间有明确的关系和依赖。
主要组件：
rcoder：主服务agent_runner：代理运行器docker_manager：Docker管理器pingora-proxy：反向代理shared_types：共享类型
组件关系：
rcoder依赖docker_manager和pingora-proxyagent_runner依赖docker_managerrcoder和agent_runner共享shared_typespingora-proxy提供反向代理功能
classDiagram
class Rcoder {
+start()
+load_config()
+init_docker_manager()
+start_proxy()
}
class AgentRunner {
+start()
+load_config()
+run_agent()
}
class DockerManager {
+create_container()
+stop_container()
+get_container_info()
}
class PingoraProxy {
+start()
+add_backend()
+health_check()
}
class SharedTypes {
+AgentType
+ContainerInfo
+AppError
}
Rcoder --> DockerManager : "使用"
Rcoder --> PingoraProxy : "使用"
AgentRunner --> DockerManager : "使用"
Rcoder --> SharedTypes : "共享"
AgentRunner --> SharedTypes : "共享"
Section sources
服务启动流程
服务启动时，各个组件按照特定顺序初始化和启动。
启动流程：
- 初始化遥测系统
- 解析命令行参数
- 加载配置文件
- 创建项目工作目录
- 初始化Docker管理器
- 启动代理服务
- 启动HTTP服务器
sequenceDiagram
participant Main as "main函数"
participant Telemetry as "遥测系统"
participant Config as "配置系统"
participant Docker as "Docker管理器"
participant Proxy as "代理服务"
participant Server as "HTTP服务器"
Main->>Telemetry : init_telemetry()
Telemetry-->>Main : 初始化成功
Main->>Config : load_config_with_args()
Config-->>Main : 返回配置
Main->>Main : create_dir_all(projects_dir)
Main->>Docker : init_global_docker_manager()
Docker-->>Main : 初始化成功
Main->>Proxy : start()
Proxy-->>Main : 启动成功
Main->>Server : serve()
Server-->>Main : 服务器运行
Section sources
请求处理流程
HTTP请求的处理流程涉及多个组件的协作。
处理流程：
- 接收HTTP请求
- 通过追踪中间件处理
- 路由到相应处理器
- 处理请求
- 生成响应
- 返回响应
sequenceDiagram
participant Client as "客户端"
participant Server as "HTTP服务器"
participant Middleware as "追踪中间件"
participant Router as "路由"
participant Handler as "处理器"
Client->>Server : HTTP请求
Server->>Middleware : 调用中间件
Middleware->>Middleware : 生成trace_id
Middleware->>Middleware : 创建span
Middleware->>Router : 调用下一个处理器
Router->>Handler : 路由到处理器
Handler->>Handler : 处理请求
Handler-->>Router : 返回响应
Router-->>Middleware : 返回响应
Middleware-->>Server : 返回响应
Server-->>Client : HTTP响应
Section sources