🤖 Telegrab v6.0 — Архиватор сообщений Telegram

Telegrab — это сервер для автоматического архивирования сообщений из Telegram-чатов. Работает 24/7, сохраняет сообщения в реальном времени, предоставляет REST API и WebSocket для уведомлений.

---

📋 Оглавление

• Возможности
• 🚀 Быстрый старт
• Установка
• Получение API ключей Telegram
• Настройка
• Веб-интерфейс
• API Документация
• Database v6
• Production развёртывание
• Структура проекта
• Лицензия

---

✨ Возможности

Основные функции

Функция	Описание
📥 Real-time сохранение	Мгновенное сохранение новых сообщений из чатов
🔔 WebSocket уведомления	Push-уведомления о новых сообщениях
📚 Загрузка истории	Поэтапная загрузка с rate limiting
🔍 Поиск	Полнотекстовый поиск по сообщениям
📊 Статистика	Подробная статистика по чатам
🚀 Работа 24/7	Сервер работает постоянно
🌐 REST API	HTTP API с автодокументацией (Swagger)
🎨 Веб-интерфейс	Современная панель управления
🤖 UserBot режим	Работает как обычный пользователь
⚡ Очередь задач	Фоновая обработка с rate limiting

Database v6

Функция	Описание
🗄️ RAW + Meta архитектура	Полные JSON дампы + метаданные для поиска
📎 Дедупликация файлов	Таблица files для экономии места
✏️ История редактирований	Таблица message_edits
📅 События	Таблица message_events для удалений
📁 Справочник чатов	Таблица chats с подробной информацией

Веб-интерфейс v6

Функция	Описание
📸 Галерея медиа	Просмотр фото/видео с превью
📄 Детали сообщения	RAW данные, редактирования, события, файлы
🔎 Расширенный поиск	Поиск по дате, типу медиа, чату
📊 Статистика чата	Подробная информация по чату
💾 Управление файлами	Просмотр и скачивание файлов
🌓 Тёмная тема	Современный дизайн в стиле Telegram

---

🚀 Быстрый старт

1. Получите API ключи Telegram

1. Откройте https://my.telegram.org
2. Войдите под своим номером
3. Выберите API Development Tools
4. Создайте приложение:
   • App title: Telegrab
   • Short name: telegrab
   • Platform: Desktop
5. Скопируйте API ID и API Hash

2. Установите

git clone https://github.com/JeBance/telegrab.git /opt/telegrab
cd /opt/telegrab
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Настройте

cp .env.example .env
nano .env

Заполните:

API_ID=12345678
API_HASH=abcdef1234567890abcdef1234567890
PHONE=+79991234567
API_PORT=3000

4. Запустите

# Запуск
python telegrab.py

# Или в фоне
nohup python telegrab.py > /tmp/telegrab.log 2>&1 &

5. Авторизуйтесь

1. Откройте http://localhost:3000/ui
2. Нажмите Авторизоваться по QR-коду
3. Отсканируйте в Telegram: Настройки → Устройства → Подключить устройство

---

Установка

Требования

Ресурс	Минимум	Рекомендуется
CPU	1 ядро	2 ядра
RAM	512 MB	1 GB
Disk	5 GB	20 GB SSD
OS	Ubuntu 20.04+	Ubuntu 22.04 LTS
Python	3.8+	3.10+

Пошаговая установка

# Обновление
sudo apt update && sudo apt upgrade -y

# Установка Python
sudo apt install -y python3 python3-pip python3-venv

# Создание директории
sudo mkdir -p /opt/telegrab
sudo chown $USER:$USER /opt/telegrab
cd /opt/telegrab

# Клонирование
git clone https://github.com/JeBance/telegrab.git .

# Виртуальное окружение
python3 -m venv venv
source venv/bin/activate

# Зависимости
pip install --upgrade pip
pip install -r requirements.txt

---

Получение API ключей Telegram

1. Перейдите на https://my.telegram.org
2. Войдите под номером телефона (в формате +7...)
3. Выберите "API Development Tools"
4. Заполните форму:

   App title: Telegrab
   Short name: telegrab
   URL: (оставьте пустым)
   Platform: Desktop
   

5. Получите ключи:
   • API ID: число (например, 12345678)
   • API Hash: 32 символа

⚠️ Важно: Не коммитьте .env в репозиторий!

---

Настройка

Через файл .env

cp .env.example .env
nano .env

Обязательные параметры:

API_ID=12345678
API_HASH=abcdef1234567890abcdef1234567890
PHONE=+79991234567
API_KEY=          # Генерируется автоматически
API_PORT=3000

Настройки загрузки:

AUTO_LOAD_HISTORY=true
HISTORY_LIMIT_PER_CHAT=200
MAX_CHATS_TO_LOAD=20
AUTO_LOAD_MISSED=true
MISSED_LIMIT_PER_CHAT=500
MISSED_DAYS_LIMIT=7

Rate limiting:

REQUESTS_PER_SECOND=1
MESSAGES_PER_REQUEST=100
JOIN_CHAT_TIMEOUT=10

Через веб-интерфейс

1. Запустите: python telegrab.py
2. Откройте http://localhost:3000/ui
3. Введите API_ID, API_HASH, PHONE
4. Отсканируйте QR-код

Через Docker Compose

version: '3.8'
services:
  telegrab:
    build: .
    container_name: telegrab
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env:ro

docker-compose up -d

---

Веб-интерфейс

URL: http://localhost:3000/ui

Вкладки

Вкладка	Описание
Обзор	Дашборд с активностью
Чаты Telegram	Управление чатами, загрузка истории
Сообщения	Просмотр с фильтрами, детали сообщения
Задачи	Очередь задач, мониторинг
Поиск	Расширенный поиск по сообщениям
Галерея	Просмотр медиа файлов
Файлы	Управление файлами
Настройки	Конфигурация приложения

