chronicle.nixg.ru/telegram-archiver/README.md

# 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. Установка uv (менеджер пакетов и виртуальных окружений)

```bash
# Windows
pip install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Создание виртуального окружения

```bash
cd telegram-archiver
uv venv
```

Активация виртуального окружения:

```bash
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (cmd)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```

### 3. Установка зависимостей

```bash
uv 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