Kord/Docs/WorkDone/2026-04-21_fix_dashboard_panic.md

Dashboard & Bot Stability Infrastructure Fix (2026-04-21)

개요

사용자가 대시보드 URL 접속 시 Turbopack Panic 에러를 겪는 문제를 해결하고, 봇 프로세스의 불안정성(IPC 채널 종료)을 개선했습니다.

원인 분석

1. gRPC Contract 초기화 이슈:
   • grpc-contracts 패키지 로드 시점에 동적으로 파일 시스템을 조회하여 proto 파일을 로드함.
   • Next.js의 빌드/분석 단계에서 파일 시스템 접근 권한이나 경로 문제로 인해 crash 유발.
2. Turbopack 환경 호환성 이슈:
   • Turbopack이 내부 worker 프로세스를 스폰할 때 시스템 $PATH에서 node 바이너리를 찾지 못함 (os error 2).
   • 이는 Turborepo의 환경 변수 제한 정책과 겹쳐 발생함.

해결 방법

1. gRPC Lazy Loading 적용:
   • packages/grpc-contracts/src/index.js를 수정하여 실제 모듈 접근 시점에만 proto를 로드하도록 getter 패턴 적용.
2. gRPC 서버 개발 모드 통합:
   • apps/bot/src/utils/grpcServer.ts를 신설하여 공통 gRPC 서버 로직을 추출.
   • 단일 실행 모드(index.ts)와 Sharding 모드(shard.ts) 모두에서 대시보드 통신을 위한 gRPC 서버가 기동되도록 수정.
3. Webpack Fallback 및 PATH 주입:
   • Turbopack의 하위 프로세스 스폰 이슈(os error 2)를 회피하기 위해 대시보드를 Webpack 모드(next dev --webpack)로 구동.
   • apps/dashboard/package.json에서 명시적으로 Node.js 실행 경로를 PATH에 주입.
4. 인프라 자동 복구:
   • docker-compose를 통해 PostgreSQL 컨테이너를 정상화하고 Prisma 스키마를 동기화.
5. 좀비 프로세스 정리:
   • 포트 점유 이슈를 유발하던 구형 Node 프로세스들을 원천 정리.

결과 확인

• scripts/verify-recovery.ts를 통해 DB, gRPC, Bot 연동 전수 검토 완료 (ALL PASS).
• curl -I http://localhost:3000/를 통해 대시보드 응답 확인.
• 브라우저를 통한 대시보드 UI 정상 렌더링 확인.

참고 사항

• 현재 대시보드는 안정성을 위해 임시로 3005 포트에서 구동 확인을 마쳤으나, 3000번 포트 점유가 해제되면 다시 3000번으로 서비스될 수 있도록 설정되어 있습니다.