Документируем чужую систему: минимум, который спасёт следующего человека

MAATRIX

Вы разобрались в чужом сервере: прошли по сервисам, конфигам, cron-задачам, проверили бэкапы. Осталось сделать последний шаг — записать то, что узнали, для человека, который придёт после вас. И вот тут чаще всего всё останавливается: полноценная документация кажется отдельным большим проектом, на который нет ни времени, ни сил после недель разбора, и в итоге не пишется ничего. Хорошая новость в том, что вам не нужен wiki-раздел на сорок страниц. Нужен один файл с десятком пунктов, который вы реально успеете написать за час — и который спасёт следующего человека от того ада, через который только что прошли вы сами.

Это не карта за неделю и не полная документация — это то, что остаётся после вас

Стоит сразу развести два разных документа, которые легко перепутать.

Первый — это ваша рабочая карта разбора: подробный процесс исследования незнакомой системы, с инвентаризацией процессов, портов, cron-задач, поиском следов в bash history и git log. Такой методичный проход по чужому серверу описан отдельно — с чего начинать разбор незнакомой машины. Это ваш инструмент, ваш процесс, и результат этого процесса может занимать десятки страниц заметок, черновиков, вопросов без ответа.

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

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

Принцип «одна страница лучше, чем ничего»

Главная причина, по которой документация после разбора чужой системы не пишется вообще — это стремление сделать её полной. Начинаете описывать сервер, вспоминаете, что не до конца разобрались с одним из cron-заданий, откладываете файл «пока не проясню», переключаетесь на текучку — и файл так и остаётся недописанным черновиком, который никто никогда не откроет.

Работает обратная логика: документ, который можно дописать за один присест и закрыть, будет создан. Документ, который требует «ещё немного доразобраться» перед тем, как его можно показать другим, создан не будет почти никогда. Короткий актуальный документ полезнее длинного, но так и не дописанного или мгновенно устаревшего — это тот же принцип, что работает и в полноценной документации, просто доведённый до предела.

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

Формат — обычный markdown-файл, а не презентация и не wiki-страница с оформлением. Цель не в красоте, а в том, чтобы файл реально существовал и реально был найден в нужный момент.

Что абсолютно обязательно: доступы

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

Минимум, который нужно зафиксировать:

• SSH — адрес сервера, порт (если не стандартный 22), какой пользователь используется для входа, где искать или как получить SSH-ключ (в менеджере паролей команды, а не «спросить у меня в личке»).
• Панель управления хостингом/облаком — ссылка на панель, кто владелец аккаунта, как восстанавливается доступ, если основной email недоступен.
• Регистратор домена и DNS-провайдер — отдельно от хостинга почти всегда, и именно этот пункт чаще всего забывают: домен «просто работает», пока не понадобится поменять NS-запись или продлить регистрацию, а логина ни у кого нет.
• Хранилище секретов команды — где лежат пароли от баз данных, API-ключи сторонних сервисов, токены CI/CD. Не сами секреты (это отдельная политика безопасности), а именно указание, где их искать.
• Административные аккаунты внутри системы — суперпользователь БД, admin-панель CMS, аккаунт в системе мониторинга.

Формат — простая таблица прямо в документе:

| Точка входа       | Где / как                          | У кого спросить, если не работает |
|--------------------|-------------------------------------|-------------------------------------|
| SSH сервер prod-01 | root@203.0.113.10, ключ в Bitwarden | — |
| Панель хостинга    | panel.example-host.com              | биллинг-аккаунт: billing@company    |
| Регистратор домена | reg.example.com, логин admin@company| — |
| Секреты БД/API     | Vault: /secret/prod/db              | — |

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

Критичные зависимости: то, без чего всё падает

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

Что сюда точно входит:

• Единая точка отказа (SPOF). Единственный сервер БД без реплики, единственный шлюз для внутренней сети, единственный человек с доступом к платёжному аккаунту хостинга — если такое есть, это должно быть написано прямым текстом, а не подразумеваться.
• Внешние сервисы, от которых зависит работа. Платёжный шлюз, SMTP-релей для писем, стороннее API, без которого падает ключевая функциональность. Отдельно стоит пометить сервисы с истекающими подписками или сертификатами, если срок известен и приближается.
• Нестандартные решения без очевидной причины. Cron-задача, которая выглядит бессмысленной, но на самом деле держит критичный процесс; правило firewall, разрешающее подключение раз в месяц для партнёрской интеграции. Такие вещи не найти в конфиге — их можно только записать явно, потому что случайное отключение «явно лишнего» — самая частая причина инцидентов на унаследованных системах.
• Бэкапы: факт наличия и факт проверки. Не полное описание схемы резервного копирования, а два простых факта: настроены ли бэкапы вообще и куда, и когда в последний раз кто-то реально проверял восстановление, а не просто смотрел на дату файла.

Формулировка для нестандартных решений должна включать не только «что», но и «почему», иначе ценность записи падает почти до нуля:

- cron `0 3 * * * /opt/scripts/sync_legacy.sh` — синхронизация с внешней CRM
  партнёра. НЕ ОТКЛЮЧАТЬ: партнёр получает данные только этим способом,
  альтернативного канала нет. Скрипт написан в 2024, автор неизвестен,
  логика разобрана в комментариях внутри файла.
