系统工具健康检查:一个 /health 端点比看起来重要得多
一、不是所有 /health 端点都一样
很多人对健康检查的理解停留在"返回一个 200 就行了"。这种健康检查我叫它"存活性检查(liveness)"——只告诉你进程还活着,但完全不关心它还能不能正常工作。
但真正成熟的健康检查需要两个维度:存活性检查 告诉编排系统要不要重启容器;就绪性检查(readiness) 告诉负载均衡器这个实例能不能接收流量;很多时候还需要深度检查 去探测数据库、Redis、消息队列等外部依赖的状态。
graph TD
subgraph "健康检查分层"
L1["L1: 存活性检查 / Liveness<br/>进程还在吗?<br/>→ 返回 200 即可"] --> L2["L2: 就绪性检查 / Readiness<br/>能接收请求了吗?<br/>→ 连接池初始化完成?"] --> L3["L3: 深度检查 / Deep<br/>依赖服务正常吗?<br/>→ DB / Redis / 队列 PING"]
end
subgraph "编排层响应"
L1C["K8s liveness probe<br/>失败 → 重启 Pod"]
L2C["K8s readiness probe<br/>失败 → 摘除流量"]
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 框架)暴露三个端点,分别对应三种健康检查。每个检查器都是一个实现了 HealthCheck trait 的结构体,这样新增检查项只需要加一行注册代码。
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: HashMap<String, 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::RedisResult<String> = 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: Vec<Box<dyn HealthCheck>>,
}
impl HealthManager {
fn new() -> Self {
Self { checkers: vec![] }
}
/// 注册一个健康检查器
fn register(&mut self, checker: Box<dyn 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: Arc<HealthManager>) -> 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::State<Arc<HealthManager>>,
) -> Result<Json<HealthResponse>, 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::State<Arc<HealthManager>>,
) -> Json<HealthResponse> {
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: 5
K8s 的 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 后,运维事件从"事后补救"变成了"事前发现"。
说句实在话,做健康检查这件事远没有写核心业务逻辑那么容易有成就感。但在我看来,工程能力就体现在这些看起来不炫酷但又少不了的细节上。希望这篇文章能帮你少踩一个我踩过的坑。
1294



被折叠的 条评论
为什么被折叠?



