docs: update README with new features and settings

2026-08-16 05:41:19 +05:00
parent 37d4400513
commit f5cf63bac0
1 changed files with 173 additions and 1 deletions
@@ -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/)