여기서는 멈추세요
- 명령 출력의 서버·서비스·경로가 예상 대상과 다르면 변경 단계로 넘어가지 않습니다.
- 현재 접속 세션, 백업 또는 콘솔 복구 경로를 확보하지 못했다면 상태 변경 명령을 실행하지 않습니다.
UPLOAD LIMIT
NGINX에서 413 파일 업로드 오류가 날 때
413 응답을 만든 프록시 계층, client_max_body_size 적용 위치와 임시 저장공간을 확인한 뒤 필요한 범위만 조정합니다.413 Request Entity Too Largeclient_max_body_sizeNGINX upload파일 업로드 실패request body
환경NGINX reverse proxy · 파일 업로드 API
분류웹·보안
검토일2026-08-27
진행5단계 · 조회 우선
SAFE OPERATING BOUNDARY
중단·복구 기준부터 확인하세요
복구 기준
변경 전 설정과 출력값을 기록하고, 예상과 다른 결과가 나오면 추가 변경을 멈춘 뒤 승인된 운영 복구 절차로 되돌립니다.
담당자에게 전달할 자료
- 장애 발생 시각·정상화 시각과 원문 오류 메시지
- 민감정보를 제거한 조회 명령 출력과 변경 전후 차이
- 조치 후 동일 조건으로 수행한 재검증 결과
BEFORE YOU START
이런 증상에서 시작합니다
- 작은 파일은 성공하지만 큰 파일은 413
- 브라우저 파일 업로드 실패
- 프록시 추가 후 업로드 제한
- 애플리케이션 로그에 요청이 없음
CHECK THE BRANCH
놓치기 쉬운 원인 분기
애플리케이션 로그가 없는 경우
요청이 upstream에 도달하기 전에 NGINX나 상위 프록시가 거부했을 가능성이 큽니다.
특정 경로만 실패
http·server·location 중 더 구체적인 context에서 다른 제한이 적용되는지 확인합니다.
설정 후 500·쓰기 오류
요청 본문 임시 경로의 용량과 NGINX worker 사용자 권한을 확인합니다.
FOLLOW THE FLOW
순서대로 확인하기
조회시스템을 변경하지 않는 확인 단계
413을 반환한 계층과 재현 조건 확인
도메인·업로드 경로와 안전한 테스트 파일을 사용하고 응답 헤더를 기록합니다.
응답 헤더
curl -I --max-time 15 https://example.com/upload최근 접근 로그
sudo tail -n 100 /var/log/nginx/access.log최근 오류 로그
sudo tail -n 100 /var/log/nginx/error.log결과 읽기
NGINX 로그에 413이 있고 upstream 로그에 요청이 없으면 프록시 제한을 우선 확인합니다.
다음 판단
성공하는 파일 크기와 실패하는 파일 크기를 기록합니다.
조회시스템을 변경하지 않는 확인 단계
실제로 적용된 body 제한 찾기
nginx -T는 include된 설정까지 출력합니다. 인증서 키 내용은 출력하지 않지만 공유 전 경로·도메인을 검토합니다.
설정 문법
sudo nginx -tbody 제한 위치
sudo nginx -T 2>&1 | grep -n 'client_max_body_size'결과 읽기
지시어가 없으면 기본 제한이 적용됩니다. 여러 위치에 있으면 요청을 처리하는 server·location context를 찾습니다.
다음 판단
무조건 전역 http에 크게 설정하지 말고 필요한 업로드 location 범위를 정합니다.
조회시스템을 변경하지 않는 확인 단계
상위 프록시와 애플리케이션 제한 비교
CDN·로드밸런서·Ingress·애플리케이션 프레임워크도 별도 제한을 가질 수 있습니다.
virtual host 선택 확인
curl -vkI --resolve example.com:443:SERVER_IP https://example.com/uploadupstream 직접 확인
curl -i --max-time 15 http://127.0.0.1:PORT/upload결과 읽기
직접 upstream은 통과하고 외부 경로만 413이면 중간 프록시 계층의 제한입니다.
다음 판단
각 계층의 허용 크기를 동일하게 키우기보다 업무상 필요한 최대값으로 맞춥니다.
조회시스템을 변경하지 않는 확인 단계
임시 저장공간과 worker 권한 확인
큰 요청은 메모리 버퍼를 넘으면 임시 파일로 저장될 수 있습니다.
body 임시 경로 설정
sudo nginx -T 2>&1 | grep -n 'client_body_temp_path'기본 후보 경로 용량
df -hT /var/lib/nginx /tmp 2>/dev/nullNGINX 실행 사용자
ps -o user,group,pid,comm -C nginx결과 읽기
임시 경로의 디스크 부족이나 권한 오류는 413과 별도의 후속 실패를 만들 수 있습니다.
다음 판단
경로를 변경하기 전에 파일시스템 용량과 보안 정책을 확인합니다.
변경데이터·서비스 상태가 달라질 수 있는 단계
필요한 location만 조정하고 업로드 검증
업무상 허용 크기와 보안·스토리지 영향을 정한 뒤 설정 파일에 client_max_body_size를 추가합니다.
변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.
설정 문법 재검증
sudo nginx -t무중단 반영
sudo systemctl reload nginx승인된 테스트 파일 업로드
curl -i -F 'file=@/path/to/test-file.bin' https://example.com/upload결과 읽기
의도한 크기는 성공하고 제한을 넘는 파일은 여전히 거부되며 디스크·메모리 사용이 안정적이어야 합니다.
다음 판단
오류 로그와 upstream 처리 시간을 함께 관찰해 새로운 병목이 없는지 확인합니다.
PRIMARY REFERENCES
공식 문서
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.