chronicle.nixg.ru/telegram-archiver

Telegram Archiver

Микросервис для архивирования Telegram-каналов в локальную файловую систему с генерацией Markdown для Hugo.

Возможности

• ✅ Скачивание всех постов канала (без ограничений)
• ✅ Сохранение текста в Markdown с front-matter для Hugo
• ✅ Скачивание медиа: фото, видео, документы, аудио
• ✅ Ограничение на размер файла (настраивается, по умолчанию 200 MB)
• ✅ Отчёт о слишком больших файлах в 2big2get.md
• ✅ Дедупликация по ID сообщения
• ✅ Обработка репостов и ответов (reply-to)
• ✅ REST API + CLI интерфейс
• ✅ Логирование в файл и консоль

Структура выходных данных

<channel_name>/
├── 12345/
│   ├── index.md          # Контент поста + front-matter
│   ├── photo.jpg         # Медиафайлы
│   └── document.pdf
├── 12346/
│   └── index.md          # Только текст
└── 2big2get.md           # Отчёт о больших файлах

Установка

1. Клонирование и зависимости

cd telegram-archiver
pip install -r requirements.txt

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

1. Перейди на https://my.telegram.org/apps
2. Войди по номеру телефона
3. Создай новое приложение (любое название)
4. Скопируй API_ID и API_HASH

3. Настройка .env

cp .env.example .env

Отредактируй .env:

API_ID=12345678
API_HASH=abcdef1234567890
PHONE=+79991234567
MAX_FILE_SIZE=209715200
OUTPUT_DIR=./archives
LOG_LEVEL=INFO

Использование

CLI (Command Line Interface)

Скачать весь канал:

python -m app.main --channel dedinit

С опциями:

python -m app.main \
  --channel dedinit \
  --output ./my-archives \
  --limit 100 \
  --from-message-id 5000 \
  --force

Опции CLI:

Опция	Кратко	Описание
--channel	-c	Username канала (с @ или без)
--output-dir	-o	Папка для архива
--limit	-l	Лимит постов (для теста)
--from-message-id	-f	Начать с этого ID
--force		Перескачать существующие
--env-file		Путь к .env файлу

REST API

Запуск сервера:

uvicorn app.main:app --host 0.0.0.0 --port 8000

Endpoints:

GET /health - Проверка здоровья

curl http://localhost:8000/health

POST /archive - Запуск архивации

curl -X POST http://localhost:8000/archive \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "dedinit",
    "limit": 100
  }'

GET /docs - Swagger UI документация

Открой в браузере: http://localhost:8000/docs

Front-matter формат

Каждый index.md содержит YAML front-matter:

---
message_id: 12345
date: 2024-02-19T14:30:00
author: "Channel Name"
reply_to: "../12340/index.md"
repost_from: 12300
repost_channel: "Other Channel"
media_files:
  - filename: photo.jpg
    type: photo
    caption: "Описание"
    size: 102400
    is_too_large: false
---

Текст сообщения в Markdown

Обработка больших файлов

Файлы > MAX_FILE_SIZE (по умолчанию 200 MB) не скачиваются. Вместо этого:

1. В index.md добавляется is_too_large: true
2. В корне канала создаётся 2big2get.md со списком всех больших файлов:

   # Files Too Large to Download
   
   | Message ID | Filename | Size (bytes) |
   |------------|----------|-------------|
   | 12345 | video.mp4 | 524288000 |
   

Логирование

Логи пишутся:

• В консоль (stdout)
• В файл: YYYYMMDD-channel.log

Пример: 20260219-dedinit.log

Docker (опционально)

Создай Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Запуск:

docker build -t telegram-archiver .
docker run -v $(pwd)/.env:/app/.env -v $(pwd)/archives:/app/archives telegram-archiver

Интеграция с Hugo

После архивации:

1. Скопируй содержимое канала в content/posts/ Hugo
2. Front-matter совместим с Hugo (date, author, tags)
3. Медиафайлы будут доступны по относительным ссылкам

Разработчикам

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

telegram-archiver/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI + CLI entry point
│   ├── telethon_client.py # Telethon wrapper
│   ├── archiver.py       # Core logic
│   ├── models.py         # Pydantic models
│   └── logger.py         # Logging setup
├── config.py             # Settings management
├── requirements.txt
├── .env.example
└── README.md

Запуск тестов:

pytest

Лицензия

MIT