init commit
This commit is contained in:
351
README.md
Normal file
351
README.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# 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 в репозитории.
|
||||
Reference in New Issue
Block a user