# Устройство backup-master

## Компоненты

```
Старый сервер                     Сервер бэкапов                     Новый сервер
backupctl backup ──PUT части──►   backupctl server                ◄── backupctl restore
 (systemd timer)                  SQLite + файлы, веб-морда            provision.sh → recipes → распаковка → сервисы
                                  ретеншн, ntfy
```

| Пакет | Назначение |
|---|---|
| `internal/manifest` | формат манифеста бэкапа (общий для всех) |
| `internal/catalog` | категории бэкапа: встроенный `default.yaml` + переопределения клиента |
| `internal/archive` | tar (PAX) + zstd: запись, распаковка, исключения, владельцы по имени |
| `internal/api` | протокол и HTTP-клиент |
| `internal/agent` | сбор: files / systemd / xui / compose, дампы, проверка crontab, отправка |
| `internal/restore` | восстановление: provision.sh, recipes бинарников, compose, порядок категорий |
| `internal/server` | API, веб-морда, ретеншн, уведомления |

## Формат архива

Каждая часть — `tar.zst`. В main первой записью идёт `manifest.json`. Пути внутри архива:

- `<cat>/files/<абсолютный путь>` — восстанавливается в `/`;
- `<cat>/dumps/<файл>` — дампы БД и снимок x-ui.db;
- `<cat>/volumes/<том>/…` — именованные docker-тома;
- `<cat>/bin/<абсолютный путь>` — fallback-копии бинарников.

Heavy-часть называется именем категории и устроена так же. Main без неё самодостаточен.

## Протокол

| Метод | Токен | Назначение |
|---|---|---|
| `GET /api/v1/agent/config` | агент | домен, переопределения каталога, пора ли слать heavy |
| `POST /api/v1/backups` | агент | манифест → id |
| `PUT /api/v1/backups/{id}/parts/{name}` | агент | потоковая загрузка части |
| `POST /api/v1/backups/{id}/complete` | агент | sha256/размеры частей + предупреждения архивации |
| `POST /api/v1/backups/{id}/fail` | агент | ошибка |
| `GET /api/v1/restore/manifest[?backup=]` | restore | манифест и доступные части |
| `GET /api/v1/restore/{id}/parts/{name}` | restore | скачивание (Range — докачка) |

Агентский токен даёт только запись: если клиента взломают, злоумышленник не сможет прочитать или удалить его историю. Restore-токен выпускается в морде на 24 часа и даёт только чтение бэкапов одного клиента. В БД хранятся только sha256 токенов.

Агент архивирует часть прямо в тело PUT (`io.Pipe`), временный архив на диске не создаётся. Дампы БД снимаются **до** архивации. Поэтому в Stoat порядок «сначала mongodump, потом файлы MinIO» соблюдается сам собой: файлы, загруженные во время бэкапа, станут лишними объектами без ссылок, но ссылок на отсутствующие файлы не появится.

## Compose

- Проекты берутся из `docker compose ls -a`, к ним добавляются явные `dir` из каталога. Сервисы, bind-mounts и тома — из `docker compose config --format json`.
- БД определяются по образу. Если контейнер запущен, делается дамп через `docker exec`: учётные данные берутся из окружения контейнера, а каталог данных исключается. Если остановлен — каталог данных копируется как есть (он консистентен).
- Данные `rabbitmq` и сервисов из `skip_services` не бэкапятся.
- Записываются digest запущенных образов. При восстановлении создаётся `compose.restore.yml` с `image: repo@sha256:…`, потому что `latest` на новом сервере дал бы другую Mongo/MinIO.
- Отсутствующие external-сети создаются пустыми. Так stoat-mbot поднимается без psiphon.
- Порядок восстановления: `pull` → `build` → `create` → для каждой БД `up -d <db>` → ожидание TCP-готовности → заливка дампа → `up -d`.

## Версии

| Что | Как записывается | Как восстанавливается |
|---|---|---|
| apt-пакеты (caddy, telegraf, docker-ce, docker-compose-plugin) | `dpkg-query` | `provision.sh` ставит `pkg=version`, если версия есть в репозитории |
| 3x-ui, nebula, sing-box-extended | `version_cmd` | recipes в `internal/restore/recipes.go`: release-архивы нужного тега; при неудаче — копия из `bin/` |
| образы compose | digest | `compose.restore.yml` |

## Расширение

- Новая категория — запись в `default.yaml` или в YAML клиента в морде.
- Новый способ установки бинарника — функция в `recipes`, имя указывается в поле `install` категории.
- Новый тип БД в compose — `dbKind`/`dumpCmds` в `internal/agent/compose.go` и `dbReady`/`dbRestore` в `internal/restore/compose.go`.