> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Обслуживание и безопасность

> Бэкапы, техработы, бан-система, чёрный список, ротация логов

## Бэкапы

### Автоматические бэкапы

Бот автоматически создаёт резервные копии базы данных по расписанию.

```env theme={null}
BACKUP_AUTO_ENABLED=true
BACKUP_INTERVAL_HOURS=24
BACKUP_TIME=03:00
BACKUP_MAX_KEEP=7
```

При запуске бот рассчитывает следующее время бэкапа от `BACKUP_TIME`, далее повторяет каждые `BACKUP_INTERVAL_HOURS`.

### Содержимое бэкапа

Формат: `.tar.gz` (или `.tar` без сжатия). Архив содержит:

| Компонент | Описание |
| - | - |
| `metadata.json` | Метаданные (время, тип БД, таблицы, записи) |
| `database.sql` / `database.json` | Дамп БД (`pg_dump` или ORM-дамп) |
| `files/` | Конфигурационные файлы (`app-config.json`) |
| `data/` | Снимок директории `data/` |

Покрывает **70+ таблиц** в порядке зависимостей foreign key.

### Ручные бэкапы

Из админ-панели: **"Бэкап-панель"** → **"Создать бэкап"**.

### Отправка в Telegram

```env theme={null}
BACKUP_SEND_ENABLED=true
BACKUP_SEND_CHAT_ID=-100123456789
BACKUP_SEND_TOPIC_ID=123
BACKUP_ARCHIVE_PASSWORD=          # AES-шифрование (опционально)
```

Если указан `BACKUP_ARCHIVE_PASSWORD`, бэкап оборачивается в AES-шифрованный ZIP.

### Восстановление

Два режима:

* **Восстановление (merge)** — данные добавляются/обновляются (upsert по PK)
* **Полная замена** — существующие данные удаляются, затем импорт

Поддерживается загрузка файла бэкапа (`.json`, `.json.gz`, `.tar.gz`) через Telegram (до 50 МБ).

После восстановления PostgreSQL последовательности автоматически синхронизируются (`sync_postgres_sequences()`).

### Настройки бэкапов

| Переменная | По умолчанию | Описание |
| - | - | - |
| `BACKUP_AUTO_ENABLED` | `true` | Автобэкапы |
| `BACKUP_INTERVAL_HOURS` | `24` | Интервал (часы) |
| `BACKUP_TIME` | `03:00` | Время первого бэкапа |
| `BACKUP_MAX_KEEP` | `7` | Максимум хранимых файлов |
| `BACKUP_COMPRESSION` | `true` | Сжатие gzip |
| `BACKUP_INCLUDE_LOGS` | `false` | Включать MonitoringLog |
| `BACKUP_LOCATION` | `/app/data/backups` | Директория хранения |
| `BACKUP_SEND_ENABLED` | `true` | Отправка в Telegram |
| `BACKUP_SEND_CHAT_ID` | — | ID чата для бэкапов |
| `BACKUP_SEND_TOPIC_ID` | — | ID топика |
| `BACKUP_ARCHIVE_PASSWORD` | — | Пароль AES-шифрования |

## Режим техработ

### Принцип работы

Глобальный `MaintenanceMiddleware` перехватывает все запросы:

* Если техработы активны — пользователь видит сообщение, запрос блокируется
* Администраторы обходят блокировку

### Ручное управление

Из админ-панели: включение с указанием причины (или без — `/skip`).

### Автоматический режим

Мониторинг API RemnaWave с автоматическим включением/выключением:

1. Фоновая задача проверяет доступность API каждые `MAINTENANCE_CHECK_INTERVAL` секунд
2. При каждой проверке пытается подключиться к RemnaWave (до `MAINTENANCE_RETRY_ATTEMPTS` попыток)
3. **API доступен**: сбрасывает счётчик ошибок. Если техработы были автовключены — автоотключает
4. **API недоступен**: увеличивает счётчик. После 3 последовательных сбоев — автовключает техработы

### Панель администратора

