504 Gateway Timeout

이 오류의 의미와 확인 방법

• 브라우저가 즉시 실패하지 않고 기다린 후 504 Gateway Timeout을 표시합니다.
• 단순한 페이지는 계속 작동하지만 보고서, 대량 가져오기, 내보내기, 이미지 처리 또는 복잡한 검색이 실패합니다.
• 애플리케이션이 사용 중이거나 요청이 대기열에 들어가면 실패가 더 자주 발생합니다.
• 직접 테스트하면 백엔드가 응답하지만, 프록시, CDN 또는 로드 밸런서를 거친 동일한 요청은 타임아웃됩니다.
• 게이트웨이 로그에는 504가 반환되기 전에 업스트림 요청이 오랫동안 실행된 기록이 나타납니다.
• 브라우저가 타임아웃을 받은 후에도 애플리케이션이 계속 처리할 수 있습니다. 이때 작업을 재시도하면 중복 작업이나 중단된 작업이 남을 수 있습니다.

가능성이 높은 순서의 주요 원인

1. 느리거나 차단된 데이터베이스 쿼리: 인덱스 누락, 테이블 증가, 비효율적인 쿼리, 잠금 경합으로 인해 애플리케이션이 게이트웨이 제한 시간을 초과할 때까지 대기할 수 있습니다.
2. 백엔드 과부하 또는 대기열: 요청이 애플리케이션 워커, 데이터베이스 연결, CPU, 메모리 또는 기타 부족한 리소스를 기다리고 있을 수 있습니다.
3. 실제로 오래 걸리는 동기 작업: 대규모 내보내기, 가져오기, 보고서 또는 파일 처리는 정상적인 작업일 수 있지만 일반적인 페이지 요청에는 적합하지 않을 수 있습니다.
4. 느린 다운스트림 API 또는 webhook: 애플리케이션이 응답하기 전에 다른 서비스의 응답을 기다리고 있을 수 있습니다.
5. 제한적인 프록시 또는 서버 타임아웃: Nginx, Apache, CDN 또는 로드 밸런서가 애플리케이션의 처리가 끝나기 전에 대기를 중단할 수 있습니다.
6. 게이트웨이 계층 사이의 네트워크 문제: 애플리케이션 처리 시간만으로 지연이 설명되지 않는 경우, 특히 다중 서버 또는 다중 리전 배포에서는 지연, 간헐적인 패킷 손실 또는 라우팅 오류의 가능성이 더 높습니다.

해결 방법

1. 실패한 요청과 소요 시간 확인

504를 발생시킨 요청을 게이트웨이 및 애플리케이션 액세스 로그에서 확인하세요. 경로 또는 사용자 작업, 타임스탬프, 응답 시간, 상태, 그리고 모든 요청이 실패하는지 특정 작업만 실패하는지를 기록합니다.

보고서, 가져오기, 내보내기 또는 복잡한 검색만 실패한다면 장애를 전체 서버 중단으로 간주하기보다 해당 작업부터 조사하세요.

2. 백엔드와 전체 요청 경로 비교

권한이 있고 안전한 테스트 요청을 사용하여 백엔드에 직접 요청했을 때의 응답 시간과 프록시, CDN 또는 로드 밸런서를 거친 동일한 요청의 응답 시간을 비교하세요.

• 직접 요청과 게이트웨이를 통한 요청 모두 느리다면 애플리케이션, 데이터베이스, 용량 또는 의존 서비스가 원인일 가능성이 있습니다.
• 직접 요청은 빠르지만 프록시를 거친 요청이 실패한다면 중간 계층의 타임아웃, 라우팅 문제 또는 게이트웨이와 백엔드 사이의 네트워크 문제가 원인일 수 있습니다.

테스트를 위해 프로덕션 접근 제어를 우회하거나 상태를 변경하는 요청을 보내지 마세요.

3. 데이터베이스 처리 시간과 잠금 대기 조사

사용 중인 데이터베이스 플랫폼의 운영 지침에 따라 데이터베이스의 느린 쿼리 및 잠금 대기 진단 기능을 활성화하거나 결과를 확인하세요. 현재 활성화된 게이트웨이 타임아웃에 근접하거나 이를 초과하여 실행되는 쿼리를 찾습니다.

인덱스 누락, 비효율적인 조인 또는 필터, 테이블 증가, 잠금 경합을 확인하세요. 측정된 병목을 실제로 해결한다는 점을 확인한 후에만 쿼리를 최적화하거나, 처리할 데이터를 줄이거나, 인덱스를 추가하세요. 스키마 또는 인덱스 변경은 리소스를 사용하고 동시 작업에 영향을 줄 수 있으므로 데이터베이스 담당자와 조율하세요.

빠르게 완료되어야 하는 쿼리를 숨기기 위해 타임아웃을 늘리지 마세요.

4. 백엔드 용량과 대기열 확인

장애가 발생한 동안 애플리케이션, 웹 서버 및 시스템 메트릭에서 워커 고갈, 대기 중인 요청, 데이터베이스 연결 제한, CPU 또는 메모리 압박 및 기타 리소스 제약을 확인하세요.

요청이 용량을 기다리고 있다면 타임아웃을 늘리기 전에 해당 병목을 해결하세요. 용량 또는 프로세스 설정을 변경하면 서비스 안정성에 영향을 줄 수 있으므로, 적용 가능한 운영 권한 및 변경 절차에 따라 변경하세요.

