Документация инфраструктуры

Документация инфраструктуры — это не формальность и не “бумажная работа”. Это способ сохранить порядок в системе, которая со временем становится сложнее.

Домашняя инфраструктура часто начинается с простых вещей: роутер, сервер, один сервис, несколько папок, пара настроек. Но постепенно появляются локальные сервисы, reverse proxy, DNS, резервные копии, мониторинг, автоматизация, внешние домены, сертификаты, контейнеры и сетевые зоны.

Пока всё свежо в памяти, кажется, что документация не нужна. Но через несколько месяцев становится сложно вспомнить, почему сервис настроен именно так, где лежит конфигурация, какой порт используется, где смотреть логи и как восстановить систему после сбоя.

Главная идея простая: инфраструктура должна быть понятной не только сегодня, но и позже.

Зачем нужна документация

Документация нужна не для красоты. Она нужна для обслуживания, диагностики и восстановления.

Она помогает ответить на вопросы:

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

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

Почему нельзя держать всё в голове

Память хорошо работает, пока система маленькая. Но инфраструктура почти всегда растёт.

Сначала появляется один сервис. Потом второй. Потом нужен домен. Потом reverse proxy. Потом backup. Потом мониторинг. Потом отдельная зона для устройств. Потом автоматизация. Потом обновления. Потом аварийное восстановление.

Через какое-то время уже сложно помнить:

какой сервис от чего зависит;
какие команды использовались при настройке;
что можно безопасно обновлять;
какие файлы нельзя удалять;
какой каталог содержит реальные данные;
почему открыт конкретный порт;
какой маршрут ведёт к сервису;
что делать при ошибке.

Документация разгружает память. Она позволяет не вспоминать, а открыть нужный раздел и действовать по шагам.

Что нужно документировать

Документировать нужно не всё подряд, а то, что помогает обслуживать систему.

Область	Что фиксировать
Сервисы	назначение, адрес, способ запуска, данные, конфигурация, логи
Сеть	зоны, правила доступа, DNS, маршруты, внешний периметр
Reverse proxy	домены, backend-сервисы, HTTPS, маршруты
Backup	что копируется, куда, как часто, как восстановить
Мониторинг	что проверяется, какие уведомления важны
Обновления	порядок действий, риски, проверка после обновления
Доступы	кто имеет доступ, какие роли, как отключить доступ
Команды	проверка статуса, перезапуск, просмотр логов
Ошибки	типовые проблемы и способы решения
Изменения	что менялось, когда и зачем

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

Карточка сервиса

Для каждого важного сервиса полезно иметь короткую карточку.

В ней можно фиксировать:

Поле	Что писать
Название	понятное имя сервиса
Назначение	зачем он нужен
Адрес	как к нему подключиться
Тип запуска	systemd, контейнер, compose, отдельное приложение
Где данные	путь к постоянным данным
Где конфигурация	путь к настройкам
Где логи	команда или путь к журналам
Backup	что сохраняется и куда
Проверка статуса	команда или URL проверки
Восстановление	краткий порядок действий
Особенности	нестандартные решения и ограничения

Такая карточка особенно полезна при сбое. Она позволяет быстро понять, где смотреть проблему и что нельзя трогать без подготовки.

Документация сети

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

Если не записывать сетевую схему, со временем становится сложно понять:

какие зоны существуют;
какие устройства где находятся;
какие правила доступа разрешены;
какие DNS-имена используются;
какие сервисы доступны извне;
какие маршруты проходят через reverse proxy;
какие устройства изолированы;
какие порты открыты.

Сетевая документация не обязательно должна быть сложной. Даже простая таблица уже помогает.

Зона	Назначение	Примеры устройств
CoreNet	сервисные узлы	серверы, внутренние приложения
UserNet	личные устройства	компьютеры, телефоны
IoTNet	устройства автоматизации	датчики, камеры, контроллеры
GuestNet	гостевой доступ	устройства гостей
ShieldNet	внешний периметр	reverse proxy, входящие маршруты

Главное — чтобы было понятно, кто где находится и кто куда может обращаться.

Документация reverse proxy

Reverse proxy часто становится центральной точкой web-инфраструктуры. Через него проходят домены, HTTPS и маршруты к внутренним сервисам.

Поэтому важно фиксировать:

какой домен к какому сервису ведёт;
какой backend используется;
какой порт или внутренний адрес обслуживает сервис;
где настроен HTTPS;
какие маршруты опубликованы наружу;
какие сервисы доступны только внутри;
где смотреть логи proxy;
как временно отключить маршрут.

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

