Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
bot
bot
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
requirements.txt
requirements.txt
 
 

Repository files navigation

Referral Telegram Bot

GitHub

Полноценный реферальный бот с принудительной подпиской, личным кабинетом и интерактивным меню на aiogram-dialog.

Быстрая установка с GitHub

Скопируйте и выполните на Linux-сервере (Ubuntu/Debian):

# 1. Системные зависимости
sudo apt update && sudo apt install -y python3 python3-pip python3-venv git

# 2. Клонировать репозиторий
git clone https://github.com/Riderus88/Referal.git
cd Referal

# 3. Виртуальное окружение и зависимости
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# 4. Настроить конфиг
cp .env.example .env
nano .env   # укажите BOT_TOKEN и ADMIN_IDS

# 5. Запуск
python -m bot.main

Перед запуском создайте бота через @BotFather и узнайте свой Telegram ID через @userinfobot. Подробная инструкция — ниже.

Возможности

  • Реферальные ссылки t.me/BotName?start=ref_XXXXX
  • Force Subscribe — проверка подписки на группы/каналы
  • Мониторинг вступлений и выходов из группы (ChatMemberUpdated)
  • Интерактивное inline-меню с FSM-навигацией
  • Личный кабинет, статистика, топ кураторов
  • Админ-панель: группы, рассылка, логи, пользователи

Требования к серверу

Компонент Версия
ОС Ubuntu 20.04+ / Debian 11+ / любой Linux с systemd
Python 3.10 или новее
RAM от 512 MB
Диск от 500 MB

Дополнительно понадобится:

  • VPS или выделенный сервер с доступом по SSH
  • Аккаунт Telegram
  • Бот, созданный через @BotFather
  • Telegram-группа или канал для Force Subscribe

Установка на Linux-сервер

Шаг 1. Подключитесь к серверу

ssh user@your-server-ip

Замените user на имя пользователя, your-server-ip — на IP вашего VPS.

Шаг 2. Установите системные зависимости

Ubuntu / Debian

sudo apt update
sudo apt install -y python3 python3-pip python3-venv git

CentOS / Rocky Linux / AlmaLinux

sudo dnf install -y python3 python3-pip git

Проверьте версию Python:

python3 --version
# Должно быть: Python 3.10.x или выше

Если версия ниже 3.10 (Ubuntu 20.04), установите Python из deadsnakes:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev

Далее вместо python3 используйте python3.11.

Шаг 3. Создайте бота в Telegram

  1. Откройте @BotFather.
  2. Отправьте /newbot, задайте имя и username (должен заканчиваться на bot).
  3. Сохраните токен — он понадобится в .env.

Настройки в BotFather

/mybots → ваш бот:

Настройка Значение Зачем
Group Privacy Turn off Бот видит сообщения в группе (нужно для /add_group_here)
Allow Groups? Enable Бот работает в группах

При добавлении бота в группу согласитесь на право «Просмотр списка участников» — без него Force Subscribe и отслеживание рефералов не работают.

Шаг 4. Узнайте свой Telegram ID

Напишите @userinfobot или @getmyid_bot и скопируйте число из строки Id:.

Пример: 123456789 — это значение для ADMIN_IDS.

Шаг 5. Загрузите проект на сервер

cd ~
git clone https://github.com/Riderus88/Referal.git
cd Referal

Репозиторий: github.com/Riderus88/Referal

Шаг 6. Создайте виртуальное окружение и установите зависимости

cd ~/Referal

python3 -m venv venv
source venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

После активации в начале строки появится (venv).

Устанавливаемые пакеты:

Пакет Назначение
aiogram Telegram Bot API
aiogram-dialog Интерактивные inline-меню
sqlalchemy + aiosqlite База данных SQLite
python-dotenv Загрузка .env
apscheduler Ежедневная рассылка статистики

Шаг 7. Настройте .env

cp .env.example .env
nano .env

Заполните файл:

# ОБЯЗАТЕЛЬНО — токен от @BotFather
BOT_TOKEN=7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# ОБЯЗАТЕЛЬНО — Telegram ID администраторов через запятую
ADMIN_IDS=123456789

# База данных (можно не менять)
DATABASE_URL=sqlite+aiosqlite:///./referral_bot.db

# Часовой пояс сервера
TIMEZONE=Europe/Moscow

# Ежедневная статистика админам (true / false)
DAILY_STATS_ENABLED=false

# Час отправки сводки (0–23)
DAILY_STATS_HOUR=9

# Пароль для подтверждения «Сброс статистики» в админ-меню
RESET_STATS_PASSWORD=your_secure_password_here

