Skip to content

Latest commit

 

History

History
214 lines (151 loc) · 21.7 KB

operations.md

File metadata and controls

214 lines (151 loc) · 21.7 KB

Эксплуатация: бэкапы, восстановление, ключи

Руководство для оператора self-hosted-инсталляции. Версия продукта — файл VERSION в корне репозитория. Все пути — относительно каталога установки (корня репозитория на сервере).


1. Критичные активы

Что бэкапить и что будет, если потерять.

Актив Путь Что случится при потере Как бэкапить
База данных PostgreSQL docker-volume postgres_data Потеря всех данных: устройства, пользователи, политики, скрипты, аудит, релизы агентов. Инсталляция с нуля. pg_dump -Fc (раздел 2). update.sh делает дамп автоматически перед каждым обновлением.
CA (ca.crt + ca.key) certs/ Потеря только ca.key: парк продолжает работать, но новые устройства не зарегистрировать (enrollment подписывает агентские сертификаты ключом CA) и серверный сертификат не перевыпустить — бомба замедленного действия (срок серверного серта 1 год). Потеря всего CA с перегенерацией: агенты доверяют только старому ca.crt, а сервер (mTLS) — только сертификатам, подписанным старым CA → весь парк теряет связь безвозвратно, лечится только переустановкой/перерегистрацией агентов. ⚠️ Одно и то же действие ведёт из первого случая во второй: scripts/gen-certs.sh на каталоге без ca.key выпускал НОВЫЙ корень поверх старого. Скрипт теперь отказывается это делать, но правило прежнее: без ca.key не запускать перевыпуск, а восстанавливать ключ из бэкапа. Копия каталога certs/ в защищённое хранилище после установки и после любого перевыпуска.
Серверный сертификат (server.crt + server.key) certs/ При живом ca.key перевыпускается (scripts/gen-certs.sh — удалить старую пару, добавить внешний адрес в SAN). Без ca.key — см. выше. Вместе с certs/.
Приватный ключ подписи релизов агента release_ed25519.pem (корень) Потеря не оставляет парк навсегда без обновлений. Восстановление: сгенерировать новую пару → положить новый pubkey в RELEASE_PUBKEY (.env.prod) → перезапустить сервер. Новые энроллменты сразу получают новый ключ; уже развёрнутые агенты держат старый сохранённый ключ (получен при enroll) и не примут релизы, подписанные новым ключом, пока их не переэнроллят — переустановка pkg/msi переэнроллит, бинарь универсальный (тот же пакет). Пересборка под каждый деплой не нужна. Копия в защищённое хранилище + оффлайн-копия (носитель вне сервера): бэкап избавляет от переэнроллмента всего парка.
.env.prod корень Потеря JWT_SECRET (все админ-сессии слетят — терпимо), пароля БД (важен для подключения к существующему volume/дампам), RELEASE_PUBKEY, SMTP-кредов, всей конфигурации. Восстановимо по частям, но болезненно. Копия в защищённое хранилище (файл chmod 600, содержит секреты).
Enrollment-токены БД Не критичны: одноразовые (TTL 24 ч) либо массовые (многоразовые, лимит max_uses/срок настраиваются, отзыв кнопкой). Истёк/потерян — кнопка «Перерегистрировать» или новый bulk-токен в UI. Не требуется.
releases/ корень Не критичен: пересоздаётся пересборкой (update.sh публикует агентов заново). Не требуется.
Записи сеансов удалённого стола (Enterprise) SCREEN_DIR, по умолчанию ./screen-recordings; том ./screen-recordings смонтирован в docker-compose.prod.yml Единственный невосстановимый артефакт: строка сеанса и аудит остаются, а запись — то, ЧТО именно видел оператор, — заново не берётся ниоткуда. Пересоздание контейнера её больше не уносит. Включить каталог в бэкап отдельно (в backup.sh он не входит). Планируйте место: 20-минутный сеанс — десятки-сотни мегабайт, ретеншен 30 дней.

Итого обязательный бэкап-набор: дамп БД + роли кластера + certs/ + release_ed25519.pem + .env.prod (+ license/ и directory/, если применимо). Всё это снимает scripts/backup.sh — раздел 2.

Ёмкость записей сеансов (Enterprise)

Переменная Умолчание Что означает
ROUTINEOPS_SCREEN_TENANT_MAX_BYTES 20GiB Сколько места занимают ВСЕ записи одного тенанта. Исчерпан — новый сеанс не начинается: наблюдение без улики запрещено контрактом, отказ честнее.
ROUTINEOPS_SCREEN_SESSION_MAX_BYTES 512MiB Потолок одной записи на профиле low. Для более широких профилей масштабируется автоматически, чтобы сохранялась предельная длительность сеанса, а не число байт.

Принимаются суффиксы GiB/MiB/KiB (двоичные) и GB/MB/KB (десятичные); голое число — байты. Непонятное значение не роняет сервер: в лог уходит предупреждение, берётся умолчание.

