문제 해결

CoreRx 운영 중 발생할 수 있는 일반적인 문제와 해결 방법을 정리합니다. 캐시 불일치, ETL 실패, Docker/Superset 이슈를 다룹니다.

캐시 관련 문제

대시보드 데이터가 오래됨

증상: 대시보드에 표시되는 데이터가 최신 업로드 내용을 반영하지 않습니다.

원인과 해결:

캐시 불일치 (원본과 캐시 수치 다름)

증상: SQL Lab에서 원본 테이블을 직접 조회한 결과와 캐시 테이블의 수치가 다릅니다.

원인과 해결:

조치 절차:

1. corerx_cache_meta에서 해당 캐시의 상태와 갱신 시각을 확인합니다.
2. 상태가 failed이면 error_message를 확인합니다.
3. 전체 캐시를 재갱신합니다.

SELECT refresh_all_kpi_cache(
  '4b5b1d04-23f6-42a7-9fe5-acb0a9998c55',
  'manual'
);

캐시 갱신 실패 (status = failed)

증상: corerx_cache_meta의 상태가 failed로 표시됩니다.

일반적인 원인:

ETL 관련 문제

UBIST 엑셀 파싱 실패

증상: ubist_import.py 실행 시 헤더 파싱 에러가 발생합니다.

원인과 해결:

디버깅 절차:

1. --dry-run 옵션으로 먼저 테스트합니다.
2. 에러 메시지에서 실패한 행 번호를 확인합니다.
3. 해당 행의 데이터를 엑셀에서 직접 확인합니다.

python3 scripts/ubist_import.py --file "UBIST_D1 Sales.xlsx" --dry-run

ETL 실행 중 DB 연결 끊김

증상: ETL 실행 중 connection reset 또는 server closed the connection 에러가 발생합니다.

원인과 해결:

supply_qty 타입 에러

증상: 매출 집계 시 cannot cast text to numeric 에러가 발생합니다.

원인: kpis_gap_rows.supply_qty는 TEXT 타입입니다. 합산 시 반드시 CAST가 필요합니다.

해결: 모든 쿼리에서 supply_qty::numeric 또는 CAST(supply_qty AS numeric)을 사용합니다.

주의: supply_qty 컬럼은 기존 테이블(kpis_gap_rows)의 컬럼이므로 타입 변경(ALTER)이 금지됩니다. KPIS, CSO Web 사이트에서 공유하는 테이블입니다.

Docker/Superset 관련 문제

Superset 컨테이너 시작 실패

증상: Superset Docker 컨테이너가 시작되지 않거나, 시작 후 즉시 종료됩니다.

확인 절차:

1. Docker 컨테이너 상태를 확인합니다.

sudo docker compose -f docker-compose.superset.yml ps

2. 실패한 컨테이너의 로그를 확인합니다.

sudo docker compose -f docker-compose.superset.yml logs --tail 100

일반적인 원인:

Superset 대시보드 접속 불가

증상: 브라우저에서 대시보드 URL에 접속할 수 없습니다.

확인 절차:

Superset 재배포

문제 해결 후 Superset을 재배포해야 하는 경우:

bash scripts/redeploy_superset.sh

이 스크립트는 Docker 컨테이너를 중지, 재빌드, 재시작합니다.

PostgreSQL 관련 문제

DB 연결 실패

증상: ETL 스크립트 또는 Superset에서 DB 연결이 실패합니다.

확인 절차:

1. Supabase Docker 컨테이너 상태를 확인합니다.

sudo docker ps | grep supabase

2. PostgreSQL 포트(5432)가 리스닝 중인지 확인합니다.

sudo ss -tlnp | grep 5432

3. 직접 연결을 시도합니다.

psql -h localhost -p 5432 -U postgres -d postgres

디스크 용량 부족

증상: ETL 실행 또는 캐시 갱신 시 no space left on device 에러가 발생합니다.

확인 및 해결:

1. 디스크 사용량을 확인합니다.

df -h

2. Docker 이미지/볼륨 정리로 공간을 확보합니다.

sudo docker system prune -f

3. PostgreSQL WAL 로그가 과도하게 쌓인 경우 체크포인트를 실행합니다.

공통 진단 절차

문제 발생 시 다음 순서로 진단합니다:

1. 증상 확인: 대시보드 화면, 에러 메시지, 로그를 수집합니다.
2. 서비스 상태 확인: Docker 컨테이너, Nginx, PostgreSQL 상태를 확인합니다.
3. 로그 확인: Superset 로그, PostgreSQL 로그, ETL 스크립트 출력을 확인합니다.
4. 원인 특정: 네트워크, 디스크, 메모리, 데이터 문제 중 어떤 것인지 구분합니다.
5. 해결 후 검증: 문제 해결 후 캐시 갱신 → 대시보드 확인으로 정상 동작을 검증합니다.

다음 단계

• 캐시 관리 — 캐시 갱신 전략 상세
• ETL 파이프라인 — ETL 스크립트 사용법
• 데이터 관리 — 데이터 업로드 및 시스템 관리