Back to Details

serverpod-health-checks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Serverpod Health Checks

Serverpod 健康检查

Kubernetes-style HTTP health endpoints on the main API server (default port 8080), not the optional web server (default port 8082). Unauthenticated: HTTP status only (200/503). Authenticated requests get detailed JSON (RFC Health Check Response Format) through the server's normal authentication handler.
在主API服务器（默认端口8080）上提供Kubernetes风格的HTTP健康检查端点，而非可选的Web服务器（默认端口8082）。未认证请求仅返回HTTP状态码（200/503）。已认证请求通过服务器常规认证处理程序返回符合RFC健康检查响应格式的详细JSON数据。

Endpoints

端点

  • /livez
     — Process alive? Does not check DB/Redis. Use for liveness probes.
  • /readyz
     — Dependencies healthy? Returns 503 if not. Use for readiness probes.
  • /startupz
     — Server finished initializing? Use for startup probes.
  • /livez
     — 进程是否存活？不检查数据库/Redis。用于存活探针。
  • /readyz
     — 依赖项是否健康？若不健康返回503。用于就绪探针。
  • /startupz
     — 服务器是否完成初始化？用于启动探针。

Built-in indicators

内置检查指标

  • ServerpodStartupIndicator — startup complete
  • DatabaseHealthIndicator — configured database (if enabled)
  • RedisHealthIndicator — Redis (if enabled)
  • ServerpodStartupIndicator — 启动完成
  • DatabaseHealthIndicator — 已配置的数据库（若启用）
  • RedisHealthIndicator — Redis（若启用）

Custom health indicator

自定义健康检查指标

dart
class StripeApiIndicator extends HealthIndicator<double> {
  @override String get name => 'stripe:api';
  @override String get componentType => HealthComponentType.component.name;
  @override String get observedUnit => 'ms';
  @override Duration get timeout => const Duration(seconds: 3);

  @override
  Future<HealthCheckResult> check() async {
    final sw = Stopwatch()..start();
    try {
      await stripeClient.ping();
      return pass(observedValue: sw.elapsedMilliseconds.toDouble());
    } catch (e) {
      return fail(output: 'Stripe unavailable: $e');
    }
  }
}
dart
class StripeApiIndicator extends HealthIndicator<double> {
  @override String get name => 'stripe:api';
  @override String get componentType => HealthComponentType.component.name;
  @override String get observedUnit => 'ms';
  @override Duration get timeout => const Duration(seconds: 3);

  @override
  Future<HealthCheckResult> check() async {
    final sw = Stopwatch()..start();
    try {
      await stripeClient.ping();
      return pass(observedValue: sw.elapsedMilliseconds.toDouble());
    } catch (e) {
      return fail(output: 'Stripe unavailable: $e');
    }
  }
}

Registration

注册

dart
final pod = Serverpod(
  args,
  healthConfig: HealthConfig(
    cacheTtl: Duration(seconds: 2), // default is 1 second
    additionalReadinessIndicators: [StripeApiIndicator()],
    additionalStartupIndicators: [CacheWarmupIndicator()],
  ),
);
Each indicator can override 
timeout
(default 5s). 
cacheTtl
caches results to reduce load under frequent probing. Serverpod also has a legacy 
GET /
health response with a different, simpler contract; use 
/livez
, 
/readyz
, and 
/startupz
for Kubernetes probes.
dart
final pod = Serverpod(
  args,
  healthConfig: HealthConfig(
    cacheTtl: Duration(seconds: 2), // default is 1 second
    additionalReadinessIndicators: [StripeApiIndicator()],
    additionalStartupIndicators: [CacheWarmupIndicator()],
  ),
);
每个指标可覆盖
timeout
（默认5秒）。
cacheTtl
用于缓存检查结果，以降低频繁探测时的负载。Serverpod还提供了传统的
GET /
健康响应，其契约更为简单；对于Kubernetes探针，请使用
/livez
、
/readyz
和
/startupz
。