운영 트러블슈팅 — 디스크·터널·포트포워딩
2026-07-27~28 · GCP 공용 VM(sprint-ai-11-2)에서 겪은 것들.
코드 문제가 아니라 환경 문제로 시간을 크게 잡아먹은 건들이라 따로 남긴다.
1. VSCode 포트포워딩이 POST만 못 보내던 문제
증상: 웹은 뜨는데 추천·자동추론이 전부 실패. 프론트엔 “백엔드에 연결할 수 없습니다”가 뜨는데, 백엔드 로그엔 요청이 아예 안 찍힘.
확인 과정
- VM 안에서
curl localhost:8010/health→ 정상 - VM 안에서 preflight(OPTIONS) 직접 테스트 → 0.001초 만에 200, CORS 헤더 정상
- 브라우저 Network 탭 →
recommendations요청이 Pending에서 멈춤
결론: 서버는 완벽. VSCode Remote-SSH 포워딩 터널이 GET은 통과시키는데 POST/preflight는 못 넘기는 상태였다. PORTS 탭엔 초록불로 멀쩡해 보였다.
해결: 포워딩을 아예 우회 — cloudflared quick tunnel로 공개 주소를 뚫었다.
cloudflared tunnel --url http://localhost:8010 # 백엔드
cloudflared tunnel --url http://localhost:5173 # 프론트- 백엔드
.env의WEB_ALLOWED_ORIGINS에 프론트 터널 주소 추가 - 프론트
.env의VITE_API_URL을 백엔드 터널 주소로 vite.config.ts에server.allowedHosts: ['.trycloudflare.com'](없으면 Vite가 모르는 호스트라며 403)
터널은 재시작할 때마다 주소가 바뀐다. 위 세 곳을 매번 같이 갱신해야 함.
교훈: “연결 안 됨”이 떴을 때 서버 로그에 요청이 찍혔는지 먼저 본다. 안 찍혔으면 서버 문제가 아니라 그 사이 경로 문제다.
2. CORS 포트 불일치
증상: 프론트가 5173이 아니라 5175로 떠서(5173이 이미 점유돼 밀림) 백엔드 화이트리스트에 없어 차단.
해결: .env에 5173·5174·5175를 모두 허용.
WEB_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174,http://localhost:5175
3. 디스크 99% → VM이 통째로 멈춤
증상: 파이프라인 재빌드 중 프론트·백엔드·터널이 한꺼번에 다 죽음.
확인: df -h → 96G 중 94G 사용(99%). 메모리는 멀쩡(15G 중 5G).
중요: 내 몫은 약 12G, 전체의 12%뿐. 나머지 88%는 다른 팀원 홈과 시스템 영역인데 권한이 없어 누가 쓰는지 조회 불가. 관리자만 확인 가능:
sudo du -sh /home/* | sort -rh당장 확보한 것: 폐지한 리랭커 모델 캐시 2.2G 삭제 →
rm -rf ~/.cache/huggingface/hub/models--Dongjin-kr--ko-reranker99% → 96%로 숨통. 근데 공용이라 언제든 다시 찰 수 있음 → 팀 차원 정리가 필요.
4. 프로세스가 조용히 죽어 있는 일이 잦음
공용 VM이라 원인 불명으로 프로세스가 사라진다(재부팅 흔적·OOM 흔적 없이). “안 열린다”면 먼저 살아있는지부터 확인:
ps -u $USER -o pid,cmd | grep -E "uvicorn src.api|node.*vite|cloudflared" | grep -v grep
curl -s localhost:8010/health
curl -s -o /dev/null -w '%{http_code}\n' localhost:5173/주의: pkill -f uvicorn 은 다른 팀원 프로세스까지 노린다(권한 없어 실패하지만
자기 자신도 죽일 수 있음 — 실제로 pkill 명령줄에 “uvicorn”이 들어 있어 자기가
자기를 죽이는 일이 있었다). PID를 지정해 죽이는 게 안전하다.
5. uv 가상환경 함정
uv pip install <pkg> 가 프로젝트 .venv가 아니라 활성화된 다른 venv(myenv)에
설치되는 일이 있었다(.venv에 pip 바이너리가 없어 조용히 빗나감).
uv pip install --python .venv/bin/python <pkg> # 명시적으로 지정관련
- 데이터 쪽 정리는 데이터 정리 — 중복 문서·Chroma 재빌드
- 웹 구동 절차는 웹 UI 개편 — 사이드바 3단 구조