From 16f6c0484c8d0a5994d237e5a12c517470ff7d31 Mon Sep 17 00:00:00 2001 From: Roman Buryan Date: Fri, 25 Sep 2026 20:17:00 +0300 Subject: [PATCH] docs: add DR plan v1 (4 scenarios: CT155, CT151, VPS, pve) --- docs/dr-plan.md | 295 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/dr-plan.md diff --git a/docs/dr-plan.md b/docs/dr-plan.md new file mode 100644 index 0000000..cf6966d --- /dev/null +++ b/docs/dr-plan.md @@ -0,0 +1,295 @@ +# Disaster Recovery Plan — Matrix / buryan-hub + +**Дата:** 2026-09-25 +**Область:** Matrix (Synapse, Element, Coturn, LiveKit) + Postgres CT 151 +**Статус:** Черновик v1 (покрывает 4 сценария отказа) + +--- + +## 1. Область применения + +План описывает восстановление **Matrix-стека** после отказов разного масштаба — от падения одного контейнера до смерти всего pve-хоста. + +**Что покрыто:** +- CT 155 (Synapse, Element, Coturn, LiveKit) +- CT 151 (Postgres `matrix_db`) +- VPS (nginx, edge) +- pve-хост целиком + +**Что НЕ покрыто (отдельные DR-планы в бэклоге):** +- Authentik (CT 114) — SSO для Matrix критичен, но план отдельный +- Gitea (CT 140), n8n (CT 108), Vaultwarden (CT 109) — не блокируют Matrix +- Headscale — VPN, восстановление отдельно + +--- + +## 2. Целевые RTO / RPO + +| Метрика | Цель | Комментарий | +|---|---|---| +| **RTO** (Recovery Time Objective) | 2 часа | За это время Matrix должен снова работать | +| **RPO** (Recovery Point Objective) | 24 часа | Допустима потеря до суток переписки (бэкап раз в сутки в 03:30) | + +**Обоснование RPO:** локальный pg_dump раз в сутки + offsite restic раз в сутки. Более частый бэкап — в бэклоге (по мере роста нагрузки). + +--- + +## 3. Сценарий A — CT 155 (Synapse) упал + +**Приоритет:** 🔴 самый частый +**Симптомы:** +- Element не подключается к `matrix.buryans.ru` (502/503 от nginx) +- `pct status 155` → `stopped` +- `docker ps` в CT 155 пуст или контейнеры в `Restarting` +- В логах Synapse — `FATAL`, `OOM`, `database connection refused` + +### Диагностика (5–10 мин) + + # 1. Статус контейнера + pct status 155 + + # 2. Если running — что с Docker + pct exec 155 -- docker ps -a + pct exec 155 -- docker logs --tail 100 matrix-synapse + + # 3. Если stopped — почему + pct exec 155 -- journalctl -n 100 --no-pager 2>/dev/null + pct list | grep 155 + + # 4. Место на диске + pct exec 155 -- df -h + + # 5. Доступность Postgres + pct exec 155 -- nc -zv 192.168.1.151 5432 + +### Восстановление + +**A1. Контейнер running, но Synapse в рестарте:** + + pct exec 155 -- docker logs --tail 200 matrix-synapse | grep -iE 'error|fail|fatal' + + # Частые причины: + # - Диск заполнен → pct exec 155 -- df -h; чистить /var/log, /opt/matrix/data/media_store + # - Postgres недоступен → идти в Сценарий B + # - YAML сломан → проверить синтаксис + + pct exec 155 -- bash -c 'cd /opt/matrix && docker compose restart synapse' + pct exec 155 -- docker logs --tail 50 -f matrix-synapse + +**A2. Контейнер stopped:** + + pct start 155 + sleep 10 + pct exec 155 -- bash -c 'cd /opt/matrix && docker compose up -d' + pct exec 155 -- docker ps --format 'table {{.Names}}\t{{.Status}}' + +**A3. CT 155 полностью потерян:** + + # 1. Создать новый CT 155 с тем же IP (192.168.1.155) + # 2. Восстановить данные из локального бэкапа на pve + ls -la /root/matrix-backups/config/ + ls -la /root/matrix-backups/files/ + ls -la /root/matrix-backups/pg/ + + # 3. Развернуть стек с нуля + bash ~/buryan-infra/deploy-matrix-v2.sh + # При запросе OIDC — взять client_id/secret из Authentik (Vaultwarden) + +### Проверка (5 мин) + + # 1. Synapse отвечает + pct exec 155 -- curl -sS http://localhost:8008/_matrix/client/versions | head -c 100 + + # 2. Element открывается + curl -sS -o /dev/null -w "%{http_code}\n" https://element.buryans.ru/ + + # 3. .well-known отдаёт JSON + curl -sS https://matrix.buryans.ru/.well-known/matrix/server + + # 4. Юзер заходит в Element (реальный тест) + +--- + +## 4. Сценарий B — CT 151 (Postgres) упал + +**Приоритет:** 🟡 +**Симптомы:** +- Synapse в логах: `could not connect to server`, `connection refused` к `192.168.1.151:5432` +- `pct status 151` → `stopped` или Postgres не отвечает +- Все сервисы на CT 151 лежат (Mealie, Immich, Nextcloud и т.д.) + +### Диагностика + + pct status 151 + pct exec 151 -- ss -tlnp | grep 5432 + pct exec 151 -- journalctl -u postgresql -n 100 --no-pager + pct exec 151 -- tail -100 /var/log/postgresql/postgresql-17-main.log + pct exec 151 -- df -h + +### Восстановление + +**B1. Postgres упал, но CT жив:** + + pct exec 151 -- systemctl restart postgresql + sleep 5 + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db -tAc "SELECT COUNT(*) FROM users;" + +**B2. БД matrix_db повреждена:** + + # 1. Последний локальный бэкап + ls -lt /root/matrix-backups/pg/ | head -5 + + # 2. Если локальный недоступен — из restic + export RESTIC_REPOSITORY="sftp:root@100.64.0.2:/backup/restic-repo" + export RESTIC_PASSWORD_FILE="/root/.restic-password" + restic snapshots --tag pve-matrix-backups + + # 3. Восстановить во временную БД + LATEST=$(ls -t /root/matrix-backups/pg/matrix_db-*.sql.gz | head -1) + pct exec 151 -- sudo -u postgres psql -P pager=off -c "DROP DATABASE IF EXISTS matrix_db_restore_test;" + pct exec 151 -- sudo -u postgres psql -P pager=off -c "CREATE DATABASE matrix_db_restore_test OWNER matrix;" + zcat "$LATEST" | pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db_restore_test + + # 4. Сравнить количество таблиц (ожидаем 169) + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db_restore_test -tAc \ + "SELECT COUNT(*) FROM pg_tables WHERE schemaname='public';" + + # 5. Переключить + pct exec 155 -- bash -c 'cd /opt/matrix && docker compose stop synapse' + pct exec 151 -- sudo -u postgres psql -P pager=off -c "ALTER DATABASE matrix_db RENAME TO matrix_db_broken_$(date +%Y%m%d);" + pct exec 151 -- sudo -u postgres psql -P pager=off -c "ALTER DATABASE matrix_db_restore_test RENAME TO matrix_db;" + pct exec 155 -- bash -c 'cd /opt/matrix && docker compose start synapse' + +**B3. CT 151 потерян целиком:** +Поднять новый CT с IP 192.168.1.151, установить Postgres 17, создать БД и юзера (пароль из `/root/.matrix-pg-pass`), восстановить pg_dump из бэкапа (см. B2). + +### Проверка + + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db -tAc "SELECT COUNT(*) FROM users;" + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db -tAc "SELECT COUNT(*) FROM pg_tables WHERE schemaname='public';" + pct exec 155 -- curl -sS http://localhost:8008/_matrix/client/versions | head -c 50 + +--- + +## 5. Сценарий C — VPS упал + +**Приоритет:** 🟡 +**Симптомы:** +- `matrix.buryans.ru`, `element.buryans.ru` не открываются из интернета +- Из локальной сети — работают +- `ssh root@193.233.210.184` — не подключается + +### Диагностика + + ping -c 3 193.233.210.184 + ssh -o ConnectTimeout=5 root@193.233.210.184 'uptime' + ssh root@193.233.210.184 'systemctl status nginx' + ssh root@193.233.210.184 'nginx -t' + +### Восстановление + +**C1. nginx упал:** + + ssh root@193.233.210.184 'systemctl restart nginx' + ssh root@193.233.210.184 'systemctl status nginx' + +**C2. Сертификаты истекли:** + + ssh root@193.233.210.184 'certbot renew --dry-run' + ssh root@193.233.210.184 'certbot renew' + ssh root@193.233.210.184 'systemctl reload nginx' + +**C3. VPS потерян целиком:** +Восстановить nginx + LE-сертификаты, прописать DNS на новый IP. **Внимание:** конфиги nginx не в git (пробел в DR, см. §7). + +### Проверка + + curl -sS -o /dev/null -w "%{http_code}\n" https://matrix.buryans.ru/ + curl -sS -o /dev/null -w "%{http_code}\n" https://element.buryans.ru/ + curl -sS https://matrix.buryans.ru/.well-known/matrix/server + +--- + +## 6. Сценарий D — pve мёртв целиком + +**Приоритет:** 🔴 самый тяжёлый +**Симптомы:** +- `ssh root@192.168.1.10` — не подключается +- Все CT недоступны +- pve не стартует (диск, железо, питание) + +### Что уцелеет + +| Ресурс | Уцелеет? | Где | +|---|---|---| +| Matrix Postgres (pg_dump) | ⚠️ | `/root/matrix-backups/` — погибнет с pve | +| Matrix Postgres (offsite) | ✅ | vps `100.64.0.2:/backup/restic-repo` | +| media_store, uploads | ✅ | offsite restic | +| homeserver.yaml, signing.key | ✅ | offsite restic | +| Секреты (`/root/.matrix-pg-pass` и др.) | ❌ | только на pve → пробел | +| nginx-конфиги (vps) | ✅ | на vps | +| Authentik (CT 114) | ❌ | погибнет → SSO сломается | +| Gitea, n8n, Vaultwarden | ❌ | погибнут | + +### Восстановление (высокоуровнево) + + # 1. Поднять новый pve-хост + # 2. Восстановить CT 151 (Postgres) — см. §4 B3 + # 3. Восстановить CT 155 (Synapse) — см. §3 A3 + # 4. Восстановить CT 114 (Authentik) — отдельный DR-план (в бэклоге) + # 5. Восстановить остальные CT — отдельные планы + + # 6. Matrix-данные из offsite restic: + export RESTIC_REPOSITORY="sftp:root@100.64.0.2:/backup/restic-repo" + export RESTIC_PASSWORD_FILE="/root/.restic-password" + restic snapshots --tag pve-matrix-backups + restic restore --target /tmp/restore-from-vps + +**Критично:** пароли `restic` и `Postgres` живут только на pve. Без них восстановление невозможно. До переезда в Vaultwarden — сохранить их в защищённом офлайн-месте (сейф, менеджер паролей на отдельном устройстве). + +### Проверка + +- Matrix открывается +- Все юзеры на месте +- История — до последнего бэкапа +- SSO работает (если Authentik восстановлен) + +--- + +## 7. Точки отказа (что НЕ покрыто) + +| Пробел | Риск | Решение | +|---|---|---| +| Секреты только на pve | 🔴 pve умер → восстановление невозможно | Перенести в Vaultwarden | +| nginx-конфиги не в git | 🟡 VPS умер → вручную | Вынести в `buryan-infra/nginx/` | +| Authentik DR-плана нет | 🔴 pve умер → SSO не работает | Написать отдельный план | +| `deploy-matrix-v2.sh` не воспроизводит Element/LiveKit | 🟡 CT 155 умер → вручную | Дописать скрипт | +| `restore-test.sh` без push-токена | 🟡 молчит при сбое | Настроить в `infra-monitoring` | +| Offsite restic через DERP | 🟡 медленно, но работает | UDP 41641 — в бэклоге | + +--- + +## 8. Регулярные учения + +| Что | Периодичность | Как | +|---|---|---| +| Restore-test БД | Каждое воскресенье, 06:00 | Cron `0 6 * * 0` (настроен) | +| Проверка restic-снапшотов | Раз в месяц | `restic snapshots --tag pve-matrix-backups` | +| Симуляция «CT 155 умер» | Раз в квартал | На тестовом CT | +| Симуляция «pve умер» | Раз в полгода | На копии, из offsite | +| Обновление DR-плана | После каждого инцидента | PR в `buryan-infra` | + +--- + +## 9. Контакты и ссылки + +- **Runbook:** `docs/matrix-sprint-runbook.md` +- **Backlog:** `docs/backlog-matrix.md` +- **AGENTS.md:** `AGENTS.md` +- **Gitea:** `git.buryans.ru/root/buryan-infra` + +--- + +**Автор:** Роман + Claude +**Дата:** 2026-09-25 +**Версия:** v1 (черновик)