🔴 Поднимать эти числа приходится не ради диска. Упор в потолок обрывает запись, а сеанс с управлением при обрыве записи прекращается на месте (§9.21 п.2 контракта удалённого стола) — то есть слишком низкая квота выглядит для оператора как «сеанс поддержки разорвался посреди работы». При профиле medium тот же объём набирается заметно быстрее, чем при low.


2. Регулярный бэкап

Всё делает scripts/backup.sh — запускайте по расписанию:

cd /path/to/mdm && ./scripts/backup.sh

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

Файл Что внутри Почему обязателен
db-<ts>.dump pg_dump -Fc рабочей базы данные, схема, schema_migrations
globals-<ts>.sql pg_dumpall --globals-only роли кластера и их пароли. В дамп базы они не входят вообще: восстановите одну базу — БД поднимется, а сервер к ней не подключится, потому что роль mdm_app создаётся миграцией без пароля
secrets-<ts>.tar.gz certs/, release_ed25519.pem, .env.prod, license/, directory/ всё gitignored — git clone не восстанавливает ни один секрет

Расписание (cron пользователя, от которого работает Docker; root не нужен):

crontab -e
17 3 * * * cd $HOME/mdm && ./scripts/backup.sh >> backups/backup.log 2>&1
  • Переменные: BACKUP_DIR (по умолчанию ./backups), KEEP — сколько поколений держать (14).
  • 🔴 Копия на том же диске — не бэкап. Выносите BACKUP_DIR на отдельный том и синхронизируйте каталог за пределы хоста: дампы, роли и секреты лежат рядом с тем, от чьей гибели они страхуют.
  • Для release_ed25519.pem заведите дополнительно оффлайн-копию — без бэкапа восстановление ключа требует переэнроллмента всего парка (новый pubkey в .env.prod подхватывается только при переустановке/переэнроллменте устройств).
  • Архив содержит приватные ключи и хеши паролей ролей: доступ — только владельцу, при передаче — шифруйте.
  • update.sh дополнительно дампит БД перед каждым обновлением — это снимок перед миграциями, а не замена расписанию: нет апдейтов неделю, нет и копии за неделю.

3. Восстановление сервера с нуля из бэкапа

Сценарий: сервер умер, есть бэкап-набор из раздела 2. Новый хост — те же требования, что при установке (Docker + Compose v2, см. docs/install.md). Внешний адрес сервера должен остаться прежним (IP/домен зашит в агентах и в SAN сертификата).

# 1. Код
git clone <ваш-репозиторий> mdm && cd mdm

# 2. Вернуть секреты ДО запуска (иначе install.sh сгенерирует новые)
tar xzf /backup/secrets-<дата>.tar.gz            # certs/, release_ed25519.pem, .env.prod

# 3. Поднять стек
set -a; . ./.env.prod; set +a
export VERSION=$(cat VERSION)
docker compose -f docker-compose.prod.yml up -d --build

# 4. Восстановить роли кластера — ДО базы: пароль mdm_app живёт только здесь,
#    без него сервер не подключится к восстановленной БД
docker exec -i "$(docker compose -f docker-compose.prod.yml ps -q postgres)" \
  psql -U mdm -d postgres < /backup/globals-<дата>.sql

# 5. Восстановить БД
docker exec -i "$(docker compose -f docker-compose.prod.yml ps -q postgres)" \
  pg_restore -U mdm -d mdm --clean --if-exists < /backup/db-<дата>.dump

# 6. Перезапустить server, чтобы он работал поверх восстановленных данных
docker compose -f docker-compose.prod.yml restart server

# 7. Перепубликовать бинари агентов (каталог releases/ в бэкап не входит)
./update.sh

Агенты переподключаются сами: CA тот же, их сертификаты по-прежнему валидны, адрес сервера не изменился. Ничего на устройствах делать не нужно.

Проверка: docker compose -f docker-compose.prod.yml ps — всё Up/healthy; вход в веб; устройства в UI выходят из agent_unreachable за несколько минут.


4. Обновление сервера

Одна команда:

./update.sh

Что делает (в этом порядке):

  1. Автобэкап БД в backups/db-<время>.dump — обязателен, потому что…
  2. git pull --ff-only — новая версия кода.
  3. Пересборка контейнеров; migrate-сервис накатывает pending-миграции до старта server (fail-closed: миграция не прошла — server не стартует).
  4. Пересборка и публикация бинарей агента (windows/amd64, linux/amd64, darwin/arm64) с подписью вашим release_ed25519.pem. Парк подтянет новую версию self-update'ом в пределах интервала проверки (по умолчанию 6 ч, docs/self-update.md).

Отката миграций НЕТ. Откат — только восстановлением:

  • Сервер: git checkout <старый-тег> && docker compose -f docker-compose.prod.yml up -d --build.
  • БД (если схема несовместима): pg_restore --clean --if-exists из дампа, снятого на шаге 1 (команда — в разделе 3).
  • Агенты назад не даунгрейдятся (anti-rollback): битый релиз агента чинится выпуском версии вперёд.