Сохраните: Ctrl+O → Enter → Ctrl+X.

Описание переменных

Переменная Обязательная Описание
BOT_TOKEN ✅ Токен бота от @BotFather
ADMIN_IDS ✅ ID администраторов. Несколько: 123456789,987654321
DATABASE_URL ❌ Подключение к БД. По умолчанию referral_bot.db в корне проекта
TIMEZONE ❌ Часовой пояс. Пример: Europe/Moscow, Asia/Novosibirsk
DAILY_STATS_ENABLED ❌ true — ежедневная сводка статистики админам
DAILY_STATS_HOUR ❌ Час отправки (0–23)
RESET_STATS_PASSWORD ❌ Пароль для подтверждения сброса статистики в админ-меню

Не публикуйте .env — файл содержит секретный токен. Он добавлен в .gitignore.

Защитите файл:

chmod 600 .env

Шаг 8. Проверьте запуск вручную

source venv/bin/activate
python -m bot.main

При успешном запуске:

INFO:__main__:Бот запущен

Откройте бота в Telegram и отправьте /start. Если всё работает — остановите бота: Ctrl+C.

При первом запуске создаётся файл referral_bot.db.

Шаг 9. Настройте автозапуск через systemd

Создайте systemd-сервис:

sudo nano /etc/systemd/system/referral-bot.service

Вставьте (замените your_user и путь к проекту):

[Unit]
Description=Referral Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/root/Referal
ExecStart=/root/Referal/venv/bin/python -m bot.main
Restart=always
RestartSec=10
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

your_user — имя пользователя Linux, под которым запущен бот (whoami).

Активируйте и запустите сервис:

sudo systemctl daemon-reload
sudo systemctl enable referral-bot
sudo systemctl start referral-bot
sudo systemctl status referral-bot

Статус active (running) означает, что бот работает.

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

# Статус
sudo systemctl status referral-bot

# Остановить
sudo systemctl stop referral-bot

# Запустить
sudo systemctl start referral-bot

# Перезапустить (после изменений в коде или .env)
sudo systemctl restart referral-bot

# Логи в реальном времени
journalctl -u referral-bot -f

# Последние 100 строк логов
journalctl -u referral-bot -n 100 --no-pager

Шаг 10. Настройка группы (Force Subscribe)

10.1. Добавьте бота в группу

  1. Откройте Telegram-группу → Управление группой → Участники → Добавить → найдите бота.
  2. Назначьте бота администратором с правом «Просмотр списка участников» (остальные права не обязательны).

10.2. Зарегистрируйте группу

В группе от имени администратора (ID из ADMIN_IDS) отправьте:

/add_group_here

Бот ответит:

✅ Группа Название вашей группы добавлена для Force Subscribe.

10.3. Добавление канала (опционально)

  1. Добавьте бота администратором в канал.
  2. Перешлите сообщение из канала боту в личку.
  3. Ответьте на пересланное сообщение: /add_group.

Шаг 11. Проверка работы

  1. Откройте бота в Telegram → /start — появится главное меню.
  2. Без подписки на группу — кнопки «Подписаться» и «Проверить подписку».
  3. Подпишитесь → «✅ Проверить подписку» → меню откроется.
  4. «🔗 Моя ссылка» → реферальная ссылка t.me/YourBot?start=ref_XXXXX.
  5. Переход по ссылке с другого аккаунта → куратор получит уведомление.

Обновление бота на сервере

cd ~/Referal

git pull

# Обновить зависимости
source venv/bin/activate
pip install -r requirements.txt --upgrade

# Перезапустить сервис
sudo systemctl restart referral-bot

# Проверить статус
sudo systemctl status referral-bot

База referral_bot.db сохраняется между перезапусками.

Команды бота

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

Команда Описание
/start Регистрация + главное меню
/menu Открыть главное меню
/profile Личный кабинет

Для администраторов

Команда Описание
/add_group_here Добавить текущую группу/канал для Force Subscribe
/add_group Добавить группу через пересланное сообщение
/remove_group <chat_id> Удалить группу из проверки подписки
/users Количество зарегистрированных пользователей
/admin Справка по админ-командам

Полная админ-панель — через ⚙️ Настройки в главном меню (только для ID из ADMIN_IDS).

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

