Yuriy Yuriev
161 lines
4.9 KiB
Markdown
161 lines
4.9 KiB
Markdown
# PythonBot Backend
|
||
|
||
Бэкенд сервис с **FastAPI** + **Telegram Bot** и асинхронной очередью задач.
|
||
|
||
## Возможности
|
||
|
||
- 🚀 FastAPI REST API с авто-документацией (Swagger)
|
||
- 🤖 Telegram бот для создания и мониторинга задач
|
||
- ⚡ Асинхронная очередь задач с воркерами
|
||
- 🔔 Уведомления о завершении задач в Telegram
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
PythonBot/
|
||
├── Bot.py # Точка входа — запускает FastAPI + Telegram бота
|
||
├── main.py # FastAPI приложение + эндпоинты
|
||
├── bot.py # Telegram бот (aiogram)
|
||
├── tasks.py # Очередь задач + воркеры
|
||
├── config.py # Настройки (pydantic-settings)
|
||
├── requirements.txt
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Установка зависимостей
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. Настройка
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте .env — укажите BOT_TOKEN от @BotFather
|
||
```
|
||
|
||
### 3. Запуск
|
||
|
||
```bash
|
||
python Bot.py
|
||
```
|
||
|
||
Сервис запустится на `http://localhost:8000`
|
||
|
||
## API эндпоинты
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|------|----------|
|
||
| `POST` | `/tasks` | Создать задачу |
|
||
| `GET` | `/tasks` | Список задач (фильтр: `?status=pending`) |
|
||
| `GET` | `/tasks/{id}` | Статус задачи |
|
||
| `POST` | `/tasks/{id}/cancel` | Отменить задачу |
|
||
| `GET` | `/health` | Проверка здоровья |
|
||
|
||
### Примеры запросов
|
||
|
||
```bash
|
||
# Создать echo-задачу
|
||
curl -X POST http://localhost:8000/tasks \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name": "My Echo", "task_type": "echo", "params": {"message": "Hello!"}}'
|
||
|
||
# Создать задачу решения капчи
|
||
curl -X POST http://localhost:8000/tasks \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "Solve CF Turnstile",
|
||
"task_type": "captcha_solve",
|
||
"params": {
|
||
"url": "https://example.com/page-with-captcha",
|
||
"captcha_type": "cloudflare_turnstile"
|
||
}
|
||
}'
|
||
|
||
# Список задач
|
||
curl http://localhost:8000/tasks
|
||
|
||
# Статус задачи
|
||
curl http://localhost:8000/tasks/{task_id}
|
||
|
||
# Swagger UI
|
||
open http://localhost:8000/docs
|
||
```
|
||
|
||
## Telegram бот
|
||
|
||
Получите токен у **@BotFather** и укажите в `.env`:
|
||
|
||
```
|
||
BOT_TOKEN=123456:ABC-DEF...
|
||
```
|
||
|
||
### Команды бота
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `/start` | Приветствие + список команд |
|
||
| `/echo <текст>` | Создать echo-задачу |
|
||
| `/delay <текст> [сек]` | Отложенное сообщение |
|
||
| `/sum <a> <b>` | Сумма двух чисел |
|
||
| `/captcha <url> [тип]` | Решение капчи на странице |
|
||
| `/tasks` | Список ваших задач |
|
||
| `/task <id>` | Статус задачи |
|
||
| `/help` | Справка |
|
||
|
||
## Типы задач
|
||
|
||
| Тип | Параметры | Описание |
|
||
|-----|-----------|----------|
|
||
| `echo` | `message: str` | Вернуть сообщение |
|
||
| `delayed_message` | `message: str, delay: int` | Ответить через N секунд |
|
||
| `sum` | `a: int, b: int` | Сложить два числа |
|
||
| `captcha_solve` | `url: str, captcha_type: str` | Решить капчу на странице |
|
||
|
||
## Добавление своих задач
|
||
|
||
1. Опишите асинхронную функцию в `main.py`:
|
||
|
||
```python
|
||
async def my_task(arg1: str, arg2: int) -> str:
|
||
await asyncio.sleep(2)
|
||
return f"Result: {arg1} {arg2}"
|
||
```
|
||
|
||
2. Добавьте в реестр в `main.py`:
|
||
|
||
```python
|
||
TASK_REGISTRY = {
|
||
"echo": echo_task,
|
||
"delayed_message": delayed_task,
|
||
"sum": sum_task,
|
||
"my_task": my_task, # ←
|
||
}
|
||
```
|
||
|
||
3. Обновите фабрику `create_task()` аналогично.
|
||
|
||
## Конфигурация
|
||
|
||
| Переменная | По умолчанию | Описание |
|
||
|------------|-------------|----------|
|
||
| `HOST` | `0.0.0.0` | Хост FastAPI |
|
||
| `PORT` | `8000` | Порт FastAPI |
|
||
| `DEBUG` | `false` | Режим разработки (reload) |
|
||
| `BOT_TOKEN` | `` | Токен Telegram бота |
|
||
| `MAX_WORKERS` | `3` | Количество воркеров |
|
||
| `TASK_TIMEOUT` | `300` | Таймаут задачи (сек) |
|
||
| `CAPTCHA_SOLVER` | `click` | Тип решателя: `click` \| `2captcha` \| `10captcha` |
|
||
| `CAPTCHA_MAX_ATTEMPTS` | `3` | Макс. попыток решения |
|
||
| `CAPTCHA_ATTEMPT_DELAY` | `5` | Задержка между попытками (сек) |
|
||
| `TWO_CAPTCHA_API_KEY` | `` | API ключ 2Captcha |
|
||
| `TEN_CAPTCHA_API_KEY` | `` | API ключ 10Captcha |
|
||
|
||
## Лиценхия
|
||
|
||
MIT
|