Cloudflare 뒤에서 발생하는 504 Gateway Timeout

이 오류의 의미와 확인 방법

• 오류 페이지에 Cloudflare 브랜드가 표시되며, 일반적인 사이트 오류 레이아웃 대신 Cloudflare Ray ID가 포함되는 경우가 많습니다.
• 일반 페이지는 계속 로드되지만 특정 report, export, upload, API call 또는 bulk action이 실패합니다.
• 동일한 요청을 origin에 직접 테스트하면 응답이 느리거나 timeout이 발생하거나 실패할 수 있습니다.
• origin에 과부하가 걸린 경우 문제는 간헐적으로 발생할 수 있고, Cloudflare가 구성된 origin에 연결하지 못하는 경우에는 일관되게 발생할 수 있습니다.
• 애플리케이션 또는 웹 서버 로그에는 요청이 시작되었지만 client-facing timeout 전에 완료되지 않은 것으로 나타날 수 있습니다.

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

1. origin 응답이 너무 오래 걸립니다. 데이터베이스 query, report, export, upload 또는 기타 동기 작업이 Cloudflare가 기다리는 시간을 초과할 수 있습니다.
2. 요청이 Cloudflare timeout limit에 도달합니다. 적용되는 limit은 요청, account configuration 및 plan에 따라 다릅니다. origin 웹 서버 timeout을 늘려도 Cloudflare의 edge limit은 연장되지 않습니다.
3. Cloudflare가 origin에 안정적으로 연결하지 못합니다. 방화벽 규칙, 네트워크 장애, 잘못된 DNS target, 사용할 수 없는 service 또는 connection saturation으로 인해 제때 응답하지 못할 수 있습니다.
4. 해당 endpoint가 proxy에 적합하지 않습니다. 내부용 또는 특수 목적의 API는 Cloudflare proxy를 통과시키기보다 신중하게 제어되는 DNS-only 설계가 필요할 수 있습니다.
5. SSL/TLS 설정이 origin과 일치하지 않습니다. Full (strict)을 사용하는 경우 origin certificate, hostname 및 certificate validity를 확인하세요. Certificate 문제는 다른 Cloudflare origin 오류를 발생시킬 수도 있으므로 모든 SSL 문제가 504라고 가정하지 말고 정확한 응답을 확인해야 합니다.

해결 방법

1. Cloudflare가 응답을 생성했는지 확인

오류 페이지에서 Cloudflare 브랜드와 Ray ID를 확인한 다음, 애플리케이션의 일반 오류 페이지와 비교하세요. Cloudflare가 페이지를 생성했다면 애플리케이션의 오류 처리만 변경해서는 edge에서 origin으로 연결되는 문제를 해결할 수 없습니다.

2. 범위와 발생 시점을 파악

정확한 hostname과 path, HTTP method, 사용자 작업, 대략적인 시작 시각, 문제가 모든 방문자에게 발생하는지 또는 하나의 작업에만 발생하는지를 기록하세요. 일반 페이지는 정상적으로 작동하면서 report, export 또는 API request만 실패하는지 확인합니다.

하나의 비용이 큰 작업에만 실패가 제한된다면 백엔드 처리 시간이 원인일 가능성이 더 높습니다. 일반적이고 빠른 요청에서도 실패한다면 origin 연결 가능성, capacity 또는 configuration 문제일 가능성이 더 높습니다.

3. origin을 별도로 테스트

필요한 hostname, Host header, TLS 동작, authentication 및 routing을 유지하는 인증된 직접 origin 테스트를 사용하세요. 안전하게 구성하고 origin 접근을 적절히 제한할 수 있다면 임시 DNS-only 테스트 hostname이 유용할 수 있습니다.

• origin에서도 느리거나 실패함: 애플리케이션 로그, database query, worker capacity, upstream dependency, server load 및 connection saturation을 점검하세요.
• origin은 빠르지만 public hostname에서 504가 반환됨: Cloudflare에서 origin으로의 방화벽 접근, DNS, SSL/TLS 설정, proxy status 및 해당 endpoint를 점검하세요.
• 직접 테스트가 실제 요청을 제대로 반영하지 못함: 실패한 요청에 사용된 것과 동일한 authentication, host-based routing, header 및 기타 요구 사항으로 테스트를 반복하세요.

