Nginx 리버스 프록시 운영 실전: timeout, buffering, keepalive 설정으로 장애 줄이기

Nginx 리버스 프록시 운영 실전: timeout, buffering, keepalive 설정으로 장애 줄이기

Nginx는 잘못 설정해도 당장 티가 안 나다가 트래픽이 몰릴 때 한꺼번에 문제를 드러낸다.

중급 운영에서는 timeout, buffering, keepalive를 별개의 튜닝 포인트가 아니라 같은 연결 수명 관리 문제로 봐야 한다.

왜 지금 이 주제가 중요한가

• 프록시 timeout과 업스트림 timeout이 어긋나면 재시도 폭주가 쉽게 생긴다.
• buffering은 느린 클라이언트를 보호해 주지만 디스크 I/O와 메모리 사용을 바꿔 놓는다.
• keepalive는 성능 레버이지만 과하면 서버와 LB 연결 자원을 잠식한다.

핵심 설계 포인트

• client, proxy, upstream의 timeout 계층을 짧은 순서로 정렬한다.
• request/response buffering은 payload 크기와 스트리밍 여부로 다르게 둔다.
• keepalive requests, timeout, pool 크기를 업스트림 동시성에 맞춰 제한한다.
• 대형 업로드/다운로드 경로는 일반 API와 별도 location 또는 서버 블록으로 분리한다.

예시 구성

proxy_connect_timeout 2s;
proxy_send_timeout 10s;
proxy_read_timeout 10s;
proxy_http_version 1.1;
proxy_set_header Connection "";
keepalive_timeout 30s;

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

1. 현재 499, 502, 504 비율과 upstream response time을 먼저 확인한다.
2. 클라이언트 유형(브라우저, 모바일, 내부 API)에 따라 timeout 요구를 나눈다.
3. 일반 API와 스트리밍/업로드 경로를 구분해 buffering 정책을 설정한다.
4. keepalive 설정을 바꾼 뒤 upstream 연결 생성 수와 에러율을 비교한다.
5. 릴리스 전 `nginx -t`와 카나리 트래픽 검증을 자동화한다.

운영 체크포인트

• 장문 업로드와 일반 API를 같은 timeout/buffering 정책으로 묶지 않는다.
• 에러 로그와 access 로그에 upstream 응답시간을 남긴다.
• 프록시 설정 변경은 트래픽이 낮은 시간에 단계적으로 반영한다.

운영 지표/알람 추천

• upstream 4xx/5xx, timeout, reset 비율
• request/response buffering으로 인한 디스크 spill
• keepalive 재사용률과 연결 생성량
• TLS handshake 지연과 upstream connect 시간

빠른 점검 명령/쿼리

nginx -t
curl -I https://example.com
tail -n 100 /var/log/nginx/error.log

구조화 로그 필드 추천

• traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
• endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

• 운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
• 기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
• 팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행 또는 데이터 유실: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. 504가 나면 proxy_read_timeout만 무작정 늘린다: 근본 원인은 업스트림일 수 있다.
2. buffering을 모두 끈다: 느린 클라이언트가 업스트림을 오래 붙잡는다.
3. keepalive 수를 크게 잡는다: 업스트림 연결 풀 고갈로 이어질 수 있다.

바로 적용 템플릿

Nginx 기본 템플릿:
connect/send/read timeout 계층 정렬
API vs stream/upload 경로 분리
upstream response time 로깅
keepalive pool 크기 명시

검증 방법

• 느린 클라이언트와 느린 업스트림을 각각 재현해 어느 계층에서 timeout이 먼저 터지는지 확인한다.
• keepalive 설정 전후로 upstream 새 연결 생성 수와 p95 지연을 비교한다.

장애 대응 Runbook(초안)

• 현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
• 범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
• 근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

1. 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
3. 관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "Nginx 리버스 프록시 운영 실전: timeout, buffering, keepalive 설정으로 장애 줄이기"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

• NGINX Reverse Proxy
• NGINX ngx_http_proxy_module