byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
245a210b25c8006373e9d768a85d54ac47851877
qiming/qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/健康检查接口.md
Codex 4b1a580132 添加qiming-rcoder模块
2026-06-01 13:54:52 +08:00

14 KiB
Raw Blame History

健康检查接口

**本文引用的文件列表** - [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)

目录

  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服务器，健康检查端点即随服务启动而可用
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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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 或错误码

图表来源

详细组件分析

健康检查端点定义与响应

  • HTTP方法与URL模式
    • 方法：GET
    • 路径：/health
  • 响应结构
    • status：字符串，表示服务健康状态
    • timestamp：UTC时间戳
    • service：服务标识
  • 成功响应
    • HTTP状态码：200 OK
    • 响应体：包含上述字段的JSON对象
  • 失败响应
    • 当HTTP服务器未启动或路由未注册时，可能出现非200的状态码（例如5xx）
    • 由于健康检查处理器不进行数据库或其他外部依赖的深度校验，一般不会出现500错误；若出现，通常表示服务启动异常或中间件/路由配置问题
flowchart TD
Start(["请求进入 /health"]) --> Route["匹配路由 /health"]
Route --> HandlerCall["调用健康检查处理器"]
HandlerCall --> BuildResp["构造响应对象(status, timestamp, service)"]
BuildResp --> ReturnOK["返回 200 OK + JSON"]
ReturnOK --> End(["结束"])

图表来源

章节来源

服务启动与健康检查可用性

  • rcoder主服务
    • main.rs中创建Axum Router并绑定监听端口，随后启动HTTP服务器
    • 启动日志明确打印了API端点信息，包括GET /health
  • agent_runner服务
    • 同样在main.rs中绑定监听端口并启动HTTP服务器
    • 路由注册中包含GET /health
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 端点随服务启动而可用

图表来源

章节来源

在Kubernetes等容器编排系统中的集成

  • 健康检查配置
  • 推荐配置
    • 在Kubernetes中，使用livenessProbe/readinessProbe指向同一端点
    • 建议将探针超时时间设置为小于探测周期，避免长时间阻塞导致误判
    • 若使用代理（Pingora），建议直接对代理监听端口进行探测，或在代理层暴露健康检查端点

章节来源

curl命令示例与客户端实现指南

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

章节来源

健康检查与负载均衡器健康探测

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

章节来源

依赖关系分析

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

图表来源

章节来源

性能考量

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

章节来源

故障排查指南

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

章节来源

结论

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

附录

API定义与示例

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

章节来源

集成与最佳实践

  • curl示例
  • Kubernetes集成
    • 使用livenessProbe/readinessProbe指向同一端点
    • HEALTHCHECK已在Dockerfile中定义，可直接复用
  • 超时与周期
    • 建议周期10-30秒，超时小于周期
    • failureThreshold根据稳定性需求调整

章节来源

Reference in New Issue View Git Blame Copy Permalink