服务运行配置

runtime 配置块控制数据墙DBW 服务的全局行为。大多数字段有合理的默认值，不写 runtime 也能运行。但了解每个配置项有助于在生产环境中调优服务。

基本结构

{
  "runtime": {
    "rest": { "enabled": true, "path": "/api" },
    "graphql": { "enabled": true, "path": "/graphql" },
    "host": { "mode": "development" },
    "pagination": { "default-page-size": 100, "max-page-size": 100000 }
  }
}

REST 设置

字段	说明	默认值
rest.enabled	全局启用/禁用 REST 端点	true
rest.path	REST 端点路径前缀	"/api"
rest.request-body-strict	请求体中出现多余字段时是否拒绝	true

当 request-body-strict 为 true 时，POST/PUT/PATCH 请求体中的字段如果在数据库表中不存在，引擎会返回 400 错误。设为 false 允许忽略多余字段。

注意： path 不支持子路径（如 /api/data），只能设置一级路径前缀。

GraphQL 设置

字段	说明	默认值
graphql.enabled	全局启用/禁用 GraphQL	true
graphql.path	GraphQL 端点路径	"/graphql"
graphql.allow-introspection	是否允许架构内省查询	true
graphql.depth-limit	查询最大嵌套深度	null（不限制）
graphql.multiple-mutations.create.enabled	是否允许多重创建变更	false

生产环境建议关闭 allow-introspection 以避免暴露完整的 API 架构。depth-limit 防止恶意深层嵌套查询消耗服务资源。

注意： path 不支持子路径。

MCP 设置

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "description": "数据访问服务",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": { "enabled": true, "query-timeout": 30 }
      }
    }
  }
}

字段	说明	默认值
mcp.enabled	全局启用 MCP 服务	true
mcp.path	MCP 端点路径	"/mcp"
mcp.description	发送给 MCP 客户端的服务器描述	null
mcp.dml-tools	可设为布尔值（全部开/关）或对象（逐个控制）	全部启用

aggregate-records 支持 query-timeout（1-600 秒）和 enabled 子属性。其他工具仅支持布尔值。

分页设置

字段	说明	默认值
pagination.default-page-size	默认每页记录数	100
pagination.max-page-size	允许的最大每页记录数	100000
pagination.next-link-relative	分页链接使用相对 URL	false

分页适用于 REST 的 $first 参数和 GraphQL 的 first 参数。客户端可以传 $first=-1 获取最大页大小。

next-link-relative 为 true 时，分页 nextLink 使用相对 URL：

值	示例
false（默认）	"nextLink": "https://localhost:5001/api/users?$after=..."
true	"nextLink": "/api/users?$after=..."

主机设置

{
  "host": {
    "mode": "production",
    "max-response-size-mb": 158,
    "cors": { "origins": ["https://app.example.com"] },
    "authentication": {
      "provider": "Unauthenticated"
    }
  }
}

字段	说明	默认值
host.mode	运行模式：development 或 production	production
host.max-response-size-mb	单个响应允许的最大数据库结果大小（MB）	158
host.cors.origins	允许的跨域来源	[]
host.cors.allow-credentials	是否允许跨域携带凭据	false
host.authentication.provider	认证提供程序	Unauthenticated

Development vs Production

行为	Development	Production
Swagger UI	启用	禁用
详细错误信息	启用	禁用
健康检查匿名访问	允许	需配置 roles
日志级别	Debug	Warning

认证提供程序

提供程序	用例	说明
Unauthenticated	默认，所有请求以 anonymous 身份运行	无需额外配置
Custom	第三方身份提供商（JWT）	需配置 jwt.issuer 和 jwt.audience
Simulator	本地开发测试	仅在 development 模式下有效

使用 Custom 认证时需配置 JWT：

{
  "authentication": {
    "provider": "Custom",
    "jwt": {
      "audience": "<api-audience>",
      "issuer": "https://<your-idp-domain>/"
    }
  }
}

注意： Simulator 提供程序仅在 host.mode 为 development 时有效。生产模式下配置 Simulator 会导致服务无法启动。

缓存设置

{
  "cache": {
    "enabled": true,
    "ttl-seconds": 30,
    "level-2": {
      "enabled": true,
      "provider": "redis",
      "connection-string": "@env('REDIS_CONN_STR')",
      "partition": "my-app"
    }
  }
}

