Паспорт сервера: одна страница, которая заменяет память админа

MAATRIX

Новый человек в команде смотрит на сервер и не понимает, можно ли его перезагружать прямо сейчас, кто держит домен и почему nginx слушает на порту 8443, а не 443. Всё это знал один админ — а он в отпуске, уволился или просто забыл, потому что настраивал сервер полтора года назад. Паспорт сервера — это не документация на пятьдесят страниц, которую никто не читает, а один файл, который отвечает на пять вопросов за тридцать секунд. Ниже — что в нём должно быть, где его хранить и как не дать ему протухнуть.

Чем паспорт отличается от полной документации

Разница не в глубине, а в назначении. Полная документация — это справочник: туда лезут, когда нужно разобраться, как настроен конкретный сервис, какие переменные окружения у приложения, откуда брать ключи API. Такой документ может расти сколько угодно, и чем он подробнее — тем лучше (о том, что стоит вести в полной документации сервера, отдельный разговор — см. документацию сервера).

Паспорт — это другое. Это карточка, которую открывают в панике: сервер лежит, звонит клиент, нужно принять решение за минуту. Или наоборот — спокойно, раз в квартал, когда нужно быстро вспомнить, что вообще происходит на конкретной машине среди десятка других. У паспорта два жёстких требования:

• он умещается на один экран без прокрутки (реально — 40-60 строк markdown или таблица A4);
• его можно прочитать человеку, который видит этот сервер первый раз в жизни, и через две минуты он будет понимать, что можно трогать, а что нет.

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

Проверка на практике простая: дайте паспорт коллеге, который никогда не видел этот сервер, и засеките время до первого правильного действия (например, «где бэкап, чтобы восстановиться»). Если это больше двух минут — паспорт слишком длинный или плохо структурирован.

Что обязательно должно быть в паспорте

Минимальный набор полей, без которого паспорт бесполезен:

Назначение и что на нём работает. Не «веб-сервер», а конкретно: какое приложение, для какого проекта или клиента, какая роль в общей схеме (фронт, база, очередь, VPN-узел). Если сервер выполняет несколько ролей одновременно — это тоже стоит явно пометить, потому что именно такие сервера чаще всего роняют неосторожным перезапуском не той службы.

Кто отвечает. Имя, контакт (телеграм, почта — то, что реально проверяется), и отдельно — кто бэкап-ответственный, если это другой человек. Без привязки к конкретному человеку паспорт превращается в «отвечает команда», а на практике это значит «не отвечает никто».

Критичные зависимости. От чего сервер зависит и что зависит от него. Пример из практики: сервер с приложением ничего не делает без подключения к базе на соседней машине через WireGuard-туннель — если туннель падает, приложение не падает визуально, просто копит ошибки в очереди. Это ровно тот факт, который нужно знать до того, как чинить «зависший» сервер: проблема не в нём.

Расписание бэкапов. Что бэкапится, куда, как часто, и — это часто забывают — когда последний раз проверялось восстановление из бэкапа, а не только факт, что архив создаётся.

Контакты провайдера и доступ к панели. Не логин-пароль (это отдельная история ниже), а сам факт: кто провайдер, где панель управления, есть ли договор поддержки и SLA, куда писать тикет при аварии на стороне хостинга.

Неочевидные особенности конфигурации. Самое ценное и самое часто пропускаемое поле. Про него — отдельная секция ниже.

Вот минимальный шаблон, который можно скопировать и адаптировать:

# Паспорт сервера: app-prod-01

- **Назначение:** бэкенд + очередь задач проекта X (Node.js, BullMQ)
- **Роль:** прод, единственный экземпляр (нет резервного узла на 2026-08)
- **Ответственный:** Иван П., @ivan_tg, дежурство пн-пт
- **Бэкап-ответственный:** Мария С., @maria_tg
- **Провайдер / панель:** MAATRIX, панель — panel.maatrix.io, договор №1234
- **Контакт поддержки провайдера:** support@maatrix.io, тикет-система, ответ ~2ч
- **Критичные зависимости:**
  - PostgreSQL на db-prod-01 (10.0.0.5) через WireGuard-туннель wg0
  - Redis локально, порт 6380 (не 6379 — см. особенности)
  - S3-совместимое хранилище для вложений (MinIO на storage-01)
