安全最佳实践

本文汇总了数据墙DBW 在生产环境中部署和运维的安全最佳实践。涵盖传输层安全、身份验证配置、授权设计、配置保护、网络安全和持续运维六个方面。

传输安全

对所有连接使用 TLS

客户端与数据墙DBW 之间的通信必须通过 HTTPS 加密。TLS 连接提供三项核心安全保障：

保障	说明
机密性	防止攻击者窃听传输内容
完整性	防止攻击者篡改传输内容
身份验证	客户端可验证连接的确实是目标服务器

禁用旧版 TLS 协议

TLS 1.2 是最低可接受版本，推荐使用 TLS 1.3。建议在操作系统层面禁用 TLS 1.0 和 TLS 1.1，而不是在数据墙DBW 内硬编码 TLS 版本——这样新版本 TLS 发布后可以自动获得支持。

数据墙DBW 基于 ASP.NET Core Kestrel 运行，默认遵从操作系统的 TLS 设置。各平台确认方式：

• Windows：在注册表中或通过组策略确认 TLS 1.2 已启用。
• Linux：确认 OpenSSL 版本支持 TLS 1.2+。
• macOS：macOS 10.9 及以上默认启用 TLS 1.2。

使用反向代理终止 TLS

推荐在数据墙DBW 前部署反向代理（Nginx、Traefik）或 API 网关处理 HTTPS，数据墙DBW 通过 HTTP 与代理通信。这样：

• 证书管理集中在代理层，不侵入应用代码。
• 代理层统一处理 HTTPS 重定向和 HSTS 头。
• 数据墙DBW 的容器镜像不需要内置证书。

IMPORTANT

即使数据墙DBW 通过代理访问，也必须确保代理与数据墙DBW 之间的网络是内网隔离的，外部无法直接访问数据墙DBW 的 HTTP 端口。

身份验证

生产环境不要用 Unauthenticated

生产环境必须配置有效的身份验证。默认的 Unauthenticated 提供程序将所有请求视为匿名，实体上配置的 authenticated 和自定义角色永远不会生效。

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "issuer": "https://identity.example.com/",
          "audience": "api://dab-api"
        }
      }
    }
  }
}

如果数据墙DBW 部署在网关之后且网关已完成认证，确保：

• 数据墙DBW 的服务端口只允许网关内网访问，不对外暴露。
• 网关正确地将用户角色通过 X-MS-API-ROLE 头注入到后端请求中。
• 网关的认证机制具备令牌过期检查、吊销检查和签名验证。

不要在生产环境使用 Simulator

Simulator 提供程序会完全跳过所有身份验证，强制要求 host.mode: development。在生产模式下引擎会拒绝启动。部署前务必检查配置。

确保 roles 声明正确输出

数据墙DBW 固定使用 JWT 中的 roles 声明进行角色判定。确认你的身份提供程序已将用户角色输出到 roles 声明中。如果提供程序使用了其他声明名（如 groups、permissions、realm_access.roles），需要配置声明映射。

令牌有效期管理

建议 Access Token 的有效期设置为 15-60 分钟。较短的过期时间减少令牌泄露的风险窗口。通过 Refresh Token 实现无缝续期。

授权

遵循最小权限原则

只授予角色完成其任务所需的最少操作。避免在开发初期用 * 通配符配置权限后遗忘收窄——应先快速验证用 * 跑通，再逐步替换为精确的操作列表：

// 初期验证
{ "role": "anonymous", "actions": ["*"] }

// 确认后收紧
{ "role": "anonymous", "actions": ["read"] }

创建专用角色而非复用系统角色

不要把所有认证用户的需求都堆在 authenticated 角色上。创建业务含义清晰的命名角色：

{ "role": "inventory_viewer", "actions": ["read"] },
{ "role": "inventory_manager", "actions": ["read", "create", "update"] },
{ "role": "order_processor", "actions": ["read", "create"] }

为 AI 代理创建受限 MCP 角色

MCP 代理应使用独立的受限角色——只给 read 和必要的 create，永远不给 delete 和 *。通过 fields.exclude 对代理隐藏敏感字段。

敏感数据始终配置行级和字段级过滤

不要仅仅依赖实体级权限。对包含敏感数据的实体，必须配置：

{
  "action": "read",
  "fields": {
    "include": ["*"],
    "exclude": ["salary", "password_hash", "internal_notes"]
  },
  "policy": {
    "database": "@item.departmentId eq @claims.departmentId"
  }
}

避免在 Unauthenticated 模式下配置非 Anonymous 角色

使用 Unauthenticated 提供程序时，即使配置了 authenticated 和命名角色的权限，这些角色也永远不会生效。引擎会在启动时对此发出警告。如果发现该警告，说明当前配置存在安全理解偏差——要么改用 Custom 认证，要么移除无用的角色配置。

定期审查有效权限

每隔一段时间运行以下命令，确认所有实体上的最终权限与业务预期一致：

