Nginx로 502 에러 시 사용자 친화적인 유지보수 페이지 보여주기

Maria Kim·2025년 7월 30일

502 Nginx aws ec2

배경

회사 프로젝트에서 배포 플랫폼을 사용하면 502 에러를 볼 일이 거의 없습니다. 하지만 개인 프로젝트에서 직접 서버를 운영하다 보면 서버 재시작이 불가피한 순간들이 있죠.

특히 Next.js 프론트엔드 프로젝트의 경우, 다음과 같은 상황에서 서버를 내려야 합니다:

빌드 및 배포 과정
서버 설정 변경
메모리 부족으로 인한 재시작
EC2 인스턴스 관리

문제는 빌드 시간이 길어질수록 사용자들이 502 Bad Gateway 에러 화면을 오래 봐야 한다는 점입니다. 이때 사용자들은 사이트가 완전히 다운되었다고 생각하고 떠날 수 있습니다.

이 글에서는 nginx 설정만으로 502 에러 시 사용자 친화적인 유지보수 페이지를 보여주는 방법을 알아보겠습니다.

구현 방법

에러 페이지용 HTML 파일 생성

먼저 에러 페이지를 저장할 디렉토리를 생성

sudo mkdir -p /var/www/error-pages

유지보수 페이지 HTML 파일을 생성

sudo nano /var/www/error-pages/502.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Under Maintenance</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f5f5f5;
        }
        .container {
            max-width: 600px;
            margin: 0 auto;
            background: white;
            padding: 40px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        h1 { color: #e74c3c; }
        p { color: #666; font-size: 18px; }
    </style>
</head>
<body>
    <div class="container">
        <h1>🔧 Under Maintenance</h1>
        <p>We're currently performing some updates to improve your experience.</p>
        <p><strong>Please try again later.</strong></p>
        <p>We apologize for any inconvenience.</p>
    </div>
</body>
</html>

Nginx 설정 수정

nginx 설정 파일을 편집

cd /etc/nginx/sites-enabled 
sudo vim default

기존 server 블록에 다음 설정을 추가

server {
    listen 80;
    server_name domain.com;
    
    # 백엔드 서버
    location /api {
        proxy_pass http://your-backend-ec2-ip;
    }
    
    # 프론트엔드 서버
    location / {
        proxy_pass http://your-frontend-ec2-ip;
        
        # 코드 추가하기!!! 502 핸들링
        proxy_intercept_errors on;
        error_page 502 /502.html;
    }
    
    # 코드 추가하기!!! 유지보수 페이지 전달
    location = /502.html {
        root /var/www/error-pages;
        internal;
    }
    
}