- **От него зависят:** app-worker-02 (читает из очереди), фронт на CDN
- **Бэкапы:** BorgBackup, ежедневно в 03:00 МСК, хранение 14 дней,
  куда — storage-01:/backups/app-prod-01
  Последняя проверка восстановления: 2026-08-15 (см. журнал ниже)
- **Особенности конфигурации:** см. раздел ниже, файл gotchas.md
- **Дата создания паспорта:** 2026-02-10
- **Последнее обновление:** 2026-08-20, обновил Иван П.

Неочевидные особенности конфигурации — «грабли», которые не видны снаружи

Это поле спасает больше времени, чем все остальные вместе. Речь о решениях, которые в момент настройки казались логичными и о которых через полгода никто не вспомнит, пока не наступит на них снова.

Примеры того, что стоит фиксировать:

• нестандартные порты и почему они нестандартные («Redis на 6380, потому что 6379 занят legacy-сервисом, который нельзя трогать до миграции в Q4»);
• обходные пути и временные решения, которые стали постоянными («cron-задача fix_orphaned_sessions.sh запускается каждый час — это заплатка от бага в старой версии либы, тикет #482, снять после апгрейда»);
• нестандартные права и владельцы файлов, если это принципиально («директория /var/app/uploads принадлежит www-data:www-data, потому что nginx пишет туда напрямую — не менять на root»);
• отключённые проверки или security-исключения с причиной («fail2ban не банит подсеть офиса 203.0.113.0/24 — whitelisted, IP статический»);
• порядок запуска служб, если он важен («приложение падает при старте, если PostgreSQL ещё не готов — есть systemd-юнит с After=postgresql.service, но иногда недостаточно, руками: systemctl restart app через 10 сек после postgresql»).

Формат — обычный список, без попытки объяснить архитектурно правильное решение. Задача не в том, чтобы оправдать костыль, а в том, чтобы следующий человек не потратил два часа на выяснение того, что вы уже знаете за пять секунд. Держите этот список отдельным файлом (gotchas.md рядом с паспортом или прямо в нём отдельным блоком) и дописывайте туда сразу, как только сами наступили на грабли — не «потом занесу», а в моменте, пока контекст свежий.

Где хранить паспорт: не в голове и не в переписке

Три места, где паспорт умирает:

В голове одного человека. Очевидная проблема — человек уходит в отпуск, увольняется, попадает в больницу, и всё знание уходит вместе с ним. Это ровно тот сценарий, который разбирается в статье про возврат контроля после ухода единственного админа — паспорт сервера снижает вероятность такого сценария в разы, потому что критичная информация не завязана на одну память.

В переписке. «Я же писал в чате три месяца назад» — паспорт, размазанный по сообщениям в телеграме или почте, невозможно найти в момент аварии, а поиск по чату с сотней сообщений в час — это ещё пять минут потерянного времени, которых в аварии обычно нет. Переписка годится для обсуждения решения, но не для его фиксации.

В личном ноутбуке или облаке одного человека. Файл на рабочем столе — это голова того же самого человека, просто в текстовом виде. Как только он недоступен — недоступен и паспорт.

Куда стоит: централизованное место, доступное минимум двум-трём людям и не зависящее от одного логина.

• Git-репозиторий (даже приватный, даже без CI) — если команда и так работает в git, это естественное место. Плюс — история изменений бесплатно, видно, кто и когда что поправил.
• Внутренняя wiki (Confluence, Outline, самостоятельно поднятая на VPS BookStack или Wiki.js) — удобно для команд, где не все технари и git — лишний барьер.
• Общий диск с версионированием (Nextcloud на своём сервере, корпоративный Google Workspace) — минимальный порог входа, но версионирование хуже, чем в git.

Важное условие независимо от инструмента: паспорт не должен физически лежать на самом описываемом сервере как единственная копия. Если сервер лежит — паспорт должен быть доступен, а не погребён вместе с ним. Держите копию (или оригинал) вне этого сервера — в репозитории, в wiki, на отдельном сервере документации.

Доступы (пароли, приватные ключи, токены) в паспорт не идут вообще — ни в открытом виде, ни зашифрованными inline. Для них отдельный менеджер секретов (Vaultwarden, HashiCorp Vault, даже просто общая запись в Bitwarden/1Password с ограниченным доступом), а в паспорте — только ссылка «где искать доступ» и кто может его выдать.

Как поддерживать паспорт актуальным

Паспорт, который не обновлялся год, хуже, чем его отсутствие — он создаёт ложную уверенность. Устаревшее «бэкап каждый день в 03:00» страшнее честного «бэкапов нет», потому что во втором случае хотя бы понятно, что проверять.

Рабочие механики, которые реально держат паспорт живым:

Привязка к событию, а не к календарю. Обновление паспорта — обязательный последний шаг любого изменения инфраструктуры: сменили порт, добавили зависимость, поменяли расписание бэкапа — паспорт правится в том же PR/коммите, что и сама смена, а не «потом». Если в команде есть чек-лист на изменения — пункт «обновлён паспорт сервера» в него.

Ревизия по расписанию как страховка. Даже при дисциплине с событиями стоит раз в квартал (можно совместить с еженедельным регламентом обслуживания или отдельным пунктом ежемесячного ТО) сверять паспорт с реальностью: правда ли эта версия ОС, правда ли эти зависимости, работает ли контакт провайдера. Пять минут на сервер, но именно они ловят расхождения, которые накопились незаметно.

Дата и автор последнего обновления — обязательное поле. Если в паспорте нет Последнее обновление: 2026-08-20, невозможно понять, насколько ему можно доверять. Свежая дата — сигнал доверия, дата полугодовой давности — сигнал перепроверить вручную перед тем, как действовать по паспорту.

Один паспорт — один владелец за актуальность. Не «команда следит», а конкретный человек отвечает за то, что поле «ответственный» и «зависимости» не врут. Это не значит, что обновлять может только он — значит, что спросить «почему паспорт устарел» есть с кого.

Проверка при приёмке нового сервера — это уже часть паспорта, а не после. Паспорт логично заводить сразу на этапе ввода сервера в строй, вместе с чек-листом приёмки нового сервера — тогда в паспорт сразу попадают версия ОС, реальная топология сети и первое расписание бэкапов, а не реконструируются задним числом через полгода по логам.

Пример: как паспорт спасает во время реальной аварии

Сценарий, который проверяется на практике чаще, чем хотелось бы: сайт клиента отдаёт 502, дежурный на связи впервые видит этот сервер — предыдущий человек, который его настраивал, в отпуске без связи.

Без паспорта: 20-30 минут уходит на то, чтобы понять топологию — куда смотрит nginx, где база, есть ли балансировщик, какие сервисы вообще должны быть живы. Ещё 10-15 минут — искать доступ к панели хостинга, потому что логин был только у ушедшего в отпуск. Итого — до аварии реально начинают чинить проблему через 30-45 минут после первого сигнала.

С паспортом: за две минуты понятно, что это единственный прод-экземпляр (поле «роль»), что 502 скорее всего от воркера, который зависит от очереди (поле «зависимости»), и что у Redis нестандартный порт, который легко перепутать при ручной проверке (поле «особенности конфигурации»). Доступ к панели провайдера — по ссылке на менеджер секретов, а не по звонку человеку в отпуске. Реальная работа над проблемой начинается на 5-й минуте, а не на 35-й.

Разница — не в героизме дежурного, а в том, что критичная информация была зафиксирована заранее, а не жила в чужой голове.

Частые вопросы