字段	说明	默认值
cache.enabled	全局缓存开关	false
cache.ttl-seconds	默认缓存生存时间（秒）	5
cache.level-2.enabled	启用分布式二级缓存	false
cache.level-2.provider	分布式缓存提供程序	"redis"
cache.level-2.connection-string	缓存服务连接字符串	null
cache.level-2.partition	隔离分布式缓存空间的分区名称	null

cache.ttl-seconds 可在实体级被覆盖。启用全局缓存后，还需要在各实体上显式开启 cache.enabled。

当 level-2.enabled 为 true 时，配置了缓存级别 L1L2 的实体会先检查本地内存缓存，再检查分布式缓存，最后才访问数据库。

压缩设置

{
  "compression": {
    "level": "optimal"
  }
}

字段	说明	默认值
compression.level	HTTP 响应压缩级别	"optimal"

支持的压缩级别：

值	描述	压缩节省	性能影响
optimal	平衡比率和速度（默认）	Gzip: ~90% / Brotli: ~92%	中等 CPU 使用
fastest	优先速度而非比率	Gzip: ~90% / Brotli: ~91%	低 CPU 使用
none	无压缩	0%	无

压缩由客户端的 Accept-Encoding 头触发，支持 Gzip 和 Brotli 算法。

遥测与日志

日志级别

{
  "telemetry": {
    "log-level": {
      "Azure.DataApiBuilder.Core": "information",
      "default": "warning"
    }
  }
}

按命名空间配置日志详细程度。log-level 是唯一支持在生产环境中热重载的配置项。

也可以通过启动参数指定全局日志级别：

dab start --LogLevel Debug

日志级别选项：Trace、Debug、Information、Warning、Error、Critical、None。生产环境建议 Warning 或 Error。

OpenTelemetry

{
  "telemetry": {
    "open-telemetry": {
      "enabled": true,
      "endpoint": "http://localhost:4317",
      "headers": "api-key=key",
      "service-name": "数据墙DBW",
      "exporter-protocol": "grpc"
    }
  }
}

字段	说明	默认值
open-telemetry.enabled	启用 OpenTelemetry	true
open-telemetry.endpoint	OpenTelemetry 收集器 URL	null
open-telemetry.headers	导出头（逗号分隔）	{}
open-telemetry.service-name	服务名称	"数据墙DBW"
open-telemetry.exporter-protocol	协议：grpc 或 httpprotobuf	"grpc"

gRPC（端口 4317）更快并支持流式传输，HTTP/protobuf（端口 4318）更简单且更容易调试。

文件日志

{
  "telemetry": {
    "file": {
      "enabled": true,
      "path": "/var/log/dab/dab-log.txt",
      "rolling-interval": "Day",
      "retained-file-count-limit": 7,
      "file-size-limit-bytes": 10485760
    }
  }
}

字段	说明	默认值
file.enabled	启用文件日志	false
file.path	日志文件路径	"/logs/dab-log.txt"
file.rolling-interval	滚动间隔：Minute、Hour、Day、Month、Year、Infinite	"Day"
file.retained-file-count-limit	保留的日志文件最大数量	1
file.file-size-limit-bytes	滚动前的最大文件大小（字节）	1048576

健康检查

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

字段	说明	默认值
health.enabled	全局启用/禁用健康检查端点	true
health.roles	允许访问健康检查的角色（生产环境必需）	null
health.cache-ttl-seconds	健康检查报告缓存 TTL（秒）	5
health.max-query-parallelism	最大并发健康检查查询数（范围：1-8）	4

开发环境与生产环境的行为

条件	Development 行为	Production 行为
health.enabled = false	403	403
roles 省略或 null	显示健康状态	403
当前角色不在 roles 中	403	403
当前角色在 roles 中	显示健康状态	显示健康状态
roles 包含 anonymous	显示健康状态	显示健康状态

使用 CLI 配置

# 设置运行模式
dab configure --runtime.host.mode "development"

# 关闭 GraphQL
dab configure --runtime.graphql.enabled false

# 设置分页大小
dab configure --runtime.pagination.default-page-size 50

# 配置 MCP 路径
dab configure --runtime.mcp.path "/mcp"

# 启用压缩
dab configure --runtime.compression.level "optimal"

# 启用缓存
dab configure --runtime.cache.enabled true
dab configure --runtime.cache.ttl-seconds 30

CLI 会直接修改配置文件，与手动编辑 JSON 等效。

下一步

• 配置数据源 — 数据库连接配置。
• 配置最佳实践 — 生产环境配置建议。