Перейти к основному содержимому

Руководство по техническому обслуживанию по ГОСТ 19.508-79

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ
Руководителю Аналитику Техническому писателю
Теория данных (раздел 3)

ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.

Руководство по техническому обслуживанию​

ГОСТ

Основано на ГОСТ 19.508-79.

Руководство по техническому обслуживанию - это регламентные процедуры — (1) как сделать резервную копию данных, (2) как обновить программу без потери конфигурации, (3) как проверить целостность файлов, (4) как архивировать старые логи, (5) как перезапустить модуль, если он завис.

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

Можно сказать, это регулярные, плановые действия, а не аварийные. Чтоб программа "не умерла от старости".

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

1. Введение — ГОСТ 19.508-79 — краткий обзор​

ГОСТ 19.508-79 — советский государственный стандарт из состава Единой системы программной документации (ЕСПД), принятый 11 декабря 1979 г., введён в действие с 1 января 1981 г. Он определяет требования к содержанию и оформлению документа "Руководство по техническому обслуживанию" (РТО).

🎯 Назначение стандарта​

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

⚠ Обратите внимание: хотя ГОСТ 19.508-79 формально применяется к диагностике и тестированию оборудования, его принципы применимы и к современным программным системам, особенно в контексте:

  • мониторинга и самодиагностики (health checks),
  • процедур восстановления (recovery procedures),
  • профилактического обслуживания (preventive maintenance),
  • инструментов DevOps и SRE (например, инвентаризация, проверка целостности, регрессионные тесты инфраструктуры).

📦 Область применения​

Стандарт не распространяется на:

  • пользовательские инструкции (это — ГОСТ 19.504),
  • программные документы общего назначения (ГОСТ 19.501–19.509),
  • проектную и конструкторскую документацию.

Он применим к:

  • тестовым программам (self-test, burn-in, soak tests),
  • диагностике неисправностей оборудования (memory, disk, CPU, Сеть),
  • средствам автоматизированной проверки состояния систем.

📐 Общая структура документа по ГОСТ​

РазделОбязательностьКомментарий
Титульный лист✅ ОбязательноПо ГОСТ 19.105-78
Аннотация✅ ОбязательноКраткое описание назначения и области применения РТО
Содержание✅ ОбязательноДерево разделов и подразделов с номерами страниц
Введение✅ ОбязательноНазначение РТО, перечень сопутствующих эксплуатационных документов
Общие указания✅ ОбязательноПорядок, организация и особенности проведения ТО
Требования к техническим средствам✅ ОбязательноМинимальная конфигурация оборудования для запуска программы
Описание функций✅ ОбязательноПодробное описание функциональности диагностической программы
Дополнительные разделы🟡 ОпциональноНапример: "Меры безопасности", "Аварийные ситуации", "Журналирование", "Примеры использования"

📌 Примечание:

  • Все разделы оформляются по ГОСТ 19.105-78 (требования к построению, изложению, оформлению и содержанию программных документов).
  • В современной практике вместо "технических средств" подразумевается инфраструктурная среда — серверы, ОС, сетевые интерфейсы, виртуальные/контейнеризованные окружения.
  • Стандарт не требует строго литературного качества — важна точность, однозначность и полнота информации.

2. Пошаговое руководство по составлению РТО​

Ниже приведено пошаговое руководство по написанию РТО. Каждый шаг включает:

  • что делать,
  • почему это важно,
  • как оформлять (с учётом современной практики технического письма).

Шаг 1. Подготовка — сбор информации​

Перед началом работы необходимо:

  • получить спецификацию диагностируемой системы (аппаратной или программной),
  • выделить функции самодиагностики или тестирования,
  • определить целевую аудиторию (например — инженер 2-й категории, SRE, техподдержка),
  • уточнить сценарии использования — штатная проверка, восстановление после сбоя, предварительная приёмка.

Шаг 2. Составьте информационную часть​

Обязательные элементы:

  • Титульный лист:
    Включает наименование документа, код по ГОСТ (19.508), идентификатор системы/версии, дату, организацию-разработчика.
  • Аннотация (резюме):
    Объём — 3–5 предложений. Ответьте на вопросы:
    • Что это за документ?
    • Для какой системы/программы?
    • Кто читатель?
    • Какие операции охватывает (диагностика, калибровка, сброс)?
  • Содержание:
    Генерируется автоматически при финальной сборке (Docusaurus, Confluence) или из Markdown:
pandoc manual.md -o manual.pdf --toc --number-sections

Шаг 3. Раздел "Введение"​

