From f5cf63bac0a8059e6f2417a7b8b73762fea469c8 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 16 Aug 2026 05:41:19 +0500 Subject: [PATCH] docs: update README with new features and settings --- README.md | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 173 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2469b16..bbcc06c 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,15 @@ - Автоматический мониторинг темы на Lolz.team - Отправка Telegram Stars за каждый новый пост - Автоматические ответы с поддержкой шаблонов (включая случайный выбор) +- Автоматическое поднятие темы (bump) с настраиваемым интервалом +- Система капчи для фильтрации пользователей +- Поддержка прокси для Telegram и Lolz API (SOCKS5/HTTPS) - Полная поддержка Docker (рекомендуется) - CI/CD через Gitea Actions (сборка и публикация образов) - Уведомления администратору через Telegram - Гибкая настройка через `.env` - Логирование и сохранение сессии +- Обработка ошибок и повторные попытки ## Требования @@ -67,7 +71,7 @@ python main.py - `examples/.env.example` -**Основные параметры:** +### Основные параметры | Переменная | Описание | По умолчанию | | --------------------- | ----------------------------------------- | ------------ | @@ -75,9 +79,94 @@ python main.py | `LOLZ_TOKEN` | Токен API Lolz.team | - | | `LOLZ_THREAD_ID` | ID темы на форуме | - | | `STARS_COUNT` | Сколько звёзд отправлять за пост | 1 | +| `START_PAGE` | С какой страницы начинать парсинг | 1 | | `ENABLE_REPLY` | Отправлять ли комментарии | true | | `SKIP_COMMENTED` | Пропускать посты, на которые уже отвечали | true | +### Параметры производительности + +| Переменная | Описание | По умолчанию | +| ---------------- | ------------------------------------------- | ------------ | +| `CHECK_INTERVAL` | Интервал проверки новых постов (секунды) | 10 | +| `API_DELAY` | Задержка между API запросами (секунды) | 5 | +| `API_TIMEOUT` | Таймаут для API запросов (секунды) | 15 | +| `MAX_RETRIES` | Количество повторных попыток при ошибках | 3 | + +### Уведомления + +| Переменная | Описание | По умолчанию | +| ------------- | ---------------------------------------------- | ------------ | +| `BOT_TOKEN` | Токен бота для уведомлений (от @BotFather) | - | +| `ADMIN_ID` | Telegram ID администратора для уведомлений | - | +| `NOTIFY_ADMIN`| Включить уведомления администратору | true | + +### Автоматическое поднятие темы (Bump) + +| Переменная | Описание | По умолчанию | +| -------------------- | ---------------------------------------- | ------------ | +| `ENABLE_AUTO_BUMP` | Включить автоматическое поднятие темы | true | +| `BUMP_CHECK_INTERVAL`| Интервал между поднятиями (секунды) | 3600 | + +> **Примечание**: Минимальный интервал поднятия — 3600 секунд (1 час) согласно правилам Lolz.team. + +### Система капчи + +| Переменная | Описание | По умолчанию | +| --------------------- | ----------------------------------------------- | ------------ | +| `ENABLE_CAPTCHA` | Включить систему капчи | false | +| `CAPTCHA_ANSWER` | Правильный ответ на капчу | - | +| `CAPTCHA_CHECK_INTERVAL` | Интервал проверки обновления капчи (секунды) | 1800 | + +Капча добавляется в нижний спойлер первого поста темы: `Капча (обязательно)`. + +Текст капчи хранится в файле `storage/captcha.txt` и поддерживает BBCode форматирование. + +**Пример `storage/captcha.txt`:** +``` +[CENTER][B]Напишите ответ:[/B] +сколько будет 20 + 20? [I][COLOR=rgb(80, 80, 78)](Капча меняется раз в месяц)[/COLOR][/I][/CENTER] +``` + +### Прокси + +Бот поддерживает использование прокси отдельно для Telegram и Lolz API. + +| Переменная | Описание | По умолчанию | +| ---------------- | ------------------------------------------- | ------------ | +| `PROXY_TELEGRAM` | Использовать прокси для Telegram | false | +| `PROXY_LOLZ` | Использовать прокси для Lolz API | false | + +#### Вариант 1: Единая строка прокси + +```env +PROXY=socks5://username:password@host:port +``` + +Или без авторизации: +```env +PROXY=socks5://host:port +``` + +#### Вариант 2: Отдельные параметры + +| Переменная | Описание | По умолчанию | +| ---------------- | --------------------------------- | ------------ | +| `PROXY_PROTOCOL` | Протокол прокси (socks5 или https)| socks5 | +| `PROXY_HOST` | Хост прокси-сервера | - | +| `PROXY_PORT` | Порт прокси-сервера | - | +| `PROXY_USERNAME` | Логин (опционально) | - | +| `PROXY_PASSWORD` | Пароль (опционально) | - | + +**Поддерживаемые форматы прокси:** +- SOCKS5: `socks5://host:port` +- HTTPS: `https://host:port` + +**Поддерживаемые возможности:** +- ✓ Пароли с символом `:` внутри +- ✓ IPv6 адреса +- ✓ Авторизация с логином и паролем +- ✓ Независимая настройка для Telegram и Lolz API + ## Шаблоны ответов Если `ENABLE_REPLY=true`, бот будет отвечать под постами. @@ -97,3 +186,86 @@ python main.py ``` Если файл пустой — используется `✓`. + +## Структура проекта + +``` +Auto-Stars-Improved/ +├── main.py # Точка входа +├── config.py # Загрузка конфигурации +├── modules/ +│ ├── stars_bot.py # Основная логика бота +│ ├── lolz.py # API клиент Lolz.team +│ ├── notification_bot.py # Уведомления через Telegram +│ └── processed.py # Менеджер обработанных постов +├── storage/ +│ ├── replies.txt # Шаблоны ответов +│ ├── captcha.txt # Текст капчи +│ ├── processed_posts.json # История обработанных постов +│ ├── logs/ # Логи +│ └── sessions/ # Сессии Pyrogram +├── examples/ +│ ├── .env.example # Пример конфигурации +│ └── docker-compose.yml # Docker Compose конфигурация +└── Dockerfile # Docker образ +``` + +## Обработка ошибок + +Бот включает систему обработки ошибок с повторными попытками: + +- **Network errors**: Автоматические повторные попытки с задержкой +- **API errors**: Логирование и уведомление администратора +- **Config errors**: Валидация при старте с понятными сообщениями об ошибках +- **Timeout errors**: Настраиваемый таймаут через `API_TIMEOUT` + +Все ошибки логируются в `storage/logs/` с ротацией файлов. + +## Логирование + +Логи сохраняются в `storage/logs/auto_stars.log` с автоматической ротацией: +- Максимальный размер файла: 5 MB +- Количество резервных копий: 3 +- Формат: `[YYYY-MM-DD HH:MM:SS] [LEVEL] [module] message` + +Уровни логирования: +- `INFO` — основные операции +- `DEBUG` — детальная информация (запросы, ответы) +- `WARNING` — предупреждения +- `ERROR` — ошибки с трейсбеком + +## Разработка + +### Локальная разработка + +```bash +git clone https://git.sakamoto.best/Lolz/Auto-Stars-Improved.git +cd Auto-Stars-Improved +python -m venv venv +source venv/bin/activate # или venv\Scripts\activate на Windows +pip install -r requirements.txt +cp examples/.env.example .env +# редактируйте .env +python main.py +``` + +### CI/CD + +Проект использует Gitea Actions для автоматической сборки Docker образов: + +- **main branch** → `ghcr.io/username/auto-stars-improved:latest` +- **dev branch** → `ghcr.io/username/auto-stars-improved:dev` + +## Автор + +Разработчик: (https://lolz.team/members/7272152/) на Lolz.team + +## Лицензия + +Этот проект распространяется "как есть" без каких-либо гарантий. + +## Поддержка + +- Создайте Issue на Gitea: https://git.sakamoto.best/Lolz/Auto-Stars-Improved/issues +- Форум Lolz.team: https://lolz.team/threads/10187517/ +- Автор: [@sakamotogoat](https://lolz.team/members/7272152/)