# 맞춤형 오류 페이지

Source: https://support.kapsulehost.com/ko-kr/site-error-pages

커스텀 오류 페이지는 서버의 기본 화면을 여러분의 브랜드가 담긴 HTML로 대체하면서도 실제 오류 상태는 그대로 유지하여 검색 엔진이 여전히 진짜 404를 보도록 합니다. 이 가이드에서는 지원되는 각 코드에 페이지를 추가하는 방법, 안전을 위해 제거되는 요소, 확인 배지가 작동하는 방식을 다룹니다.

## KPanel에서 오류 페이지의 위치

1. [KPanel](https://kpanel.kapsulehost.com)에 로그인합니다.
2. 왼쪽 사이드바에서 **웹사이트**를 클릭한 다음 사이트를 클릭합니다.
3. 사이트의 왼쪽 메뉴에서 **설정**를 열고 **오류 페이지**를 클릭합니다.

직접 주소는 `/websites/<site-id>/error-pages`입니다.

![KPanel에서 사이트의 커스텀 오류 페이지](https://support.kapsulehost.com/help/screenshots/site-error-pages.89c17e2d.webp)

## 왜 신경 써야 할까요

기본 서버 오류 페이지는 막다른 길입니다. 브랜드도 없고, 내비게이션도 없고, 설명도 없어서 그 페이지에 도착한 방문자는 대개 그냥 떠나버립니다.

커스텀 페이지는 이를 사이트로 되돌아오는 경로로 바꿔줍니다. 여러분의 로고, 여러분의 서체, 여러분의 목소리로 쓴 한 문장, 그리고 홈이나 검색창으로 가는 링크를 담을 수 있습니다. 규모가 큰 사이트에서는 오타가 난 URL이나 오래된 URL이 꾸준히 트래픽을 발생시키므로, 404 페이지는 여러분이 만들 수 있는 가장 값싼 복구 수단입니다.

## 지원되는 코드

8개의 코드에 대해 커스텀 페이지를 설정할 수 있으며, 코드당 하나의 페이지가 가능합니다:

| 코드 | 의미 | 일반적인 원인 |
|---|---|---|
| 400 | 잘못된 요청 | 잘못된 형식의 요청 |
| 401 | Unauthorized | 인증이 필요하거나 인증 실패 |
| 403 | Forbidden | 접근 규칙이 요청을 차단함 |
| 404 | 찾을 수 없음 | 해당 URL에 아무것도 존재하지 않음 |
| 500 | 내부 서버 오류 | 애플리케이션이 실패함 |
| 502 | 잘못된 게이트웨이 | 애플리케이션이 올바르게 응답하지 않음 |
| 503 | 서비스를 사용할 수 없음 | 애플리케이션이 다운되었거나 과부하 상태임 |
| 504 | 게이트웨이 시간 초과 | 애플리케이션이 시간을 너무 오래 끎 |

404부터 시작하세요. 이것이 단연 가장 흔하며, 방문자가 오류가 아니라 일반적인 탐색 중에 마주치는 유일한 코드입니다.

5xx 계열도 그다음으로 해둘 가치가 있습니다. 여러분의 최악의 날에 사람들이 보게 되는 페이지이기 때문입니다. 문제가 생겼다고 침착하게 알려주고 이메일 주소를 제공하는 브랜드 페이지가, 텅 빈 서버 오류 화면보다 훨씬 낫습니다.

## 페이지 추가하기

1. **오류 페이지 추가**를 클릭합니다.
2. 드롭다운에서 오류 코드를 선택합니다. 이미 사용 중인 코드는 목록에 표시되지 않습니다.
3. **HTML 본문** 필드의 샘플 HTML을 여러분의 HTML로 교체합니다.
4. **오류 페이지 추가**를 클릭합니다.

편집기는 작동하는 404 문서로 시작하며 여기서 수정해 나갈 수 있으므로, 빠르게 깔끔한 결과물을 원한다면 합리적인 출발점이 됩니다.

## HTML 작성하기

doctype으로 시작하는 완전한 HTML 문서를 제공하세요. 있는 그대로 제공되므로 그 자체로 완결되어야 합니다.

안전을 위해 일부 HTML은 저장되기 전에 제거됩니다:

- `<script>` 태그
- `onclick`와 같은 인라인 이벤트 핸들러
- iframe
- 원격 스타일시트

무언가 제거되었다면 저장 후 경고가 표시됩니다.

> **Warning:** 원격 스타일시트는 제거되므로 오류 페이지는 사이트의 메인 CSS 파일을 불러올 수 없습니다. 인라인 CSS나 문서 head의 `<style>` 블록으로 스타일을 지정하세요. 이는 의도된 설계입니다. 오류 페이지는 사이트의 나머지 부분이 고장 났을 때도 렌더링되어야 하는데, 실패 중인 서버에서 자산을 가져오는 데 의존하는 페이지는 하필 가장 안 좋은 순간에 스타일 없는 텍스트로 렌더링되고 말 것이기 때문입니다.

실용적인 조언:

- **작고 자체 완결적으로 유지하세요.** 모든 것을 인라인으로 넣으세요. 외부 이미지는 피하세요. 페이지 목록에는 각 페이지의 용량이 KB 단위로 표시됩니다.
- **무슨 일이 일어났는지 평범한 말로 설명하세요.** "찾을 수 없음"보다 "해당 페이지를 찾을 수 없습니다"가 낫습니다.
- **앞으로 나아갈 방법을 제시하세요.** 홈으로 가는 링크, 주요 섹션으로 가는 링크, 또는 검색창을 넣으세요.
- 방문자가 사이트를 이용해 여러분에게 연락할 수 없으므로, 5xx 페이지에는 **연락 경로를 포함하세요**.
- **리디렉션 용도로 사용하지 마세요.** URL이 이동했다면 대신 제대로 리디렉션하세요. [사이트 리디렉션](https://support.kapsulehost.com/ko-kr/site-redirects)을 참고하세요.

## 상태 코드는 그대로 유지됩니다

커스텀 페이지는 200이 아니라 실제 오류 상태와 함께 제공됩니다. 404는 클라이언트에게 전달될 때까지 끝까지 404로 남습니다.

이는 보이는 것보다 더 중요합니다. 200으로 반환되는 브랜드 페이지는 소프트 404가 됩니다. 검색 엔진은 이를 실제 페이지로 색인하고, 분석 도구는 이를 성공적인 조회로 집계하며, 깨진 링크는 어떤 도구로도 발견되지 않습니다. KapsuleHost는 실제 상태를 유지하기 때문에 이 모든 것이 올바르게 계속 작동합니다.

## 상태 배지 읽는 법

**Status** 열은 실제로 확인할 수 있었던 내용을 보여주며, 그 한계에 대해 의도적으로 정직하게 표시합니다.

| 배지 | 의미 |
|---|---|
| 확인됨: 브랜드 페이지 제공(실제 404) | 외부에서 강제로 404를 발생시켰고 올바른 상태와 함께 여러분의 페이지를 받았습니다 |
| 구성됨(외부 테스트 미실시) | 페이지가 적용되어 있습니다. 해당 코드는 외부에서 임의로 발생시킬 수 없습니다 |
| 아직 확인되지 않음 | 아직 검사가 실행되지 않았습니다 |
| 적용됨, 실시간 테스트 결과 불확실 | 점검 결과 정상적인 404가 아닌 다른 응답을 받았으며, 종종 리디렉션이 가로챈 경우입니다 |
| 404는 받았지만 브랜드 페이지는 제공되지 않음 | 규칙은 적용되어 있지만 여러분의 페이지가 반환되지 않았습니다. 다시 저장해 보세요 |

외부에서 강제로 발생시킬 수 있는 것은 404뿐입니다. 존재하지 않는 URL을 요청하면 안정적으로 404가 발생하지만, 정상적으로 작동하는 서버에서 서버를 망가뜨리지 않고 진짜 500을 임의로 발생시킬 방법은 없습니다. 그래서 다른 코드들은 실제로 일어나지 않은 확인을 주장하는 대신 **구성됨**으로 표시됩니다. 실제로 오류가 발생하면 이 코드들도 여전히 정상적으로 제공됩니다.

서버의 다른 구성이 동일한 도메인을 사용한다고 주장하는 경고가 표시될 수도 있습니다. 이 문제가 해결되기 전까지는 오류 페이지가 적용되지 않을 수 있습니다. 이런 경우를 보게 되면 지원팀에 문의하세요.

## 실제로 오류가 발생하는 사이트 문제 해결하기

더 보기 좋은 페이지를 원해서가 아니라 사이트가 실제로 오류를 발생시키고 있어서 이 페이지를 보고 있다면, 상단 배너에 있는 **Troubleshoot with Kora** 버튼이라는 지름길이 있습니다.

이 버튼은 KPanel 내부의 어시스턴트인 Kora에게 이 사이트의 오류 로그와 최근 실패 기록을 읽고 가능성 있는 원인과 해결 방법을 알려달라고 요청합니다. 원본 로그를 직접 읽는 것보다 훨씬 빠른 첫 단계입니다.

기본적인 성능 현황은 [사이트 성능 및 APM](https://support.kapsulehost.com/ko-kr/site-performance)을, 시간에 따른 오류율은 [사이트 트래픽 분석](https://support.kapsulehost.com/ko-kr/site-analytics)을 참고하세요.

## 편집 및 삭제

각 행에는 편집 버튼이 있어 코드는 고정된 채 HTML이 로드된 동일한 편집기가 열리며, 삭제 버튼도 있습니다.

삭제 시 확인을 요청하며 그 결과를 설명합니다. 해당 코드에 해당하는 요청은 서버 기본 페이지로 돌아갑니다.

## 문제 해결

**페이지가 표시되지 않습니다.** 올바른 코드를 트리거하고 있는지 확인하세요. 리디렉션되는 경로는 절대 404에 도달하지 않습니다. 캐시가 개입되지 않도록 시크릿 창에서 실제로 존재하지 않는 URL로 테스트하세요.

**페이지는 표시되지만 스타일이 적용되지 않은 것처럼 보입니다.** 스타일시트가 원격 자산으로 간주되어 제거되었습니다. CSS를 인라인으로 작성하세요.

**추적 스크립트가 누락되었습니다.** 스크립트는 설계상 제거됩니다. 이곳의 커스텀 오류 페이지에서 JavaScript를 실행할 방법은 없습니다.

**모든 코드에 이미 페이지가 있습니다.** 여덟 개 전부 사용 중입니다. 새로 추가하는 대신 기존 페이지를 수정하세요.

**배지에 브랜드 페이지가 제공되지 않았다고 표시됩니다.** 페이지를 다시 저장하세요. 계속 반복되고 도메인 충돌 경고가 나타나지 않았다면 지원 티켓을 열어주세요.

## 관련 페이지

- 404가 애초에 발생하지 않도록 하려면 [사이트 리디렉션](https://support.kapsulehost.com/ko-kr/site-redirects)을 참고하세요.
- 실제로 몇 건의 4xx 및 5xx 응답이 발생하고 있는지 보려면 [사이트 트래픽 분석](https://support.kapsulehost.com/ko-kr/site-analytics)을 참고하세요.
- 설계상 401 응답을 발생시키는 [사이트 비밀번호 보호](https://support.kapsulehost.com/ko-kr/site-password-protect)를 참고하세요.