Что включить:

  • Назначение РТО: "Настоящий документ предназначен для специалистов по техническому обслуживанию и содержит инструкции по диагностике и восстановлению работоспособности системы X".
  • Перечень сопутствующих документов (обязательно!):
    • Руководство оператора (ГОСТ 19.504),
    • Описание применения (ГОСТ 19.502),
    • Программа и методика испытаний (ГОСТ 19.301),
    • Техническое задание (ГОСТ 19.201),
    • Руководство администратора (если есть),
    • API Reference, OpenAPI/Swagger-спецификации (в современной практике).

Формат рекомендуется табличный:

Наименование документаОбозначениеПримечание
Руководство оператораРО-X-v2.1Версия 2.1, 2025 г.
Описание примененияОП-X-2025Используется при интеграции в ELK

Шаг 4. Раздел "Общие указания"​

Ключевые подпункты:

  • Общая последовательность действий (например: "1. Подготовка → 2. Запуск диагностической процедуры → 3. Анализ результатов → 4. Принятие решений").
  • Периодичность проведения — штатная (ежедневно), после сбоя, перед обновлением.
  • Организационные требования:
    • Требуемая квалификация персонала (например — "инженер по эксплуатации, аттестованный по программе Х"),
    • Необходимые разрешения (доступ к консоли, права sudo, MFA).
  • Особые условия — температура, ЭМ-помехи, отключение от сети и т.п. (для hardware) или изоляция окружения (для ПО — например, запуск в maintenance mode).

Шаг 5. Раздел "Требования к техническим средствам"​

Фокус — на минимальные требования.
В современном контексте это требования к среде выполнения. Пример структуры:

КатегорияМинимальные требованияРекомендуемые
ОСUbuntu 22.04 LTS, ядро ≥ 5.15Ubuntu 24.04 LTS
Процессор2 ядра, x86_644+ ядер, AES-NI
Память2 ГБ ОЗУ8 ГБ ОЗУ
Дисковое пространство500 МБ свободноSSD, 5 ГБ
Сетевые интерфейсыIPv4, localhostIPv6, TLS 1.3
ЗависимостиPython 3.10+, psutil, requestsPython 3.12, виртуальное окружение
Права доступаdiag-user в группе admRBAC: role:diagnostic

✅ Правило: указывайте версии строго ("Python ≥ 3.10, < 3.13"). При изменении требований — фиксируйте мажорную версию РТО.

Шаг 6. Раздел "Описание функций"​

Самый объёмный и технически насыщенный раздел. Структура по ГОСТ:

  1. Максимальный состав технических средств, проверяемых программой
    → В современном понимании — поддерживаемые компоненты системы (например — БД PostgreSQL, брокер RabbitMQ, frontend-контейнеры).
    Лучше оформить в виде таблицы совместимости (см. ниже).

  2. Описание совместного функционирования технических средств и программы
    → Требуется:

    • описание workflow (например — "программа инициирует HTTP-запрос к /health, ожидает 200 OK в течение 5 с"),
    • метод обработки ошибок (логика обработки timeout, 5xx, connection refused),
    • действия при выявлении неисправности (например: "при коде 0x7E — перезапуск сервиса auth-service").

  3. Организация входных и выходных данных
    → Укажите:

    • формат входных параметров (CLI-аргументы, env-vars, конфиг-файл),
    • структуру выходных данных (JSON schema, CLI exit codes, syslog-сообщения),
    • коды возврата:
     0 — OK (все проверки пройдены)
     1 — предупреждение (рекомендуется вмешательство)
     2 — критическая ошибка (система неработоспособна)
     3 — ошибка среды (не хватает прав/ресурсов)
  1. Описание взаимодействия устройств с программой
    → Для software-систем: это интерфейсы и сценарии взаимодействия.
    Пример:
    • "Программа diag-net опрашивает все активные сетевые интерфейсы через netlink сокет",
    • "При обнаружении packet loss > 5% — отправляет alert в Prometheus через Pushgateway",
    • "Результаты сохраняются в /var/log/diag/net-<timestamp>.json".

Шаг 7. Дополнительные рекомендуемые разделы (современные практики)​

Хотя ГОСТ их не требует, они повышают ценность документа:

  • Меры безопасности — запуск не от root:
[Service]
User=diag
NoNewPrivileges=yes
AmbientCapabilities=CAP_NET_ADMIN CAP_SYS_PTRACE
  • Журналирование и мониторинг
    (формат логов, интеграция с Grafana/Prometheus, retention policy).
  • Примеры запуска
    (CLI-команды с комментариями, скриншоты терминала — но в текстовом формате!).
  • Устранение типовых неисправностей
    (FAQ-style: ошибка соединения → проверить службу и логи):