Инсталляция, где миграции когда-то катались вручную: перед первым update.sh один раз выполнить scripts/migrate-backfill.sh с BACKFILL_UPTO=<последняя накатанная миграция> — иначе migrate-сервис откажется стартовать (защита от двойного наката). Подробности — docs/self-hosted-deploy.md.


5. Ротация секретов и сроки сертификатов

JWT_SECRET — замена значения в .env.prod + перезапуск server. Инвалидирует все активные админ-сессии (это и есть цель ротации). Пошагово — docs/jwt-secret-rotation.md.

Сроки сертификатов (из scripts/gen-certs.sh и enrollment):

Сертификат Срок
Root CA 10 лет
Серверный 1 год
Агентский (выпускается при enrollment) 1 год

Проверка срока:

openssl x509 -enddate -noout -in certs/ca.crt
openssl x509 -enddate -noout -in certs/server.crt
  • Серверный сертификат — перевыпустить до истечения: остановить стек, mv certs/server.crt certs/server.crt.bak && mv certs/server.key certs/server.key.bak, запустить bash scripts/gen-certs.sh (сгенерирует только серверную пару — CA не тронет), при внешнем адресе не забыть SAN (см. docs/install.md), поднять стек. Агенты доверяют CA, а не конкретному серверному серту — парк не заметит замены.
  • Агентские сертификаты — автоматического продления нет. По истечении агент теряет mTLS-канал; восстановление — «Перерегистрировать» в UI и повторный enrollment на устройстве. Планируйте перерегистрацию парка до годовщины установки агентов.
  • Плановая ротация CA: процедура в разработке. Следите за сроком (10 лет с момента установки); перевыпуск CA сегодня означает переустановку/перерегистрацию всех агентов. Главное практическое следствие: ca.key должен жить дольше сервера — бэкапьте.

6. Мониторинг здоровья

Сервер:

docker compose -f docker-compose.prod.yml ps          # все сервисы Up, postgres/redis healthy,
                                                      # migrate — Exited (0)
docker compose -f docker-compose.prod.yml logs -f server
curl -k https://localhost:8081/healthz                # проверка API с хоста сервера (8081
                                                      # привязан к 127.0.0.1; через 443/nginx
                                                      # /healthz не проксируется)

Признаки проблем:

  • Алерты agent_unreachable в разделе «Алерты»: устройство без heartbeat дольше порога. Порог — AGENT_UNREACHABLE_MINUTES (по умолчанию 10080, т.е. 7 суток), подавление повторов — AGENT_UNREACHABLE_COOLDOWN_MINUTES (по умолчанию 360) в .env.prod. Порог в неделю отсекает выходные, отпуска и отключённый VPN — алерт означает, что машина реально выпала из парка. Массовые unreachable = проблема сервера/сети (проверьте порт 50051 и срок серверного сертификата), единичные — проблема конкретного устройства.
    • Устройство, которое так и не вернулось, повторно алертит примерно раз в DATA_RETENTION_DAYS: эпизодный анти-дубль опирается на строку в alerts, а ретеншен её удаляет. Это напоминание, а не баг; чтобы оно прекратилось — удалите устройство из парка.
  • migrate завершился с ненулевым кодом → server не стартует: docker compose -f docker-compose.prod.yml logs migrate.
  • seed admin failed в логах server при первом запуске — пароль первого администратора не прошёл политику сложности (см. docs/self-hosted-deploy.md).
  • Место на диске: backups/ и postgres_data растут — чистите старые дампы по своей политике хранения.

Логи агента на устройствах:

ОС Путь
Windows %ProgramData%\RoutineOps\logs\agent.log
macOS /Library/Logs/RoutineOps/agent.log
Linux /var/log/RoutineOps-agent/agent.log

Статус службы агента: Get-Service RoutineOps-agent (Windows), launchctl list | grep -i routineops (macOS), systemctl status RoutineOps-agent (Linux). Разбор типовых полевых проблем — docs/field-troubleshooting.md.

7. Telegram-уведомления

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

Настройка:

  1. В Telegram напишите @BotFather → /newbot → задайте имя и username (например AcmeRoutineOps_bot).
  2. Положите выданный токен в TELEGRAM_BOT_TOKEN в .env.prod и перезапустите сервер.
  3. Каждый администратор в панели жмёт «Подключить Telegram», получает одноразовый токен привязки и отправляет боту /start <токен>.

Имя бота сервер узнаёт сам через Bot API (getMe) и подставляет ссылку в панель — вшивать его в конфиг или код не нужно. Если ссылки нет, значит TELEGRAM_BOT_TOKEN не задан либо Telegram недоступен с сервера.

Уведомления получают только пользователи с ролью IT-администратора и привязанным chat_id. Пустой TELEGRAM_BOT_TOKEN полностью отключает бота — сервер стартует без него.