系统工具健康检查：一个 `/health` 端点比看起来重要得多

系统工具健康检查一个/health端点比看起来重要得多一、不是所有/health端点都一样很多人对健康检查的理解停留在返回一个 200 就行了。这种健康检查我叫它存活性检查liveness——只告诉你进程还活着但完全不关心它还能不能正常工作。但真正成熟的健康检查需要两个维度存活性检查告诉编排系统要不要重启容器就绪性检查readiness告诉负载均衡器这个实例能不能接收流量很多时候还需要深度检查去探测数据库、Redis、消息队列等外部依赖的状态。graph TD subgraph 健康检查分层 L1[L1: 存活性检查 / Livenessbr/进程还在吗br/→ 返回 200 即可] -- L2[L2: 就绪性检查 / Readinessbr/能接收请求了吗br/→ 连接池初始化完成?] -- L3[L3: 深度检查 / Deepbr/依赖服务正常吗br/→ DB / Redis / 队列 PING] end subgraph 编排层响应 L1C[K8s liveness probebr/失败 → 重启 Pod] L2C[K8s readiness probebr/失败 → 摘除流量] L3C[监控告警br/失败 → 通知 oncall] end L1 -- L1C L2 -- L2C L3 -- L3C style L1 fill:#336,stroke:#48a,color:#fff style L2 fill:#963,stroke:#c84,color:#fff style L3 fill:#933,stroke:#c44,color:#fff这三种检查经常被混在一起写在同一个路径下但从语义上讲把它们分开才是对的。就绪性检查需要判断当前实例能不能接请求而深度检查需要查外部系统这两者的超时策略和频率完全不同。二、用 Rust 实现一个分层的健康检查下面是一个简单的 Rust 实现。它用 axum轻量 HTTP 框架暴露三个端点分别对应三种健康检查。每个检查器都是一个实现了HealthChecktrait 的结构体这样新增检查项只需要加一行注册代码。use axum::{Router, routing::get, Json, http::StatusCode, response::IntoResponse}; use serde::Serialize; use std::sync::Arc; use std::collections::HashMap; /// 单个检查项的结果 #[derive(Debug, Clone, Serialize)] struct CheckItem { status: String, // ok 或 failed message: String, // 人类可读的描述中文注释也在这里 latency_ms: u64, // 检查耗时单位毫秒 } /// 健康检查完整响应体 #[derive(Debug, Clone, Serialize)] struct HealthResponse { overall: String, // 总体状态 checks: HashMapString, CheckItem, // 各项检查汇总 } /// 健康检查器 trait —— 任何需要被检查的服务都实现这个接口 #[axum::async_trait] trait HealthCheck: Send Sync { /// 执行检查并返回结果的名称和详情 async fn check(self) - (str, CheckItem); } /// 数据库连接检查器 struct DatabaseChecker { pool: sqlx::PgPool, } #[axum::async_trait] impl HealthCheck for DatabaseChecker { async fn check(self) - (str, CheckItem) { let start std::time::Instant::now(); // 用简单的 SELECT 1 验证数据库连接 let result sqlx::query(SELECT 1).execute(self.pool).await; let latency start.elapsed().as_millis() as u64; let item match result { Ok(_) CheckItem { status: ok.to_string(), message: 数据库连接正常.to_string(), latency_ms: latency, }, Err(e) CheckItem { status: failed.to_string(), message: format!(数据库连接失败: {}, e), latency_ms: latency, }, }; (database, item) } } /// Redis 连接检查器 struct RedisChecker { client: redis::Client, } #[axum::async_trait] impl HealthCheck for RedisChecker { async fn check(self) - (str, CheckItem) { let start std::time::Instant::now(); let mut conn match self.client.get_async_connection().await { Ok(conn) conn, Err(e) { return (redis, CheckItem { status: failed.to_string(), message: format!(Redis 连接获取失败: {}, e), latency_ms: start.elapsed().as_millis() as u64, }); } }; // PING 命令验证 Redis 是否响应 let result: redis::RedisResultString redis::cmd(PING) .query_async(mut conn) .await; let latency start.elapsed().as_millis() as u64; let item match result { Ok(response) if response PONG CheckItem { status: ok.to_string(), message: Redis PING 响应正常.to_string(), latency_ms: latency, }, _ CheckItem { status: failed.to_string(), message: Redis PING 失败.to_string(), latency_ms: latency, }, }; (redis, item) } } /// 健康检查管理器 —— 聚合所有检查器 struct HealthManager { checkers: VecBoxdyn HealthCheck, } impl HealthManager { fn new() - Self { Self { checkers: vec![] } } /// 注册一个健康检查器 fn register(mut self, checker: Boxdyn HealthCheck) { self.checkers.push(checker); } /// 执行所有已注册的检查返回聚合结果 async fn run_all_checks(self) - HealthResponse { let mut checks HashMap::new(); let mut all_ok true; // 并发执行所有检查用 join_all let futures: Vec_ self.checkers .iter() .map(|checker| checker.check()) .collect(); let results futures::future::join_all(futures).await; for (name, item) in results { if item.status ! ok { all_ok false; } checks.insert(name.to_string(), item); } HealthResponse { overall: if all_ok { ok.to_string() } else { degraded.to_string() }, checks, } } }这个实现的关键设计点有两个一是用 trait 抽象检查逻辑方便扩展新的检查项比如 Kafka 连接检查、文件系统可用空间检查二是所有检查项并发执行不会因为某个依赖响应慢就拖慢整个健康检查。三、暴露 HTTP 端点与 K8s 集成检查器实现好了下一步是挂到 HTTP 路由上。这里做了分层处理/health/live是存活性检查极简版直接返回 200用于 K8s liveness probe/health/ready是就绪性检查轻量级只检查核心依赖/health/deep是深度检查全部依赖。use tower_http::timeout::TimeoutLayer; use std::time::Duration; /// 构建包含健康检查路由的 axum 应用 fn build_app(manager: ArcHealthManager) - Router { // 存活性检查 —— 最简单的版本无任何依赖K8s liveness probe 用 async fn liveness() - impl IntoResponse { Json(serde_json::json!({ status: alive, message: 进程正常运行 })) } // 就绪性检查 —— 核心依赖检查K8s readiness probe 用 let manager_ref manager.clone(); async fn readiness( axum::extract::State(manager): axum::extract::StateArcHealthManager, ) - ResultJsonHealthResponse, StatusCode { let result manager.run_all_checks().await; if result.overall ok { Ok(Json(result)) } else { Err(StatusCode::SERVICE_UNAVAILABLE) } } // 深度检查 —— 全部依赖监控告警用 async fn deep_check( axum::extract::State(manager): axum::extract::StateArcHealthManager, ) - JsonHealthResponse { Json(manager.run_all_checks().await) } Router::new() .route(/health/live, get(liveness)) .route(/health/ready, get(|| async { readiness(axum::extract::State(manager_ref.clone())).await })) .route(/health/deep, get(|| async { deep_check(axum::extract::State(manager.clone())).await })) // 为所有健康检查路由设置 5 秒超时 .layer(TimeoutLayer::new(Duration::from_secs(5))) } /// Alpine Linux 风格的 K8s deployment 配置示例 /// /// livenessProbe: /// httpGet: /// path: /health/live /// port: 3000 /// initialDelaySeconds: 5 /// periodSeconds: 10 /// /// readinessProbe: /// httpGet: /// path: /health/ready /// port: 3000 /// initialDelaySeconds: 15 /// periodSeconds: 5K8s 的initialDelaySeconds我一般对 liveness 设 5 秒readiness 设 15 秒。原因是 readiness 需要等连接池建立完成慢启动的服务比如数据库连接可能需要更长时间。设太短了 K8s 会误判为不健康频繁重启只会让问题更糟。四、健康检查的真正价值 —— 运维心智模型转变把健康检查代码写完只是第一步。真正让我觉得这个功能物超所值的是它改变了我们排查问题的模式。以前是用户说工具挂了 → 我登录服务器看日志 → 发现 Redis 连接失败 → 群里 运维。有了/health端点后变成了监控系统发现就绪性检查返回 503 → 告警自动触发 → 我打开 /health/deep 看详细报告 → 发现 Redis 延迟 2.3 秒 → 排查 Redis 集群状态。从被动响应到主动发现的转变靠的就是那几十行检查代码。/// 一个常见的误区健康检查超时设得太短 /// 下面这段代码演示了如何正确处理慢依赖 impl HealthCheck for SlowServiceChecker { async fn check(self) - (str, CheckItem) { let start std::time::Instant::now(); // 用 tokio::time::timeout 给单个检查设置独立的超时 // 这样即使某个依赖慢了也不会影响其他检查的执行 let check_future async { // 模拟一个可能需要 3 秒的外部调用 tokio::time::sleep(Duration::from_secs(3)).await; CheckItem { status: ok.to_string(), message: 慢服务正常.to_string(), latency_ms: 3000, } }; match tokio::time::timeout(Duration::from_secs(2), check_future).await { Ok(item) (slow_service, item), Err(_elapsed) (slow_service, CheckItem { status: timeout.to_string(), message: 慢服务检查超时超过 2 秒未响应.to_string(), latency_ms: 2000, }), } } }这里每个检查项要有独立的超时而且要设置合理的阈值。如果一个健康检查要等三十秒才有结论那它本身就变成了一个问题。五、总结一个靠谱的健康检查应该分三层存活性检查证明进程活着就绪性检查验证核心依赖可用深度检查探测所有外部服务。用 trait 模式实现健康检查器可以让检查项可插拔可扩展。集成到 axum 和 K8s 后运维事件从事后补救变成了事前发现。说句实在话做健康检查这件事远没有写核心业务逻辑那么容易有成就感。但在我看来工程能力就体现在这些看起来不炫酷但又少不了的细节上。希望这篇文章能帮你少踩一个我踩过的坑。