From d63d3fb9372af1899136986ebf09debece22cc2b Mon Sep 17 00:00:00 2001 From: exostring Date: Fri, 14 Aug 2026 20:02:41 +0500 Subject: [PATCH] docs: add full infrastructure, deploy, commands and architecture guide to README.md and .infra.md --- README.md | 147 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 88 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index e15d322..4b83780 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,112 @@ # 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 с ``, инлайн-фото/видео и форматированным текстом. - - Поддержка облачного Telegram Bot API и локального `telegram-bot-api` (для видео больше 50 МБ). - - При недоступности формата Rich Message — автоматический переход на классические медиагруппы (`sendMediaGroup` / `sendPhoto` / `sendVideo`). -2. **Надёжная интеграция с Мессенджером МАКС**: - - Загрузка изображений и видео через `/uploads?type=...`. - - Полный цикл поллинга готовности видео (`/videos/{token}`) перед отправкой сообщения. - - Обработка `attachment.not.ready` и рейтов (429 Retry-After). - - Автоматическая простановка реакций (например, 👍) на первый опубликованный пост. - - Чанкинг длинных текстов (до 4000 символов). -3. **Безопасная очистка кэша и загрузок**: - - Немедленное удаление временных файлов после обработки каждого поста. - - Фоновый процесс очистки старых «хвостов» (`cleaner.py`), который **никогда** не удаляет файлы, находящиеся в процессе скачивания или отправки (благодаря реестру активных локов). -4. **Отчёты администраторам в ЛС Telegram**: - - Поддержка одного или списка Telegram ID через запятую (`TG_ADMIN_IDS=123456,789012`). - - Отправка ссылок на оригинал в ВК, опубликованный пост в Telegram и МАКС. -5. **Сохранение состояния (SQLite)**: - - База данных в папке `data/poster.db` (монтируется в Docker volume). - - Исключает повторную публикацию уже обработанных постов при перезапуске контейнера. +| Параметр | Значение | +|---|---| +| **Хост Proxmox** | `192.168.1.222` (root SSH через ключ `~/.ssh/id_ed25519_proxmox`) | +| **LXC Контейнер** | **CT 107** (`redairsoft-poster`, IP: `192.168.1.106`, Debian 12) | +| **Ресурсы LXC** | 2 vCPU, 1.5 GB RAM, 512 MB Swap, 16 GB Disk, `onboot=1` | +| **Gitea Репозиторий** | `http://192.168.1.135:3000/exostring/redairsoft_vk_gt_max_sender` | +| **Gitea SSH Remote** | `ssh://git@192.168.1.135:2222/exostring/redairsoft_vk_gt_max_sender.git` | +| **Путь проекта на LXC 107** | `/opt/redairsoft_poster/` | +| **Имя Docker контейнера** | `redairsoft-vk-poster` | +| **Локальный Telegram Bot API** | Встроен в контейнер (`http://127.0.0.1:8081`), поддерживает загрузку видео до 2 ГБ | +| **База данных** | SQLite `/opt/redairsoft_poster/data/poster.db` (персистентный том Docker `./data`) | --- -## 🛠 Быстрый старт +## 🚀 Управление проектом (Команды из консоли / PowerShell) -### 1. Клонирование и настройка окружения +Все команды выполняются через Proxmox хост: -Скопируйте пример файла конфигурации: ```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`: -- `VK_ACCESS_TOKEN`: ваш токен ВКонтакте. -- `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. Логи в реальном времени (follow): +ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- docker logs -f redairsoft-vk-poster' -### 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"' -Запустите контейнер в фоновом режиме: -```bash -docker compose up -d --build -``` +# 4. Остановить проект: +ssh -i ~/.ssh/id_ed25519_proxmox root@192.168.1.222 'pct exec 107 -- bash -c "cd /opt/redairsoft_poster && docker-compose stop"' -Просмотр логов: -```bash -docker compose logs -f +# 5. Обновить из Gitea и пересобрать: +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"' ``` --- -## 📁 Структура проекта +## ⚙️ Как работает сервис + +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-ссылки. + - Первый абзац / заголовок выделяется жирным шрифтом `...`. + - Удаляются разделительные полосы (`━━━`, `───`) и лишние переносы строк. +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/ -│ ├── config.py # Загрузка и валидация настроек из .env -│ ├── database.py # SQLite хранилище опубликованных постов -│ ├── vk_client.py # Клиент VK API (wall.get, resolve, media extraction) -│ ├── media_processor.py # Загрузчик фото/видео (yt-dlp, ffmpeg) с защитой активных файлов -│ ├── text_formatter.py # Форматирование текста (HTML, заголовки, хештеги) -│ ├── tg_poster.py # Публикация в Telegram (Rich Message + Legacy) -│ ├── max_poster.py # Публикация в MAX Messenger (Uploads + Messages + Reactions) -│ ├── cleaner.py # Фоновая очистка зависшего кэша -│ ├── admin_notifier.py # Отправка отчетов администраторам -│ └── main.py # Главный цикл оркестрации -├── Dockerfile # Мультистейдж образ с ffmpeg и сертификатами -├── docker-compose.yml # Конфигурация Docker Compose -├── docker-entrypoint.sh # Скрипт запуска и опционального поднятия local bot api -├── requirements.txt # Зависимости Python -├── .env.example # Шаблон переменных окружения -└── README.md +│ ├── config.py # Настройки Pydantic Settings +│ ├── database.py # Хранилище SQLite (посты, статусы, даты) +│ ├── vk_client.py # Клиент VK API (wall.get, извлечение медиа) +│ ├── media_processor.py # Загрузка фото/видео (yt-dlp, aiohttp) +│ ├── text_formatter.py # Конвертер ссылок ВК, очистка текста, HTML +│ ├── tg_poster.py # Отправка в Telegram (Rich Message + Local API) +│ ├── max_poster.py # Отправка в MAX Messenger (Uploads + Polling) +│ ├── cleaner.py # Фоновая очистка временных файлов +│ ├── admin_notifier.py # Отправка отчётов администраторам +│ └── main.py # Точка входа и главный цикл опроса +├── Dockerfile # Multi-stage образ: aiogram/telegram-bot-api + python:3.12-slim + ffmpeg +├── docker-compose.yml # Конфигурация запуска сервиса +├── docker-entrypoint.sh # Автозапуск локального Telegram Bot API + постера +├── requirements.txt # Python зависимости (aiogram, yt-dlp, loguru, aiohttp, pydantic) +└── .env # Переменные окружения ```