# 健康检查接口

<cite>
**本文引用的文件列表**
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
- [README.md](file://README.md)
- [docker/Dockerfile](file://docker/Dockerfile)
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
</cite>

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

## 简介
本文件面向RCoder项目的健康检查API，聚焦GET /health端点的HTTP方法、URL模式、响应格式与行为语义。文档解释该接口如何用于系统状态监控与负载均衡器健康探测，给出成功与失败场景的JSON结构说明，阐述服务启动时的验证作用，并提供在Kubernetes等容器编排系统中的集成方式、curl示例与客户端实现要点，以及性能监控与超时处理的最佳实践。

## 项目结构
- 健康检查端点在两个主要服务中均可用：
  - rcoder主服务：提供HTTP API与健康检查
  - agent_runner服务：同样提供健康检查端点
- 路由注册与OpenAPI文档由各服务的router模块负责
- 服务启动时绑定端口并启动HTTP服务器，健康检查端点即随服务启动而可用

```mermaid
graph TB
subgraph "rcoder主服务"
RMain["main.rs<br/>启动HTTP服务器"]
RRouter["router.rs<br/>路由注册 /health"]
RHandler["health_handler.rs<br/>健康检查处理器"]
end
subgraph "agent_runner服务"
AMain["main.rs<br/>启动HTTP服务器"]
ARouter["router.rs<br/>路由注册 /health"]
AHandler["health_handler.rs<br/>健康检查处理器"]
end
RMain --> RRouter --> RHandler
AMain --> ARouter --> AHandler
```

图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)

章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)

## 核心组件
- 健康检查处理器
  - 路径：/health
  - 方法：GET
  - 响应：JSON对象，包含status、timestamp、service字段
- 路由注册
  - rcoder：在router.rs中将GET /health绑定到处理器
  - agent_runner：同理
- 服务启动
  - main.rs中创建Axum Router并绑定TCP监听，健康检查端点随服务启动而可用

章节来源
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)

## 架构总览
健康检查端点作为系统健康状态的快速探测入口，既可用于内部监控，也可供外部负载均衡器/编排系统进行存活探针。在rcoder中，健康检查端点位于HTTP API层，不依赖业务逻辑，因此其可用性直接反映服务进程的启动与HTTP服务器的就绪状态。

```mermaid
sequenceDiagram
participant LB as "负载均衡器/探针"
participant HTTP as "HTTP服务器(Axum)"
participant Router as "路由(/health)"
participant Handler as "健康检查处理器"
LB->>HTTP : GET /health
HTTP->>Router : 分发请求
Router->>Handler : 调用处理器
Handler-->>HTTP : 返回JSON响应
HTTP-->>LB : 200 OK 或错误码
```

图表来源
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)

## 详细组件分析

### 健康检查端点定义与响应
- HTTP方法与URL模式
  - 方法：GET
  - 路径：/health
- 响应结构
  - status：字符串，表示服务健康状态
  - timestamp：UTC时间戳
  - service：服务标识
- 成功响应
  - HTTP状态码：200 OK
  - 响应体：包含上述字段的JSON对象
- 失败响应
  - 当HTTP服务器未启动或路由未注册时，可能出现非200的状态码（例如5xx）
  - 由于健康检查处理器不进行数据库或其他外部依赖的深度校验，一般不会出现500错误；若出现，通常表示服务启动异常或中间件/路由配置问题

```mermaid
flowchart TD
Start(["请求进入 /health"]) --> Route["匹配路由 /health"]
Route --> HandlerCall["调用健康检查处理器"]
HandlerCall --> BuildResp["构造响应对象(status, timestamp, service)"]
BuildResp --> ReturnOK["返回 200 OK + JSON"]
ReturnOK --> End(["结束"])
```

图表来源
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)

章节来源
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)

### 服务启动与健康检查可用性
- rcoder主服务
  - main.rs中创建Axum Router并绑定监听端口，随后启动HTTP服务器
  - 启动日志明确打印了API端点信息，包括GET /health
- agent_runner服务
  - 同样在main.rs中绑定监听端口并启动HTTP服务器
  - 路由注册中包含GET /health

```mermaid
sequenceDiagram
participant Main as "main.rs"
participant Router as "router.rs"
participant Server as "HTTP服务器(Axum)"
Main->>Router : create_router(state)
Router-->>Main : 返回Router
Main->>Server : 绑定监听端口并启动
Server-->>Main : 服务就绪
Note over Main,Server : /health 端点随服务启动而可用
```

图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)

章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)