dab configure --show-effective-permissions

重点检查：

• 是否所有实体都有权限配置（没有遗漏导致 403）。
• 是否有实体对 anonymous 开放了写操作。
• 命名角色的权限范围是否与岗位职责匹配。

配置安全

密钥永不进入配置文件

所有密码和连接字符串使用 @env() 引用：

{
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

.gitignore 必须包含

.env
*.env
dab-config.Production.json

即使只有开发环境密钥的 .env 文件也不能提交——攻击者可能通过开发密钥推断生产密钥的模式。包含密钥的生产环境配置文件同样需要排除。

生产环境关闭调试功能

{
  "runtime": {
    "host": { "mode": "production" },
    "graphql": { "allow-introspection": false }
  }
}

配置项	生产值	原因
host.mode	production	禁用 Swagger UI 和详细错误堆栈
graphql.allow-introspection	false	防止攻击者探测完整的 API 架构
日志级别	Warning 或 Error	减少敏感信息输出

部署前校验配置

将 dab validate 加入 CI/CD 流水线，在每次部署前自动检查组配置的语法和引用完整性：

dab validate --config ./dab-config.json

失败时阻断部署。

环境变量隔离配置差异

不同环境（开发、测试、生产）使用各自的配置文件或环境变量，不在基础配置文件中写入生产特有设置：

dab-config.json              # 实体定义、权限
dab-config.Production.json   # 仅覆盖：mode、认证provider、连接字符串引用

定期轮换密钥

数据库密码、Redis 密码、JWT 签名密钥等应定期轮换。轮换流程应自动化，并在轮换后验证数据墙DBW 仍能正常启动和访问数据库。

网络安全

网络隔离

规则	说明
数据墙DBW 端口不对外	只允许反向代理或内网其他服务访问
数据库端口不对外	数据库只接受数据墙DBW 所在网络（或特定 IP）的连接
Redis 端口不对外	如果启用 L2 缓存，Redis 同样只允许内网访问
管理端点限制访问	/health 端点通过 roles 限制只允许监控系统访问

CORS 严格配置

生产环境中，cors.origins 应精确指定允许的域名，不使用 "*"：

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["https://app.example.com", "https://admin.example.com"],
        "allow-credentials": false
      }
    }
  }
}

如果 API 仅供后端服务调用（不通过浏览器访问），可以完全禁用 CORS。

速率限制

数据墙DBW 本身没有内置速率限制。建议在反向代理或 API 网关层配置：

# Nginx 示例：每秒最多 10 个请求
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

location /api/ {
    limit_req zone=api_limit burst=5 nodelay;
    proxy_pass http://dab-api:5000;
}

日志与审计

监控安全事件

通过日志持续监控以下事件：

事件	日志表现	响应
认证失败	401 Unauthorized	检查是否有暴力破解尝试
权限拒绝	403 Forbidden	检查是否有越权访问尝试
重复的 400 错误	Bad Request	可能是恶意探测 API 结构

日志保留与轮转

生产环境日志建议至少保留 30 天。配置日志轮转策略避免日志占满磁盘。关键安全事件应输出到独立的审计日志流中。

通过 OpenTelemetry 追踪安全决策

启用 OpenTelemetry 追踪，可以在分布式追踪中看到认证和授权决策的完整链路，包括每个请求的角色判定结果。

依赖与更新

保持数据墙DBW 版本更新

定期更新 Microsoft.DataApiBuilder 到最新稳定版：

dotnet tool update --global Microsoft.DataApiBuilder

关注官方发布说明中的安全修复。更新前在测试环境验证兼容性。

保持运行时和依赖更新

• .NET Runtime 保持最新补丁版本。
• 数据库驱动（SqlClient、Npgsql、MySqlConnector）随数据墙DBW 更新自动升级。
• Redis 客户端如有独立部署需单独维护。

安全检查清单

部署前逐项确认：

类别	检查项	状态
传输	所有对外通信使用 HTTPS	☐
传输	TLS 1.2+，禁用旧版本	☐
认证	生产 Provider 不是 Unauthenticated 或 Simulator	☐
认证	JWT issuer 和 audience 正确配置	☐
授权	所有实体都有明确的 permissions 配置	☐
授权	无 anonymous 角色持有 write/delete 权限	☐
授权	敏感字段已配置 fields.exclude	☐
配置	无明文密码，全部使用 @env()	☐
配置	host.mode 为 production	☐
配置	GraphQL introspection 关闭	☐
配置	配置文件通过 dab validate 校验	☐
网络	服务端口不对外暴露	☐
网络	CORS origins 精确指定	☐
网络	网关或防火墙配置了速率限制	☐
日志	日志级别设为 Warning 或 Error	☐
依赖	工具和运行时已更新到最新	☐

下一步

• 安全总览 — 回到安全模型的全局视角。
• 身份验证概述 — 选择和配置认证方式。
• 授权模型 — 设计角色和权限体系。