[Troubleshooting] 504 Gateway Timeout 에러 완벽 방어: 파이썬(Python) Celery와 Redis 기반 비동기 백그라운드 아키텍처

8월 06, 2026

"어드민(Admin) 페이지에서 10만 건짜리 매출 데이터 엑셀 다운로드 버튼을 누르면, 화면이 30초 동안 멈춰있다가 결국 하얀 바탕에 '504 Gateway Timeout' 에러만 뜹니다."

엔터프라이즈 B2B 솔루션이나 사내 인트라넷을 개발하는 백엔드 팀이 가장 뼈아프게 마주하는 시스템의 붕괴점이다. 초보 개발자들은 이 에러를 보면 Nginx 프록시 설정 파일(nginx.conf)을 열어서 proxy_read_timeout 값을 30초에서 300초로 무식하게 늘려버린다. 하지만 이는 시한폭탄의 타이머를 늦췄을 뿐, 여러 명의 직원이 동시에 다운로드를 누르면 결국 웹 서버 워커(Worker)가 모두 고갈되어 사이트 전체가 마비되는 대참사로 이어진다.

본 가이드에서는 클라이언트를 기다리게 만드는 무능한 동기식(Synchronous) 설계의 한계를 해체하고, 메시지 브로커(Message Broker)를 활용하여 작업을 백그라운드로 우아하게 던져버리는 비동기(Asynchronous) 아키텍처를 단호하게 제시한다.

1단계: 핵심 원인 분석 (동기식 HTTP 통신의 족쇄)

웹 브라우저와 Nginx(또는 AWS ALB) 간의 HTTP 통신은 철저히 동기식이다. 사용자가 요청을 보내면, 응답이 올 때까지 브라우저와 프록시 서버는 연결 통로(Connection)를 잡고 하염없이 기다린다. 만약 DB에서 10만 건의 데이터를 조회하고 엑셀로 변환하는 데 60초가 걸린다면? 30초를 한계치로 설정해 둔 Nginx는 "이 서버는 죽었다"고 판단하고 연결을 강제로 끊어버린 뒤 클라이언트에게 504 에러를 던지는 것이다.

2단계: 완벽한 해결책 - Celery + Redis 비동기 아키텍처

해결책은 무거운 작업을 웹 서버(Django, FastAPI 등)가 직접 처리하지 않게 분리(Decoupling)하는 것이다. 웹 서버는 "작업 접수 완료!"라는 짧은 대답만 0.1초 만에 유저에게 던져주고(200 OK), 진짜 무거운 엑셀 변환 작업은 뒤에 숨어있는 Celery 워커(Worker)에게 넘겨버려야 한다. 이때 웹 서버와 Celery 사이에서 작업 지시서를 안전하게 전달해 주는 우체국 역할이 바로 Redis(메시지 브로커)다.

# 비동기 처리를 위한 Python Celery 아키텍처 (tasks.py)
from celery import Celery
import time
import pandas as pd

# Redis를 메시지 브로커 및 결과 저장소(Backend)로 설정
app = Celery('excel_tasks', broker='redis://localhost:6379/0', backend='redis://localhost:6379/1')

@app.task
def generate_massive_excel(user_id, date_range):
    print(f"[{user_id}] 대용량 엑셀 백그라운드 생성 시작...")
    
    # 웹 서버의 응답과는 독립적으로 무거운 DB I/O 작업 수행 (예: 60초 소요)
    time.sleep(60) 
    
    # 엑셀 파일 생성 후 AWS S3 등에 업로드
    file_url = "https://s3.aws.com/your-bucket/massive_report.xlsx"
    
    print("엑셀 생성 완료. 다운로드 링크 반환.")
    return file_url

3단계: 유저 경험(UX)의 완성 - 폴링(Polling) 또는 웹소켓(WebSocket)

이제 유저는 다운로드 버튼을 누르면 대기 화면(Spinner)을 보게 된다. 클라이언트(브라우저)는 3초에 한 번씩 서버에 "엑셀 다 만들어졌어?"라고 가볍게 묻고(Polling), Celery 작업이 끝났다는 신호(file_url)가 떨어지면 그때 다운로드를 띄워주면 된다. 웹 서버의 커넥션은 0.1초 만에 맺고 끊어지므로, 서버 자원의 고갈이나 504 Timeout 에러는 우주에서 영원히 소멸된다.

아키텍트의 시선 (Insight)

504 Gateway Timeout은 서버가 죽었다는 뜻이 아니다. 당신의 시스템 아키텍처가 동기식의 늪에 빠져 트래픽의 유연성을 상실했다는 처절한 비명이다. 타임아웃 시간을 늘려 시스템을 혹사시키는 1차원적 타협을 멈춰라. Celery와 Redis를 도입하여 작업을 위임하는 순간, 당신의 서버는 어떤 무거운 요청에도 즉각적으로 응답하며 무너지지 않는 엔터프라이즈급 안정성을 손에 쥐게 될 것이다.

이 블로그 검색

HagoCube | 디지털 생산성 아키텍트