Документация резервного копирования

Backup без документации часто оказывается бесполезным в момент аварии.

Недостаточно знать, что “где-то есть копия”. Нужно понимать:

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

Для каждого важного сервиса желательно иметь короткий план восстановления. Он должен быть написан так, чтобы по нему можно было действовать в стрессовой ситуации.

Журнал изменений

Журнал изменений помогает понять, что происходило с инфраструктурой.

В нём можно фиксировать:

дату изменения;
что было изменено;
зачем это было сделано;
какие файлы затронуты;
какие команды выполнялись;
был ли backup перед изменением;
как проверялся результат;
были ли ошибки.

Это особенно полезно, если проблема появилась не сразу. Например, сервис начал работать нестабильно через день после изменения. Журнал помогает вспомнить, что именно могло повлиять на систему.

Команды обслуживания

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

Например:

проверить статус сервиса;
посмотреть логи;
перезапустить сервис;
проверить конфигурацию;
выполнить backup;
проверить свободное место;
проверить доступность сайта;
пересобрать статический сайт;
применить изменения web-сервера.

Команды должны быть понятными и безопасными. Особенно важно отдельно помечать действия, которые могут что-то удалить, перезаписать или остановить.

Главный принцип: опасные команды не должны быть спрятаны среди обычных проверок.

Документация ошибок

Хорошая база знаний хранит не только идеальную схему, но и реальные проблемы.

Если ошибка уже встречалась, её стоит записать.

Полезно фиксировать:

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

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

Что не стоит публиковать

Документация бывает внутренней и публичной.

Публичная документация может объяснять подходы, архитектуру, принципы, общие схемы и безопасные примеры. Но в неё не стоит помещать чувствительные детали.

Не стоит публиковать:

реальные IP-адреса внутренних узлов;
пароли;
токены;
приватные ключи;
точные пути к чувствительным данным;
реальные имена устройств, если они раскрывают структуру;
конфигурации с секретами;
внутренние домены, если они не предназначены для публикации;
данные пользователей;
журналы с приватной информацией.

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

Внутренняя и публичная документация

Полезно разделять два типа документации.

Публичная документация объясняет идеи. Она может быть полезна другим людям, показывает подход и описывает архитектурную логику.

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

Тип документации	Что содержит
Публичная	принципы, общие схемы, подходы, безопасные примеры
Внутренняя	реальные команды, пути, узлы, backup, восстановление, доступы

Такое разделение помогает делиться знаниями без раскрытия лишней информации.

Документация как часть восстановления

Документация особенно важна при аварии.

Когда сервис недоступен, диск заполнен, proxy возвращает ошибку или backup нужно срочно восстановить, нет времени вспоминать старые решения.

Хорошая документация позволяет быстро понять:

что именно сломалось;
какие проверки выполнить;
где смотреть журналы;
какие сервисы связаны;
где лежит backup;
как восстановить данные;
как проверить результат.

В момент сбоя документация становится не текстом, а инструментом восстановления.

Частые ошибки

В документации инфраструктуры часто встречаются одни и те же ошибки.

Первая ошибка — не писать ничего, пока всё работает.

Вторая ошибка — хранить заметки в разных местах без структуры.

Третья ошибка — документировать только установку, но не восстановление.

Четвёртая ошибка — не обновлять документацию после изменений.

Пятая ошибка — хранить секреты рядом с публичными заметками.

Шестая ошибка — не фиксировать нестандартные решения.

Седьмая ошибка — писать слишком сложно, так что через месяц текст уже непонятен.

Документация должна быть простой, практичной и живой.

Практический результат

Хорошая документация даёт несколько преимуществ.

Во-первых, инфраструктуру проще обслуживать.

Во-вторых, проблемы решаются быстрее.

В-третьих, меньше риска случайно сломать важный сервис.

В-четвёртых, проще переносить сервисы на новый узел.

В-пятых, backup и восстановление становятся реальными, а не теоретическими.

В-шестых, система перестаёт зависеть только от памяти владельца.

Итог

Документация инфраструктуры — это часть самой инфраструктуры.

Сервисы должны быть описаны.
Сеть должна быть понятной.
Backup должен иметь план восстановления.
Команды должны быть сохранены.
Ошибки должны превращаться в опыт.
Изменения должны фиксироваться.
Публичная и внутренняя документация должны быть разделены.

Главная цель — сделать систему понятной, обслуживаемой и восстанавливаемой.

Хорошая документация не усложняет инфраструктуру. Она делает её спокойнее.