Web Host를 누가 소유하는지에 따라 배포 형태를 선택합니다.
| 방식 | 권장 용도 |
|---|---|
| 공식 Docker 이미지 | 독립 hs-sql-agent 서비스 |
HsSqlAgent.Hosting | 완전한 제품을 .NET Host에 임베드 |
HsSqlAgent.Server | 맞춤 ASP.NET Core 구성 |
독립 Docker
repository의 .env.example에서 시작해 모든 샘플 secrets를 교체합니다. 기본 로컬 Control Plane을 사용하면 /app/data를 영속화하고 보호된 Identity State를 사용할 때는 DATA_PROTECTION_KEY_PATH도 영속화합니다.
MCP_PUBLIC_ENDPOINT는 MCP Client가 실제로 접근 가능한 절대 URL이어야 하며 /mcp를 포함합니다. Reverse Proxy는 Admin UI, MCP, Metrics, Approval Callback을 서로 다른 공개 경로로 노출할 수 있습니다.
표준 Embedded Host
HsSqlAgent.Hosting은 공식 Docker와 동일한 표준 공식 구성 및 설정 계약을 임베드합니다. URL Binding과 Logging은 일반 ASP.NET Core Host의 책임입니다.
Authentication, Authorization, UI, Telemetry, Middleware 순서 또는 DML Approval Provider를 교체해야 하면 HsSqlAgent.Server를 사용합니다.
Webhook 승인 배포
DML_APPROVAL_PROVIDER=Webhook이면 Webhook Endpoint는 hs-sql-agent에서 접근 가능해야 하고 Callback URL은 승인 서비스에서 접근 가능해야 합니다. Signing Secret은 고유한 32 UTF-8 bytes 이상으로 설정하고 공개 프로덕션 트래픽에는 TLS를 사용합니다.
Callback은 보호된 실행 Intent만 재개합니다. commit 전에 현재 권한, Database Configuration, Policy, Plan, Row Set Evidence를 다시 검증하며 승인 시스템에는 SQL 실행 권한을 주지 않습니다.
Scale-out
여러 Instance에서는 공유 Admin Database와 Distributed Coordination Provider를 사용합니다. Redis-backed Cache, Rate Limiting, Security Policy Sync, Outbound Delivery Sync, SQL Concurrency로 process-local 상태가 갈라지는 것을 막습니다.
Durable Pending Approval도 영속 Admin Store에 의존하며 재시작 또는 다른 Instance에서 재개할 때 현재 상태와 Evidence를 다시 검증합니다.
프로덕션 체크
HMAC_KEY,JWT_KEY, Webhook Signing Secret, DB Password, SMTP, OIDC secrets를 교체합니다.- Admin Database, Data Protection Keys, 필요한 Audit Archive를 영속화합니다.
- 외부에서 접근 가능한 MCP와 Approval Callback URL을 설정합니다.
- 공개 Endpoint는 TLS와 적절한 Reverse Proxy 뒤에 둡니다.
- 필요에 따라 Prometheus / OTLP를 활성화합니다.
- 두 개 이상의 Instance로 확장하기 전에 Distributed Providers를 설정합니다.