从本地开发到部署上线

数据墙DBW 的部署流程简单直接——从本地开发验证到生产环境运行，中间不需要大量环境适配工作。以下是一条推荐的完整路径。

第一步：本地开发

在本地完成安装和配置验证：

1. 安装 CLI 工具（dotnet tool install）。
2. 使用 dab init 创建配置文件。
3. 使用 dab add 添加实体。
4. 使用 dab start 启动服务，通过浏览器或 curl 验证 API 可用。
5. 在 Development 模式下享受 Swagger UI 和详细错误信息。

开发阶段的配置可以包含本地数据库连接信息，方便快速迭代。

第二步：配置管理

从开发到生产，配置文件的管理是关键。以下是推荐做法：

敏感信息使用环境变量

连接字符串和密码永远不要硬编码在配置文件中：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

不同环境（开发、测试、生产）使用不同环境变量值，同一份配置文件无需修改。

多环境配置

数据墙DBW 支持通过 DAB_ENVIRONMENT 环境变量自动加载对应环境的配置文件。配置文件的加载优先级如下：

1. 基础配置：始终尝试加载 dab-config.json。
2. 环境配置：如果设置了 DAB_ENVIRONMENT（例如 production），引擎会尝试加载 dab-config.production.json。
3. 合并规则：环境配置文件中的配置项会覆盖基础配置中的同名项。如果环境配置文件不存在，则仅使用基础配置。

# 设置环境名
export DAB_ENVIRONMENT=production

# 引擎加载 dab-config.json 和 dab-config.production.json 并合并
dab start

你可以为不同环境维护各自的配置文件，将通用的 data-source 和 entities 放在基础配置中，将环境特定的运行时设置（如日志级别、CORS）放在环境配置文件中。常见的环境变量取值和密钥通过 @env() 引用。

版本控制

配置文件是 JSON 文本，适合纳入 Git 管理：

• 将不含密钥的配置模板纳入版本控制。
• 连接字符串和密钥从环境变量注入。
• 配置变更通过 PR 审查，避免配置错误上线。

校验配置

部署前运行 dab validate 检查配置文件，该命令会依次执行以下检查：

检查项	说明
Schema	配置文件是否符合 JSON Schema 定义
Structure	配置结构是否完整（data-source、entities 等）
Permissions	权限配置是否合法（角色、操作、策略）
Connectivity	数据库连接是否可用
Metadata	实体引用的数据库对象是否存在

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

返回 0 表示全部通过，非 0 表示存在问题。可以在 CI/CD 流水线中加入此步骤，防止错误配置部署到生产环境。

第三步：容器化

数据墙DBW 提供官方容器镜像，可直接拉取运行：

docker run -p 5000:5000 \
  -e SQL_CONNECTION_STRING="..." \
  -v $(pwd)/dab-config.json:/App/dab-config.json \
  mcr.microsoft.com/azure-databases/data-api-builder:latest

如果需要将配置文件打包到镜像中，可以构建自定义镜像：

FROM mcr.microsoft.com/azure-databases/data-api-builder:latest
COPY dab-config.json /App/dab-config.json

docker build -t dab-api .
docker run -p 5000:5000 -e SQL_CONNECTION_STRING="..." dab-api

Kubernetes 部署要点

• 通过 ConfigMap 挂载配置文件。
• 通过 Secret 注入环境变量（连接字符串等）。
• 用 /health 端点配置存活探测和就绪探测。
• 多个实例可水平扩展，搭配 Redis 实现 L2 缓存共享。

第四步：上线前检查

部署到生产环境前，逐项确认：

检查项	说明
运行模式	设为 Production，关闭 Swagger 和详细错误
密码安全	配置文件中无明文密码，全部使用 @env()
身份验证	根据实际部署架构选择正确的 provider
权限配置	确认每个实体的 permissions 与业务需求一致
健康检查	/health 端点可用，容器编排平台可探测
日志级别	生产环境建议设为 Warning 或 Error
HTTPS	生产环境启用 TLS，或在前置网关层终止 HTTPS

第五步：持续运维

上线后的关注点：

• 监控：通过 OpenTelemetry 接入现有监控体系，追踪请求延迟和错误率。
• 日志：检查日志级别是否合适，关注认证失败和权限拒绝的日志。
• 更新：通过 dotnet tool update 升级到新版本，更新前在测试环境验证。
• 容量：关注数据库连接池和缓存命中率，按需调整实例数。

下一步

• 阅读部署总览 了解更多部署选项。
• 阅读配置最佳实践 深入了解配置管理。
• 阅读健康检查 配置容器编排探测。