检查健康状态

/health 端点是快速判断数据墙DBW 整体健康状况的第一个检查点。它综合了数据源连接和实体可用性的检测结果，以单一状态码和 JSON 响应呈现。

快速诊断

curl http://localhost:5000/health

健康（Healthy）

{
  "status": "Healthy",
  "details": {
    "main-db": { "status": "Healthy" },
    "Book": { "status": "Healthy" },
    "Author": { "status": "Healthy" }
  }
}

所有数据源和实体检查通过。

降级（Degraded）

{
  "status": "Degraded",
  "details": {
    "main-db": { "status": "Healthy" },
    "Book": { "status": "Healthy" },
    "Author": { "status": "Unhealthy" }
  }
}

至少一个实体检查失败或超阈值，但数据源可用。服务仍可响应，但受影响的实体可能无法正常返回数据。

不可用（Unhealthy）

{
  "status": "Unhealthy",
  "details": {
    "main-db": { "status": "Unhealthy" }
  }
}

数据源连接不可用——这是最严重的状态，服务无法执行任何数据库操作。

健康检查的三级架构

/health 综合了三个层级的检查结果：

GET /health
  ├── 数据源级：验证数据库连接可用 + 响应时间在阈值内
  │     └── 执行 SELECT 1 或等效的简单查询
  ├── 实体级：对每个启用的实体执行查询（取前 N 行）
  │     └── 验证表/视图可访问 + 响应时间在阈值内
  │     └── 存储过程自动排除
  └── 运行时级：控制缓存、并行度和权限

常见状态诊断

数据源 Unhealthy

原因：

• 数据库服务未运行。
• 连接字符串错误（主机、端口、用户名、密码）。
• 网络不可达——防火墙、安全组、容器网络配置问题。
• 数据库连接池耗尽。

诊断步骤：

1. 确认数据库服务正在运行。
2. 用数据库原生客户端从数据墙DBW 所在主机测试同一连接字符串。
3. 检查防火墙规则和网络安全组。
4. 查看数据墙DBW 日志中详细的连接错误信息（调高日志级别至 Debug）。

实体 Unhealthy

原因：

• 数据库表或视图已被删除或重命名。
• 表/视图的 schema 已变更，字段不匹配。
• 数据源仍健康但特定表不可访问（权限变更）。
• 视图的主键字段不再有效。

诊断步骤：

1. 确认数据库中的表/视图存在且可访问。
2. 检查数据库用户的权限是否被修改。
3. 运行 dab validate 获取详细的实体元数据错误报告。
4. 查看启动日志中是否有实体相关的错误信息。

所有检查都通过但 API 仍然异常

原因： 健康检查只验证连接和基本查询可用性。以下问题不会反映在 /health 中：

• 权限配置错误（实体有权限但当前角色无权）。
• 中间件层面的处理错误。
• 特定数据引起的运行时异常。
• 性能瓶颈。

诊断步骤： 检查日志中的请求处理错误、运行 dab configure --show-effective-permissions、测试具体的 API 端点。

健康检查配置

运行时配置

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  }
}

字段	建议
roles	设置限制角色防止 /health 被公开访问
cache-ttl-seconds	设置 5-15 秒避免频繁探测导致的数据库压力
max-query-parallelism	实体数量多时适当调高（1-8），减少探测总耗时

数据源配置

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "main-db",
      "threshold-ms": 1000
    }
  }
}

实体配置

{
  "Book": {
    "health": {
      "enabled": true,
      "first": 50,
      "threshold-ms": 500
    }
  }
}

字段	建议
first	设为较小值（5-20）加快检查速度，尤其实体数据量大时
threshold-ms	根据实体查询的正常响应时间设置，不要过于激进

容器编排中的使用

Docker

docker run \
  --health-cmd="curl -f http://localhost:5000/health || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  ...

Kubernetes

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 10

探测类型	用途	失败后果
livenessProbe	检测进程死锁或崩溃	重启 Pod
readinessProbe	检测服务是否就绪	从 Service 端点移除

下一步

• 查看日志 — 获取详细的错误信息。
• 校验配置文件 — 运行 dab validate 诊断配置问题。
• 排查权限问题 — 诊断 401/403 错误。