🤖 Aiogram Starter Kit

Профессиональный стартовый шаблон для создания Telegram ботов на Aiogram v3.20.0 с Docker контейнеризацией.

✨ Особенности

🐳 Docker - полная контейнеризация для разработки и продакшена
🚀 Aiogram v3.20.0 - последняя версия фреймворка
🗄️ PostgreSQL - надежная база данных с SQLAlchemy
📦 Redis - быстрое хранилище состояний
👨‍💼 Админская панель - управление ботом и рассылки
📊 Статистика - мониторинг пользователей и активности
📤 Система рассылок - массовая отправка с прогрессом
📝 Логирование - красивые логи с Loguru
🔧 Pydantic - валидация конфигурации
🛠️ Makefile - удобные команды для управления
🎯 Интерактивная настройка - мастер setup за 2 минуты
🔒 Безопасность - запуск от непривилегированного пользователя

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

🎯 Новый проект за 2 минуты (рекомендуется!)

# Клонируем шаблон и запускаем интерактивную настройку
git clone git@github.com:aislam23/aiogram_starter_kit.git my_awesome_bot
cd my_awesome_bot
make init-project  # 🚀 Интерактивный мастер настройки
make dev-d         # Запуск готового бота

Готово! 🎉 Интерактивный мастер:

Соберет информацию о боте (токен, username, описание)
Настроит все конфигурационные файлы
Обновит порты при конфликтах
Инициализирует новый Git репозиторий
Покажет следующие шаги

✅ Быстрый чек-лист

Обязательно:

BOT_TOKEN от @BotFather
BOT_USERNAME вашего бота
ADMIN_USER_IDS (ваш Telegram ID для админки)

Рекомендуется (автоматически через make init-project):

Уникальное название проекта
Безопасные пароли для БД
Свободные порты (если стандартные заняты)
Новый Git репозиторий

Результат:

Бот отвечает на /start, /help, /admin
Админская панель работает (команда /admin)
Логи показывают успешный запуск
База данных инициализирована

👨‍💼 Админская панель

Возможности админа

📊 Статистика бота: количество пользователей, статус, время запуска
📤 Система рассылок: отправка сообщений любого типа всем пользователям
🔗 Кнопки в рассылках: добавление inline кнопок с ссылками
📈 Прогресс рассылки: отслеживание процесса отправки в реальном времени
📋 Итоговая статистика: количество доставленных сообщений

Настройка админов

В файле .env укажите ID администраторов:

# Список админов (JSON массив или через запятую)
ADMIN_USER_IDS=[123456789, 987654321]
# или
ADMIN_USER_IDS=123456789,987654321

Как использовать

Команда /admin - открывает админскую панель со статистикой
Кнопка "Рассылка" - запускает мастер создания рассылки
Отправьте сообщение любого типа (текст, фото, видео, документ)
Добавьте кнопку (опционально) в формате: Текст кнопки | https://example.com
Подтвердите отправку - начнется рассылка с показом прогресса
Получите статистику - количество доставленных сообщений

Поддерживаемые типы сообщений

✅ Текстовые сообщения
✅ Фотографии с подписями
✅ Видео с подписями
✅ Документы с подписями
✅ Аудио с подписями
✅ Голосовые сообщения
✅ Видео-заметки
✅ GIF анимации
✅ Стикеры

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

aiogram_starter_kit/
├── app/                          # Код приложения
│   ├── handlers/                 # Обработчики команд
│   │   ├── admin/               # Админские хендлеры
│   │   │   ├── __init__.py      # Инициализация
│   │   │   └── admin.py         # Команда /admin и рассылки
│   │   ├── start.py             # Команда /start
│   │   └── help.py              # Команды /help, /status
│   ├── middlewares/             # Промежуточное ПО
│   │   ├── logging.py           # Логирование запросов
│   │   └── user.py              # Автосохранение пользователей
│   ├── database/                # Работа с БД
│   │   ├── models.py            # SQLAlchemy модели
│   │   ├── database.py          # Класс для работы с БД
│   │   └── __init__.py          # Инициализация
│   ├── keyboards/               # Клавиатуры
│   │   ├── admin.py             # Админские клавиатуры
│   │   └── __init__.py          # Инициализация
│   ├── services/                # Сервисы
│   │   ├── broadcast.py         # Сервис рассылок
│   │   └── __init__.py          # Инициализация
│   ├── states/                  # FSM состояния
│   │   ├── admin.py             # Состояния админки
│   │   └── __init__.py          # Инициализация
│   ├── utils/                   # Утилиты
│   ├── main.py                  # Главный файл бота
│   └── config.py                # Конфигурация
├── scripts/                     # Скрипты
│   ├── init-project.sh          # Интерактивная настройка
│   ├── init.sql                 # Инициализация БД
│   └── clean-macos.sh           # Очистка macOS файлов
├── docker-compose.yml           # Разработка
├── docker-compose.prod.yml      # Продакшен
├── Dockerfile                   # Многоэтапная сборка
├── Makefile                     # Команды управления
├── requirements.txt             # Python зависимости
└── .env.example                 # Пример переменных окружения