Детали сообщения

Клик на строку сообщения открывает модальное окно с:

• Информация: чат, ID, отправитель, дата, текст
• Вкладка RAW: полные данные сообщения
• Вкладка Редактирования: история изменений
• Вкладка События: удаления, пересылки
• Вкладка Файлы: галерея медиа, список файлов

Галерея медиа

• Фото/видео/GIF отображаются как сетка превью
• Остальные файлы в таблице
• Кнопка скачивания для каждого файла
• Фильтры по чату и типу медиа

---

API Документация

Базовый URL: http://localhost:3000

Swagger UI: http://localhost:3000/docs

Аутентификация

Все endpoints требуют API ключ:

X-API-Key: ваш_api_key

Основные endpoints

Метод	Endpoint	Описание
GET	/health	Проверка работоспособности
GET	/stats	Статистика архива
GET	/chats	Список чатов из БД
GET	/dialogs	Диалоги из Telegram
GET	/tracked_chats	Отслеживаемые чаты
POST	/tracked_chats	Добавить чат
GET	/messages	Сообщения с фильтрацией
GET	/search	Поиск по сообщениям
POST	/load	Загрузить историю
POST	/clear_chat/{id}	Очистить чат из БД
GET	/task/{id}	Статус задачи
GET	/queue	Статус очереди
GET	/config	Получить конфигурацию
POST	/config	Обновить конфигурацию
GET	/telegram_status	Статус Telegram
GET	/qr_login	Получить QR-код
WS	/ws	WebSocket для real-time

Database v6 endpoints

Метод	Endpoint	Описание
GET	/message_raw	RAW данные сообщения
GET	/message_edits	История редактирований
GET	/message_events	События сообщения
GET	/files/stats	Статистика файлов
GET	/files	Список файлов
GET	/chat_stats/{id}	Подробная статистика чата
POST	/search_advanced	Расширенный поиск
GET	/media_gallery	Галерея медиа
GET	/media/{chat_id}/{msg_id}	Загрузка файла

Примеры

# Статистика
curl -H "X-API-Key: key" http://localhost:3000/stats

# Сообщения с фильтром
curl -H "X-API-Key: key" \
  "http://localhost:3000/messages?chat_id=-1001234567890&limit=50"

# Расширенный поиск
curl -X POST -H "X-API-Key: key" \
  "http://localhost:3000/search_advanced?query=bitcoin&media_type=photo"

# Загрузка файла
curl -H "X-API-Key: key" \
  -O file.jpg \
  "http://localhost:3000/media/-1001234567890/12345"

---

Database v6

Структура БД

telegrab_v6.db
├── chats              # Справочник чатов
├── messages_raw       # RAW JSON дампы сообщений
├── message_meta       # Метаданные для поиска
├── files              # Дедупликация файлов
├── message_files      # Связь сообщений с файлами
├── message_edits      # История редактирований
├── message_events     # События (удаления, etc.)
├── chat_loading_status # Статус загрузки чатов
└── tracked_chats      # Отслеживаемые чаты

Преимущества v6

1. RAW данные — полное сохранение структуры Telegram
2. Метаданные — быстрый поиск без парсинга JSON
3. Дедупликация — файлы хранятся один раз
4. История — отслеживание изменений сообщений
5. События — логирование удалений и пересылок

Миграция со старой БД

Старая БД telegrab.db сохраняется. Новые данные записываются в telegrab_v6.db.

---

Production развёртывание

Systemd сервис

1. Создайте сервис:

sudo nano /etc/systemd/system/telegrab.service

2. Конфигурация:

[Unit]
Description=Telegrab Telegram Archiver
After=network.target

[Service]
Type=simple
User=telegrab
WorkingDirectory=/opt/telegrab
Environment="PATH=/opt/telegrab/venv/bin"
ExecStart=/opt/telegrab/venv/bin/python telegrab.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

3. Включите:

sudo systemctl daemon-reload
sudo systemctl enable telegrab
sudo systemctl start telegrab
sudo systemctl status telegrab

HTTPS через nginx

1. Установите nginx:

sudo apt install -y nginx

2. Конфиг:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

3. SSL:

sudo ln -s /etc/nginx/sites-available/telegrab /etc/nginx/sites-enabled/
sudo certbot --nginx -d your-domain.com

Мониторинг

# Логи
tail -f /tmp/telegrab.log
journalctl -u telegrab -f

# Health check
curl http://localhost:3000/health

# Статус
curl -H "X-API-Key: key" http://localhost:3000/telegram_status

---

Структура проекта

telegrab/
├── telegrab.py           # Главный файл запуска
├── api.py                # FastAPI + Telethon
├── database_v6.py        # Database v6.0
├── requirements.txt      # Зависимости
├── .env.example          # Шаблон конфигурации
├── .env                  # Конфигурация
├── docker-compose.yml    # Docker Compose
├── Dockerfile            # Docker образ
├── nginx.conf            # nginx конфиг
├── telegrab.service      # Systemd сервис
├── static/
│   ├── index.html        # Веб-интерфейс
│   └── app.js            # JavaScript клиент
├── data/
│   ├── telegrab_v6.db    # БД v6
│   └── telegrab_*.session # Сессии Telegram
└── scripts/
    ├── auto-update.sh    # Автообновление
    └── README.md         # Документация скриптов

---

Лицензия

MIT License — см. файл LICENSE

---

Поддержка

• GitHub Issues: https://github.com/JeBance/telegrab/issues
• Wiki: https://github.com/JeBance/telegrab/wiki

---

Telegrab v6.0 — работает 24/7 для архивирования ваших Telegram сообщений 🚀