Это машинный перевод текста, который может содержать ошибки!
Хорошая документация — это разница между тем, чтобы помнить, как всё работает, и тем, чтобы застрять в 23 часа воскресенья из-за того, что сервер не отвечает, а никто не помнит, как он был настроен. Документация, возможно, не самая увлекательная часть эксплуатации ИТ-инфраструктуры, но она является одной из самых важных.
Зачем документировать?
| Причина | Пояснение |
|---|---|
| Память | Вы не будете помнить всё через шесть месяцев, и в этом нет необходимости |
| Сотрудничество | Другие должны понимать, что вы сделали, без возможности спросить вас |
| Отладка | Когда что-то идёт не так, крайне важно знать, что является нормой |
| Восстановление | Если сервер выходит из строя, необходимо точно знать, как он был настроен |
| Прослеживаемость | Что было изменено, когда и кем? |
Пишите документацию для «будущего вас»
Лучшее правило пальца: пишите так, как будто объясняете себе через шесть месяцев. Так вы гарантированно включите достаточно деталей, не усложняя вещи чрезмерно.
Типы документации в ИТ-эксплуатации
Схема сети
Схема сети отображает физическую и/или логическую структуру сети. Это может быть всё что угодно — от простого эскиза до детальной диаграммы с VLAN, IP-адресами и правилами межсетевых экранов.
Хорошая схема сети должна включать в себя:
- Все сетевые устройства (коммутаторы, маршрутизаторы, межсетевого экрана, точки доступа)
- Структуру VLAN с подсетями
- IP-адреса важных устройств (серверы, шлюзы)
- Соединения между устройствами
План IP-адресации
План IP-адресации — это обзор того, как распределены IP-адреса в сети. Он помогает поддерживать порядок и избегать конфликтов (две устройства с одним адресом).
Пример:
| VLAN | Имя | Подсеть | Шлюз | Диапазон DHCP | Примечания |
|---|---|---|---|---|---|
| 10 | Администрирование | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | Ограниченный доступ |
| 20 | Сотрудники | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | Учащиеся | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | Только интернет |
| 50 | Серверы | 10.0.50.0/24 | 10.0.50.1 | Нет (статический) | Статические IP-адреса |
Статические адреса:
| IP-адрес | Устройство | Роль |
|---|---|---|
10.0.50.10 | web-01 | Nginx |
10.0.50.11 | db-01 | PostgreSQL |
10.0.50.12 | monitoring-01 | Grafana + Loki |
10.0.50.20 | proxmox | Гипервизор |
Чек-листы
Чек-листы обеспечивают, чтобы ничего не было упущено. Они особенно полезны для задач, которые выполняются редко, таких как настройка нового сервера или проведение аудита безопасности.
Пример: чек-лист для нового Linux-сервера:
- Установить операционную систему (Debian/Ubuntu)
- Обновить все пакеты (
sudo apt update && sudo apt upgrade) - Создать пользователя с правами sudo
- Отключить вход через root по SSH
- Настроить брандмауэр (
ufw) - Установить необходимое программное обеспечение
- Настроить резервное копирование
- Задокументировать сервер в плане IP-адресов
- Проверить работоспособность службы
Документирование изменений
Каждый раз при вносимых изменениях в производственную среду (сервер, сеть, служба) их следует документировать. Простой журнал может быть достаточен:
## Журнал изменений
### 2026-04-14 - Обновление Nginx
- **Что:** Обновлён Nginx с версии 1.24 до 1.26
- **Почему:** Безопасное обновление (CVE-2025-XXXX)
- **Кто:** Ола
- **Результат:** ОК, без простоя
### 2026-04-10 - Новый VLAN для IoT
- **Что:** Создан VLAN 40 для устройств IoT
- **Почему:** Изоляция IoT от остальной части сети
- **Кто:** Кари
- **Результат:** ОК, все принтеры перемещены в VLAN 40
Используйте Git!
Если вы пишете документацию в файлах Markdown (рекомендуется), вы можете вести их версионирование с помощью Git. Тогда у вас автоматически появится история всех изменений, и вы сможете видеть, кто что изменил и когда.
Операционная документация
Операционная документация описывает, как система работает в своем текущем состоянии:
| Что | Пример |
|---|---|
| Архитектура системы | «Мы используем Proxmox с тремя ВМ: веб, БД, мониторинг» |
| Информация об доступе | «SSH через порт 22, только из VPN» |
| Процедуры резервного копирования | «Ежедневное резервное копирование в 02:00 на внешний диск» |
| Контактные данные | «При проблемах обращайтесь к Оле (администратор)» |
| Шаги восстановления | «Перезапуск командой: sudo systemctl restart nginx» |
Инструменты для документирования
| Инструмент | Для чего используется | Преимущества |
|---|---|---|
| Markdown | Текст с простым форматированием | Лёгкий, переносимый, работает с Git |
| draw.io | Диаграммы и сетевые схемы | Бесплатный, наглядный, экспорт в изображение |
| Obsidian | Приложение для заметок с Markdown и ссылками | Хорошо подходит для личной базы знаний |
| MkDocs | Публикация Markdown как веб-страницы | Профессиональная документация |
| Git/GitHub | Контроль версий документации | История, совместная работа, резервное копирование |
Задание 1 — Создайте простую сетевую схему
Используйте draw.io (бесплатно), чтобы нарисовать сеть дома или в школе:
- Начните с интернет-соединения и роутера
- Добавьте коммутаторы и точки доступа
- Нарисуйте серверы, ПК и другие устройства
- Укажите IP-адреса там, где они вам известны
Это не обязательно должно быть идеально. Суть в том, чтобы начать мыслить о сети визуально.
Задание 2 — Составьте собственный чек-лист
Подумайте о том, что вы регулярно делаете с ИТ (например, настройка новой виртуальной машины, установка рабочей среды разработки или конфигурирование VS Code). Напишите чек-лист для этого процесса:
- Какие все шаги входят в процесс?
- Что вы чаще всего забываете?
- Можно ли упростить некоторые шаги?
Сохраните его в документе Markdown, чтобы использовать в следующий раз.
Задание 3 — Документирование одной из ваших служб
Выберите службу, которую вы настроили (виртуальную машину, контейнер Docker, веб-сервер), и напишите краткую документацию по эксплуатации:
- Что делает служба?
- Как её запускать/останавливать?
- Каковы IP-адрес и порт?
- Существует ли резервное копирование?
Составьте это в формате Markdown и разместите в репозитории Git.
Резюме
- Документы для будущего вас: Пишите так, будто объясняете тому, кто ничего не знает
- Схемы сетей и планы IP-адресации обеспечивают обзор инфраструктуры
- Чек-листы гарантируют, что при повторяющихся задачах ничего не будет забыто
- Журналы изменений отслеживают то, что было сделано, когда и кем
- Эксплуатационная документация описывает, как системы работают сегодня
- Используйте Markdown + Git для простой документации с контролем версий