# ERR_CONN_REFUSED
systemctl status netd
journalctl -u netd -n 50 --no-pager

3. Типичные ошибки и как их избежать​

Особенно актуально при обучении начинающих технических писателей.

ОшибкаПочему это плохоКак избежать
Размытые формулировки "программа работает на компьютере"Не позволяет воспроизвести средуУказывайте точные версии, архитектуру, зависимости. Используйте термины: x86_64, arm64/v8, glibc 2.35+.
Отсутствие кодов возвратаИнженер не знает, что делать при exit code = 255Включайте таблицу exit codes. Согласуйте с разработчиками.
Нет ссылок на другие документыЧитатель "застревает" — не знает, где искать доп. информациюВ "Введении" дайте полный перечень с обозначениями и версиями.
Смешение уровней абстракции — описание "как работает алгоритм CRC-32" в РТОРТО — не справочник разработчикаОписывайте поведение, не реализацию. "Программа проверяет контрольную сумму образа диска" — достаточно.
Нет примеровТеория без практики → ошибки при выполненииДобавляйте 1–2 рабочих примера с пояснением каждой опции.
Игнорирование безопасностиЗапуск с sudo "для удобства" → уязвимостиВыделяйте блоки "Безопасность Note": ⚠ Не используйте --force в production.
Однократное написание, без актуализацииДокумент устаревает быстрее, чем ПОПропишите в титуле: "Последнее обновление: 2025-11-11. Актуально для версии X v3.2.1". Завяжите на CI: если изменился CLI — запретить мердж без обновления РТО.

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

4. Пример РТО для вымышленной системы​

Система XenonCache v2.1​

Распределённая система кэширования данных с встроенной самодиагностикой

📌 Пояснение: XenonCache — виртуальная система. Для целей демонстрации:

  • это stateless кэш-сервер на базе in-memory хранилища,
  • поддерживает кластеризацию, репликацию, автоматическое восстановление,
  • содержит встроенную утилиту диагностики xenon-diag (CLI + HTTP API),
  • предназначена для эксплуатации инженерами SRE-группы.

Документ оформляется строго по структуре ГОСТ 19.508-79, с дополнениями современных практик (без нарушения требований стандарта).

📄 Руководство по техническому обслуживанию​

Система XenonCache, версия 2.1
Документ: РТО-XC-2.1
Дата составления: 11.11.2025
Разработчик: ООО "НейтронЛабс"

Аннотация​

Настоящий документ содержит инструкции по техническому обслуживанию распределённой кэш-системы XenonCache версии 2.1 с использованием встроенной диагностической программы xenon-diag. Предназначен для инженеров по эксплуатации и SRE. Описывает порядок запуска, интерпретацию результатов, обработку ошибок и действия при выявлении неисправностей. Обеспечивает соответствие требованиям надёжности и восстанавливаемости в условиях 24/7 эксплуатации.

Содержание​

  1. Введение
  2. Общие указания
  3. Требования к техническим средствам
  4. Описание функций
    4.1. Максимальный состав проверяемых технических средств
    4.2. Совместное функционирование и обработка ошибок
    4.3. Организация входных и выходных данных
    4.4. Взаимодействие устройств с программой и вывод результатов

1. Введение​

Настоящее Руководство по техническому обслуживанию (РТО) предназначено для специалистов, ответственных за эксплуатацию и обслуживание распределённой кэш-системы XenonCache v2.1. Оно описывает процедуры диагностики и контроля работоспособности с помощью программы xenon-diag, входящей в поставку XenonCache.

Для полного выполнения задач технического обслуживания дополнительно используются следующие документы:

Наименование документаОбозначениеПримечание
Руководство оператораРО-XC-2.1Содержит описание интерфейсов управления и мониторинга
Описание примененияОП-XC-2.1Условия интеграции, сценарии использования
Программа и методика испытанийПМИ-XC-2.1Испытания при приёмке
Спецификация HTTP APISPEC-XC-HTTP-v2OpenAPI 3.1, доступна по /openapi.json
Инструкция по развёртываниюDEPLOY-XC-K8SДля окружения Kubernetes

2. Общие указания​

Техническое обслуживание XenonCache выполняется с периодичностью:

# ежедневно
xenon-diag --mode quick

# еженедельно
xenon-diag --mode full --replicas all
  • По требованию — после сбоя, перед обновлением, при расширении кластера.

Порядок проведения​

  1. Подготовка
    • Убедиться, что все узлы в состоянии Ready:
kubectl get nodes
  • Перевести кластер в режим обслуживания:
curl -X PUT 'https://cluster.example/api/v1/maintenance?enable=true'
  • Проверить наличие свободного дискового пространства (≥ 20% на /var/lib/xenon):
df -h /var/lib/xenon

  1. Запуск диагностики

    • Выполнить xenon-diag с нужным режимом (см. п. 4.3).
    • Сохранить выходные данные в архив (/var/log/xenon/diag/YYYYMMDD_HHMM.tar.gz).

  2. Анализ результатов

    • Проверить код возврата (см. табл. 4.3.1).
    • При коде ≥ 1 — свериться с таблицей ошибок (прил. A).
    • При выявлении проблем — выполнить рекомендации из раздела 4.2.

  3. Завершение

    • Отключить режим обслуживания (PUT /api/v1/maintenance?enable=false).
    • Заархивировать отчёт и передать в систему учёта инцидентов (Jira, проект XC-OPS).

Квалификационные требования к персоналу​

  • Инженер по эксплуатации (категория не ниже 2-й),
  • Допуск к консоли управления,
  • Опыт работы с kubectl, systemd, journalctl (см. примеры диагностики в разделе и в FAQ выше).
  • Знание принципов распределённых систем (кворум, репликация, шардирование).

3. Требования к техническим средствам​

Программа xenon-diag может быть запущена на любом узле кластера XenonCache, где установлен агент xenon-agent >= 2.1.0. Минимальная конфигурация:

КомпонентТребованиеОбоснование
Операционная системаUbuntu 22.04 LTS / Rocky Linux 9 / RHEL 9Поддержка systemd, cgroup v2
Ядро Linux≥ 5.15Требуется io_uring и memfd_create
Процессорx86_64 или arm64/v8, 2+ ядраПараллельная проверка шардов
Оперативная память4 ГБ (при кластере ≤ 10 узлов)Буферизация метаданных диагностики
Дисковое пространство1 ГБ свободно на /varЛоги, временные файлы, отчёты
Сетевые интерфейсыlo, активный eth0, IPv4/IPv6Внутрикластерная коммуникация
Зависимостиbash ≥ 4.4, jq ≥ 1.6, curl ≥ 7.74, python3.10см. проверку ниже
ПраваПользователь xenon в группах adm, dockerБезопасный доступ к сокетам

Проверка зависимостей на хосте:

bash --version
jq --version
curl --version
python3 --version

⚠ Примечание: Запуск от root запрещён — capabilities задаются в unit-файле (см. блок "Меры безопасности" выше).

4. Описание функций​

4.1. Максимальный состав технических средств, проверяемых программой​

Программа xenon-diag поддерживает диагностику следующих компонентов:

КомпонентМаксимальная конфигурацияПримечание
Узлы XenonCacheдо 64 узлов в одном кластереТопология: mesh или star
Хранилищаmem://, ssd://, nvme://, ramdisk://Только локальные устройства
Сетевые интерфейсыдо 8 интерфейсов на узелВключая VLAN, VRF
Внешние сервисыconsul, etcd, prometheus, lokiТолько read-only проверки подключения
ОборудованиеSMART-статус дисков, температура CPU (через ipmi-sensors)При наличии ipmi и прав sudo diag-ipmi

4.2. Совместное функционирование и обработка ошибок​

Программа работает в два этапа:

  1. Сбор метаданных
    Выполняется параллельно по всем узлам через gRPC-канал к xenon-agent.
    Запросы:

    • /healthz (HTTP 200 OK),
    • /metrics?name=alloc_bytes (Prometheus-формат),
    • GET /v1/shards?state=all (состояние шардов).

  2. Исполнение проверок
    На каждом узле запускаются локальные скрипты (в chroot-окружении):

    • Проверка целостности индексов (crc32 хэш-свёртка),
    • Тест latency: 10 000 GET → SET → DEL (в памяти),
    • Проверка диска:
fio --name=diag --rw=randread --bs=4k --size=64M

Метод обработки ошибок:

Тип ошибкиОбработка
Сетевая недоступность узлаПовтор 2 раза с backoff=2^i * 500ms. При 3 отказах — статус UNREACHABLE, исключить из диагностики, отправить alert.
Несовпадение контрольной суммыЗаписать в отчёт checksum_mismatch: {shard_id, expected, actual}. Рекомендуется xenon-repair --shard <id>.
Таймаут операции (> 30s)Прервать поток, зафиксировать timeout_in_phase: <phase_name>, продолжить остальные проверки.
Отказ оборудования (SMART Reallocated_Sector_Ct > 0)Установить статус HW_DEGRADED, рекомендовать замену диска в ближайшие 72 ч.

✅ Все ошибки логируются в структурированном формате JSON (см. 4.3).

