HELPER Discord Bot
BACKUP CORE // OWNER ONLY // SQLITE SAFE

HELPER BACKUP РЕЗЕРВНЫЙ КОНТУР FULL ZIP / GUILD EXPORT / OWNER DM / AUTO MODE

Модуль резервного копирования — это закрытая owner-система HELPER. Он создаёт архивы data / banners / backgrounds, делает безопасные SQLite-снимки, умеет выгружать данные конкретного сервера, отправляет zip владельцам в ЛС и сохраняет техническую meta-информацию.

Показать визуально Команды owner Dashboard preview
ZIPполный архив
Guildserver export
SQLitesafe snapshot
DMowner delivery
Owner onlyдоступ через OWNER_IDS
Full backupdata / banners / backgrounds
Guild exportданные одного сервера
Safety.env и логи не попадают
Auto modeрасписание через .env
// MODULE_PURPOSE

Что делает Backup Core

Backup Core закрывает технический риск: перед деплоем или крупными изменениями owner может сохранить рабочее состояние HELPER. Архив строится синхронным builder-слоем, а Discord cog отвечает за owner-проверку, lock, отправку и статус.

01

Собирает архив

В полный backup входят папки data, banners и backgrounds.

02

Фильтрует мусор

.env, логи, кэш, zip, lock и sidecar SQLite файлы исключаются.

03

Шлёт owner

Если размер проходит лимит, zip отправляется владельцам в Discord ЛС.

04

Пишет meta

Последний статус, размер, область и путь сохраняются в backup_meta.json.

// VISUAL_GUIDE

Как это выглядит картинками

Ниже — визуальные mockup-блоки: owner-команда, процесс сборки, Discord DM, zip-архив, guild export и панель статуса.

owner slash command/backup_now
command owner only cooldown 60s
/backup_nowсоздать полный архив
full
guild_idнеобязательный параметр
optional
responseephemeral-статус владельцу
private
backup pipelineСоздание архива
1Lock

один процесс

2Scan

data/banners

3SQLite

snapshot

4Zip

manifest

5DM

owner

owner dmСообщение владельцу
📨
HELPER BACKUPАвтоматический бэкап

✅ Архив успешно создан

📌 Область: вся система
📦 Элементов: 128
⚖️ Размер: 6.42 MB
🧹 Старых архивов удалено: 2

📎
helper_backup_auto.zipфайл вложен в сообщение
too large caseЕсли архив большой
⚠️
SAFE FALLBACKФайл оставлен локально

Размер больше BACKUP_MAX_MB

Бот не пытается отправить слишком большой zip в Discord. Он оставляет архив на сервере и показывает путь owner.

statustoo_large
local
zip structureПолный архив
FULL ZIP
helper_backup_manual_YYYY-MM-DD.zip
├─ BACKUP_MANIFEST.json
├─ data/
│  ├─ module_states.json
│  ├─ licenses.db
│  └─ *.db snapshot
├─ banners/
├─ backgrounds/
└─ BACKUP_WARNINGS.json
guild exportДанные сервера
GUILD ZIP
helper_backup_guild_123456789.zip
├─ BACKUP_MANIFEST.json
└─ guild_123456789/
   ├─ json/
   │  └─ settings.json
   ├─ sqlite_exports/
   │  └─ applications.json
   └─ BACKUP_WARNINGS.json
// OWNER_COMMANDS

Команды owner

Все команды закрыты owner-проверкой. Если пользователь не владелец, бот отвечает ephemeral-сообщением об отказе.

manual/backup_now
/backup_now

Создаёт полный архив всей системы и отправляет zip в ЛС владельцам.

server scope/backup_now guild_id
/backup_now guild_id:123456789012345678

Создаёт архив только с данными конкретного сервера.

status/backup_status
/backup_status

Показывает auto-mode, лимит размера, локальные архивы, owner IDs и последний backup.

local files/backup_list
/backup_list

Показывает последние локальные zip-файлы, их размер и время создания.

cleanup/backup_cleanup
/backup_cleanup

Запускает ручную очистку старых локальных архивов по TTL и keep-last правилам.

protectioncooldown
1 запуск / 60 секунд

Защищает owner-команду от случайного спама архивами.

// FULL_BACKUP

Полный backup.zip

Полный архив сохраняет рабочий слой HELPER. Он нужен перед обновлением проекта, переносом, массовой правкой данных или восстановлением после ошибки.

includedЧто попадает внутрь
data/настройки модулей, JSON, SQLite базы, meta-файлы.
banners/изображения и визуальные материалы панелей.
backgrounds/фоны и графика, используемые сайтом или ботом.
BACKUP_MANIFEST.jsonдата, причина, область, root, cleanup и заметка об исключениях.
snapshotКак копируются базы
sqlite snapshot
source = sqlite3.connect("file:db?mode=ro") target = sqlite3.connect(temp_snapshot) source.backup(target) zip.write(temp_snapshot)

Почему так лучше

Живую SQLite-базу нельзя просто копировать как обычный файл во время работы. Snapshot снижает риск битого архива.

// GUILD_EXPORT

Бэкап конкретного сервера

Guild export используется, когда нужен не весь HELPER, а только данные одного Discord-сервера. Это удобно для диагностики, переноса клиента или ручного восстановления части настроек.

json filterКак выбирается JSON
1key

ищет guild_id как ключ

2dict

ищет поле guild_id