| Действие | Описание |
| - | - |
| Включить/Выключить | Ручное управление |
| Запустить/Остановить мониторинг | Управление фоновой проверкой |
| Принудительная проверка | Немедленная проверка API |
| Статус панели | Детальная информация (время ответа, ноды, пользователи) |
| Ручное уведомление | Отправка уведомления с выбранным типом и текстом |

### Настройка

| Переменная | По умолчанию | Описание |
| - | - | - |
| `MAINTENANCE_MODE` | `false` | Начальное состояние при запуске |
| `MAINTENANCE_CHECK_INTERVAL` | `30` | Интервал проверки API (секунды) |
| `MAINTENANCE_AUTO_ENABLE` | `true` | Автовключение после 3 сбоев |
| `MAINTENANCE_MONITORING_ENABLED` | `true` | Мониторинг при запуске бота |
| `MAINTENANCE_RETRY_ATTEMPTS` | `1` | Попытки на одну проверку |
| `MAINTENANCE_MESSAGE` | `Ведутся технические работы...` | Сообщение для пользователей |

## Система бан-интеграции (BedolagaBan)

Интеграция с внешней системой мониторинга BedolagaBan для контроля злоупотреблений.

### Типы уведомлений

| Тип | Описание |
| - | - |
| `punishment` | Блокировка за превышение лимита устройств |
| `enabled` | Разблокировка пользователя |
| `warning` | Предупреждение |
| `network_wifi` | Блокировка за использование WiFi |
| `network_mobile` | Блокировка за использование мобильной сети |

Уведомления приходят через FastAPI endpoint `POST /ban-notifications/send` и пересылаются пользователю.

### Шаблоны сообщений

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

| Переменная | Плейсхолдеры |
| - | - |
| `BAN_MSG_PUNISHMENT` | `{ip_count}`, `{limit}`, `{ban_minutes}`, `{node_info}` |
| `BAN_MSG_ENABLED` | — (статический текст) |
| `BAN_MSG_WIFI` | `{ban_minutes}`, `{network_info}`, `{node_info}` |
| `BAN_MSG_MOBILE` | `{ban_minutes}`, `{network_info}`, `{node_info}` |
| `BAN_MSG_WARNING` | `{warning_message}` |

#### Типизированные шаблоны по причине бана

С `v4.1.0` шаблон выбирается по причине, которую прислал BedolagaBan:

| Переменная | Причина |
| - | - |
| `BAN_MSG_REVOKE` | Ключи доступа обновлены |
| `BAN_MSG_TORRENT` | Торренты |
| `BAN_MSG_HWID_LIMIT` | Превышен лимит устройств |
| `BAN_MSG_SUSPICIOUS_DESTINATION` | Подозрительное направление трафика |
| `BAN_MSG_TRAFFIC_LIMIT` | Превышен лимит трафика |
| `BAN_MSG_MANUAL` | Ручной бан администратором |

> [!NOTE]
>
> Общий выключатель `ENABLE_NOTIFICATIONS` действует и на типизированные баны: при выключенных уведомлениях они не отправляются.

### Настройка

| Переменная | По умолчанию | Описание |
| - | - | - |
| `BAN_SYSTEM_ENABLED` | `false` | Включить интеграцию |
| `BAN_SYSTEM_API_URL` | — | URL BedolagaBan API |
| `BAN_SYSTEM_API_TOKEN` | — | Bearer-токен авторизации |
| `BAN_SYSTEM_REQUEST_TIMEOUT` | `30` | Таймаут запросов (секунды) |

## Чёрный список

Глобальный чёрный список Telegram ID, загружаемый из GitHub.

### Как работает

1. `BlacklistMiddleware` проверяет каждый запрос
2. Если пользователь в списке — показывается "Доступ запрещён" с причиной
3. Результаты кэшируются в памяти на 5 минут
4. Список автообновляется с GitHub каждые `BLACKLIST_UPDATE_INTERVAL_HOURS`

### Формат файла

```
# Комментарии начинаются с #
7021477105 #@username, причина блокировки
1234567890 @another_user, перепродажа подписок
```

### Настройка

| Переменная | По умолчанию | Описание |
| - | - | - |
| `BLACKLIST_CHECK_ENABLED` | `false` | Включить проверку |
| `BLACKLIST_GITHUB_URL` | *(URL к blacklist.txt)* | URL файла на GitHub |
| `BLACKLIST_UPDATE_INTERVAL_HOURS` | `24` | Интервал обновления |
| `BLACKLIST_IGNORE_ADMINS` | `true` | Игнорировать администраторов |