4.3. Организация входных и выходных данных​

Входные данные​
  • CLI-аргументы:
  xenon-diag \
    --mode <quick|full> \
    --nodes <node1,node2,...|all> \
    --timeout <sec> \
    --output <json|text|both> \
    --log-level <error|warn|info|debug>
  • Переменные окружения (приоритет ниже CLI):
  XENON_DIAG_MODE=full
  XENON_DIAG_NODES=all
  XENON_DIAG_OUTPUT_DIR=/var/log/xenon/diag
Выходные данные​
  • Стандартный вывод (stdout): краткий отчёт в text (если --output=text или both).
  • Файл <timestamp>.json: полный отчёт в формате:

Код ITЗагрузка примера кода…

Коды возврата​
КодЗначениеДействие
0Все проверки пройденыШтатная работа
1Предупреждения (нестабильность, деградация)Проверить логи, запланировать вмешательство
2Критические ошибки (потеря данных, неработоспособность узла)Немедленное вмешательство
3Ошибки среды (недостаточно прав, отсутствуют зависимости)Исправить окружение, повторить
255Внутренняя ошибка программыОбратиться к разработчикам, приложить лог --log-level=debug

4.4. Взаимодействие устройств с программой и вывод результатов​

  • Программа не модифицирует состояние системы — только чтение и временные операции в памяти.
  • Взаимодействие с оборудованием:
    • Диски — только чтение SMART (без записи на устройство):
smartctl -a /dev/sda
smartctl -H /dev/nvme0
  • Сеть: через AF_PACKET сокеты (только recv для latency-проверок),
  • CPU: через /proc/cpuinfo, /sys/class/thermal.
  • Результаты выводятся:
    • В stdout (если --output=text),
    • В файлы *.json и *.log (автоматически, в XENON_DIAG_OUTPUT_DIR),
    • В syslog (приоритет LOG_NOTICE для exit_code=0, LOG_ERR — для ≥2),
    • В Prometheus Pushgateway (если PUSHGATEWAY_URL задан): метрика xenon_diag_last_run_status{mode="full"} = 0|1|2.

📌 Пример вывода stdout (--mode quick):

[INFO] XenonDiag v2.1.3 starting (mode=quick, nodes=12)
[OK] node-01..node-06: latency < 2ms
[OK] node-07: skipped (maintenance mode)
[WARN] node-08: disk I/O latency 15ms (threshold=10ms)
[OK] All shards healthy (96/96)
[SUMMARY] exit_code=1 (warnings present)

5. Проверочный чек-лист по заполнению РТО​

Используйте этот список до сдачи документа в версионирование. Каждый пункт — обязательное требование ГОСТ или критически важная практика.

✅ Структура и оформление​

  • Титульный лист содержит наименование, обозначение, дату, разработчика
  • Аннотация присутствует (3–5 предложений), отражает назначение и аудиторию
  • Содержание актуально и соответствует нумерации разделов
  • Все разделы пронумерованы по ГОСТ 19.105-78 (1, 1.1, 1.2, …)
  • Документ оформлен в соответствии с корпоративным стилем (шрифты, поля, колонтитулы)

✅ Содержание по требованиям ГОСТ 19.508-79​

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

✅ Техническая точность и безопасность​

  • Все версии ПО/ОС/зависимостей указаны точно, с ограничениями (>=, <)
  • Приведены коды возврата с расшифровкой
  • Есть хотя бы один рабочий пример запуска (CLI или HTTP)
  • Указаны требования к квалификации персонала
  • Присутствуют меры безопасности (права, режимы запуска, запреты)
  • Все действия обратимы или идемпотентны (если применимо)

✅ Актуальность и поддержка​

  • В титуле/шапке указана актуальная версия системы, для которой документ применим
  • Есть ссылка на процесс актуализации (например: "Обновляется при каждом minor-релизе")
  • Документ прошёл техническое ревью разработчиком и эксплуатацией
  • Протестирован на стенде ("сухой прогон" инструкций)

📎 Совет — интегрируйте этот чек-лист в CI/CD — при пуше в docs/ — запускайте markdownlint, vale, и семантическую проверку по шаблону (например, через jq на наличие ключевых полей в метаданных).

Дополнение — регулярное обслуживание без потерь​

Ежедневный, еженедельный и ежемесячный цикл​

  • Ежедневно — health-check, проверка очередей, проверка последних ошибок.
  • Еженедельно: тест восстановления из резервной копии на стенде.
  • Ежемесячно: ревизия порогов мониторинга и регламентов обслуживания.

Критерий качества обслуживания​

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

Смежные материалы​

Содержание