### 在Kubernetes等容器编排系统中的集成
- 健康检查配置
  - Dockerfile中定义了HEALTHCHECK指令，使用curl对http://localhost:PORT/health进行探测
  - 默认端口为8087（来自rcoder_default.yml中的port字段）
- 推荐配置
  - 在Kubernetes中，使用livenessProbe/readinessProbe指向同一端点
  - 建议将探针超时时间设置为小于探测周期，避免长时间阻塞导致误判
  - 若使用代理（Pingora），建议直接对代理监听端口进行探测，或在代理层暴露健康检查端点

章节来源
- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L10-L12)

### curl命令示例与客户端实现指南
- curl示例
  - GET http://localhost:8087/health
- 客户端实现要点
  - 使用HTTP客户端库发起GET请求
  - 解析JSON响应，读取status、timestamp、service字段
  - 对于200以外的状态码，视为不健康
  - 设置合理的超时时间，避免阻塞

章节来源
- [README.md](file://README.md#L229-L242)

### 健康检查与负载均衡器健康探测
- 健康检查处理器不进行外部依赖（如数据库、代理后端）的深度校验，仅反映服务进程与HTTP服务器的就绪状态
- 负载均衡器可将其作为存活探针，结合探针超时、重试次数与周期进行综合判断
- 若需要对代理后端进行健康探测，可参考代理健康检查配置（见下一节）

章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)

## 依赖关系分析
- 路由到处理器的依赖
  - rcoder与agent_runner分别在各自的router.rs中注册GET /health
  - 处理器在各自handler/health_handler.rs中实现
- 服务启动依赖
  - main.rs负责创建Router并启动HTTP服务器
- 代理健康检查（额外能力）
  - rcoder的ProxyConfig包含HealthCheckConfig
  - Pingora服务实现健康检查循环，定期对后端端口进行连通性探测

```mermaid
graph LR
RMain["rcoder/main.rs"] --> RRouter["rcoder/router.rs"]
RRouter --> RHandler["rcoder/handler/health_handler.rs"]
AMain["agent_runner/main.rs"] --> ARouter["agent_runner/router.rs"]
ARouter --> AHandler["agent_runner/handler/health_handler.rs"]
Config["rcoder/config.rs<br/>ProxyConfig/HealthCheckConfig"] --> PingoraSvc["pingora-proxy/service.rs<br/>健康检查循环"]
```

图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)

章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)

## 性能考量
- 健康检查处理器为纯内存计算，开销极低，适合高频探测
- 探测周期与超时设置建议
  - 周期：根据业务SLA设定，常见为10-30秒
  - 超时：建议小于周期，避免探针阻塞影响其他请求
- 在Kubernetes中，合理设置initialDelaySeconds、periodSeconds、timeoutSeconds与failureThreshold，避免误判
- 若使用代理（Pingora），可利用其健康检查能力对后端进行更细粒度的探测

章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L124-L134)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L591)

## 故障排查指南
- 无法访问/health
  - 检查服务是否已启动并绑定到预期端口
  - 确认防火墙与网络策略允许访问
- 响应非200
  - 查看服务日志，定位路由或中间件异常
  - 确认路由注册是否正确
- 健康检查频繁失败
  - 检查探针超时与周期设置
  - 在Kubernetes中适当增大failureThreshold，避免抖动
- 代理健康检查相关
  - 确认ProxyConfig中的health_check.enabled、interval_seconds、timeout_seconds配置
  - 检查后端端口连通性

章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)

## 结论
GET /health端点为RCoder提供了轻量、可靠的健康状态探测入口，适用于服务启动验证与负载均衡器健康探测。其简单实现确保了低开销与高可用性。在生产环境中，建议结合探针超时、周期与重试策略，以及必要时启用代理健康检查，以获得更全面的健康状态视图。

## 附录

### API定义与示例
- 端点：GET /health
- 响应示例（成功）
  - 状态码：200 OK
  - 响应体：包含status、timestamp、service字段的JSON对象
- 响应示例（失败）
  - 状态码：非200（例如5xx）
  - 响应体：错误信息（由HTTP服务器或中间件决定）

章节来源
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
- [README.md](file://README.md#L229-L242)

### 集成与最佳实践
- curl示例
  - curl -X GET http://localhost:8087/health
- Kubernetes集成
  - 使用livenessProbe/readinessProbe指向同一端点
  - HEALTHCHECK已在Dockerfile中定义，可直接复用
- 超时与周期
  - 建议周期10-30秒，超时小于周期
  - failureThreshold根据稳定性需求调整

章节来源
- [README.md](file://README.md#L229-L242)
- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)