## Защита имён (Banwords)

`DisplayNameRestrictionMiddleware` блокирует пользователей с подозрительными именами:

| Проверка | Описание |
| - | - |
| Символ `@` | Блокировка имён с `@` или `＠` |
| Ссылки | `t.me/+`, `joinchat`, `https://`, `www.`, `tg://` |
| Обфускация доменов | Варианты вроде `t . m e`, кириллические подмены |
| Нормализация символов | Кириллические а→a, е→e, о→o и т.д. |
| Запрещённые слова | Из `DISPLAY_NAME_BANNED_KEYWORDS` |

```env theme={null}
DISPLAY_NAME_BANNED_KEYWORDS=tme,joingroup,support,admin
```

## Очистка неактивных пользователей

Бот автоматически удаляет пользователей, которые не проявляли активность дольше `INACTIVE_USER_DELETE_MONTHS` месяцев.

При определении неактивности учитываются два фактора:

* **Дата последней активности** — последнее взаимодействие с ботом
* **Дата окончания подписки** (`end_date`) — пользователь с активной или недавно истёкшей подпиской не будет удалён, даже если давно не заходил в бота

| Переменная | По умолчанию | Описание |
| - | - | - |
| `INACTIVE_USER_DELETE_MONTHS` | `3` | Период неактивности для удаления (месяцы) |

> [!NOTE]
>
> Пользователь считается неактивным только если и дата последней активности, и дата окончания подписки старше порога. Это предотвращает удаление пользователей с действующими подписками.

## Сканер заблокированных пользователей

Массовая проверка пользователей, заблокировавших бота:

1. Отправляет тестовый запрос каждому пользователю
2. Определяет заблокировавших бот
3. Действия: удалить из БД, из RemnaWave, отметить как заблокированного

## Массовый бан

Массовая блокировка по списку Telegram ID:

* Ввод ID (по одному на строку, через запятую или пробел)
* Максимум 1000 ID за раз
* Каждому отправляется уведомление
* Результаты: заблокировано / ошибки

## Ротация логов

### Автоматическая ротация

```env theme={null}
LOG_ROTATION_ENABLED=true
LOG_ROTATION_TIME=00:00
LOG_ROTATION_KEEP_DAYS=7
LOG_ROTATION_COMPRESS=true
```

Ежедневно в указанное время:

1. Сброс всех обработчиков логов
2. Сбор непустых файлов: `info.log`, `warning.log`, `error.log`, `payments.log`, `bot.log`
3. Создание архива `logs_YYYY-MM-DD.tar.gz`
4. Очистка текущих файлов
5. Удаление старых архивов (> `LOG_ROTATION_KEEP_DAYS`)
6. Опционально — отправка в Telegram

### Отправка в Telegram

```env theme={null}
LOG_ROTATION_SEND_TO_TELEGRAM=true
LOG_ROTATION_CHAT_ID=          # Fallback на BACKUP_SEND_CHAT_ID
LOG_ROTATION_TOPIC_ID=         # Fallback на BACKUP_SEND_TOPIC_ID
```

### Просмотр логов (админ)

Из админ-панели:

* Последние 2300 символов лога в раскрывающемся блоке
* Кнопка обновления
* Скачивание полного файла как Telegram-документ

### Настройки логирования

| Переменная | По умолчанию | Описание |
| - | - | - |
| `LOG_LEVEL` | `INFO` | Уровень логирования |
| `LOG_FILE` | `logs/bot.log` | Основной лог-файл |
| `LOG_ROTATION_ENABLED` | `false` | Ротация логов |
| `LOG_ROTATION_TIME` | `00:00` | Время ежедневной ротации |
| `LOG_ROTATION_KEEP_DAYS` | `7` | Хранить архивы (дни) |
| `LOG_ROTATION_COMPRESS` | `true` | Сжатие gzip |
| `LOG_ROTATION_SEND_TO_TELEGRAM` | `false` | Отправка архивов |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.