配置参考 | hs-sql-agent

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。