docs: add full infrastructure, deploy, commands and architecture guide to README.md and .infra.md
This commit is contained in:
@@ -1,83 +1,112 @@
|
|||||||
# RedAirsoft VK to Telegram & MAX Messenger Poster
|
# RedAirsoft VK to Telegram & MAX Messenger Poster
|
||||||
|
|
||||||
Автоматизированный Docker-сервис для периодического парсинга новых постов из сообщества ВКонтакте и их одновременной публикации в **Telegram** и мессенджер **МАКС** (MAX Messenger) с отправкой отчётов администраторам в личные сообщения.
|
Автоматизированный Docker-сервис для периодического парсинга новых постов из сообщества ВКонтакте (**Red Airsoft | Страйкбол**) и их одновременной публикации в **Telegram** и мессенджер **МАКС** (MAX Messenger) с отчётами администраторам.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚡ Особенности и возможности
|
## 📌 Инфраструктура и Деплой
|
||||||
|
|
||||||
1. **Telegram Rich Messages (современный формат) & Legacy fallback**:
|
| Параметр | Значение |
|
||||||
- Автоматическая сборка Rich Messages с `<tg-collage>`, инлайн-фото/видео и форматированным текстом.
|
|---|---|
|
||||||
- Поддержка облачного Telegram Bot API и локального `telegram-bot-api` (для видео больше 50 МБ).
|
| **Хост Proxmox** | `192.168.1.222` (root SSH через ключ `~/.ssh/id_ed25519_proxmox`) |
|
||||||
- При недоступности формата Rich Message — автоматический переход на классические медиагруппы (`sendMediaGroup` / `sendPhoto` / `sendVideo`).
|
| **LXC Контейнер** | **CT 107** (`redairsoft-poster`, IP: `192.168.1.106`, Debian 12) |
|
||||||
2. **Надёжная интеграция с Мессенджером МАКС**:
|
| **Ресурсы LXC** | 2 vCPU, 1.5 GB RAM, 512 MB Swap, 16 GB Disk, `onboot=1` |
|
||||||
- Загрузка изображений и видео через `/uploads?type=...`.
|
| **Gitea Репозиторий** | `http://192.168.1.135:3000/exostring/redairsoft_vk_gt_max_sender` |
|
||||||
- Полный цикл поллинга готовности видео (`/videos/{token}`) перед отправкой сообщения.
|
| **Gitea SSH Remote** | `ssh://git@192.168.1.135:2222/exostring/redairsoft_vk_gt_max_sender.git` |
|
||||||
- Обработка `attachment.not.ready` и рейтов (429 Retry-After).
|
| **Путь проекта на LXC 107** | `/opt/redairsoft_poster/` |
|
||||||
- Автоматическая простановка реакций (например, 👍) на первый опубликованный пост.
|
| **Имя Docker контейнера** | `redairsoft-vk-poster` |
|
||||||
- Чанкинг длинных текстов (до 4000 символов).
|
| **Локальный Telegram Bot API** | Встроен в контейнер (`http://127.0.0.1:8081`), поддерживает загрузку видео до 2 ГБ |
|
||||||
3. **Безопасная очистка кэша и загрузок**:
|
| **База данных** | SQLite `/opt/redairsoft_poster/data/poster.db` (персистентный том Docker `./data`) |
|
||||||
- Немедленное удаление временных файлов после обработки каждого поста.
|
|
||||||
- Фоновый процесс очистки старых «хвостов» (`cleaner.py`), который **никогда** не удаляет файлы, находящиеся в процессе скачивания или отправки (благодаря реестру активных локов).
|
|
||||||
4. **Отчёты администраторам в ЛС Telegram**:
|
|
||||||
- Поддержка одного или списка Telegram ID через запятую (`TG_ADMIN_IDS=123456,789012`).
|
|
||||||
- Отправка ссылок на оригинал в ВК, опубликованный пост в Telegram и МАКС.
|
|
||||||
5. **Сохранение состояния (SQLite)**:
|
|
||||||
- База данных в папке `data/poster.db` (монтируется в Docker volume).
|
|
||||||
- Исключает повторную публикацию уже обработанных постов при перезапуске контейнера.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🛠 Быстрый старт
|
## 🚀 Управление проектом (Команды из консоли / PowerShell)
|
||||||
|
|
||||||
### 1. Клонирование и настройка окружения
|
Все команды выполняются через Proxmox хост:
|
||||||
|
|
||||||
Скопируйте пример файла конфигурации:
|
|
||||||
```bash
|
```bash
|
||||||
cp .env.example .env
|
# 1. Посмотреть статус и логи бота:
|
||||||
```
|
ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- docker logs --tail 50 redairsoft-vk-poster'
|
||||||
|
|
||||||
Заполните переменные в файле `.env`:
|
# 2. Логи в реальном времени (follow):
|
||||||
- `VK_ACCESS_TOKEN`: ваш токен ВКонтакте.
|
ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- docker logs -f redairsoft-vk-poster'
|
||||||
- `VK_SOURCE`: ссылка, короткое имя или ID группы ВК (например, `redairsoft` или `https://vk.com/redairsoft`).
|
|
||||||
- `TG_BOT_TOKEN`: токен бота Telegram (от `@BotFather`).
|
|
||||||
- `TG_CHAT_ID`: ID канала/группы Telegram (например, `-1001234567890`).
|
|
||||||
- `TG_ADMIN_IDS`: ID администраторов через запятую для отчётов.
|
|
||||||
- `MAX_BOT_TOKEN`: токен бота в мессенджере МАКС.
|
|
||||||
- `MAX_CHAT_ID`: ID чата в МАКС.
|
|
||||||
|
|
||||||
### 2. Запуск через Docker Compose
|
# 3. Запустить проект:
|
||||||
|
ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- bash -c "cd /opt/redairsoft_poster && docker-compose up -d"'
|
||||||
|
|
||||||
Запустите контейнер в фоновом режиме:
|
# 4. Остановить проект:
|
||||||
```bash
|
ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- bash -c "cd /opt/redairsoft_poster && docker-compose stop"'
|
||||||
docker compose up -d --build
|
|
||||||
```
|
|
||||||
|
|
||||||
Просмотр логов:
|
# 5. Обновить из Gitea и пересобрать:
|
||||||
```bash
|
ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- bash -c "cd /opt/redairsoft_poster && git pull origin main && docker-compose build && docker-compose up -d"'
|
||||||
docker compose logs -f
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📁 Структура проекта
|
## ⚙️ Как работает сервис
|
||||||
|
|
||||||
|
1. **Опрос стены ВКонтакте**:
|
||||||
|
- Каждые 15 минут делает запрос к методу `wall.get` для группы `public36860851` (`owner_id: -36860851`).
|
||||||
|
- Фильтрует посты автора (без репостов и рекламы сторонних сообществ).
|
||||||
|
2. **Защита от спама и режим запуска (`BOOTSTRAP_MODE`)**:
|
||||||
|
- Установлен режим `BOOTSTRAP_MODE=skip_existing`.
|
||||||
|
- При первом запуске или перезапуске сервис запоминает текущие посты стены и **ничего не публикует**, пока в ВК не выйдет новый пост.
|
||||||
|
3. **Загрузка медиа и поддержка длинных видео**:
|
||||||
|
- Картинки скачиваются в максимальном разрешении.
|
||||||
|
- Видео загружается через `yt-dlp` в качестве до 720p (длительностью до 2 часов и размером до 2000 МБ).
|
||||||
|
- Встроенный в контейнер локальный `telegram-bot-api` загружает тяжелые видеофайлы напрямую в Telegram без ограничений облачного API (20-50 МБ).
|
||||||
|
4. **Форматирование текста**:
|
||||||
|
- Ссылки ВКонтакте вида `[club123|Название]` и `[id123|Имя]` преобразуются в корректные кликабельные HTML-ссылки.
|
||||||
|
- Первый абзац / заголовок выделяется жирным шрифтом `<b>...</b>`.
|
||||||
|
- Удаляются разделительные полосы (`━━━`, `───`) и лишние переносы строк.
|
||||||
|
5. **Публикация в мессенджер МАКС**:
|
||||||
|
- Загрузка медиа в МАКС через `/uploads?type=photo` и `/uploads?type=video`.
|
||||||
|
- Поллинг готовности видео (`/videos/{token}`) перед публикацией сообщения.
|
||||||
|
6. **Отчёты администраторам**:
|
||||||
|
- После успешной публикации или при ошибке бот отправляет отчёт со ссылками на оригинальный пост в ВК, Telegram и МАКС в личные сообщения администраторам (`TG_ADMIN_IDS`).
|
||||||
|
7. **Очистка диска и кэша**:
|
||||||
|
- Временные файлы удаляются сразу после публикации.
|
||||||
|
- Фоновый воркер `cleaner.py` каждые 15 минут удаляет старые файлы из `/tmp/poster_cache`, гарантируя защиту активных скачиваний через реестр локов.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔑 Конфигурация (`.env`)
|
||||||
|
|
||||||
|
| Переменная | Описание |
|
||||||
|
|---|---|
|
||||||
|
| `VK_ACCESS_TOKEN` | Сервисный токен приложения ВК (`d0a64...`) |
|
||||||
|
| `VK_SOURCE` | `public36860851` |
|
||||||
|
| `TG_BOT_TOKEN` | Токен Telegram бота (от `@BotFather`) |
|
||||||
|
| `TG_CHAT_ID` | ID канала Telegram (например `-1001303630155`) |
|
||||||
|
| `TG_MEDIA_CHANNEL_ID` | Скрытый канал-хранилище (опционально) |
|
||||||
|
| `TG_ADMIN_IDS` | Telegram ID админов через запятую (например `442509142`) |
|
||||||
|
| `LOCAL_BOT_API_URL` | `http://127.0.0.1:8081` (встроен в контейнер) |
|
||||||
|
| `MAX_BOT_TOKEN` | Токен бота в мессенджере МАКС |
|
||||||
|
| `MAX_CHAT_ID` | ID чата в МАКС |
|
||||||
|
| `BOOTSTRAP_MODE` | `skip_existing` |
|
||||||
|
| `CHECK_INTERVAL_MINUTES` | `15` |
|
||||||
|
| `VIDEO_MAX_DURATION_SEC` | `7200` (2 часа) |
|
||||||
|
| `VIDEO_MAX_SIZE_MB_LOCAL` | `2000` (2 ГБ) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 Структура исходного кода
|
||||||
|
|
||||||
```
|
```
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── config.py # Загрузка и валидация настроек из .env
|
│ ├── config.py # Настройки Pydantic Settings
|
||||||
│ ├── database.py # SQLite хранилище опубликованных постов
|
│ ├── database.py # Хранилище SQLite (посты, статусы, даты)
|
||||||
│ ├── vk_client.py # Клиент VK API (wall.get, resolve, media extraction)
|
│ ├── vk_client.py # Клиент VK API (wall.get, извлечение медиа)
|
||||||
│ ├── media_processor.py # Загрузчик фото/видео (yt-dlp, ffmpeg) с защитой активных файлов
|
│ ├── media_processor.py # Загрузка фото/видео (yt-dlp, aiohttp)
|
||||||
│ ├── text_formatter.py # Форматирование текста (HTML, заголовки, хештеги)
|
│ ├── text_formatter.py # Конвертер ссылок ВК, очистка текста, HTML
|
||||||
│ ├── tg_poster.py # Публикация в Telegram (Rich Message + Legacy)
|
│ ├── tg_poster.py # Отправка в Telegram (Rich Message + Local API)
|
||||||
│ ├── max_poster.py # Публикация в MAX Messenger (Uploads + Messages + Reactions)
|
│ ├── max_poster.py # Отправка в MAX Messenger (Uploads + Polling)
|
||||||
│ ├── cleaner.py # Фоновая очистка зависшего кэша
|
│ ├── cleaner.py # Фоновая очистка временных файлов
|
||||||
│ ├── admin_notifier.py # Отправка отчетов администраторам
|
│ ├── admin_notifier.py # Отправка отчётов администраторам
|
||||||
│ └── main.py # Главный цикл оркестрации
|
│ └── main.py # Точка входа и главный цикл опроса
|
||||||
├── Dockerfile # Мультистейдж образ с ffmpeg и сертификатами
|
├── Dockerfile # Multi-stage образ: aiogram/telegram-bot-api + python:3.12-slim + ffmpeg
|
||||||
├── docker-compose.yml # Конфигурация Docker Compose
|
├── docker-compose.yml # Конфигурация запуска сервиса
|
||||||
├── docker-entrypoint.sh # Скрипт запуска и опционального поднятия local bot api
|
├── docker-entrypoint.sh # Автозапуск локального Telegram Bot API + постера
|
||||||
├── requirements.txt # Зависимости Python
|
├── requirements.txt # Python зависимости (aiogram, yt-dlp, loguru, aiohttp, pydantic)
|
||||||
├── .env.example # Шаблон переменных окружения
|
└── .env # Переменные окружения
|
||||||
└── README.md
|
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user