Add telegram-archiver microservice (MVP)

2026-09-29 09:55:08 +00:00 · 2026-02-19 21:41:52 +03:00
parent 7166f535d6
commit 6332b91ba4
13 changed files with 1635 additions and 0 deletions
@@ -0,0 +1,229 @@
+# 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. Клонирование и зависимости
+
+```bash
+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
+
+```bash
+cp .env.example .env
+```
+
+Отредактируй `.env`:
+
+```env
+API_ID=12345678
+API_HASH=abcdef1234567890
+PHONE=+79991234567
+MAX_FILE_SIZE=209715200
+OUTPUT_DIR=./archives
+LOG_LEVEL=INFO
+```
+
+## Использование
+
+### CLI (Command Line Interface)
+
+#### Скачать весь канал:
+
+```bash
+python -m app.main --channel dedinit
+```
+
+#### С опциями:
+
+```bash
+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
+
+#### Запуск сервера:
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+#### Endpoints:
+
+**GET /health** - Проверка здоровья
+
+```bash
+curl http://localhost:8000/health
+```
+
+**POST /archive** - Запуск архивации
+
+```bash
+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:
+
+```yaml
+---
+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` со списком всех больших файлов:
+   ```markdown
+   # Files Too Large to Download
+
+   | Message ID | Filename | Size (bytes) |
+   |------------|----------|-------------|
+   | 12345 | video.mp4 | 524288000 |
+   ```
+
+## Логирование
+
+Логи пишутся:
+- В консоль (stdout)
+- В файл: `YYYYMMDD-channel.log`
+
+Пример: `20260219-dedinit.log`
+
+## Docker (опционально)
+
+Создай `Dockerfile`:
+
+```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"]
+```
+
+Запуск:
+
+```bash
+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
+```
+
+### Запуск тестов:
+
+```bash
+pytest
+```
+
+## Лицензия
+
+MIT