Referal/
├── .env                  # Конфигурация (не в git)
├── .env.example          # Шаблон конфигурации
├── requirements.txt      # Python-зависимости
├── referral_bot.db       # База данных (создаётся автоматически)
├── venv/                 # Виртуальное окружение
└── bot/
    ├── main.py           # Точка входа
    ├── config.py         # Загрузка настроек из .env
    ├── database/
    │   ├── models.py     # Модели SQLAlchemy
    │   └── db.py         # Подключение к БД
    ├── dialogs/          # aiogram-dialog меню (FSM)
    ├── handlers/         # Обработчики команд и событий
    ├── middlewares/      # Force Subscribe middleware
    ├── services/         # Бизнес-логика
    └── utils/            # Вспомогательные функции

Меню бота (FSM-состояния)

Состояние Раздел
MainMenu Главное меню
ProfileMenu Личный кабинет
ReferralMenu Список рефералов с пагинацией
StatsMenu Общая статистика и топ кураторов
SettingsMenu Админ-панель
GroupManagement Управление группами Force Subscribe

Решение проблем

Бот не запускается

Ошибка Решение
BOT_TOKEN не задан в .env Проверьте файл .env в WorkingDirectory сервиса
ModuleNotFoundError source venv/bin/activate && pip install -r requirements.txt
status=203/EXEC в systemd Проверьте пути в .service: ExecStart, WorkingDirectory, User
Permission denied chmod +x venv/bin/python или проверьте владельца файлов: chown -R your_user:your_user ~/Referal

Проверка путей:

# Файл .env существует?
ls -la ~/Referal/.env

# Python из venv работает?
~/Referal/venv/bin/python --version

# Запуск вручную от имени пользователя сервиса
sudo -u your_user bash -c 'cd ~/Referal && source venv/bin/activate && python -m bot.main'

Force Subscribe не работает

Проблема Решение
Бот не видит подписку Бот — администратор группы с правом «Просмотр участников»
Группа не добавлена /add_group_here в группе от имени админа
Кнопка «Подписаться» не работает Создайте постоянную invite-ссылку в настройках группы

Рефералы не отслеживаются

Проблема Решение
Статус «⏳ ожидает» Пользователь перешёл по ссылке, но не вступил в группу
Нет уведомлений куратору Куратор должен нажать /start у бота (бот может писать в личку)
Вступление не фиксируется Бот — админ группы; проверьте логи: journalctl -u referral-bot -f

Как узнать chat_id группы

  1. Добавьте @getidsbot в группу.
  2. Или посмотрите ID в ответе бота на /add_group_here (формат: -1001234567890).

Бот упал после перезагрузки сервера

sudo systemctl status referral-bot
sudo systemctl start referral-bot

Если сервис не стартует автоматически:

sudo systemctl enable referral-bot

Резервное копирование и сброс базы

База данных — один файл referral_bot.db в корне проекта.

Создать бэкап

cd ~/Referal

# Бэкап с датой в имени файла
cp referral_bot.db ~/referral_bot_backup_$(date +%Y%m%d).db

# Или в отдельную папку
mkdir -p ~/backups
cp referral_bot.db ~/backups/referral_bot_$(date +%Y%m%d_%H%M).db

Автоматический бэкап через cron (ежедневно в 3:00):

mkdir -p ~/backups
crontab -e

Добавить строку (замените your_user на имя пользователя Linux):

0 3 * * * cp /home/your_user/Referal/referral_bot.db /home/your_user/backups/referral_bot_$(date +\%Y\%m\%d).db

Восстановить из бэкапа

cd ~/Referal

# Остановить бота
sudo systemctl stop referral-bot

# Восстановить файл (укажите свой бэкап)
cp ~/backups/referral_bot_20260805.db referral_bot.db

# Запустить бота
sudo systemctl start referral-bot

Полный сброс базы (начать с нуля)

Удаляет всех пользователей, рефералов, группы и логи. Файл .env не затрагивается.

cd ~/Referal

# Остановить бота
sudo systemctl stop referral-bot

# По желанию — сохранить бэкап перед удалением
cp referral_bot.db ~/referral_bot_before_reset.db

# Удалить базу
rm referral_bot.db

# Запустить бота (создастся новая пустая БД)
sudo systemctl start referral-bot

После сброса заново:

  1. Отправьте боту /start
  2. В группе выполните /add_group_here от администратора
  3. Проверьте работу с чистой базой

Частичный сброс (без удаления БД)

В боте: ⚙️ Настройки → 🗑 Сброс статистики → введите пароль из RESET_STATS_PASSWORD в .env

Сбрасывает только членства в группах и логи активности. Пользователи и привязанные группы остаются. Без пароля в .env кнопка не сработает.

Лицензия

Свободное использование и модификация.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages