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

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/`)

---

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

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

|Установка|По умолчанию|Описание|
| --- | --- | --- |
| `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|

---

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

### Руководство пользователя (панель администратора)

Нажмите **Создайте резервную копию прямо сейчас** на странице резервных копий. При этом задание 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
```

---

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

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

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

Процесс:

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 самых последних файлов. Сначала удаляются самые старые.
- If `backups_to_keep = 0`: сохраняет все файлы (неограниченное количество).

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

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

Очистка выполняется автоматически после каждого резервного копирования с помощью `BackupsCronJob`.

---

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

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

Когда параметр `dropbox_remote` включен:

1. После создания локальной резервной копии загрузите ее в Dropbox.
2. Во время загрузки создается файл маркера `.uploading`.
3. В случае успеха: `.uploading` удаляется.
4. On failure: `.error` file is created with the error message.

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

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

Методы:

```php
BackupService::checkRemoteConnection()        // validate Dropbox token
BackupService::uploadRemote($path, $filename, $overwrite = true)  // upload backup
BackupService::downloadRemote($path, $filename) // download backup
BackupService::deleteRemote($path)             // delete remote backup
BackupService::getRemote()                     // list remote backups
```

---

## Команды CLI

### cron:резервные копии

Автоматическое задание 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  # force
```

### миграция инструментов

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

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

### база данных инструментов - подтвердите

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

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

### инструменты mysql

Повторная авторизация подсистем балансировки нагрузки на MySQL:

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

---

## Конечная точка API

Действие: `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` |Инструменты миграции командной строки и базы данных|
| `src/Public/Views/admin/backups.php` |пользовательский интерфейс панели администратора|
| `src/Public/Views/admin/api.php` |Обработчик конечной точки API|
| `src/Public/Controllers/Admin/BackupsController.php` |административный контроллер|