- firewall правило для 198.51.100.0/24 — подсеть подрядчика по обработке
  платежей, открыта только на порт 443. Список подсетей уточнять у
  бухгалтерии, не удалять без согласования.

Такая запись занимает четыре строки, но именно она чаще всего экономит следующему человеку день или два самостоятельного расследования — вместо того чтобы заново поднимать всю методологию поиска по правилам firewall и cron-задачам, он открывает файл и сразу знает ответ.

Контакты и границы ответственности

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

Что зафиксировать:

• Кто ещё что-то знает. Коллега, настраивавший конкретный сервис; подрядчик, обслуживающий отдельный компонент; бывший сотрудник, к которому можно обратиться с конкретным вопросом. Даже «неофициальный» источник знаний лучше явно назвать («спросить у Х про Y»), чем промолчать.
• Контакты внешних провайдеров и подрядчиков с договорными обязательствами по системе: хостинг-провайдер, платёжный шлюз, поддержка регистратора домена.
• Что не входит в вашу зону ответственности. Если вы разбирали только часть системы, напишите прямо, что осталось за скобками — «код приложения не разбирал, только инфраструктуру». Иначе следующий человек может принять вашу карту за полную, когда она таковой не является.
• Как с вами можно связаться после ухода, если вы готовы отвечать на редкие вопросы, и на какой срок. Не обязательный пункт, но честный жест, который экономит обеим сторонам недели переписки через третьих лиц.

Этот блок логично примыкает к вопросу о границах ревизии: если вы, помимо доступов, решали, какие сервисы вообще нужны бизнесу, а какие можно гасить, — итоговое решение стоит зафиксировать здесь, коротко: что выключено, когда и почему, и что осталось работать, потому что бизнес подтвердил необходимость.

Что можно смело опустить

Столько же важно понимать, что НЕ входит в минимальный документ — иначе соблазн «дописать ещё немного» снова превратит его в незаконченный проект.

Осознанно опускайте:

• Полный список установленного ПО и всех версий. Статичная информация, устаревающая за недели и восстанавливаемая одной командой (dpkg -l, docker images) за минуту, когда реально понадобится. Хранить её в документе — значит гарантированно хранить неактуальные данные.
• Историю ваших действий по разбору. То, как именно вы искали и находили факты, — процесс, а не результат. Он был ценен вам во время расследования, но следующему человеку нужен вывод, а не хроника пути к нему.
• Полное архитектурное описание с диаграммами каждого компонента. Если системе действительно нужна такая документация — это отдельный, более объёмный проект, и обзор того, что стоит в неё включать, есть в статье что нужно вести в документации сервера. Это не блокирует минимальный документ: одностраничник можно сдать сегодня, а полную документацию начать вести отдельно, если найдётся время.
• Автоматически генерируемые данные без объяснения. Дамп конфигов, вывод ps auxf, экспорт правил firewall без единого комментария — это не документация, а сырые данные. Инструмент вместо объяснения — известный антипаттерн, разобранный в статье «скрипт вместо документации»: автоматизация фиксирует, что делает система, но не отвечает на «почему», а именно «почему» и есть главная ценность минимального документа.
• Незавершённые гипотезы без пометки. Если не уверены в факте — либо явно пометьте это («предположительно», «не проверял»), либо не включайте вовсе. Неверный факт, поданный как достоверный, опаснее отсутствующего: он создаёт ложную уверенность.

Хороший тест: если раздел документа не меняет ни одного решения следующего человека в критической ситуации — он необязателен для минимума, даже если было бы приятно его иметь.

Формат и место хранения одностраничника

Файл бесполезен, если его никто не найдёт в нужный момент. Два практических правила решают большую часть этой проблемы.

Место хранения — там, где и так ищут информацию о системе, а не в личных заметках или переписке:

• README.md в корне репозитория проекта, если код лежит в git;
• отдельный файл в общей папке команды (Dropbox, внутренний wiki), путь к которому известен минимум двум людям;
• файл прямо на сервере в предсказуемом месте (/root/HANDOVER.md или аналогично) — с обязательной копией вне сервера, потому что если сервер перестанет отвечать, документ должен быть доступен независимо от него.

Дублирование — не излишество, а страховка: копия только на сервере бесполезна, если проблема как раз в том, что на сервер нельзя зайти.

Структура — фиксированный шаблон, который заполняется по разделам этой статьи, без произвольного добавления «интересных, но не обязательных» пунктов:

# Handover: <название системы/сервера>
Дата: <когда составлен>
Составил: <имя, контакт>

Доступы

(таблица: точка входа / где искать / запасной контакт)

Критичные зависимости

• SPOF: ...
• Внешние сервисы: ...
• Нестандартные решения (что + почему + не трогать/можно менять): ...
• Бэкапы: настроены (да/нет) → куда → когда проверено восстановление

Контакты

• Кто ещё в курсе: ...
• Внешние подрядчики/провайдеры: ...
• Зона ответственности этого документа: что НЕ покрыто

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