Nginx 사용자 정의 오류 페이지: 사용자 경험 향상
실제 오류를 숨기지 않고 404, 403 및 50x 응답에 유용한 Nginx 사용자 정의 오류 페이지를 구성합니다.
Nginx 사용자 정의 오류 페이지: 사용자 경험 향상
Nginx 사용자 정의 오류 페이지는 원시 오류를 명확한 다음 단계로 전환합니다. 끊어진 링크, 누락된 파일 또는 충돌한 업스트림 앱을 수정하지는 않습니다. 하지만 더 작지만 여전히 가치 있는 일을 합니다: 방문자에게 무슨 일이 일어났는지 평이한 언어로 알려주고 사이트에서 버려진 느낌을 받지 않도록 합니다.
이는 일반적인 실수 상황에서 중요합니다. 누군가 오래된 문서 링크를 따라가 404를 받습니다. 개인 파일 경로가 403을 반환합니다. 배포 중 앱이 재시작되고 Nginx가 잠시 502를 봅니다. 사용자 정의 페이지가 없으면 사용자는 갑작스럽거나 기술적으로 보이는 기본 서버 응답을 볼 수 있습니다. 좋은 정적 페이지가 있으면 사용자는 검색, 돌아가기, 재시도 또는 대기해야 하는지 알 수 있습니다.
최고의 오류 페이지는 지루한 운영 도구입니다. 정적이고, 빠르고, 접근 가능하며, 정직합니다. 모니터링에서 중단을 숨기지 않고, 사용자에게 내부 세부 정보를 노출하지 않습니다.
사람들이 실제로 보는 오류부터 시작하세요
모든 HTTP 상태 코드에 대한 페이지를 디자인할 필요는 없습니다. 일반적인 것부터 시작하세요.
404 Not Found는 사용자 정의할 첫 번째 페이지입니다. 요청된 URL이 파일, 경로 또는 콘텐츠를 반환하는 Nginx 위치와 일치하지 않을 때 나타납니다. 오래된 링크, 이름이 변경된 게시물, 삭제된 문서 페이지 및 수동으로 입력한 URL이 모두 여기로 이어집니다.
유용한 404 페이지는 "해당 페이지를 찾을 수 없습니다."와 같은 내용을 말합니다. 그런 다음 홈페이지, 문서 색인, 제품 영역 또는 검색 페이지로 돌아갈 수 있는 경로를 제공합니다. 사용자를 비난하지 마십시오. URL은 사용자가 클릭하기 훨씬 전에 잘못되었을 수 있습니다.
403 Forbidden은 다릅니다. Nginx가 요청을 이해했지만 제공하지 않습니다. 원인에는 파일 권한, 액세스 규칙, 비활성화된 디렉토리 목록, IP 허용/거부 규칙 또는 인증 요구 사항이 포함됩니다. 403 페이지는 차분하고 짧아야 합니다. 리소스가 비공개이면 그렇게 말하십시오. 사용자가 액세스해야 할 수도 있으면 올바른 로그인 또는 지원 경로를 알려주십시오.
앱 기반 사이트의 경우 50x 오류를 신중하게 처리하십시오:
500 Internal Server Error는 일반적으로 요청을 처리하는 동안 애플리케이션이 실패했음을 의미합니다.502 Bad Gateway는 종종 Nginx가 업스트림 서비스로부터 유효한 응답을 받지 못했음을 의미합니다.503 Service Unavailable은 유지 관리, 과부하 또는 의도적으로 서비스를 사용할 수 없게 하는 경우에 유용합니다.504 Gateway Timeout은 Nginx가 업스트림 응답을 너무 오래 기다렸음을 의미합니다.
SaaS 대시보드 예: 배포 중 앱 프로세스가 다시 시작됩니다. 몇 초 동안 Nginx가 업스트림에 연결할 수 없고 사용자가 502를 봅니다. 사용자 정의 페이지는 "대시보드를 일시적으로 사용할 수 없습니다. 잠시 후 새로고침 해주세요."라고 말할 수 있습니다. 완벽하지는 않지만 기본 게이트웨이 오류보다는 명확합니다.
정적 오류 파일 생성
오류 페이지를 애플리케이션 종속성 체인 외부에 유지하십시오. 데이터베이스가 다운된 경우 500 페이지가 여전히 로드되어야 합니다. Node, Python, Ruby 또는 PHP 앱이 비정상인 경우 Nginx가 여전히 정적 폴백을 제공해야 합니다.
간단한 파일 레이아웃은 다음과 같을 수 있습니다:
/var/www/example.com/public/
index.html
assets/
/var/www/example.com/errors/
404.html
403.html
50x.html
HTML을 가볍게 유지하십시오. 타사 스크립트, 무거운 이미지, 클라이언트 측 앱 번들 및 손상된 백엔드를 호출하는 모든 것을 피하십시오. Nginx가 직접 제공할 수 있다면 작은 CSS 파일은 괜찮습니다.
최소한의 404.html은 다음과 같을 수 있습니다:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>페이지를 찾을 수 없음</title>
</head>
<body>
<main>
<h1>페이지를 찾을 수 없음</h1>
<p>페이지가 이동되었거나 링크가 오래되었을 수 있습니다.</p>
<p><a href="/">홈페이지로 이동</a></p>
</main>
</body>
</html>
그것으로 충분합니다. 사이트에 맞게 스타일을 지정할 수 있지만 메시지와 링크가 장식보다 중요합니다.
error_page로 페이지 연결
Nginx에서 error_page 지시문은 하나 이상의 상태 코드를 URI에 매핑합니다. 기본 서버 블록은 다음과 같습니다:
server {
listen 80;
server_name example.com www.example.com;
root /var/www/example.com/public;
error_page 404 /errors/404.html;
error_page 403 /errors/403.html;
error_page 500 502 503 504 /errors/50x.html;
location /errors/ {
internal;
root /var/www/example.com;
}
location / {
try_files $uri $uri/ =404;
}
}
경로 확인은 사람들을 혼란스럽게 하는 부분입니다. 이 예에서 /errors/ 아래의 요청은 root /var/www/example.com;을 사용하므로 /errors/404.html은 /var/www/example.com/errors/404.html에 매핑됩니다.
internal 지시문은 외부 클라이언트가 일반 URL로 직접 /errors/404.html을 요청할 수 없음을 의미합니다. Nginx는 오류를 처리할 때 내부적으로 계속 제공할 수 있습니다.
구성을 편집한 후 테스트하고 다시 로드하십시오:
sudo nginx -t
sudo systemctl reload nginx
그런 다음 동작을 테스트하십시오:
curl -I http://example.com/definitely-missing-page
curl -s http://example.com/definitely-missing-page | head
본문이 친숙한 HTML이더라도 상태는 여전히 404여야 합니다. 누락된 페이지에 대해 실수로 200 OK를 반환하는 것은 일반적인 실수로, 모니터링과 검색 엔진이 누락된 URL을 실제 페이지로 생각하게 만듭니다.
리버스 프록시 뒤의 사용자 정의 페이지
Nginx가 업스트림 애플리케이션으로 프록시하는 경우 앱이 자체 오류 응답을 반환할 수 있습니다. 기본적으로 프록시된 응답은 일반적으로 클라이언트에 다시 전달됩니다. Nginx가 업스트림 오류 응답을 가로채서 error_page 규칙을 사용하도록 하려면 관련 컨텍스트에서 proxy_intercept_errors를 활성화하십시오.
location /app/ {
proxy_pass http://app_backend;
proxy_intercept_errors on;
error_page 502 503 504 /errors/50x.html;
}
Nginx 문서는 proxy_intercept_errors가 300 이상의 상태 코드를 가진 프록시된 응답에 적용되며, 그런 다음 error_page 처리를 위해 Nginx로 리디렉션될 수 있다고 설명합니다. 실제로는 생각 없이 모든 곳에서 켜지 마십시오.
브라우저 페이지의 경우 502 또는 503을 가로채는 것이 종종 유용합니다. JSON API의 경우 잘못될 수 있습니다. API 클라이언트는 일반적으로 HTML 페이지가 아닌 구조화된 JSON 오류 본문을 기대합니다. 별도의 위치가 필요할 수 있습니다:
location /api/ {
proxy_pass http://api_backend;
proxy_intercept_errors off;
}
location /dashboard/ {
proxy_pass http://app_backend;
proxy_intercept_errors on;
error_page 502 503 504 /errors/50x.html;
}
이러한 분할은 사람을 위한 페이지를 친숙하게 유지하면서 기계가 읽을 수 있는 API 오류를 보존합니다.
올바른 상태 코드 유지
Nginx를 사용하면 error_page로 응답 코드를 변경할 수 있지만, 의도한 경우에만 수행하십시오. 다음은 유효한 구문입니다:
error_page 404 =200 /fallback.html;
대부분의 웹사이트에서 이것은 나쁜 생각입니다. 누락된 페이지는 404로 유지되어야 합니다. 검색 엔진, 가동 시간 확인, 분석 및 사용자 모두 진실의 혜택을 받습니다.
특정 오류를 명명된 위치로 라우팅하거나 503으로 유지 관리 페이지를 반환하는 등 코드를 변경하는 합법적인 경우가 있습니다. 그러나 기본 규칙으로 원래 오류 상태를 유지하십시오.
유지 관리의 경우 명시적으로 할 수 있습니다:
location / {
return 503;
}
error_page 503 /errors/maintenance.html;
location = /errors/maintenance.html {
root /var/www/example.com;
internal;
}
Nginx 앞에 CDN 또는 로드 밸런서를 사용하는 경우 자체 오류 페이지 동작이 있을 수 있음을 기억하십시오. 어떤 계층이 어떤 오류를 소유할지 결정하십시오. 그렇지 않으면 Nginx를 직접 테스트할 때 한 페이지를 보고 CDN 뒤의 사용자는 다른 페이지를 볼 수 있습니다.
사람을 위한 오류 페이지 작성
콘텐츠는 세 가지 질문에 신속하게 답변해야 합니다:
- 무슨 일이 일어났습니까?
- 일시적입니까?
- 다음에 무엇을 할 수 있습니까?
404의 경우 유용한 다음 단계는 검색, 홈페이지, 문서 색인 또는 누락된 페이지가 있어야 하는 경우 지원팀에 문의하는 것입니다. 503의 경우 유용한 지침은 나중에 다시 시도하거나 상태 페이지를 확인하는 것입니다. 403의 경우 해당되는 경우 로그인 또는 액세스 요청 지침을 알려주십시오.
스택 추적, 업스트림 호스트 이름, 파일 시스템 경로, 패키지 버전, 내부 IP, 설명 없는 요청 ID 및 인시던트 세부 정보를 피하십시오. 요청 ID는 지원팀이 사용할 수 있는 경우 유용할 수 있지만 명확하게 레이블을 지정하십시오:
<p>지원팀에 문의하는 경우 이 요청 ID를 포함하십시오: <code>$request_id</code></p>
$request_id와 같은 변수를 삽입하려면 이를 지원하는 구성 패턴이 필요합니다. 정적 HTML 파일은 자체적으로 Nginx 변수를 확장하지 않습니다. 많은 팀이 공개 오류 페이지를 정적으로 유지하고 대신 요청 ID에 대해 로그를 사용합니다.
접근성은 유용성의 일부입니다. 하나의 명확한 h1, 읽기 쉬운 대비, 일반 링크 및 일반 텍스트를 사용하십시오. 유일한 복구 작업을 작은 아이콘이나 스크립트 기반 버튼으로 만들지 마십시오.
의도적으로 페이지 테스트
사용자가 오류 페이지를 찾을 때까지 기다리지 마십시오. 모든 변경 후에 테스트하십시오.
404의 경우:
curl -i https://example.com/no-such-page
403의 경우 제어된 테스트 위치를 만들거나 개인 테스트 파일을 사용하십시오. 오류를 트리거하기 위해 프로덕션 권한을 느슨하게 하지 마십시오.
502 또는 503의 경우 사용할 수 없는 업스트림을 가리키는 위치를 지정하여 스테이징에서 테스트하십시오:
location /broken-upstream-test/ {
proxy_pass http://127.0.0.1:59999;
proxy_intercept_errors on;
error_page 502 503 504 /errors/50x.html;
}
그런 다음 요청하고 상태 코드와 본문을 모두 확인하십시오:
curl -i https://staging.example.com/broken-upstream-test/
또한 로그를 확인하십시오:
sudo tail -f /var/log/nginx/error.log /var/log/nginx/access.log
보기 좋은 오류 페이지는 운영 신호를 지워서는 안 됩니다. 50x 비율이 증가할 때 경고가 계속 작동해야 합니다.
Nginx 사용자 정의 오류 페이지는 실제 사용자 영향이 있는 작은 구성 작업입니다. 404, 403 및 일반적인 50x 오류부터 시작하십시오. Nginx에서 직접 정적 파일을 제공하십시오. 정확한 상태 코드를 유지하십시오. HTML 폴백이 의미 있는 경우에만 proxy_intercept_errors를 사용하십시오. 그런 다음 다른 프로덕션 동작을 테스트하는 것과 같은 방식으로 페이지를 테스트하십시오.