Однажды я был маленьким и любил специально искать запрещенку то, что обычные юзвери не должны увидеть никогда - страницы ошибок, забытые файлики в проде, пасхалки в коде. Потом время как-то незаметно ускорилось, за забытыми файликами в прод билде приходится уже самому приглядывать, но уже с “той стороны” (а это уже совсем не то удовольствие), пасхалки в коде сам раскладываешь чаще чем находишь - ну, такое. Но вот тайная любовь к страницам ошибок не угасла со временем.

Если у тебя тоже, %USERNAME%, что-то внутри начинает грустить, глядя на белый экран с текстом “Not Found.*Nginx”, то знай - ты не один. Сейчас мы разберём, как прикрутить к ним весёлые обои, от простого до Kubernetes.

Шаг номер ноль - а что, собственно, показываем?

И это хороший вопрос. Если твой проект продуктовый, есть штатные дизайнеры и всякие там фронтендеры - жира, таска, “сделайте красиво” и они сами там разберутся (вообще - нет, но это история не об этом).

Сперва надо определиться с тем, что именно будем показывать. Окей, гугл, “404 error page design template %CURRENT_YEAR%” - что-нибудь да найдётся. Особенно если пойти дальше пятой страницы, то найдётся что-то, что можно адаптировать с адекватными трудозатратами. Можно поискать на github по тегам - там тоже найдется всякого, но будь готов к тому, что оно будет трех-пяти-восьмилетней давности без обновлений, с запашком, но мы и не такое видали.

Главное, держи в уме золотое правило - чтоб не было проблем в дальнейшем, все должно уместиться в одну html страницу. Да, она, возможно, будет тяжелее чем хотелось бы, но помни, что тяжесть - это хорошо. Тяжесть - это надёжно. Даже если она не выстрелит… Если у неё будут внешние ассеты - ты намучаешься с base URL. Даже если сделать загрузку ассетов с CDN - вспомни сам или тебе напомнят про GDPR. Оно тебе не надо, всё в одну страницу, и точка.

Также не пренебрегай SEO - и в HTTP заголовках ответа, и в meta тегах оставляй пометку “не индексировать, не архивировать, не бухтеть” (<meta name="robots" content="nofollow,noarchive,noindex,ne-buhti"> / X-Robots-Tag: noindex, nofollow, nosnippet, noarchive).

Дружим с нашим сервером

Не удивлюсь, если у тебя там Nginx. Или Caddy. Или ты старовер из племени Апачей, или поклонник демона Lighttpd - не важно, но давай остановимся на первых двух.

Создавай столько страниц ошибок, сколько тебе надо - простая копипаста, с заменой “Not Found” на “Forbidden” и т.д., сохраняй все в файлы, имена которых соответствуют HTTP коду, складируй всё в /usr/share/error-pages. Для nginx читаешь тут, пишешь что-то такое:

server {
  listen      80;
  server_name localhost;

  error_page 401 /_error-pages/401.html;
  error_page 403 /_error-pages/403.html;
  error_page 404 /_error-pages/404.html;
  error_page 500 /_error-pages/500.html;
  error_page 502 /_error-pages/502.html;
  error_page 503 /_error-pages/503.html;

  location ^~ /_error-pages/ {
    internal;
    root /usr/share/error-pages;
  }

  location / {
    root  /usr/share/nginx/html;
    index index.html index.htm;
  }
}

Для Caddy примерно такое:

:80 {
    root * /usr/share/caddy
    file_server

    handle_errors {
        root * /usr/share/error-pages
        rewrite * /{err.status_code}.html
        file_server
    }
}

Говоришь демону перечитать конфиг или даже перезапуститься и тыкаешь в несуществующую страницу. Красота!

А потом мы хотим в Docker

Да в чем проблема-то? Конфиг уже есть, набор файлов - тоже, пилим докерфайлы:

FROM docker.io/library/nginx:1.29-alpine

COPY --chown=nginx ./nginx.conf /etc/nginx/conf.d/default.conf

# copy prebuilt error pages from the "builder" image
# (instead of `ghost`, you can use any other template)
COPY --chown=nginx \
  ./error-pages \
  /opt/html/ghost /usr/share/nginx/errorpages/_error-pages

Или

FROM docker.io/library/caddy:2.11-alpine

COPY --chown=root ./Caddyfile /etc/caddy/Caddyfile

COPY --chown=root \
     ./error-pages \
     /opt/html/ghost /usr/share/errorpages

Собираем, пушим, разворачиваем где надо, радуемся. Но потом, приходит понимание, что есть возможность вместо того, чтобы всюду тащить свои страницы ошибок, мы можем сделать гораздо интереснее и заюзать…

Upstream

