ngrok + Vite 프록시 환경의 Multipart 파일 업로드 실패 분석 및 해결

1. 배경 및 문제 상황

Vite와 Spring Boot를 이용하여 파일 업로드 기능을 구현하던 중, 로컬 환경에서는 완벽하게 동작하던 기능이 ngrok을 통한 외부 접속 환경에서만 간헐적으로 실패하는 현상이 발생했습니다.

발생 에러

org.springframework.web.multipart.MultipartException: Failed to parse multipart servlet request
...
Caused by: org.apache.catalina.connector.ClientAbortException: java.io.EOFException

에러 로그는 백엔드 컨트롤러 진입 전, 서블릿 레이어에서 멀티파트 데이터를 파싱하다가 클라이언트가 연결을 강제로 끊었음을 가리키고 있었습니다.

---

2. 가설 설정 및 검증 과정

단순히 설정을 바꾸는 것이 아니라, 요청의 흐름을 계층별로 분리하여 원인을 추적했습니다.

[가설 1] CORS 및 서버 타임아웃 문제

• 분석: ngrok 도메인 허용 문제나 대용량 파일 처리 시 타임아웃 가능성 검토.
• 검증: CORS 설정을 업데이트하고 타임아웃을 늘렸으나 동일 증상 반복. 요청이 이미 서버에 도달해 파싱 중 에러가 나므로 CORS 문제는 아님을 확신.

[가설 2] Vite Proxy의 Payload 스트리밍 유실

• 분석: Vite Proxy가 멀티파트 데이터를 백엔드로 전달하는 과정에서 데이터 스트림이 끊길 가능성.
• 검증: 프록시 설정에서 content-length를 강제 지정했으나 증상 지속. ngrok의 무료 플랜 대역폭 제한이나 네트워크 홉 증가로 인해 데이터 전송이 불안정해진 것으로 판단.

---

3. 근본 원인

문제의 핵심은 "복잡한 프록시 체인과 데이터 스트리밍의 불일치"였습니다.

1. Proxy Chain의 복잡성: Browser → ngrok → Vite Proxy → Spring Boot라는 3단계 계층을 거치며 데이터가 전달됩니다.
2. Streaming 중단: ngrok의 네트워크 지연으로 인해 Vite Proxy가 백엔드로 보낼 데이터를 기다리는 동안, 브라우저 혹은 ngrok 레이어에서 연결을 유지하지 못하고 끊어버려 백엔드에서는 EOFException이 발생한 것입니다.

---

4. 프록시 우회 전략

개발 편의를 위한 Vite Proxy가 오히려 데이터 정합성을 해치고 있었으므로, 환경에 따라 API 엔드포인트를 동적으로 분리하여 프록시 체인을 단순화했습니다.

// 환경 변수를 활용한 엔드포인트 전략 분리
const getBaseUrl = () => {
  // ngrok 환경일 경우 프록시를 거치지 않고 백엔드 ngrok 터널로 직접 통신
  if (window.location.hostname.includes('ngrok-free.app')) {
    return import.meta.env.VITE_BACKEND_DIRECT_URL; 
  }
  return '/api'; // 로컬 개발 시에는 기존처럼 Vite 프록시 활용
};

이후 직접 통신 방식을 통해 데이터 유실 없이 대용량 파일도 안정적으로 업로드됨을 확인했습니다.

---

5. 🔧 실서비스 안정성을 위한 개선

단순히 "에러를 고쳤다"에서 끝나지 않고, 실제 운영 환경에서 발생할 수 있는 변수들을 고려하여 시스템을 보완했습니다.
이 부분은 서비스의 신뢰도와 관찰 가능성을 높이는 데 초점을 맞추었습니다.

① ClientAbortException 분리 로그 노이즈 제거

사용자가 업로드 중 브라우저를 닫는 행위는 장애가 아닌 '정상적 이탈'입니다.
이를 시스템 에러와 분리하여 로그 신뢰도를 높였습니다.

@ExceptionHandler(ClientAbortException.class)
public void handleClientAbort(ClientAbortException e) {
    // 경고 로그로 분류하여 불필요한 장애 알람 발생 방지
    log.warn("File upload aborted by user/network: {}", e.getMessage());
}

② 방어적 UX 구현: 중복 요청 및 이탈 방지

불필요한 서버 자원 낭비를 막기 위해 프론트엔드 제어권을 강화했습니다.

• Double-Click 방지: 업로드 시작 시 버튼 비활성화 처리.
• 이탈 방지 가드: beforeunload 이벤트를 통해 업로드 중 페이지 이동 시 경고창 노출.

③ AbortController 도입 명시적 자원 해제

브라우저의 암묵적 중단에 의존하지 않고, 컴포넌트 언마운트 시 네트워크 요청을 명시적으로 취소하여 메모리 누수를 방지합니다.

const controller = new AbortController();
axios.post("/upload", formData, { signal: controller.signal });

// Cleanup function
return () => controller.abort();

④ 인프라 확장성 고려

파일 업로드는 본질적으로 CPU와 I/O 소모가 큰 작업입니다.
현재의 단일 서버 구조를 넘어선 아키텍처를 설계에 반영할 예정입니다.

• Storage 분리: 서버 부하 감소를 위해 AWS S3 Presigned URL 방식 도입 검토.
• 관찰 가능성: 파일 크기별 처리 시간을 메트릭화하여 네트워크 구간의 병목 구간 모니터링.

---

6. 결론 및 교훈

"모든 네트워크 에러가 서버의 잘못은 아니다. 하지만 모든 에러는 서버에서 우아하게 처리되어야 한다."

이번 이슈를 통해 네트워크 홉이 늘어날수록 발생할 수 있는 Side Effect를 깊이 이해하게 되었습니다.
또한, 로그 분석 시 단순 에러 발생 여부보다 "어떤 레이어에서, 왜 끊겼는가"를 추적하는 정교한 디버깅 프로세스의 중요성을 다시 한번 체감했습니다.

---