5. 장시간 실행 작업을 백그라운드 작업으로 전환

가져오기, 내보내기, 보고서 생성, 이메일 처리 및 이와 유사한 작업에는 애플리케이션이 지원하는 경우 백그라운드 작업을 사용하세요. 초기 요청은 작업을 시작하거나 대기열에 넣고, 별도의 상태 화면 또는 알림이 진행 상황과 완료 여부를 알려야 합니다.

이렇게 하면 전체 작업 동안 브라우저 연결, 게이트웨이 워커 및 애플리케이션 요청을 계속 열어 둘 필요가 없습니다. 이 방식을 사용하기 전에 작업에 적절한 재시도 및 중복 제출 처리 기능이 있는지 확인하세요.

6. Nginx 타임아웃 설정을 신중하게 검토

Nginx가 게이트웨이라면 관련 server 또는 location 블록에서 적용되는 proxy_read_timeout 및 proxy_connect_timeout 설정을 검토하세요. 변경하기 전에 어느 계층이 타임아웃을 적용하는지 확인합니다.

작업에 더 오랜 시간이 걸릴 것으로 예상되고 백엔드가 정상이며 추가적인 연결 및 워커 사용량을 감당할 수 있을 때만 타임아웃을 늘리세요. 설정 변경에는 적절한 권한이 필요합니다. 변경 사항을 저장한 후 설정을 검증하고, 일반적인 배포 절차에 따라 Nginx를 reload한 다음 이전에 실패한 작업을 다시 실행하세요. 계획되지 않은 변경 중에는 서비스 reload와 읽기 전용 진단을 함께 수행하지 마세요.

7. Apache 프록시 설정 검토

mod_proxy를 사용하는 Apache에서는 적용되는 Timeout 및 ProxyTimeout 설정을 검토하세요. 대용량 업로드가 관련된 경우에는 관련 mod_reqtimeout 동작도 확인합니다.

가능한 경우 영향을 받는 경로 또는 작업에 대해 가장 범위가 좁고 안전한 변경을 적용하고, 권한과 롤백 계획을 마련하세요. 동일한 요청을 사용하여 다시 테스트하고, 더 긴 대기로 인해 워커나 연결이 고갈되지 않는지 확인합니다.

8. CDN 및 로드 밸런서 동작 확인

사이트에서 Cloudflare 또는 다른 CDN이나 로드 밸런서를 사용하는 경우 해당 서비스의 게이트웨이 타임아웃, 오리진 라우팅, 상태 및 요금제 수준 설정을 검토하세요. 사용 가능한 설정으로는 늘릴 수 없는 제한을 중간 계층에서 적용할 수 있습니다.

오리진이 해당 제한보다 더 긴 시간을 필요로 한다면 더 긴 브라우저 요청에 의존하지 말고 작업을 최적화하거나 비동기 처리로 전환하세요.

9. 느린 서드파티 호출 분리

각 외부 API 또는 webhook 호출을 별도로 측정하세요. 지원되는 경우 의존 서비스에 더 짧은 내부 타임아웃을 설정하고, 실패를 명시적으로 처리하며, 작업을 나중에 완료할 수 있다면 대기 중 또는 재시도 가능한 상태를 반환하세요.

불안정한 의존 서비스가 전체 게이트웨이 타임아웃을 소모하도록 두지 마세요. 자동 재시도 동작을 추가하기 전에 재시도 횟수가 제한되어 있고 안전한지 확인하세요.

10. 수정 사항 검증

이전에 실패한 정확한 페이지 작업 또는 요청을 다시 실행하세요. 활성 게이트웨이 타임아웃 안에 완료되는지 확인하고, 이후 로그를 검사하여 백엔드에 중단된 작업, 중복 작업 또는 비정상적으로 오래 실행되는 작업이 쌓이지 않는지 확인합니다. 백엔드에 직접 요청하는 것뿐 아니라 전체 프로덕션 경로를 통해 테스트하세요.

예방 및 해결 확인 방법

• 가져오기, 내보내기, 보고서 생성, 이메일 처리 및 일반적인 페이지 요청보다 오래 걸릴 수 있는 작업에는 백그라운드 작업을 사용하세요.
• 데이터가 증가함에 따라 자주 타임아웃되는 페이지와 관련된 데이터베이스 작업의 인덱스 및 쿼리 플랜을 검토하세요.
• 요청 시간, 대기열 시간, 데이터베이스 시간, 워커 사용량 및 의존 서비스 시간을 별도로 모니터링하세요.
• 가장 느리지만 정상적인 작업을 기준으로 프록시 및 애플리케이션 타임아웃을 신중하게 설정하되, 서드파티 의존 서비스 타임아웃은 제한된 범위로 유지하세요.
• 오리진에만 요청하지 말고 CDN 또는 로드 밸런서를 포함한 전체 프로덕션 경로를 통해 중요한 작업을 테스트하세요.
• 게이트웨이 타임아웃으로 인해 중복 작업이나 트랜잭션이 생성되지 않도록 재시도와 반복 제출을 안전하게 설계하세요.
• 변경 후 타임아웃이 발생했던 정확한 작업을 다시 실행하고, 불필요한 대기 작업이 쌓이지 않은 상태로 완료되는지 확인하세요.

자주 묻는 질문