최근 Study-Flow AI 프로젝트를 진행하며 로컬 환경에서는 발견하지 못했던 다양한 서버 배포 이슈와 런타임 오류들을 마주했습니다. t2.micro라는 제한적인 리소스 환경에서 서비스를 안정화하고 HTTPS 보안 적용까지 완료한 과정을 기록으로 남깁니다.
1. AI 서버 런타임 오류: AttributeError 진단
[현상] AI 분석 기능 실행 시 백엔드에서 500 에러 발생 및 프로세스 중단.
- 원인: ai-server/app/services.py에서 존재하지 않는 예외 클래스인 anthropic.OverloadedError를 참조하고 있었습니다.
- 해결: 실제 라이브러리에 존재하는 anthropic.APIStatusError로 수정하고, 클로드 API의 일시적 과부하(Status 529)에 대응하기 위해 비동기 재시도(Retry) 로직을 추가했습니다.
2. 카카오 지도 API: 403 Forbidden 해결
[현상] 지도 SDK가 로드되지 않아 화면이 공백으로 표시됨.
- 원인: HTTP 환경에서 HTTPS 기반 SDK 호출 시 리퍼러(Referrer) 정보 누락 및 도메인 미등록 문제였습니다.
- 해결: 카카오 앱을 **비즈 앱(Biz App)**으로 승격 후 새 키를 발급받았으며, HTML 메타 태그의 리퍼러 정책을 no-referrer-when-downgrade로 수정했습니다.
3. 저사양 서버(t2.micro) 프리징 대응
[현상] Docker 빌드 중 SSH 접속이 끊기고 서버가 응답 없음(Freezing).
- 원인: 1GB RAM 환경에서 Gradle과 Node.js 빌드 시 메모리 부족 현상이 발생했습니다.
- 해결: 서버 내에 **2GB 규모의 스왑 파일(Swap File)**을 생성하여 가상 메모리를 확보함으로써 빌드 안정성을 확보했습니다.
4. 디스크 용량 부족(ENOSPC) 결함 복구
[현상] 빌드 도중 No space left on device 에러 발생.
- 원인: 반복된 빌드로 쌓인 Docker 빌드 캐시와 쓰이지 않는 레이어들이 20GB 디스크를 모두 점유했습니다.
- 해결: 아래 명령어로 불필요한 데이터를 정리하여 10GB 이상의 공간을 확보했습니다.
docker system prune -a --volumes
5. Docker Compose V2 업그레이드
[현상] 서비스 실행 시 KeyError: 'ContainerConfig' 발생.
- 원인: 구형 docker-compose(V1)가 최신 Docker 엔진의 이미지 메타데이터 구조를 인식하지 못하는 호환성 문제였습니다.
- 해결: Docker 공식 리포지토리를 통해 docker-compose-plugin(V2)을 설치하여 근본적인 호환성 문제를 해결했습니다.
6. HTTPS 보안 연결 및 Geolocation 활성화
[현상] 지도 접속은 되지만 '내 위치 찾기' 기능이 작동하지 않음.
- 원인: 브라우저 보안 정책상 위치 정보 API는 반드시 HTTPS 환경에서만 작동합니다.
- 해결: 가비아 도메인 연동 후 **Let's Encrypt(Certbot)**로 SSL 인증서를 발급했습니다. Nginx 설정을 통해 443 포트를 활성화하고 전역 HTTPS 리다이렉트를 적용했습니다.
7. CI/CD 자동 배포 권한 충돌 해결
[현상] GitHub Actions 배포 중 특정 폴더(Certbot 인증서 등) 접근 거부로 빌드 실패.
- 원인: root 소유의 인증서 폴더가 빌드 컨텍스트에 포함되면서 Docker가 접근하지 못해 발생한 문제였습니다.
- 해결: 프로젝트 루트에 .dockerignore 파일을 생성하여 권한 충돌 소지가 있는 인증서 및 환경 설정 폴더를 빌드 대상에서 제외했습니다.
마치며
이번 트러블슈팅을 통해 단순한 기능 구현을 넘어, 인프라 리소스 관리와 보안 정책 준수가 서비스 안정성에 얼마나 큰 영향을 미치는지 배울 수 있었습니다. 이제 Study-Flow AI는 상용 환경에서도 안정적으로 운영될 준비를 마쳤습니다!