Konfigurationsreferenz | hs-sql-agent

hs-sql-agent bietet drei Nutzungswege mit derselben Sicherheitsgrenze.

Weg	Konfigurationsmodell
Docker / ToolBox	vollständige Standalone-Umgebung aus `.env.example`
`HsSqlAgent.Hosting`	dieselbe offizielle Standardkomposition über ASP.NET-Core-Konfiguration
`HsSqlAgent.Server`	Capability-eigene Options, die der Host ausdrücklich auswählt

DML-Freigabe

MCP Elicitation ist der offizielle Standard-Provider. Standalone Docker und HsSqlAgent.Hosting können auf den offiziellen generischen Webhook-Adapter wechseln, ohne die SQL-Ausführungsprimitive zu ändern.

Umgebungsvariable	Zweck
`DML_APPROVAL_PROVIDER`	`McpElicitation` oder `Webhook`
`DML_APPROVAL_WEBHOOK_ENDPOINT`	Endpoint des externen Freigabedienstes
`DML_APPROVAL_WEBHOOK_CALLBACK_URL`	öffentliche Callback URL zum Abschluss einer pending approval
`DML_APPROVAL_WEBHOOK_SIGNING_SECRET`	Webhook Signing Secret, mindestens 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"
    }
  }
}

Unbekannte Provider-Namen lassen den Start fehlschlagen. Ein asynchroner Provider kann Pending zurückgeben. Durable Resume benötigt den Admin Store zum Speichern von geschütztem Resume Intent und Approval Fingerprints.

Ein modularer HsSqlAgent.Server-Host kann HsSqlAgent.Approvals.Webhook oder einen eigenen IDmlApprovalProvider registrieren. Der Provider erhält weder Database Connection noch Transaction, validierten Plan oder Commit-Primitive.

Anwendung und Control Plane

Die Standalone-Konfiguration umfasst Application Hosting, Admin Database, MCP HMAC/Public Endpoint, integriertes Admin JWT, SMTP/Password Reset, OIDC/MFA, Bootstrap, Audit, Health, Delivery, Cache, Rate Limit, Policy Sync, Outbound Delivery Sync, SQL Concurrency, Prometheus und OTLP.

HMAC_KEY und JWT_KEY müssen verschiedene Secrets mit mindestens 32 Bytes sein. Persistieren Sie DATA_PROTECTION_KEY_PATH, wenn geschützter Identity State verwendet wird.

Einzelne Instance und verteilte Provider

Eine einzelne Instance kann SQLite als Admin Database und process-local Memory Provider verwenden. Mehrere Instances benötigen eine gemeinsame Admin Database sowie Redis-backed Provider für Cache, Rate Limiting, Security Policy Sync, Outbound Delivery Sync und SQL Concurrency.

Observability

Prometheus läuft auf einem separaten Listener mit PROMETHEUS_ENABLED, PROMETHEUS_HOST, PROMETHEUS_PORT. OTLP verwendet OTLP_ENDPOINT und OTEL_SERVICE_NAME.

Eingebetteter .NET-Host

HsSqlAgent.Hosting besitzt die vollständige Standardkomposition. HsSqlAgent.Server beginnt mit AddHsSqlAgentCore() und validiert nur Options der ausgewählten Capabilities. Host Authorization kann die integrierte Identity ersetzen; der DML-Freigabe-Provider kann unabhängig ausgetauscht werden.

Siehe Bereitstellung, ASP.NET-Core-Integration und Safe DML.