# Стратегия резервного копирования

XC_VM поддерживает автоматические и ручные резервные копии базы данных с локальным хранением и опциональной загрузкой в Dropbox.
Резервные копии управляются через панель администратора, CLI-команды и cron-задачу.

---

## Что попадает в резервную копию

Резервные копии содержат полную структуру и данные базы данных, **кроме** следующих таблиц:

```text
detect_restream_logs, epg_data, lines_activity, lines_live,
lines_logs, login_logs, mag_claims, mag_logs, mysql_syslog,
panel_logs, panel_stats, servers_stats, signals,
streams_errors, streams_logs, streams_stats, syskill_log,
users_credits_logs, users_logs, watch_logs
```

> **Примечание:** Восстановление резервной копии очищает все данные логов. Эти таблицы исключаются, чтобы размер резервной копии оставался управляемым.

Резервные копии **не** включают:

- Данные файловой системы (записи, VOD-файлы, EPG XML)
- Конфигурационные файлы (`config/`)
- Бинарные зависимости (`bin/`)
- Временные файлы (`tmp/`)

---

## Конфигурация

Настройки находятся в панели администратора в разделе **Backups**:

| Настройка | По умолчанию | Описание |
| --- | --- | --- |
| `automatic_backups` | `off` | частота: `off`, `hourly`, `daily`, `weekly`, `monthly` |
| `backups_to_keep` | `0` | количество локальных копий (0 = без ограничения) |
| `dropbox_remote` | `0` | включить загрузку в Dropbox |
| `dropbox_keep` | `0` | количество удалённых копий (0 = без ограничения) |
| `dropbox_token` | `''` | API-токен Dropbox |

---

## Создание резервных копий

### Вручную (панель администратора)

Нажмите **Create Backup Now** на странице резервных копий. Это запускает cron-задачу в принудительном режиме:

```bash
/home/xc_vm/console.php cron:backups 1
```

### Автоматически (cron)

Задача `cron:backups` проверяет расписание при каждом запуске:

| Расписание | Интервал |
| --- | --- |
| `hourly` | 3600 с |
| `daily` | 86400 с |
| `weekly` | 604800 с |
| `monthly` | 2419200 с |

Запускается только на основном сервере (`is_main=1`). Использует блокировку на основе PID для предотвращения параллельных запусков.

### Процесс резервного копирования

1. Закрытие подключения к MySQL перед дампом.
2. Запуск `mysqldump --no-data` (структура) + `mysqldump --ignore-table` (данные, без таблиц логов).
3. Проверка размера файла (пустые файлы удаляются).
4. Если Dropbox включён: загрузка с отслеживанием статуса.
5. Применение политики хранения (удаление самых старых файлов сверх лимита).

### Расположение файлов

```text
/home/xc_vm/backups/backup_YYYY-MM-DD_HH:MM:SS.sql
```

---

## Восстановление резервных копий

### Из панели администратора

Нажмите **Restore** напротив записи резервной копии. Требуется подтверждение.

Процесс:

1. Если локальный файл существует — использовать его. Иначе скачать из Dropbox в `/home/xc_vm/tmp/restore.sql`.
2. Удалить и пересоздать базу данных.
3. Импортировать SQL-файл.
4. Повторно сделать дамп структуры после импорта.

```php
BackupService::restore($filename, $config)
```

> **Важно:** Восстановление полностью удаляет базу данных и пересоздаёт её. Все данные, отсутствующие в резервной копии, будут потеряны.

### Из CLI

Для сценариев миграции с выборочным импортом таблиц:

```bash
sudo /home/xc_vm/console.php tools migration /path/to/backup.sql
```

Это восстанавливает копию в базу `xc_vm_migrate` для выборочной миграции данных, а не перезаписывает рабочую базу.

---

## Хранение

### Локальное хранение

- Если `backups_to_keep > 0`: оставляет только N последних файлов. Самые старые удаляются первыми.
- Если `backups_to_keep = 0`: оставляет все файлы (без ограничения).

### Удалённое хранение

- Если `dropbox_keep > 0`: оставляет только N последних файлов в Dropbox. Самые старые удаляются первыми.
- Если `dropbox_keep = 0`: оставляет все удалённые файлы (без ограничения).

Очистка запускается автоматически после каждой резервной копии через `BackupsCronJob`.

---

## Интеграция с Dropbox

Файл: `src/Core/Storage/DropboxClient.php`

Когда `dropbox_remote` включён:

1. После создания локальной копии — загрузка в Dropbox.
2. На время загрузки создаётся маркер-файл `.uploading`.
3. При успехе: `.uploading` удаляется.
4. При сбое: создаётся файл `.error` с текстом ошибки.

Индикаторы статуса в панели администратора:

| Индикатор | Значение |
| --- | --- |
| Зелёный | успешно загружено |
| Жёлтый | загрузка в процессе (< 10 минут) |
| Красный | загрузка не удалась (наведите для сообщения об ошибке) |
| Серый | не загружено |

Методы:

```php
BackupService::checkRemoteConnection()        // проверка токена Dropbox
BackupService::uploadRemote($path, $filename, $overwrite = true)  // загрузка резервной копии
BackupService::downloadRemote($path, $filename) // скачивание резервной копии
BackupService::deleteRemote($path)             // удаление удалённой копии
BackupService::getRemote()                     // список удалённых копий
```

---

## CLI-команды

### cron:backups

Cron-задача автоматического резервного копирования. Может быть принудительно запущена с аргументом `1`:

```bash
sudo -u xc_vm /home/xc_vm/console.php cron:backups
sudo -u xc_vm /home/xc_vm/console.php cron:backups 1  # принудительно
```

### tools migration

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

```bash
sudo /home/xc_vm/console.php tools migration /path/to/backup.sql
```

### tools database --confirm

Сброс до чистой базы данных (уничтожает все данные):

```bash
sudo /home/xc_vm/console.php tools database --confirm
```

### tools mysql

Повторная авторизация балансировщиков нагрузки на MySQL:

```bash
sudo /home/xc_vm/console.php tools mysql
```

---

## API Endpoint

Действие: `backup` (требует право `adv:database`)

| Подкоманда | Описание |
| --- | --- |
| `backup` | запустить немедленную резервную копию (в фоне) |
| `delete` | удалить локальную копию и копию в Dropbox |
| `restore` | восстановить базу данных из резервной копии |

---

## Связанные файлы

| Файл | Назначение |
| --- | --- |
| `src/Core/Backup/BackupService.php` | логика резервного копирования и восстановления |
| `src/Core/Storage/DropboxClient.php` | клиент Dropbox API |
| `src/Cli/CronJobs/BackupsCronJob.php` | cron автоматического резервного копирования |
| `src/Cli/Commands/ToolsCommand.php` | CLI-инструменты миграции и работы с БД |
| `src/Public/Views/admin/backups.php` | UI панели администратора |
| `src/Public/Views/admin/api.php` | обработчик API-эндпоинта |
| `src/Public/Controllers/Admin/BackupsController.php` | контроллер администратора |
