数据墙DBW 文档

Appearance

使用健康检查和健康端点 ​

数据墙DBW 提供 /health 端点来监控 API 数据源和实体的响应能力和健康状况。此端点针对配置的数据源和实体运行检查，验证它们是否在您设置的阈值内响应。

健康检查流程图。

前提条件 ​

您需要一个现有的 数据墙DBW 配置文件。

运行工具 ​

使用 dab configure 进行运行时健康设置。对于数据源和实体健康设置，请更新配置文件。

  1. 配置运行时健康设置。

    Bash ​

    bash
    dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

    Command Prompt ​

    cmd
    dab configure ^
  --runtime.health.enabled true ^
  --runtime.health.roles "admin,monitoring" ^
  --runtime.health.cache-ttl-seconds 10 ^
  --runtime.health.max-query-parallelism 4

  2. 启动 数据墙DBW。

    dotnetcli
    dab start

测试健康端点 ​

  1. 调用 /health 端点。

    Bash ​

    bash
    curl http://localhost:5000/health

    Command Prompt ​

    cmd
    curl http://localhost:5000/health

  2. 确认响应状态为 Healthy。

健康检查的工作原理 ​

对于每个数据源，一个简单的数据库特定查询验证连接性并测量响应时间。对于每个启用了 REST 或 GraphQL 的实体，查询返回前 N 行以确认响应能力。存储过程被排除，因为它们需要参数且可能不是确定性的。/health 端点将这些结果聚合为一个指示整体健康状况的综合报告。

配置 ​

使用以下示例配置运行时、数据源和实体健康设置。

json
{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  },
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  },
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

命令行 ​

通过 dab configure 配置运行时健康设置。

  • --runtime.health.enabled
  • --runtime.health.roles
  • --runtime.health.cache-ttl-seconds
  • --runtime.health.max-query-parallelism

示例 ​

Bash ​

bash
dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

Command Prompt ​

cmd
dab configure ^
  --runtime.health.enabled true ^
  --runtime.health.roles "admin,monitoring" ^
  --runtime.health.cache-ttl-seconds 10 ^
  --runtime.health.max-query-parallelism 4

生成的配置 ​

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

运行时健康配置 ​

健康检查在 runtime.health 部分中控制：

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

属性 ​

enabled（布尔值，默认值：true）全局启用或禁用综合健康端点。

roles（字符串[]，默认值：null）控制对 /health 端点的访问。

cache-ttl-seconds（整数，默认值：5）设置缓存的健康报告生存时间 (TTL)。

max-query-parallelism（整数，默认值：4）设置最大并发健康检查查询数（范围：1-8）。

基于角色的访问行为 ​

在开发模式下（host.mode: development），当未配置 roles 时，健康端点对所有用户可访问。当配置了 roles 时，只有指定的角色可以访问端点。在生产模式下（host.mode: production），roles 必须显式定义。省略 roles 会对所有请求返回 403 Forbidden。要允许公共访问，请设置 "roles": ["anonymous"]。

重要： 此处配置的角色控制对健康端点的访问，而不是单个实体操作的权限。如果角色缺少查询实体的权限，则该实体的健康检查反映失败，这是预期行为。

根路径的基本健康端点 ​

根路径 / 的简化健康端点始终公开可访问，无需认证。它返回基本服务信息（版本、状态），不运行任何健康检查。

数据源健康配置 ​

每个数据源可以在 data-source.health 中配置健康检查：

json
{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  }
}

属性 ​

enabled（布尔值，默认值：true）为此数据源启用健康检查。

name（字符串，默认值：database-type 值）是健康报告中显示的唯一标识符。

threshold-ms（整数，默认值：1000）是允许的最大查询执行时间（毫秒）。

name 属性是可选的。它有助于在健康报告中区分共享相同数据库类型的多个数据源（例如两个 SQL 数据库）。

实体健康配置 ​

可以在 entities.{entity-name}.health 中为每个实体启用实体检查：

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

属性 ​

enabled（布尔值，默认值：true）为实体启用健康检查。

first（整数，默认值：100）设置健康查询返回的行数（范围：1-500）。

threshold-ms（整数，默认值：1000）设置允许的最大查询执行时间（毫秒）。

注意：first 值必须小于或等于运行时配置的 max-page-size。较小的 first 值可提高性能。如果您监控许多实体，较高的 first 值可能会减慢报告速度。

如果启用了 REST 和 GraphQL，则会为两者运行实体健康检查。每个在报告中显示为单独的条目，带有标签（rest 或 graphql）。

性能和缓存注意事项 ​

cache-ttl-seconds 可防止快速请求使系统过载，并将完整的健康报告缓存配置的生存时间。设置为 0 可禁用缓存。默认值为 5 秒。max-query-parallelism 控制并发运行的健康检查查询数。较高的值可加快检查速度，但会增加数据库负载。范围为 1-8，默认值为 4。如果您有许多实体或严格的资源限制，请使用较低的值。

示例健康检查响应 ​

json
{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "currentRole": "admin",
  "timestamp": "2025-01-15T10:30:00Z",
  "configuration": {
    "rest": true,
    "graphql": true,
    "mcp": true,
    "caching": false,
    "telemetry": true,
    "mode": "Production"
  },
  "checks": [
    {
      "status": "Healthy",
      "name": "primary-sql-db",
      "tags": ["data-source"],
      "data": {
        "response-ms": 12,
        "threshold-ms": 1500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["rest", "endpoint"],
      "data": {
        "response-ms": 45,
        "threshold-ms": 500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["graphql", "endpoint"],
      "data": {
        "response-ms": 38,
        "threshold-ms": 500
      }
    }
  ]
}

currentRole 字段 ​

健康响应包含一个 currentRole 字段，指示用于授权请求的角色。数据墙DBW 使用以下优先级解析当前角色：

  1. X-MS-API-ROLE 头 — 如果存在，则使用指定的角色。
  2. authenticated — 如果请求包含有效的主体（例如 JWT 令牌）但没有 X-MS-API-ROLE 头。
  3. anonymous — 如果没有主体存在。

注意： 此功能为 数据墙DBW 2.0 预览版。

其他注意事项 ​

健康检查遵守实体和端点授权。如果角色缺少访问实体的权限，健康检查会报告它。存储过程被排除，因为它们需要参数且可能有副作用。rest.enabled: false 或 graphql.enabled: false 的实体被排除在这些检查之外。当 data-source.health.enabled: false 时，跳过数据源检查。

数据墙DBW 产品文档与开发指南。

Copyright © 2026 北京金数信安科技有限公司