На этом месте инженерная мысль уже полетела. Если у тебя есть какой-никакой intranet, почему бы нам просто не поднять отдельного HTTP демона, который бы раздавал эти самые страницы ошибок. А на всех остальных серверах вместо чтения контента страниц ошибок напрямую со своего диска - “читать” их с этого error-pages-нутого сервера? Централизация!

Для отказоустойчивости можешь реплицировать error-pages демонов, поднять балансировку трафика, прикрутить мониторинг, и обязательно чтоб где-нибудь был RAFT. Шучу. Можно без RAFT.

Это просто как опция, которую нужно рассмотреть, и она нам очень поможет в понимании следующего слоя нашего погружения. Сейчас мы рассматриваем её без оглядки на какие-либо оркестраторы или инфраструктурные паттерны.

Плюс этого подхода в том, что мы имеем один источник истины, отвечающий за контент страниц ошибок. Нашли опечатку в тексте страниц или надо добавить ещё один код? Не бегаем всюду, не занимаемся редеплоем - а просто правим в одном месте:

server {
    listen 80;
    server_name my.public.domain;
    proxy_intercept_errors on;
    error_page 400 401 403 404 405 408 409 410 429 500 502 503 504 @error_proxy;

    location @error_proxy {
        internal;
        proxy_pass http://10.0.0.1/$status.html; # твой error-pages сервер
    }

    # ...
}

Аналогично для Caddy:

my.public.domain {
    handle_errors {
        rewrite * /{err.status_code}.html
        reverse_proxy 10.0.0.1 {
            header_up Host {upstream_hostport}

            @ok status 200
            handle_response @ok {
                copy_response_headers
                copy_response {err.status_code}
            }
        }
    }

    # ...
}

Прикрутили, настроили, поигрались - классно. Но что там на счет…

Kubernetes

Как раз логику upsteam-подхода и используют не редко (хотел сказать “почти всегда”, но не хочу быть голословным) в этом звере. ingress-nginx (кстати, с недавних пор он deprecated, но, надеюсь, что он вернется), Traefik, Caddy, Envoy как раз по этой схеме или работают, или их можно убедить так работать. Называются подходы по разному - где это явно как проксирование описано, где-то в виде middleware, но суть та же самая. Приходит запрос, демон его проксирует в целевой под/сервис, если в ответ прилетел код ошибки - проверяет “а мы должны как-то по особенному это обработать, или не?”, и есди “да” - то бежит к нужному демону за контентом, возвращая его.

Очень важный момент - нужно понять и принять, что “кастомизация” реального ответа от сервиса, куда был проксирован запрос, и обслуживание просто 404й ошибки (например - запрос домена, которого нет) - это 2 разные цепочки обработки запроса. Прям совсем разные. Даже не пытайтесь мыслить так, как будто это один и тот же случай, просто входные параметры разные, и обрабатывать их надо тоже отдельно.

Если я начну тут приводить примеры kubectl команд, разговаривая с вами на YAML-ском - вы быстро утомитесь, да и должна же быть задачка на дом. Спойлер - я подготовил и шпаргалки к этой домашке, и о них в следующей главе, под названием…

Автоматизируй это

Конечно, вы можете взять ИИ и… И он, кстати, будет вас время от времени приводить к уже готовому проекту, что решает эту очень нишевую задачу, который ваш покорный написал лет так 6 назад. Просто можете пользоваться, вот ссылка на github - tarampampam/error-pages. Намедни выпустил довольно большой мажорный релиз, снабдил helm-чартом и реализовал все хотелки, что копил в голове крайние несколько лет.

Там не мало всего понаделано - и разные built-in шаблоны, и работа с заголовками в зависимости от ingress контртоллера, и gzip-сжатие контента, и различные форматы ответов, healthcheck, локализации, темные темы (обожаю темные темы), и бла-бла-бла. Если чего-то будет не хватать - вы черканите в issue, потрещим там.

Вместо заключения

Пошарьтесь по 404s.design - там есть очень интересные штуки. Если вы думаете, что излишне заморочились, когда прикрутили оригинальные страницы ошибок - то прекращайте так думать, ведь они имеют значение когда что-то пошло не так. И в этот момент у вас есть редкий шанс не просто сообщить пользователю “ну, не получилось”, а сказать это по-человечески. С характером. С настроением. Иногда даже так, что он закроет вкладку не с раздражением, а с лёгкой улыбкой.

Ну и, будем честны, это ещё один способ оставить маленькую пасхалку для таких же больных, чтобы, встретившись в одной клинике - точно было бы что обсудить.

p.s. Про очепятки - в личку, если вам удобно. Аналогично про хабы - может лишний указал, или наоборот - скажите, поправлю.