配置参考 | hs-sql-agent

必需的机密保护配置

启动 Docker 或注册运行时前，请配置三组独立、随机生成的 32 字节 Base64 机密。所有节点必须使用相同密钥，重启后也必须保留。HMAC_KEY 与 JWT_KEY 仍为独立的签名机密。请分别运行三次 openssl rand -base64 32。

Docker 环境变量	ASP.NET Core 配置
`DB_ENCRYPTION_KEY`	`SecretProtection:DatabasePasswords:Keys:db-1`
`DML_ENCRYPTION_KEY`	`SecretProtection:DmlPayloads:Keys:dml-1`
`DML_FINGERPRINT_KEY`	`SecretProtection:DmlFingerprintKey`

将 SecretProtection:DatabasePasswords:ActiveKeyId 设为 db-1，SecretProtection:DmlPayloads:ActiveKeyId 设为 dml-1。缺失、无效或重复使用的密钥会导致启动失败；示例占位值故意设为无效。

HsSqlAgent.Hosting 自动绑定 SecretProtection；模块化宿主必须显式绑定：

hs.AddHsSqlAgentRuntime(options =>
{
    builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});

新 bootstrap MCP 密钥必须显式提供 Bootstrap:Databases:*:McpKeys:*:Key，启动时不再生成或记录密钥。现有加密数据库密码必须重新输入。更改现有部署前，请阅读升级指南。

凭据存储与密钥轮换

数据库密码采用 AES-256-GCM 加密，绑定用途与可信记录的 SecretBindingId；持久化执行载荷绑定 RequestId。没有旧加密格式的解密回退。ICryptoService 接收上下文字符串，而非调用方提供的密钥字节。

轮换加密密钥环时，先将新旧密钥以不同 ID 分发到全部节点，再切换 ActiveKeyId 并重新保存密码。只要待审批或历史载荷仍需检查，就必须保留旧 DML 密钥。独立的 fingerprint key 没有版本号；轮换前必须处理完未决审批，并保留旧机密用于历史 witness 检查。

ExtraSettings 仅接受 JSON 布尔字段 Encrypt 与 TrustServerCertificate。未知或重复字段、字符串值及无效 JSON 均被拒绝。连接测试与健康探测返回通用 DB_CONNECTION_FAILED，不泄露驱动程序细节。

Doctor 的 security.secret-protection 检查密钥 ID、Base64 格式、长度和独立性，不返回机密。公开示例密钥在非生产环境显示警告，在 Production 显示错误，包含非活动的保留密钥。无效占位值在所有环境均为错误；配置无效可能在 Doctor 可用前就导致启动失败。

hs-sql-agent 有三种使用方式，但安全边界一致。

方式	配置模型
Docker / ToolBox	`.env.example` 定义的完整独立服务环境配置
`HsSqlAgent.Hosting`	通过 ASP.NET Core configuration 使用相同的标准第一方组合
`HsSqlAgent.Server`	Host 明确选择各 Capability 自己的 Options

DML 审批

MCP Elicitation 是第一方默认 Provider。独立 Docker 与 HsSqlAgent.Hosting 可切换到官方通用 Webhook adapter，而无需改变 SQL 执行 primitive。

环境变量	用途
`DML_APPROVAL_PROVIDER`	`McpElicitation` 或 `Webhook`
`DML_APPROVAL_WEBHOOK_ENDPOINT`	外部审批服务 endpoint
`DML_APPROVAL_WEBHOOK_CALLBACK_URL`	完成 pending approval 的公开 callback URL
`DML_APPROVAL_WEBHOOK_SIGNING_SECRET`	Webhook 签名 secret，至少 32 UTF-8 bytes

{
  "DmlApproval": {
    "Provider": "Webhook",
    "Webhook": {
      "Endpoint": "https://approval.example.com/hssqlagent/requests",
      "CallbackUrl": "https://sql-agent.example.com/api/hs-sql-agent/approvals/webhook",
      "SigningSecret": "replace-with-a-unique-secret-at-least-32-bytes"
    }
  }
}

未知 Provider 名称会在启动时失败。异步 Provider 可返回 Pending；Durable Resume 需要 Admin Store，以保存受保护的 Resume Intent 与 Approval Fingerprint。

模块化 HsSqlAgent.Server 可注册 HsSqlAgent.Approvals.Webhook 或自己的 IDmlApprovalProvider。审批 Provider 不会获得 Database Connection、Transaction、已验证 Plan 或 commit primitive。

应用与 Control Plane

独立服务配置涵盖 Application Hosting、Admin Database、MCP HMAC/Public Endpoint、内置 Admin JWT、SMTP/Password Reset、OIDC/MFA、Bootstrap、Audit、Health、Delivery，以及 Cache、Rate Limit、Policy Sync、Outbound Delivery Sync、SQL Concurrency、Prometheus 和 OTLP。

HMAC_KEY 与 JWT_KEY 必须使用不同且至少 32 bytes 的 secrets。启用受保护身份状态时请持久化 DATA_PROTECTION_KEY_PATH。

单机与分布式 Provider

单机可以使用 SQLite Admin Database 与 process-local Memory Provider。多 Instance 时，使用共享 Admin Database，并以 Redis-backed Provider 处理 Cache、Rate Limiting、Security Policy Sync、Outbound Delivery Sync 与 SQL Concurrency。

Observability

Prometheus 使用 PROMETHEUS_ENABLED、PROMETHEUS_HOST、PROMETHEUS_PORT 的独立 Listener；OTLP 使用 OTLP_ENDPOINT 与 OTEL_SERVICE_NAME。

Embedded .NET Host

HsSqlAgent.Hosting 负责完整标准组合；HsSqlAgent.Server 从 AddHsSqlAgentCore() 开始，只验证实际选择 Capability 的 Options。Host Authorization 可替换内置 Identity，DML 审批 Provider 也可以独立替换。

另见部署、ASP.NET Core 集成和 Safe DML。