352 lines
10 KiB
Markdown
352 lines
10 KiB
Markdown
# TG Autoposter - Telegram Group Broadcasting Bot
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Мощный бот для Telegram с возможностью автоматической рассылки сообщений в несколько групп по расписанию с полным отслеживанием участников и истории сообщений.
|
||
|
||
## 🚀 Возможности
|
||
|
||
- ✅ **Отправка сообщений** в несколько групп одновременно
|
||
- ✅ **Планировщик расписаний** (cron выражения) для автоматических рассылок
|
||
- ✅ **Отслеживание участников** групп с автоматическим обновлением
|
||
- ✅ **История сообщений** с поддержкой версионирования
|
||
- ✅ **Асинхронная обработка** через Celery для масштабирования
|
||
- ✅ **Поддержка Pyrogram и Telethon** для гибкости клиента
|
||
- ✅ **PostgreSQL** для надежного хранения данных
|
||
- ✅ **Redis** для кеширования и очередей сообщений
|
||
- ✅ **Docker Compose** для простого развертывания
|
||
- ✅ **Flower** для мониторинга Celery задач
|
||
- ✅ **CI/CD** через GitHub Actions
|
||
|
||
## 📋 Требования
|
||
|
||
- Python 3.11+
|
||
- Docker & Docker Compose (для контейнеризации)
|
||
- PostgreSQL 15+ (или используйте Docker)
|
||
- Redis 7+ (или используйте Docker)
|
||
- Telegram BotAPI Token
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### С Docker (Рекомендуется)
|
||
|
||
```bash
|
||
# 1. Клонируем репозиторий
|
||
git clone https://github.com/yourusername/TG_autoposter.git
|
||
cd TG_autoposter
|
||
|
||
# 2. Копируем и редактируем .env
|
||
cp .env.example .env
|
||
nano .env
|
||
# Добавляем: TELEGRAM_BOT_TOKEN, TELEGRAM_API_ID, TELEGRAM_API_HASH, ADMIN_ID
|
||
|
||
# 3. Быстрый старт скрипт
|
||
chmod +x quickstart.sh
|
||
./quickstart.sh
|
||
|
||
## 📋 Переменные окружения
|
||
|
||
```env
|
||
# Telegram
|
||
TELEGRAM_BOT_TOKEN=your_token_here
|
||
TELEGRAM_API_ID=123456
|
||
TELEGRAM_API_HASH=abc123...
|
||
ADMIN_ID=123456789
|
||
|
||
# Database
|
||
DB_HOST=localhost
|
||
DB_PORT=5432
|
||
DB_USER=bot_user
|
||
DB_PASSWORD=secure_password
|
||
DB_NAME=tg_autoposter
|
||
|
||
# Redis
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_DB=0
|
||
REDIS_PASSWORD=optional
|
||
|
||
# Logging
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
## 🛠️ Основные команды
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
# Запуск контейнеров
|
||
docker-compose up -d
|
||
|
||
# Просмотр логов
|
||
docker-compose logs -f
|
||
docker-compose logs -f bot
|
||
docker-compose logs -f celery_worker_send
|
||
|
||
# Остановка
|
||
docker-compose down
|
||
|
||
# Перезапуск
|
||
docker-compose restart
|
||
|
||
# Удаление данных
|
||
docker-compose down -v
|
||
```
|
||
|
||
### Make команды
|
||
|
||
```bash
|
||
make help # Показать все команды
|
||
make up # Запустить контейнеры
|
||
make down # Остановить контейнеры
|
||
make logs # Просмотр логов
|
||
make test # Запустить тесты
|
||
make lint # Проверка кода
|
||
make fmt # Форматирование кода
|
||
```
|
||
|
||
### Bash скрипты
|
||
|
||
```bash
|
||
./docker.sh up # Запуск
|
||
./docker.sh down # Остановка
|
||
./docker.sh logs # Логи
|
||
./docker.sh shell # Bash в контейнер
|
||
./docker.sh ps # Список сервисов
|
||
./docker.sh celery-status # Статус Celery
|
||
```
|
||
|
||
## 📱 Использование бота
|
||
|
||
### Запуск бота
|
||
|
||
```
|
||
/start - Начать работу
|
||
/help - Показать помощь
|
||
```
|
||
|
||
### Создание сообщения
|
||
|
||
```
|
||
/create - Создать новое сообщение
|
||
```
|
||
|
||
### Рассылка
|
||
|
||
```
|
||
/broadcast - Отправить сообщение в несколько групп
|
||
/send - Отправить сообщение в одну группу
|
||
```
|
||
|
||
### Управление расписанием
|
||
|
||
```
|
||
/schedule list - Показать все расписания
|
||
/schedule add <msg_id> <group_id> <cron_expr> - Добавить расписание
|
||
/schedule remove <job_id> - Удалить расписание
|
||
```
|
||
|
||
Примеры cron выражений:
|
||
```
|
||
"0 9 * * *" # Ежедневно в 09:00
|
||
"0 9 * * 1-5" # Только по рабочим дням в 09:00
|
||
"*/30 * * * *" # Каждые 30 минут
|
||
"0 9,12,15 * * *" # В 09:00, 12:00 и 15:00
|
||
```
|
||
|
||
## 📊 Мониторинг
|
||
|
||
### Flower (Celery Dashboard)
|
||
|
||
```bash
|
||
# Доступен на: http://localhost:5555
|
||
# Логин: admin
|
||
# Пароль: (из .env FLOWER_PASSWORD)
|
||
|
||
# Показывает:
|
||
# - Активные задачи
|
||
# - Статус рабочих
|
||
# - История выполнения
|
||
# - Графики производительности
|
||
```
|
||
|
||
### Логи
|
||
|
||
```bash
|
||
# Docker
|
||
docker-compose logs -f
|
||
|
||
# Локально
|
||
tail -f logs/bot.log
|
||
tail -f logs/celery.log
|
||
```
|
||
|
||
## 🧪 Тестирование
|
||
|
||
```bash
|
||
# Запустить все тесты
|
||
pytest
|
||
|
||
# С покрытием
|
||
pytest --cov=app
|
||
|
||
# Конкретный тест файл
|
||
pytest tests/test_handlers.py
|
||
|
||
# Verbose режим
|
||
pytest -v
|
||
|
||
# Watch режим
|
||
pytest-watch
|
||
```
|
||
|
||
## 🔒 Безопасность
|
||
|
||
- ✅ Все чувствительные данные в `.env`
|
||
- ✅ Пароли хешируются в базе данных
|
||
- ✅ HTTPS для продакшена (LetsEncrypt)
|
||
- ✅ Ограничение API rate limiting
|
||
- ✅ Валидация всех входных данных
|
||
- ✅ SQL injection защита (SQLAlchemy ORM)
|
||
- ✅ Pre-commit hooks для проверки кода
|
||
|
||
## 📚 Документация
|
||
|
||
- [DEVELOPMENT.md](DEVELOPMENT.md) - Разработка и отладка
|
||
- [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md) - Развертывание в продакшене
|
||
- [docs/DOCKER_CELERY.md](docs/DOCKER_CELERY.md) - Docker и Celery детали
|
||
- [docs/DOCKER_QUICKSTART.md](docs/DOCKER_QUICKSTART.md) - Быстрый старт
|
||
|
||
## 🔧 Troubleshooting
|
||
|
||
### Bot не отвечает
|
||
|
||
```bash
|
||
# Проверьте логи
|
||
docker-compose logs bot | tail -50
|
||
|
||
# Проверьте токен
|
||
echo $TELEGRAM_BOT_TOKEN
|
||
|
||
# Перезагрузитесь
|
||
docker-compose restart bot
|
||
```
|
||
|
||
### Ошибки с базой данных
|
||
|
||
```bash
|
||
# Проверьте подключение
|
||
docker-compose exec postgres psql -U bot -d tg_autoposter
|
||
|
||
# Откатите миграции
|
||
docker-compose exec bot alembic downgrade -1
|
||
|
||
# Примените миграции снова
|
||
docker-compose exec bot alembic upgrade head
|
||
```
|
||
|
||
### Redis не работает
|
||
|
||
```bash
|
||
# Проверьте статус
|
||
docker-compose ps redis
|
||
|
||
# Проверьте логи
|
||
docker-compose logs redis
|
||
|
||
# Очистите кеш
|
||
redis-cli FLUSHDB
|
||
```
|
||
|
||
## 🤝 Контрибьютинг
|
||
|
||
1. Форкните репозиторий
|
||
2. Создайте feature branch (`git checkout -b feature/AmazingFeature`)
|
||
3. Коммитьте изменения с `git commit -m 'feat: add AmazingFeature'`
|
||
4. Пушьте в branch (`git push origin feature/AmazingFeature`)
|
||
5. Откройте Pull Request
|
||
|
||
Пожалуйста, следуйте нашему [Code of Conduct](CODE_OF_CONDUCT.md)
|
||
|
||
## 📝 Лицензия
|
||
|
||
MIT License - смотрите [LICENSE](LICENSE) файл
|
||
|
||
## 🎯 Roadmap
|
||
|
||
- [ ] REST API для управления ботом
|
||
- [ ] Web Dashboard UI
|
||
- [ ] Поддержка файлов и медиа
|
||
- [ ] Шифрование чувствительных данных
|
||
- [ ] Kubernetes manifests
|
||
- [ ] GraphQL API
|
||
- [ ] Auto-scaling
|
||
|
||
## 📞 Контакты и Поддержка
|
||
|
||
- **Issues**: [GitHub Issues](https://github.com/yourusername/TG_autoposter/issues)
|
||
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/TG_autoposter/discussions)
|
||
- **Email**: your.email@example.com
|
||
|
||
## 🙏 Благодарности
|
||
|
||
- [Pyrogram](https://docs.pyrogram.org/) - Telegram Bot API wrapper
|
||
- [Telethon](https://docs.telethon.dev/) - Telegram Client library
|
||
- [Celery](https://docs.celeryproject.io/) - Distributed Task Queue
|
||
- [SQLAlchemy](https://docs.sqlalchemy.org/) - ORM
|
||
- [APScheduler](https://apscheduler.readthedocs.io/) - Job Scheduling
|
||
|
||
---
|
||
|
||
**Версия**: 1.0.0
|
||
**Статус**: Production Ready ✅
|
||
**Последнее обновление**: 2024-01-01
|
||
|
||
**Made with ❤️ by the Development Team**
|
||
|
||
|
||
## Логирование
|
||
|
||
Все события логируются в консоль:
|
||
|
||
```
|
||
INFO:app:Инициализация базы данных...
|
||
INFO:app:База данных инициализирована
|
||
INFO:app:Бот запущен
|
||
INFO:app.handlers.group_manager:Бот добавлен в группу: MyGroup (ID: -1001234567890)
|
||
```
|
||
|
||
## Решение проблем
|
||
|
||
### БД не инициализирована
|
||
|
||
Если вы видите ошибку `table not found`, убедитесь что:
|
||
1. БД файл существует (создается автоматически)
|
||
2. Права доступа правильные
|
||
3. DATABASE_URL в `.env` правильный
|
||
|
||
### Бот не отправляет сообщения
|
||
|
||
1. Проверьте что токен правильный в `.env`
|
||
2. Убедитесь что бот добавлен в группу
|
||
3. Проверьте что у бота есть права на отправку сообщений
|
||
4. Посмотрите логи для подробной информации
|
||
|
||
### Ошибка при добавлении в группу
|
||
|
||
Убедитесь что:
|
||
1. Это не приватный чат
|
||
2. У вас есть права администратора группы
|
||
3. Токен бота правильный
|
||
|
||
## Лицензия
|
||
|
||
MIT
|
||
|
||
## Контакты
|
||
|
||
Для вопросов и предложений создавайте Issues в репозитории.
|