环境变量与密钥

数据墙DBW 提供了两种机制来管理配置中的敏感信息和环境差异：@env() 函数和 DAB_ENVIRONMENT 环境切换。配合使用可以做到同一份配置模板适配所有环境，密钥永不进入版本控制。

@env() 环境变量引用

@env() 函数用于在配置文件中引用环境变量的值。它可以出现在任何字符串值的位置：

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

引擎在加载配置时扫描所有字符串值，将 @env('VAR_NAME') 替换为环境变量的实际值。

值的来源

来源	说明
系统环境变量	操作系统或容器中设置的环境变量
.env 文件	配置文件目录下的纯文本文件，格式为 KEY=VALUE 每行一条

管理员可以直接在系统环境中设置变量，也可以通过 .env 文件方便本地开发。

.env 文件

# .env 文件示例
DB_TYPE=mssql
SQL_CONNECTION_STRING=Server=localhost;Database=todos;User Id=sa;Password=dev-pwd;

使用 .env 的注意事项：

• 将 .env 放在 dab-config.json 所在目录。
• 必须将 .env 加入 .gitignore，防止密钥泄露。
• 以 # 开头的行为注释，空行被忽略。
• 在 Linux/macOS 上变量名区分大小写。

当 .env 和系统环境变量存在同名时，.env 文件中的值优先。

使用场景

@env() 不仅能用于连接字符串，任何字符串值都可以引用：

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@env('DB_CONN')"
  },
  "entities": {
    "RunJob": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.RunJob",
        "parameters": [
          {
            "name": "intParam",
            "required": true,
            "default": "@env('JOB_PARAM_INT')"
          },
          {
            "name": "boolParam",
            "required": false,
            "default": "@env('JOB_PARAM_BOOL')"
          }
        ]
      }
    }
  }
}

存储过程参数的默认值、任何需要按环境变化的字符串配置都可以使用 @env()。

注意事项

情况	结果
变量存在且有值	正常替换
变量不存在	配置加载失败
变量值为空	替换为空字符串
写成了 @env(DB_VAR)（缺少引号）	视为字面字符串，不替换
用在了需要数字的地方	作为字符串替换，由消费方尝试转换

DAB_ENVIRONMENT 环境切换

DAB_ENVIRONMENT 允许你为不同环境（开发、测试、生产）维护各自的配置文件，切换环境时自动加载对应的文件。

文件命名规则

dab-config.json               # 基础配置（所有环境共享）
dab-config.Development.json   # 开发环境覆盖
dab-config.Production.json    # 生产环境覆盖

• 基础文件 dab-config.json 存放共享的实体和权限配置。
• 环境文件 dab-config.{ENV}.json 只存放该环境特有的覆盖值（如连接字符串）。
• 环境文件的内容会覆盖基础文件中的同名字段。

使用方式

# 开发环境
export DAB_ENVIRONMENT=Development
dab start

# 生产环境
export DAB_ENVIRONMENT=Production
dab start

如果未设置 DAB_ENVIRONMENT，默认行为等同于 Production。也可以直接启动不依赖环境变量。

环境文件的典型内容

开发环境文件 dab-config.Development.json — 通常包含本地连接信息：

{
  "data-source": {
    "connection-string": "@env('DEV_CONN_STR')"
  },
  "runtime": {
    "host": { "mode": "development" }
  }
}

生产环境文件 dab-config.Production.json — 生产连接信息和严格模式：

{
  "data-source": {
    "connection-string": "@env('PROD_CONN_STR')"
  },
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "Custom",
        "jwt": { "issuer": "..." }
      }
    }
  }
}

最佳实践

实践	说明
基础文件存共享配置	实体定义、权限规则、关系等在基础文件中定义
环境文件只存差异	仅写连接字符串和运行时模式，不重复写实体
密钥一律 @env()	环境文件中也不写明文密码
Docker / K8s	通过容器环境变量或 Secret 注入，无需 .env 文件
CI/CD	在流水线中设置变量，部署时动态替换

容器环境中的密钥管理

在 Docker 或 Kubernetes 中运行时：

# Docker
docker run -e SQL_CONNECTION_STRING="..." dab-api

# Kubernetes
# 通过 Secret 资源注入环境变量

不需要 .env 文件——平台的环境变量机制可以直接满足 @env() 的查找需求。

下一步

• 配置数据源 — 完整的连接配置参考。
• 配置最佳实践 — 生产环境安全配置建议。