Как составить технический паспорт сайта

Редакция Romanov Lab · Опубликовано 13 октября 2026

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

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

Выберите единицу учёта и источник каждого факта

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

Каждый изменяемый факт должен иметь источник и отметку актуальности. Версию приложения подтверждает запись о выпуске или проверенный идентификатор работающего кода; расписание задания — действующая конфигурация планировщика. Фраза «так было при разработке» не является источником текущего состояния.

Покажите путь данных на одном понятном примере

Полезнее описать маршрут заявки, чем перечислить названия технологий без связей. Для условного сайта услуг цепочка может быть такой: форма сохраняет обращение в базе; фоновый обработчик передаёт его в CRM; уведомление менеджеру отправляется отдельно. Тогда отсутствие письма ещё не говорит об утрате самой заявки.

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

Объект паспорта

Передача обращения из формы «Расчёт» в CRM

Источник истины до передачи

Сохранённое обращение сайта

Успех передачи

В ответе и журнале сопоставлены идентификатор обращения и идентификатор записи CRM

Что проверять при задержке

Состояние обращения, очередь передачи и журнал обработчика

Чего не делать без сверки

Не создавать новое обращение и не повторять массовую отправку всей очереди

Ограничение образца

Названия состояний и правила повторов заполняются по фактической реализации

Такую карточку можно использовать как проверочный вопрос автору паспорта: где именно найти зависшую заявку и какое свидетельство покажет, что она уже передана?

Разделите паспорт, инструкции и секреты

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

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

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

Свяжите версии с воспроизводимым комплектом

Запись «используется Node.js» или «сайт на PHP» слишком общая для воспроизведения. Укажите фактическую версию среды, менеджер зависимостей, файл фиксации зависимостей и особенности сборки. Для проекта на npm package-lock.json описывает конкретное дерево зависимостей. В паспорте достаточно ссылки на файл нужной версии; переписывать тысячи пакетов вручную не нужно.

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

Доказательства тоже имеют срок хранения. В GitHub Actions журналы и артефакты хранятся ограниченное время, которое настраивается. Поэтому ссылка на старый запуск не заменяет долговременный комплект восстановления. Укажите, где сохраняется нужный выпуск и кто проверяет его доступность.

Помечайте неизвестное и расхождения

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

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

Проверьте документ практическими вопросами

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

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

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