기술 · 실용 가이드
NGINX “upstream sent too big header”? buffer를 늘리기 전에 protocol과 header owner를 확인하세요
route가 proxy, FastCGI, uWSGI 중 무엇인지 증명하고 response header를 측정해 runaway cookie를 줄인 뒤 해당 first buffer만 조정하세요.
이 error는 upstream response header 경계이며 upload body나 client request-header limit이 아닙니다. 모든 buffer를 키우라는 증거도 아닙니다.
한 failing request, effective location, module과 header bytes를 보존하고 비정상 field를 줄이세요. 정당한 상한만 좁은 context에서 조정합니다.
failing request와 effective route를 보존하세요
완전한 NGINX error line, timestamp, request ID, host, URI, status, upstream address와 worker PID를 보존하세요. Cookie 값 같은 secret을 기록하지 말고 access, upstream application, authentication log를 연결합니다.
실제로 실행 중인 같은 image 또는 host에서 nginx -T를 실행하고 include가 펼쳐진 server와 location을 보관하세요. master PID, config path, deployment revision을 기록하며 worker가 읽지 않은 file 수정은 fix가 아닙니다.
directive 선택 전 upstream protocol을 확인하세요
이 error는 upstream이 보낸 response에 관한 것입니다. location이 proxy_pass를 쓰면 proxy_buffer_size를, fastcgi_pass와 uwsgi_pass라면 각 module의 directive family를 확인하세요. client_max_body_size와 large_client_header_buffers는 다른 request-side boundary입니다.
일반적인 snippet이 아니라 error log의 upstream scheme과 effective location으로 directive를 고르세요. FastCGI나 uWSGI 요청에는 proxy_*가 작동하지 않으며 global 증가는 모든 route의 memory를 불필요하게 키울 수 있습니다.
response-header owner를 측정하세요
안전한 환경이나 direct upstream path에서 같은 authentication과 session state로 재현하세요. 값을 redact한 채 header name과 byte length를 기록하고 반복 Set-Cookie, Location, auth metadata, custom field를 집중 점검합니다.
통과한 response와 실패한 response를 비교해 하나의 field가 first-response buffer를 넘었는지 여러 field가 누적됐는지 구분하세요. session, OAuth state, serialized application data가 자란 경우 가능하면 producer에서 줄입니다.
최소 module-specific 변경을 적용하세요
중복되거나 큰 Cookie를 줄이고 큰 session state는 server side로 옮기며 불필요한 metadata를 제거하고 redirect/auth state를 제한하세요. 합법적인 header가 여전히 크다면 가장 좁은 effective context에서 해당 module buffer만 올립니다.
proxy buffering을 바꿀 때 proxy_buffers와 busy-buffer constraint를 유효하게 유지하되 first response header 측정을 대신하게 하지 마세요. syntax check, graceful reload, running worker의 rendered config 상속까지 검증합니다.
같은 state를 반복하고 memory를 검증하세요
같은 URI, method, upstream, authentication callback, session size를 replay하세요. 502가 사라지고 error log가 깨끗하며 application result가 맞는지 확인한 뒤 near-limit과 over-limit case도 시험합니다.
이전·새 directive, effective location, header-byte summary, worker reload time, request ID, concurrency, memory impact, rollback threshold를 기록하세요. login이나 cart expansion 뒤 header growth를 계속 감시해 새 buffer가 무한 성장을 미루기만 하지 않는지 확인합니다.
