본문으로 건너뛰기

트러블슈팅

quant-ai 운영 중 자주 마주치는 장애 패턴과 1차 대응을 정리합니다. 각 페이지는 현상 → 원인 가설 → 검증 명령 → 조치 순으로 구성되어 있어, 알림이 오면 페이지를 찾아 그대로 따라할 수 있도록 설계되었습니다.

카테고리 맵​

페이지다루는 범위
브로커 401거래소 인증 실패 (placeholder / 만료 / 권한)
KIS 토큰 만료KIS OAuth 24h 만료와 KISTokenManager 동작
LLM 예산 초과LiteLLM 일일 예산 도달 시 분석 차단 / 한도 조정
DB 마이그레이션 실패alembic 실패 패턴 (Timescale 부재 / pg_trgm / 컬럼 중복)

멀티유저 격리 사고​

cross-tenant 데이터 누출 등 격리 사고는 본 카테고리가 아닌 P0 보안 인시던트 런북에서 다룹니다. 원본은 코드 레포에서 보존됩니다 — docs/operations/isolation_incident_response.md.

해당 문서가 다루는 범위:

  1. 컨테인 (T+0~T+5) — 라이브 즉시 차단, DB 스냅샷
  2. 노출 식별 (T+5~T+30) — 누가 누구의 데이터를 봤나
  3. 알림 (T+30~T+2h) — 영향 사용자 통지, 거래소 키 강제 무효
  4. 패치 + 회귀 테스트 (T+2h~T+24h) — tests/test_user_isolation.py 에 회귀 테스트 추가
  5. 재개 (T+24h+) — 사후 검증 후 라이브 복구

이 절차는 일반 운영자 가이드와 분리하여 관리합니다.

우선 점검 순서​

알림이 와서 빠른 진단이 필요할 때:

# 1. 컨테이너 상태
docker compose ps

# 2. 최근 100줄 로그 (5개 컨테이너 병렬)
for s in api analysis-worker position-reconciler timescaledb redis; do
  echo "==== $s ===="; docker compose logs --tail=20 "$s"
done

# 3. 헬스체크 즉시 실행
bash infra/healthcheck.sh

# 4. 마이그레이션이 head?
docker compose exec api alembic current

# 5. 활성 feature flag
curl -s http://localhost:8000/health/flags | jq .

# 6. 최근 critical reconcile / broker_5xx 이벤트
docker compose exec timescaledb psql -U quant -d quantai -c "
  SELECT received_at, user_id, asset_class,
         payload->>'severity' AS sev,
         event_type
  FROM broker_order_events
  WHERE received_at > NOW() - INTERVAL '1 hour'
    AND (payload->>'severity' IN ('warning','critical')
         OR event_type LIKE '%5xx%')
  ORDER BY received_at DESC LIMIT 30;
"

관련 페이지​