배포

기본 저장소 구성은 단순한 단일 인스턴스 배포에 적합합니다. 제어 평면은 SQLite를 사용할 수 있고 process-local provider는 Memory를 사용할 수 있습니다.

개발 환경을 넘어 서비스를 노출하기 전에 외부에서 보이는 요소와 영속화할 요소를 명확히 구성해야 합니다.

Public MCP URL

MCP_PUBLIC_ENDPOINT를 MCP 클라이언트가 실제로 접근할 수 있는 URL로 설정하고 /mcp를 포함하십시오.

MCP_PUBLIC_ENDPOINT=https://sql-agent.example.com/mcp

Admin UI origin과 반드시 같다고 가정하지 마십시오. Reverse proxy가 UI와 MCP endpoint를 서로 다른 host, port, path로 노출할 수 있습니다.

Secret

예제 HMAC key와 JWT key는 서로 독립적인 최소 32바이트 고유 secret으로 교체하십시오.

Database credential, SMTP credential, OIDC client secret, webhook signing secret, Redis connection string은 source control 밖에서 관리하십시오.

제어 평면 상태 영속화

기본 SQLite Admin database path는 /app/data 아래에 있습니다. 내장 로컬 제어 평면을 사용한다면 container 교체 후에도 해당 데이터가 유지되도록 구성해야 합니다.

OIDC/TOTP 또는 기타 보호 상태가 ASP.NET Core data protection을 사용한다면 DATA_PROTECTION_KEY_PATH도 영속화하십시오. Key를 잃으면 이전에 보호된 MFA/login state를 읽지 못할 수 있습니다.

관측성

Prometheus metrics는 별도의 listener에서 활성화할 수 있습니다. 예제는 main API port와 분리된 9000 port를 사용합니다.

OTLP_ENDPOINT로 OTLP collector endpoint를 구성하고 OTEL_SERVICE_NAME으로 service name을 지정할 수도 있습니다.

언제 분산 설정으로 이동해야 하는가

애플리케이션 인스턴스가 둘 이상이면 process-local Memory는 더 이상 공유되지 않습니다. 노드 간 일관성이 필요한 subsystem을 distributed provider로 옮기고 shared Admin database를 사용하십시오. 자세한 내용은 분산 배포를 참고하십시오.