3list

фильтрует элементы

4export

пишет json

5warn

если пропуски

sqlite filterКак выбирается SQLite
table scanбот получает список таблиц, кроме системных sqlite_*.
guild_id/server_idэкспортируются только таблицы с одной из этих колонок.
JSON rowsстроки сохраняются как массив объектов, а не как готовая DB.
// DASHBOARD_PREVIEW

Как можно показать на сайте

Даже если backup управляется через Discord, в Wiki полезно показать owner-панель как визуальный ориентир: статус, последние архивы, env-настройки и ошибки.

status cardBackup Status
statusownerlocal
Auto backupкаждый 24 часа
enabled
Max sizeDiscord upload safety
8 MB
Last statusbackup_meta.json
sent
Local filesdata/backups
3 ZIP
archive listLocal Backups
helper_backup_auto_2026-06-03.zip6.42 MB · 5 минут назад
fresh
helper_backup_manual_2026-06-02.zip5.88 MB · вчера
saved
helper_backup_guild_123.zip812 KB · server export
guild
env editor mockupBackup Config
BACKUP_AUTO_ENABLEDпереключатель авто-бэкапа.
BACKUP_INTERVAL_HOURSинтервал в часах.
BACKUP_MAX_MBлимит отправки в Discord.
BACKUP_KEEP_LOCAL_FILESоставлять успешные zip на диске.
cleanup mockupCleanup Rules
1Sort

новые выше

2Keep

последние N

3TTL

72 часа

4Delete

старые zip

5Meta

сколько удалено

// DISCORD_PREVIEWS

Discord сценарии

successУспешная отправка

✅ Бэкап отправлен владельцам

Бот показывает количество успешных отправок и ошибок доставки.

📎
helper_backup_manual.zipowner получил файл
dm failedЛС закрыты

⚠️ DM не доставлен

Архив создан, но не удалось отправить его владельцам. Файл оставлен локально, путь показан owner.

statusdm_failed
local
no recipientsНет owner-получателя

OWNER_IDS не настроен

Если recipients не найдены, архив остаётся на сервере, а owner видит подсказку проверить .env.

cooldownЗащита от спама

⏳ Подождите 42.0 секунд

Cooldown защищает сервер от повторной сборки архивов слишком часто.

// AUTO_MODE

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

Auto backup выключен по умолчанию. Его нужно явно включить через .env, чтобы владелец сам контролировал нагрузку и размер архивов.

.envНастройки
OWNER_IDS=123456789012345678 BACKUP_AUTO_ENABLED=true BACKUP_INTERVAL_HOURS=24 BACKUP_MAX_MB=25 BACKUP_KEEP_LOCAL_FILES=false BACKUP_LOCAL_TTL_HOURS=72 BACKUP_KEEP_LAST_LOCAL=3
loopКак работает цикл
1Ready

bot готов

2Gap

прошёл интервал

3Send

auto backup

4Meta

статус

5Sleep

1 час loop

// SAFETY

Что сохраняется и что нет

✅

Сохраняется

data, banners, backgrounds, JSON, основные SQLite базы и manifest.

⚠

Особый режим

SQLite копируется через backup API, а guild SQLite экспортируется строками в JSON.

✕

Исключается

.env, логи, кэш, zip, tmp, lock, virtualenv и SQLite WAL/SHM sidecar.

Почему .env не попадает в backup.zip

.env содержит токены, ключи и приватные настройки. Бэкап должен защищать данные, а не превращаться в архив секретов.

// SQLITE_JSON

SQLite и JSON lock

sqliteSafe snapshot
readonly snapshot
open_sqlite_readonly(path) sqlite3.Connection.backup(dst) dst.commit() zip.write(snapshot)

Это защищает архив от битой копии живой базы.

jsonAtomic write
json_store.py
with json_file_lock(path): tmp.write_text(json.dumps(data)) tmp.replace(path)

JSON meta и настройки читаются и записываются через lock и временный файл.

// RESTORE_PLAN

Как объяснять восстановление

Backup Core делает архив. Восстановление — ручная owner-операция: нужно остановить бота, сохранить текущее состояние, распаковать только нужные файлы и затем запустить проверку.

1Stop

остановить бота

2Copy

сохранить текущее

3Unzip

нужные файлы

4Check

права и пути

5Start

запустить бота

Не заменяй живую SQLite базу при работающем боте

Сначала останови процесс. Иначе можно получить конфликт, lock или повреждение текущей базы.

// TROUBLESHOOTING

Ошибки и решения

Команда пишет “доступна только владельцу”

Проверьте OWNER_IDS. Если список пустой, бот пробует fallback через владельца Discord-приложения.

Архив создан, но не пришёл в ЛС

ЛС owner могут быть закрыты. В этом случае файл остаётся на сервере, а бот показывает локальный путь.

Файл слишком большой

Увеличьте BACKUP_MAX_MB, сделайте guild-бэкап или заберите zip напрямую с сервера.

Авто-бэкап не запускается

Проверьте BACKUP_AUTO_ENABLED=true, перезапуск бота и минимальный gap после последнего backup.

В guild-архиве нет части данных

SQLite-таблицы без guild_id или server_id не экспортируются как server-specific данные.

Локальные zip не удаляются

Cleanup сохраняет несколько новых архивов через BACKUP_KEEP_LAST_LOCAL и не трогает файлы моложе TTL.