Аксель AI | Нейро-фото

@AxelPhotoBot

Telegram-бот для генерации и редактирования AI-изображений с использованием OpenAI Images API.

📚 Документация:

• Быстрый старт за 5 минут ⚡
• Быстрый деплой без пересборки 🚀
• Production Deployment 🏭
• Developer Guide 🛠️
• Changelog 📝

🚀 Быстрый старт

# 1. Клонируйте репозиторий
git clone <repository-url>
cd NanoBananaTgBot

# 2. Настройте переменные окружения
cp .env.example .env
nano .env  # Заполните BOT_TOKEN, OPENAI_API_KEY, WEBHOOK_URL

# 3. Запустите через Docker
docker-compose up -d
# или используйте Makefile
make up

# 4. Проверьте логи
docker-compose logs -f
# или
make logs

Готово! Бот запущен и готов к работе 🎉

Makefile команды

Для удобства доступны команды через Makefile:

# Быстрый деплой (рекомендуется)
make deploy          # Деплой за 5-10 секунд без пересборки
make deploy-migrate  # Деплой с миграциями БД

# Основные команды
make help            # Показать все доступные команды
make up              # Запустить все сервисы
make down            # Остановить все сервисы
make restart         # Перезапустить все сервисы
make restart-app     # Перезапустить только app
make restart-worker  # Перезапустить только worker

# Логи
make logs            # Показать логи всех сервисов
make logs-app        # Логи FastAPI
make logs-worker     # Логи Worker

# Разработка
make shell           # Открыть shell в контейнере
make test            # Запустить тесты
make migrate         # Применить миграции
make rebuild         # Полная пересборка (только при изменении requirements.txt)
make clean           # Удалить всё (включая данные)

Возможности

• 🎨 Создание картинок — генерация изображений по текстовому описанию
• 🪄 Редактирование фото — изменение до 10 загруженных изображений с помощью AI
• 💰 Токеновая система — простая система оплаты (Low=2🪙, Medium=5🪙, High=20🪙)
• 📋 Шаблоны — готовые промпты в разделе "Идеи и тренды"
• 👤 Личный кабинет — баланс, статистика и последние 3 генерации
• 👍👎 Оценка результатов — кнопки обратной связи после генерации
• 🔄 Быстрая регенерация — кнопка "Сгенерировать ещё" с теми же настройками
• 🎁 Реферальная система — приглашай друзей и получай бонусы
• 🔔 Проверка подписки — опциональная подписка на канал для новых пользователей
• 🎥 Видео-приветствие — видео-кружок при первом запуске бота
• 🛠️ Админ-панель — управление пользователями, статистика, рассылки

Технологии

• FastAPI — веб-сервер с webhook для Telegram
• aiogram 3 — асинхронный Telegram Bot API
• PostgreSQL — хранение данных пользователей и задач
• Redis + RQ — очередь задач для асинхронной генерации
• OpenAI Images API — генерация изображений
• SQLAlchemy 2 — async ORM
• Alembic — миграции базы данных

Требования

• Python 3.11+
• PostgreSQL 14+
• Redis 6+
• OpenAI API ключ

Установка

1. Клонирование репозитория

git clone <repository-url>
cd NanoBananaTgBot

2. Создание виртуального окружения

python -m venv venv
source venv/bin/activate  # Linux/macOS
# или
venv\Scripts\activate  # Windows

3. Установка зависимостей

pip install -r requirements.txt

4. Настройка переменных окружения

Скопируйте .env.example в .env и заполните значения:

cp .env.example .env

Переменные окружения:

Переменная	Описание	Пример
BOT_TOKEN	Токен бота от @BotFather	123456:ABC-DEF...
DATABASE_URL	URL подключения к PostgreSQL	postgresql+asyncpg://user:pass@localhost:5432/bot_db
REDIS_URL	URL подключения к Redis	redis://localhost:6379/0
OPENAI_API_KEY	API ключ OpenAI	sk-...
WEBHOOK_URL	Публичный URL сервера	https://your-domain.com
INITIAL_TOKENS	Начальный баланс новых пользователей	7
ADMIN_IDS	Telegram ID админов (через запятую)	123456789,987654321
SUBSCRIPTION_CHANNEL	Канал для проверки подписки	@nkonshin_ai
SUBSCRIPTION_REQUIRED	Требовать подписку (true/false)	true
WELCOME_VIDEO_FILE_ID	File ID видео-кружка для приветствия	DQACAgIAAxkBAAI...
SUPPORT_USERNAME	Username поддержки	@support

5. Создание базы данных

# Создайте базу данных PostgreSQL
createdb telegram_bot

# Примените миграции
alembic upgrade head

Запуск

🐳 Docker (рекомендуется)

Самый простой способ — запустить всё через Docker Compose:

# 1. Скопируйте .env.example в .env и заполните переменные
cp .env.example .env
nano .env  # или любой другой редактор

# 2. Запустите все сервисы одной командой
docker-compose up -d

# 3. Проверьте логи
docker-compose logs -f

# 4. Остановка
docker-compose down

# 5. Остановка с удалением данных
docker-compose down -v

Docker Compose автоматически:

• ✅ Поднимает PostgreSQL
• ✅ Поднимает Redis
• ✅ Применяет миграции БД
• ✅ Запускает FastAPI сервер
• ✅ Запускает RQ Worker

