Руководство для оператора self-hosted-инсталляции. Версия продукта — файл VERSION в корне репозитория. Все пути — относительно каталога установки (корня репозитория на сервере).
Что бэкапить и что будет, если потерять.
| Актив | Путь | Что случится при потере | Как бэкапить |
|---|---|---|---|
| База данных 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.
| Переменная | Умолчание | Что означает |
|---|---|---|
ROUTINEOPS_SCREEN_TENANT_MAX_BYTES |
20GiB |
Сколько места занимают ВСЕ записи одного тенанта. Исчерпан — новый сеанс не начинается: наблюдение без улики запрещено контрактом, отказ честнее. |
ROUTINEOPS_SCREEN_SESSION_MAX_BYTES |
512MiB |
Потолок одной записи на профиле low. Для более широких профилей масштабируется автоматически, чтобы сохранялась предельная длительность сеанса, а не число байт. |
Принимаются суффиксы GiB/MiB/KiB (двоичные) и GB/MB/KB (десятичные); голое
число — байты. Непонятное значение не роняет сервер: в лог уходит предупреждение, берётся
умолчание.
🔴 Поднимать эти числа приходится не ради диска. Упор в потолок обрывает запись, а сеанс
с управлением при обрыве записи прекращается на месте (§9.21 п.2 контракта удалённого
стола) — то есть слишком низкая квота выглядит для оператора как «сеанс поддержки
разорвался посреди работы». При профиле medium тот же объём набирается заметно быстрее,
чем при low.
Всё делает 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дополнительно дампит БД перед каждым обновлением — это снимок перед миграциями, а не замена расписанию: нет апдейтов неделю, нет и копии за неделю.
Сценарий: сервер умер, есть бэкап-набор из раздела 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 за несколько минут.
Одна команда:
./update.shЧто делает (в этом порядке):
- Автобэкап БД в
backups/db-<время>.dump— обязателен, потому что… git pull --ff-only— новая версия кода.- Пересборка контейнеров; migrate-сервис накатывает pending-миграции до старта server (fail-closed: миграция не прошла — server не стартует).
- Пересборка и публикация бинарей агента (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.
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должен жить дольше сервера — бэкапьте.
Сервер:
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.
Бот свой у каждой инсталляции — общего бота RoutineOps нет и быть не может: токен даёт полный доступ к переписке бота, поэтому один бот на всех означал бы, что чужой сервер читает ваши алерты.
Настройка:
- В Telegram напишите @BotFather →
/newbot→ задайте имя и username (напримерAcmeRoutineOps_bot). - Положите выданный токен в
TELEGRAM_BOT_TOKENв.env.prodи перезапустите сервер. - Каждый администратор в панели жмёт «Подключить Telegram», получает одноразовый токен привязки и отправляет боту
/start <токен>.
Имя бота сервер узнаёт сам через Bot API (getMe) и подставляет ссылку в панель — вшивать его в конфиг или код не нужно. Если ссылки нет, значит TELEGRAM_BOT_TOKEN не задан либо Telegram недоступен с сервера.
Уведомления получают только пользователи с ролью IT-администратора и привязанным chat_id. Пустой TELEGRAM_BOT_TOKEN полностью отключает бота — сервер стартует без него.