4. 실제로 느린 작업을 수정

report, export, bulk action 또는 기타 장시간 실행되는 작업에서는 모든 작업이 끝날 때까지 하나의 브라우저 요청을 열어 두지 마세요. 작업을 background job으로 전환하고 처리 중 상태를 표시한 다음, polling 또는 완료 알림을 통해 사용자가 결과를 가져오도록 하세요.

또한 database query, application trace, upstream call, queue depth 및 resource usage를 측정하세요. 작업을 측정하지 않고 origin timeout 증가를 주된 해결책으로 삼지 마세요. Cloudflare가 먼저 limit에 도달하면 방문자에게는 여전히 오류가 표시되고, origin은 불필요한 작업을 계속 수행할 수 있습니다.

5. 적용되는 Cloudflare timeout 확인

해당 요청과 plan에 적용되는 timeout을 Cloudflare account 및 관련 documentation에서 확인하세요. 작업 자체는 유효하지만 고정된 limit 안에 완료할 수 없다면, 실질적인 방법은 이를 asynchronous work로 재설계하거나 필요한 timeout을 지원하는 account configuration 및 plan을 사용하는 것입니다(가능한 경우).

6. 문제가 지속될 때 연결 가능성 점검

일반적이고 빠른 요청도 실패한다면 다음을 확인하세요.

• DNS record가 현재 origin address를 가리키는지 확인합니다.
• 필요에 따라 origin firewall이 Cloudflare traffic을 허용하는지 확인하되, 불필요한 service는 노출하지 않습니다.
• 웹 서버가 예상 port에서 listen하고 요청된 hostname을 허용하는지 확인합니다.
• origin에 충분한 capacity가 있으며 connection을 drop하거나 queue에 과도하게 쌓지 않는지 확인합니다.
• 특히 Full (strict)을 사용하는 경우 SSL/TLS mode가 origin certificate, hostname 및 certificate validity와 일치하는지 확인합니다.
• 해당 record가 proxy를 사용하도록 의도된 것인지, 아니면 제어된 DNS-only configuration으로 제공되어야 하는지 확인합니다.

DNS, 방화벽, SSL/TLS 또는 proxy를 변경할 때는 적절한 authorization과 rollback plan을 갖추세요. 원인과 결과를 명확히 유지할 수 있도록 중요한 변경을 수행할 때마다 정확히 실패한 endpoint를 다시 테스트하세요.

7. 유용한 증거와 함께 에스컬레이션

origin이 정상이고 동등한 직접 테스트에서 빠르게 응답한다면 Ray ID, timestamp와 time zone, hostname, path, request method, 영향을 받은 Cloudflare zone 및 직접 테스트 결과를 수집하세요. edge에서 origin으로 연결되는 동작을 조사할 수 있도록 이 정보를 Cloudflare account administrator 또는 support contact에게 전달하세요.

예방 및 해결 확인 방법

• Cloudflare 기준 가용성과 별도로 origin response time 및 전체 request duration을 측정합니다.
• 예측 가능한 장시간 실행 report, export, upload 및 bulk operation은 진행률 또는 완료 상태를 표시하는 background job으로 처리합니다.
• 사용자가 timeout을 겪기 전에 증가하는 origin latency, connection failure, resource saturation 및 queue depth를 감지하도록 알림을 설정합니다.
• DNS record, origin firewall rule 및 Cloudflare traffic allowlist를 change control 하에 관리합니다.
• Full (strict)을 사용하는 경우 origin certificate validity 및 hostname coverage를 모니터링하고, 배포 전에 SSL/TLS 변경을 검토합니다.
• Cloudflare proxy를 사용하도록 의도된 endpoint와 제어된 DNS-only 설계가 필요한 endpoint를 문서화합니다.
• infrastructure, DNS, 방화벽, certificate 또는 proxy를 변경한 후 대표적인 origin 연결을 다시 테스트합니다.

자주 묻는 질문