운영 가이드
quant-ai를 자력으로 설치 · 설정 · 모니터링 · 사고 대응까지 수행하기 위한
운영자 가이드입니다. 본 카테고리는 코드 레포지토리에 함께 들어 있는
운영 자산(docker-compose.yml, scripts/deploy_azure.sh, infra/grafana/*,
alembic/versions/*)과 1:1 대응됩니다 — 문서가 가리키는 명령은 모두 실제로
검증된 것이며, 운영자는 별도의 추론 없이 그대로 복사해 사용할 수 있어야
합니다.
누가 읽는 문서인가
- 온콜 운영자 — 헬스체크 실패, 일일 손실 임박, 브로커 5xx 등 알림이 발생했을 때 가장 빠른 동작 경로를 찾는 사람.
- 배포 담당자 — 새 버전을 Azure VM에 무중단 배포하고, 마이그레이션을 적용하며, 실패 시 롤백을 트리거하는 사람.
- 신규 인스턴스 셋업 담당 — 자체 호스팅 환경(다른 클라우드, 베어메탈)에 quant-ai를 처음 올리는 사람.
카테고리 맵
| 카테고리 | 다루는 범위 | 시작 페이지 |
|---|---|---|
| 설치 | Docker Compose 로컬 / Azure VM amd64 / Alembic 마이그레이션 | 설치 개요 |
| 환경 설정 | .env 변수 카탈로그 · feature flag · LiteLLM 프록시 | 환경 설정 개요 |
| 모니터링 | Grafana 5종 대시보드 · Telegram 알림 · 헬스체크 cron | 모니터링 개요 |
| 운영 | 시크릿 회전 · paper→live 승급 · 비상 정지 · reconciler | 운영 개요 |
| 트러블슈팅 | 브로커 401 · KIS 토큰 만료 · LLM 예산 초과 · 마이그 실패 | 트러블슈팅 개요 |
먼저 읽어야 할 문서
처음 운영을 인계받는 경우 다음 순서를 권장합니다.
- 설치 개요 — 시스템 구성도와 컨테이너 단위 책임
- 환경변수 카탈로그 — 모든 토글의 단일 출처
- Grafana 대시보드 — 어디를 봐야 하나
- 시크릿 회전 — 사고 시 첫 행동
- 비상 정지 — 멈추는 방법
절대 규칙 (요약)
quant-ai 운영의 절대 규칙은 부록 — 리스크 규칙에서 관리합니다. 운영 카테고리에서 자주 인용되는 핵심만 적습니다.
라이브 토글은 이중 잠금
프로덕션에서 FEATURE_EQUITY_LIVE=true만 설정해도 활성화되지 않습니다. VM
호스트의 환경변수 ALLOW_LIVE=1과 동시에 만족해야만 라이브가 켜집니다 —
복사된 .env로 인한 사고 라이브를 막기 위함입니다. 자세한 동작은
paper-to-live 승급 참조.
일일 손실 -5% 자동 정지
positions.realized_pnl + unrealized_pnl 합산이 계좌 노셔널의 -5%에
도달하면 사용자별 자산군 단위로 자동 emergency_stop이 걸리고 24시간
잠깁니다. 해제 절차는 비상 정지 참조.
외부 문서와의 관계
운영 카테고리는 다음 기존 문서를 흡수했습니다 (원본은 개발자용 백업으로
docs/operations/에 그대로 남깁니다).
docs/operations/secrets.md→ 시크릿 회전docs/operations/secret_rotation.md→ 시크릿 회전docs/operations/grafana_setup.md→ Grafana 대시보드docs/operations/isolation_incident_response.md→ 보존. 멀티테넌트 격리 사고는 별도 P0 절차이므로 트러블슈팅에서 링크만 유지합니다.