🔧 Команды управления

Настройка и инициализация

make init-project        # 🚀 Интерактивная настройка нового проекта (рекомендуется!)
make setup               # Создать .env файл из примера  
make setup-git-macos     # Настроить глобальный .gitignore для macOS

Разработка

make dev          # Запуск среды разработки
make dev-d        # Запуск в фоновом режиме
make dev-tools    # Запуск с инструментами (pgAdmin)
make stop         # Остановка разработки

Продакшен

make prod         # Запуск продакшен среды
make prod-stop    # Остановка продакшена
make build-prod   # Сборка продакшен образов

Логи и мониторинг

make logs         # Все логи
make logs-bot     # Логи бота
make logs-db      # Логи базы данных
make logs-redis   # Логи Redis

Доступ к контейнерам

make shell        # Bash в контейнере бота
make db-shell     # PostgreSQL консоль
make redis-shell  # Redis консоль

Управление сервисами

make restart      # Перезапуск всех сервисов
make restart-bot  # Перезапуск только бота
make status       # Статус сервисов
make health       # Проверка здоровья

Очистка

make clean        # Очистка контейнеров и образов
make clean-all    # Полная очистка включая volumes
make clean-macos  # Очистка macOS артефактов (.DS_Store и др.)

⚙️ Конфигурация

Все настройки находятся в файле .env:

# Bot Configuration
BOT_TOKEN=your_bot_token_here
BOT_USERNAME=your_bot_username

# Admin Configuration
ADMIN_USER_IDS=[123456789, 987654321]

# Database Configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=botdb
POSTGRES_USER=botuser
POSTGRES_PASSWORD=securepassword

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

# Environment
ENV=development

# Logging
LOG_LEVEL=INFO

🗄️ База данных

Автоматические миграции

Проект включает систему автоматических миграций базы данных:

Автоприменение: Миграции применяются автоматически при запуске бота
Проверка столбцов: Система проверяет наличие нужных столбцов перед применением
История миграций: Ведется журнал примененных миграций
Откат: Поддержка отката миграций (опционально)

📚 Подробная документация по миграциям

Работа с миграциями

# Создание новой миграции
make create-migration NAME=add_user_phone DESC="Add phone column to users"

# Применение миграций вручную
make db-migrate

# Просмотр статуса миграций
make db-migration-status

# Создание миграции через скрипт
python scripts/create_migration.py add_user_phone "Add phone column to users"

Структура миграций

app/database/migrations/
├── __init__.py              # Экспорт основных классов
├── base.py                  # Базовый класс Migration
├── manager.py               # MigrationManager
└── versions/                # Файлы миграций
    ├── __init__.py
    ├── 20241201_000001_initial_tables.py
    └── 20241201_000002_add_user_columns_example.py

Автоматические таблицы

При запуске бота автоматически создаются таблицы:

users - пользователи бота (ID, username, имя, дата регистрации)
bot_stats - статистика бота (количество пользователей, время запуска)
migration_history - история примененных миграций

Подключение к PostgreSQL

Host: localhost
Port: 5432 (или заданный в интерактивной настройке)
Database: botdb
User: botuser
Password: securepassword (измените в .env)

pgAdmin (при использовании make dev-tools)

URL: http://localhost:8080
Email: admin@admin.com
Password: admin

🎬 Интерактивная настройка

Команда make init-project запускает мастер, который собирает:

📋 Информацию о проекте:

🤖 Токен бота (от @BotFather) - обязательно
📛 Username бота (без @) - обязательно
👨‍💼 ID администраторов (ваш Telegram ID) - обязательно
📁 Название проекта (для Docker volumes)
👤 Имя автора
📝 Описание проекта
🔐 Пароли для БД
🌐 Порты (если стандартные заняты)

🔧 И автоматически:

✅ Создает правильный .env файл
✅ Обновляет docker-compose.yml с новыми портами
✅ Переименовывает Docker volumes под ваш проект
✅ Переименовывает контейнеры под имя бота (например: my_bot_bot_dev)
✅ Обновляет метаданные в app/__init__.py
✅ Изменяет заголовок в README.md
✅ Инициализирует новый Git репозиторий
✅ Делает первый commit с описанием проекта
✅ Очищает macOS артефакты

📚 Полезные ссылки

🤝 Вклад в проект

Fork проекта
Создайте feature branch
Commit изменения
Push в branch
Создайте Pull Request

📄 Лицензия

MIT License - см. файл LICENSE для деталей.

Создан с ❤️ для разработчиков Telegram ботов

Версия: 2.0.0 | Aiogram: v3.20.0 | Дата: 30.06.2025

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
app		app
docs		docs
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.env.prod.example		.env.prod.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

aislam23/aiogram_starter_kit

Folders and files

Latest commit

History

Repository files navigation