Vaulty

Личный архив Telegram Business: сохраняет медиа и текст, фиксирует правки и помогает не потерять удалённые сообщения.

Vaulty — асинхронный мультипользовательский Telegram-бот на официальном Business Bot API. Он переносит медиа из подключённых личных чатов в архив пользователя, индексирует текст для поиска и сохраняет контекст правок, удалений и одноразовых сообщений. Медиафайлы не остаются на сервере: Vaulty скачивает их в память и сразу отправляет в личный чат с ботом или в выбранный канал.

Возможности

• сохранение фото, видео, кружков, голосовых, аудио, документов, стикеров и GIF;
• захват доступных через Business API view-once медиа, включая ответ на одноразовое сообщение;
• фиксация правок и уведомления об удалённых сообщениях;
• поиск по сохранённому тексту и именам отправителей через /search;
• отдельные настройки, фильтры и архив для каждого пользователя;
• архив в личке с ботом или в приватном канале пользователя;
• личная статистика через /stats;
• нативные Managed Bots Telegram без передачи токенов в сообщениях и без хранения токенов в БД;
• polling для локального запуска и webhook для продакшена и Managed Bots.

Important

Бот может сохранять входящие сообщения собеседников. Используйте его только законно, прозрачно и с учётом правил Telegram и требований вашей юрисдикции. Доступность view-once контента зависит от того, какие данные Telegram передаёт через Business API.

Быстрый запуск одной командой

Сначала создайте бота у @BotFather, включите для него Business Mode и замените PASTE_BOT_TOKEN_HERE на выданный токен.

Windows PowerShell

git clone https://github.com/makkaX2/SaveBot.git Vaulty; Set-Location Vaulty; python -m venv .venv; .\.venv\Scripts\python -m pip install -r requirements.txt; $env:BOT_TOKEN="PASTE_BOT_TOKEN_HERE"; .\.venv\Scripts\python -m bot

Linux / macOS

git clone https://github.com/makkaX2/SaveBot.git Vaulty && cd Vaulty && python3 -m venv .venv && .venv/bin/python -m pip install -r requirements.txt && BOT_TOKEN='PASTE_BOT_TOKEN_HERE' .venv/bin/python -m bot

По умолчанию Vaulty запускается через polling и создаёт SQLite-базу data/bot.db. После старта отправьте боту /start, пройдите мастер и подключите его в Telegram: Настройки → Telegram для бизнеса → Чат-боты.

Настройка через .env

Для постоянного запуска скопируйте .env.example в .env и измените нужные значения.

Переменная	Обязательность	Назначение
BOT_TOKEN	всегда	Токен основного бота от BotFather
DATABASE_URL	нет	SQLAlchemy URL; по умолчанию локальный SQLite
USE_WEBHOOK	нет	true для webhook-режима; по умолчанию false
WEBHOOK_BASE_URL	при webhook	Публичный базовый HTTPS URL без webhook-пути
WEBHOOK_SECRET	при webhook	Случайный секрет для проверки заголовка Telegram
WEBHOOK_PORT	нет	Порт aiohttp-сервера, по умолчанию 8080
WEBHOOK_HOST	нет	Интерфейс прослушивания, по умолчанию 0.0.0.0
LOG_LEVEL	нет	DEBUG, INFO, WARNING, ERROR или CRITICAL

Сгенерировать webhook-секрет:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Для PostgreSQL используйте, например:

DATABASE_URL=postgresql+asyncpg://vaulty:strong-password@localhost:5432/vaulty

Webhook и Managed Bots

Webhook нужен для нативных суб-ботов. Укажите USE_WEBHOOK=true, публичный HTTPS URL и случайный WEBHOOK_SECRET, затем включите Bot Management Mode у основного бота в BotFather. Команда /subbots откроет официальный сценарий создания Managed Bot.

Основной webhook использует фиксированный путь /webhook/main. Суб-боты используют публичный идентификатор, а не токен, в пути /webhook/subbot/<bot_id>; каждый запрос дополнительно проверяется по секретному заголовку Telegram.

Команды

Команда	Назначение
/start	мастер и настройки
/help	справка по подключению
/status	бизнес-подключения и права
/setchannel	выбрать канал-архив
/usepm	вернуть архив в личку с ботом
/search <текст>	поиск по архиву
/stats	личная статистика
/subbots	управление Managed Bots
/delbot <id>	отключить принадлежащего пользователю суб-бота

Хранение и безопасность

• медиа скачиваются в память только на время пересылки и не сохраняются в файловой системе;
• в БД остаются текст, Telegram file ID, метаданные, настройки и ссылки на сообщения архива;
• данные во всех запросах ограничиваются владельцем архива;
• токен основного бота и реквизиты БД читаются только из окружения;
• Managed Bot tokens получаются у Telegram по требованию, не хранятся в БД и не попадают в URL;
• .env, локальные базы, сессии, логи и кэши исключены из Git.

Практические рекомендации по развёртыванию и приватному сообщению об уязвимостях находятся в SECURITY.md.

Стек

• Python 3.10+ и asyncio;
• aiogram 3.30 / Telegram Bot API 10.2;
• SQLAlchemy 2.0 async;
• SQLite + aiosqlite для локального запуска;
• PostgreSQL + asyncpg для продакшена;
• aiohttp для webhook-сервера;
• pydantic-settings для типизированной конфигурации;
• pytest и Ruff для тестов и статического контроля.

Разработка

python -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m ruff check .
.venv/bin/python -m pytest -q
.venv/bin/python -m pip_audit -r requirements.txt

Схема создаётся через SQLAlchemy.create_all(). Перед изменением моделей в уже развёрнутом экземпляре подготовьте миграцию или пересоздайте базу: автоматических миграций в проекте пока нет.

Метаданные GitHub

Описание: Telegram Business-бот для личного архива медиа и сообщений: view-once, правки, удаления, поиск и Managed Bots без хранения медиа на сервере.

Topics: telegram-bot, telegram-business, aiogram, python, asyncio, sqlalchemy, postgresql, sqlite, webhook, media-archive.