Важно: Для локальной разработки с Docker используйте ngrok для webhook:

# В отдельном терминале
ngrok http 8000

# Обновите WEBHOOK_URL в .env на URL от ngrok
# Перезапустите контейнеры
docker-compose restart app

💻 Локальная разработка (без Docker)

Для локальной разработки нужно запустить три компонента:

1. FastAPI сервер:

uvicorn bot.main:app --reload --host 0.0.0.0 --port 8000

2. RQ Worker (в отдельном терминале):

python worker.py

3. Туннель для webhook (например, ngrok):

ngrok http 8000

Не забудьте обновить WEBHOOK_URL в .env на URL от ngrok.

🚀 Production

С Docker (рекомендуется):

docker-compose up -d

Подробная инструкция по production deployment: DEPLOYMENT.md

Без Docker:

# Запуск сервера
uvicorn bot.main:app --host 0.0.0.0 --port 8000

# Запуск worker (в отдельном процессе)
python worker.py

Рекомендуется использовать supervisor или systemd для управления процессами.

Тестирование

# Запуск всех тестов
pytest

# С подробным выводом
pytest -v

# Только unit тесты
pytest tests/test_db.py tests/test_services.py

Docker команды

# Просмотр логов (чистые, без ошибок docker-compose)
make logs              # Логи app (рекомендуется)
make logs-worker       # Логи worker
make logs-db           # Логи PostgreSQL
make logs-redis        # Логи Redis

# Или напрямую через docker
docker logs -f telegram_bot_app
docker logs -f telegram_bot_worker

# Все логи через docker-compose (может показывать ошибки docker-compose)
docker-compose logs -f

# Перезапуск сервиса
docker-compose restart app

# Выполнение команды внутри контейнера
docker-compose exec app bash

# Применение миграций вручную
docker-compose exec app alembic upgrade head

# Просмотр статуса сервисов
docker-compose ps

# Остановка и удаление контейнеров
docker-compose down

# Пересборка образов
docker-compose build --no-cache

# Очистка volumes (удалит данные БД!)
docker-compose down -v

Структура проекта

bot/
├── main.py              # FastAPI приложение + webhook
├── bot.py               # aiogram Bot и Dispatcher
├── config.py            # Конфигурация из .env
├── db/
│   ├── database.py      # Async SQLAlchemy engine
│   ├── models.py        # SQLAlchemy модели
│   └── repositories.py  # CRUD операции + статистика
├── handlers/            # Telegram handlers
│   ├── start.py         # /start, регистрация, проверка подписки
│   ├── menu.py          # Главное меню
│   ├── generate.py      # Создание картинки
│   ├── edit.py          # Редактирование фото (до 10 изображений)
│   ├── model.py         # Выбор модели
│   ├── profile.py       # Личный кабинет (последние 3 генерации)
│   ├── tokens.py        # Покупка токенов
│   ├── trends.py        # Идеи и тренды
│   ├── guide.py         # Гайд
│   ├── admin.py         # Админ-панель и команды
│   ├── feedback.py      # Кнопки оценки (👍/👎)
│   ├── gift.py          # Подарки (заглушка)
│   ├── support.py       # Поддержка
│   ├── invite.py        # Реферальная система
│   └── regenerate.py    # Кнопка "Сгенерировать ещё"
├── keyboards/
│   └── inline.py        # Inline клавиатуры
├── states/
│   ├── generation.py    # FSM состояния генерации
│   └── admin.py         # FSM состояния админки
├── services/
│   ├── balance.py       # Операции с токенами
│   ├── image_provider.py # OpenAI интеграция
│   ├── image_tokens.py  # Расчёт стоимости токенов
│   ├── task_service.py  # Создание задач
│   └── admin_notify.py  # Уведомления админов
├── tasks/
│   └── generation.py    # RQ задачи
├── templates/
│   └── prompts.py       # Шаблоны промптов
└── utils/
    ├── helpers.py       # Вспомогательные функции
    └── messages.py      # Текстовые сообщения

API Endpoints

Публичные

Метод	Путь	Описание
POST	/webhook	Telegram webhook
GET	/health	Health check
GET	/	Информация о сервисе

Админские (требуют X-Admin-API-Key)

Метод	Путь	Описание
GET	/admin/stats	Полная статистика бота
GET	/admin/queue	Статистика очереди RQ
GET	/admin/users/{telegram_id}	Информация о пользователе
POST	/admin/users/{telegram_id}/tokens	Добавить токены пользователю

Команды бота

Для пользователей

Команда	Описание
/start	Регистрация и главное меню
/guide	Инструкции по использованию
/balance	Проверить баланс токенов
/support	Связаться с поддержкой
/invite	Пригласить друга (реферальная ссылка)

Для админов

Команда	Описание
/admin	Открыть админ-меню
/adminhelp	Справка по админ-командам
/stats	Статистика бота
/addtokens <@username|id> <amount>	Добавить токены пользователю
/userinfo <@username|id>	Информация о пользователе
/resetuser <@username|id>	Сбросить пользователя к начальным настройкам
/togglesub	Включить/выключить проверку подписки
/broadcast	Рассылка сообщений всем пользователям

Лицензия

MIT