NGINX proxy_next_upstream으로 요청 재시도 구성하기

---

---

 

운영 중인 서비스에서 A 서버가 일시적으로 장애가 발생했을 때, 같은 업스트림 그룹의 B 서버로 요청을 자동으로 넘기고 싶다면 어떻게 해야 할까?
바로 proxy_next_upstream 지시어를 이용하면 됨.

✅ proxy_next_upstream 이란?

proxy_next_upstream 지시어는 동일 요청 안에서 첫 번째 서버가 연결 실패 또는 오류 응답(timeout, http_502, http_504 등)을 반환했을 때,
NGINX가 같은 업스트림 그룹의 다른 서버로 자동 재전송을 하도록 만들어 줌.

• 기본값: error, timeout
• POST, PATCH처럼 비멱등 요청은 non_idempotent 옵션을 명시해야 재시도 가능함

🔗 NGINX 공식 문서 - proxy_next_upstream

💡 예시 – A → B(w2.domain.com) 로 단일 요청 재시도 구성

# 1. 업스트림 그룹
upstream origin {
    zone origin 64k;
    server A.internal.lan:80 max_fails=2 fail_timeout=5s;
    server w2.domain.com:80 backup;
}

# 2. 가상 서버 설정
server {
    listen 80;
    server_name w1.domain.com;

    location / {
        proxy_pass http://origin;

        # 재시도 조건/횟수/시간 설정
        proxy_next_upstream          error timeout http_502 http_504;
        proxy_next_upstream_tries    2;
        proxy_next_upstream_timeout 10s;

        proxy_set_header Host $host;
    }
}

🔄 동작 흐름

단계	결과 설명
정상	클라이언트 → A 서버(w1 도메인)로 요청 전달
A 실패	502/504/타임아웃 발생 시, 최대 1회 B(backup)로 즉시 재시도
재시도 성공	B 서버 응답 → 클라이언트 전달
A 회복	fail_timeout(5초) 이후 A 서버를 다시 healthy 로 간주하고 복구

🔧 주요 매개변수 정리

지시어	설명	비고
proxy_next_upstream	재시도 조건 설정 (timeout, error, http_502 등)	POST는 non_idempotent 필요
proxy_next_upstream_tries	최대 시도 횟수 (0 = 무제한)	예시에서는 2 (A → B 1회)
proxy_next_upstream_timeout	재시도에 허용되는 전체 시간	초/분 단위
max_fails / fail_timeout	서버를 일시적으로 비활성화(mark down) 처리 기준	passive 헬스 체크 역할

🔍 Active Health Check와 차이점

• proxy_next_upstream : 실패한 “그 요청”을 인접 서버로 넘기는 수동 방식
• health_check (NGINX Plus 전용) : 주기적으로 서버 상태를 사전 점검 후 정상 서버에만 요청 전달하는 능동 방식

두 기능을 병행 사용해도 무방하며, health_check가 unhealthy 판정하면 NGINX는 해당 서버를 건너뜀.

🧪 실전 팁

1. POST 요청도 재시도하려면 아래처럼 non_idempotent를 추가해야 함

   proxy_next_upstream error timeout http_502 http_504 non_idempotent;

2. 우선순위 지정이 필요하다면 backup 지시어를 사용하면 됨. A 서버만 평상시에 사용되고, A 모두 다운되었을 때만 B 서버로 전환됨
3. HTTPS 백엔드를 사용할 경우 proxy_pass URL을 https://로 바꾸고 proxy_ssl_* 설정을 함께 추가해야 함
   🔗 NGINX SSL 프록시 설정 공식 문서

✅ 마무리

proxy_next_upstream은 설정만 잘 해두면 장애 대응을 자동화할 수 있음. 특히 서버가 간헐적으로 불안정한 상황에서도 유연한 트래픽 처리를 가능하게 해줌.

추후 sticky 세션, slow-start, persistent connection 설정까지 정리할 예정임.

 

---

덤) AI로 스크랩해놓은 자료 포스팅 자료로 만들어달라고 함. 인간미는 없는듯.

---

---