llm-wiki/raw/official-docs/nginx-client-max-body-size.md

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
nginx — client_max_body_size Directive (ngx_http_core_module)	official-doc	https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size		raw	high	nginx gateway file-upload size-limit http		feature-file-resource-handling-contract	2026-05-27	2026-05-27

nginx — client_max_body_size Directive (ngx_http_core_module)

Layer: raw/official-docs/ — nginx 공식 reference 문서의 client_max_body_size directive 원문 발췌. ca-tmpl 의 gateway-level 파일 크기 제한 메커니즘의 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-file-resource-handling-contract	D4 gateway-level 파일 크기 제한 메커니즘 — nginx client_max_body_size 가 limit 초과 시 HTTP 413 응답을 반환하며, default 는 1m, 컨텍스트는 http/server/location

컨텍스트

ca-tmpl feature-file-resource-handling-contract 의 D4 는 application layer (Spring Boot multipart limit) 이전에 gateway (nginx) 에서 1차 size 차단을 둔다는 결정. 본 source 는 nginx client_max_body_size directive 의 공식 spec — syntax / default / context / 초과 시 동작 (HTTP 413).

출처 / Source

• 원본 URL: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
• 아카이브 URL: (미수집)
• 저자 / 조직: nginx, Inc. / F5 (공식 nginx project)
• 발행일: rolling docs
• 마지막 확인일: 2026-05-27

왜 저장했는지 / Why archived

ca-tmpl 의 파일 업로드 흐름이 (a) 게이트웨이 nginx 에서 1차 size 검증, (b) 앱 Spring multipart 에서 2차 검증, (c) S3 / object storage 가 3차 검증으로 다층 방어함을 정당화. 1차 방어선의 directive 가 정확히 어떤 응답을 반환하는지 (HTTP 413) 의 공식 verbatim 이 핵심.

핵심 인용 / Key quotes (verbatim)

[§client_max_body_size] "Syntax: client_max_body_size size;"

[§client_max_body_size] "Default: client_max_body_size 1m;"

[§client_max_body_size] "Context: http, server, location"

[§client_max_body_size] "Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client."

[§client_max_body_size] "Please be aware that browsers cannot correctly display this error."

[§client_max_body_size] "Setting size to 0 disables checking of client request body size."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
NGINX-CMB-C1	client_max_body_size directive 의 syntax 는 client_max_body_size size;	[§client_max_body_size] "Syntax: client_max_body_size size;"	official-vendor-doc	모든 nginx 설정	size 의 단위 (k/m/g) 와 정수 표현 규칙은 본 인용 범위 밖 (nginx 공통 size 표기)
NGINX-CMB-C2	client_max_body_size 의 default 값은 1m (1 megabyte)	[§client_max_body_size] "Default: client_max_body_size 1m;"	official-vendor-doc	nginx 의 모든 설정 컨텍스트 (명시적 override 없는 경우)	1m 가 모든 배포에서 충분하다는 뜻은 아님 — 단지 nginx 의 default 값일 뿐
NGINX-CMB-C3	client_max_body_size 는 http, server, location 세 컨텍스트에서 설정 가능	[§client_max_body_size] "Context: http, server, location"	official-vendor-doc	nginx 설정의 scope override 패턴	upstream / map / if 컨텍스트에서는 사용 불가 (본 인용 범위 밖, 추론)
NGINX-CMB-C4	request body size 가 설정값을 초과하면 nginx 는 HTTP 413 (Request Entity Too Large) 응답을 client 에 반환	[§client_max_body_size] "Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client."	official-vendor-doc	client → nginx 의 request body 크기 검증	"request body size" 가 Content-Length 헤더 기반인지, 실제 수신 byte 누적 기반인지는 본 인용 범위 밖 (실제로는 둘 다 검증)
NGINX-CMB-C5	413 응답이 일부 브라우저에서 정확히 표시되지 않을 수 있음 (UX 한계 경고)	[§client_max_body_size] "Please be aware that browsers cannot correctly display this error."	official-vendor-doc	UX 측면의 413 응답 처리	어떤 브라우저가 어떻게 처리하는지의 detail 은 본 인용 범위 밖
NGINX-CMB-C6	client_max_body_size 를 0 으로 설정하면 request body size 검사 자체가 비활성화	[§client_max_body_size] "Setting size to 0 disables checking of client request body size."	official-vendor-doc	size 검사를 의도적으로 끌 때 (예: streaming proxy, large upload endpoint)	"검사 비활성화" 가 upstream / 후속 module 에서 size 검사가 일어나지 않는다 는 뜻은 아님 — nginx core 단의 check 만 비활성

Strength

모두 official-vendor-doc (nginx 공식 reference module 문서).

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • NGINX-CMB-C1 ~ C3: directive 의 syntax / default / context 정의
  • NGINX-CMB-C4: 초과 시 HTTP 413 응답 반환 (= gateway-level 1차 차단의 mechanic)
  • NGINX-CMB-C5: 413 응답의 브라우저 표시 한계 (UX 경고)
  • NGINX-CMB-C6: 0 설정으로 검사 비활성화 가능
• 이 자료가 증명하지 않는 것:
  • nginx 가 Content-Length 헤더와 실제 수신 byte 중 어느 것으로 size 를 판정하는지 — 본 인용은 "the size in a request" 로 일반화
  • chunked transfer encoding 에서의 동작 (Content-Length 없음)
  • 413 응답의 정확한 status line / body / 헤더 형식
  • nginx 가 size 초과를 감지하는 시점 (header 단계 vs body 수신 도중)
  • client_body_buffer_size, client_body_temp_path 등 관련 directive 와의 상호작용
• 내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 nginx (또는 다른 gateway) 가 client_max_body_size 의 default 1m 를 그대로 두는지, 명시적 override 하는지 확인
  • nginx 의 413 응답이 ca-tmpl 앱의 error 응답 포맷 (예: JSON {"error": ...}) 과 일치하는지 — 일반적으로 nginx default 413 은 HTML 이므로 별도 error_page 또는 custom response 필요
  • ca-tmpl 의 Spring Boot multipart limit (spring.servlet.multipart.max-file-size / max-request-size) 와 nginx limit 의 정합성 — 일반적으로 gateway limit ≥ app limit (gateway 가 먼저 차단)
  • ca-tmpl 의 upload endpoint 가 streaming 인 경우 0 으로 nginx 검사 비활성 후 app 단 검증으로 위임할지 결정

메모 / Notes

• 본 capture 는 nginx core module 의 client_max_body_size 만 다룸 — 관련 directive (client_body_buffer_size, client_body_timeout) 는 별도 capture 필요 시.
• 다음 후보 fetch:
  • https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size — buffering 동작
  • Spring Boot 의 spring.servlet.multipart.max-file-size 공식 reference — app layer 와의 정합성 검증

Related / 관련

• 같은 주제 다른 official-doc / company-tech-blog: (없음 — Spring multipart limit 의 official-doc 미수집)
• 인용하는 branch:
  • raw/branch-notes/feature-file-resource-handling-contract
• 인용하는 project:
  • raw/project-notes/ca-skeleton-operational-contract
• 인용한 wiki 요약: (미작성)