344 lines
9.7 KiB
Markdown
344 lines
9.7 KiB
Markdown
# Руководство по установке VNDB Telegram Bot
|
||
|
||
## Быстрый старт (5 минут)
|
||
|
||
### Требования
|
||
- Python 3.8 или выше
|
||
- pip (идёт с Python)
|
||
- Интернет соединение
|
||
|
||
### Шаг 1: Получение токенов
|
||
|
||
#### Telegram Bot Token
|
||
1. Откройте Telegram и найдите @BotFather
|
||
2. Напишите `/newbot`
|
||
3. Ответьте на вопросы о названии и username вашего бота
|
||
4. Вы получите токен (выглядит как `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
|
||
|
||
#### VNDB API Token (опционально)
|
||
1. Создайте аккаунт на https://vndb.org (если ещё нет)
|
||
2. Перейдите на https://vndb.org/u/tokens
|
||
3. Нажмите "Create new token"
|
||
4. Скопируйте полученный токен
|
||
|
||
### Шаг 2: Установка бота
|
||
|
||
```bash
|
||
# Скачайте проект
|
||
git clone <repo_url>
|
||
cd vntgbot
|
||
|
||
# Создайте виртуальное окружение (рекомендуется)
|
||
python -m venv venv
|
||
|
||
# Активируйте виртуальное окружение
|
||
# На Windows:
|
||
venv\Scripts\activate
|
||
# На macOS/Linux:
|
||
source venv/bin/activate
|
||
|
||
# Установите зависимости
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### Шаг 3: Настройка переменных окружения
|
||
|
||
Создайте файл `.env` в корневой папке проекта:
|
||
|
||
```
|
||
TELEGRAM_BOT_TOKEN=ваш_токен_тг
|
||
VNDB_TOKEN=ваш_токен_vndb
|
||
```
|
||
|
||
Заменив `ваш_токен_тг` и `ваш_токен_vndb` на реальные токены.
|
||
|
||
### Шаг 4: Запуск бота
|
||
|
||
```bash
|
||
python bot.py
|
||
```
|
||
|
||
Если все настроено правильно, вы должны увидеть сообщение о том, что бот запущен.
|
||
|
||
---
|
||
|
||
## Подробная установка
|
||
|
||
### Linux/macOS
|
||
|
||
```bash
|
||
# 1. Скачайте исходный код
|
||
git clone <repo_url>
|
||
cd vntgbot
|
||
|
||
# 2. Создайте виртуальное окружение
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
# 3. Обновите pip
|
||
pip install --upgrade pip
|
||
|
||
# 4. Установите зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# 5. Создайте .env файл
|
||
cp .env.example .env
|
||
# Отредактируйте .env и добавьте токены
|
||
nano .env
|
||
|
||
# 6. Запустите бота
|
||
python bot.py
|
||
```
|
||
|
||
### Windows (PowerShell)
|
||
|
||
```powershell
|
||
# 1. Скачайте исходный код
|
||
git clone <repo_url>
|
||
cd vntgbot
|
||
|
||
# 2. Создайте виртуальное окружение
|
||
python -m venv venv
|
||
.\venv\Scripts\Activate.ps1
|
||
|
||
# 3. Обновите pip
|
||
python -m pip install --upgrade pip
|
||
|
||
# 4. Установите зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# 5. Создайте .env файл
|
||
Copy-Item .env.example .env
|
||
# Отредактируйте .env с помощью notepad или вашего любимого редактора
|
||
notepad .env
|
||
|
||
# 6. Запустите бота
|
||
python bot.py
|
||
```
|
||
|
||
### Windows (CMD)
|
||
|
||
```cmd
|
||
# 1. Скачайте исходный код
|
||
git clone <repo_url>
|
||
cd vntgbot
|
||
|
||
# 2. Создайте виртуальное окружение
|
||
python -m venv venv
|
||
venv\Scripts\activate.bat
|
||
|
||
# 3. Обновите pip
|
||
python -m pip install --upgrade pip
|
||
|
||
# 4. Установите зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# 5. Создайте .env файл
|
||
copy .env.example .env
|
||
REM Отредактируйте .env
|
||
|
||
# 6. Запустите бота
|
||
python bot.py
|
||
```
|
||
|
||
---
|
||
|
||
## Развертывание с помощью Docker
|
||
|
||
### Требования
|
||
- Docker
|
||
- Docker Compose (опционально)
|
||
|
||
### С использованием Docker Compose (рекомендуется)
|
||
|
||
```bash
|
||
# 1. Создайте .env файл в корневой папке
|
||
echo "TELEGRAM_BOT_TOKEN=ваш_токен" > .env
|
||
echo "VNDB_TOKEN=ваш_токен" >> .env
|
||
|
||
# 2. Запустите бота
|
||
docker-compose up -d
|
||
|
||
# 3. Проверьте логи
|
||
docker-compose logs -f vndb-bot
|
||
|
||
# 4. Остановите бота
|
||
docker-compose down
|
||
```
|
||
|
||
### С использованием Docker напрямую
|
||
|
||
```bash
|
||
# 1. Создайте образ
|
||
docker build -t vndb-bot .
|
||
|
||
# 2. Запустите контейнер
|
||
docker run -d \
|
||
--name vndb-bot \
|
||
-e TELEGRAM_BOT_TOKEN=ваш_токен \
|
||
-e VNDB_TOKEN=ваш_токен \
|
||
vndb-bot
|
||
|
||
# 3. Проверьте логи
|
||
docker logs vndb-bot
|
||
|
||
# 4. Остановите контейнер
|
||
docker stop vndb-bot
|
||
docker rm vndb-bot
|
||
```
|
||
|
||
---
|
||
|
||
## Проверка установки
|
||
|
||
После запуска бота:
|
||
|
||
1. Откройте Telegram
|
||
2. Найдите вашего бота по username
|
||
3. Напишите `/start`
|
||
4. Вы должны увидеть приветственное сообщение
|
||
|
||
Если всё работает, попробуйте команду:
|
||
```
|
||
/stats
|
||
```
|
||
|
||
---
|
||
|
||
## Решение проблем
|
||
|
||
### Ошибка: "TELEGRAM_BOT_TOKEN not set"
|
||
- Проверьте, что файл `.env` существует в корневой папке
|
||
- Убедитесь, что в `.env` правильно указан токен
|
||
- Убедитесь, что токен не содержит кавычки или лишних пробелов
|
||
|
||
### Ошибка: "Connection refused"
|
||
- Проверьте интернет соединение
|
||
- Убедитесь, что сервер VNDB API доступен (https://api.vndb.org/kana)
|
||
|
||
### Бот не отвечает на сообщения
|
||
- Проверьте, что бот имеет права администратора в чате (если используется в групповом чате)
|
||
- Убедитесь, что в настройках бота включены приватные сообщения
|
||
- Перезагрузите бота: остановите его и запустите снова
|
||
|
||
### Медленные ответы
|
||
- Это может быть из-за ограничений API VNDB
|
||
- Попробуйте уменьшить количество запрашиваемых полей
|
||
- Убедитесь, что ваше интернет соединение стабильно
|
||
|
||
### Ошибка импорта модулей
|
||
```bash
|
||
# Убедитесь, что виртуальное окружение активировано и зависимости установлены
|
||
pip install -r requirements.txt --upgrade
|
||
```
|
||
|
||
### SSL Certificate Error
|
||
```bash
|
||
# На некоторых системах может потребоваться:
|
||
pip install certifi
|
||
# Или использовать нестабильное соединение (не рекомендуется):
|
||
# Добавьте в bot.py перед запуском: import ssl; ssl._create_default_https_context = ssl._create_unverified_context
|
||
```
|
||
|
||
---
|
||
|
||
## Конфигурация
|
||
|
||
### Переменные окружения
|
||
|
||
| Переменная | Обязательна | По умолчанию | Описание |
|
||
|-----------|----------|----------|-----------|
|
||
| TELEGRAM_BOT_TOKEN | Да | - | Токен Telegram бота |
|
||
| VNDB_TOKEN | Нет | - | Токен VNDB API для авторизации |
|
||
| LOG_LEVEL | Нет | INFO | Уровень логирования (DEBUG, INFO, WARNING, ERROR) |
|
||
| USE_SANDBOX | Нет | false | Использовать sandbox API для тестирования |
|
||
|
||
### Файл config.py
|
||
|
||
Вы можете отредактировать `config.py` для изменения других параметров:
|
||
|
||
```python
|
||
MAX_RESULTS_PER_PAGE = 100 # Максимум результатов на странице
|
||
DEFAULT_RESULTS_PER_PAGE = 10 # По умолчанию результатов на странице
|
||
MAX_QUOTES_AT_ONCE = 5 # Максимум цитат за раз
|
||
API_TIMEOUT = 10 # Timeout для API запросов (в секундах)
|
||
BOT_TIMEOUT = 30 # Timeout для бота (в секундах)
|
||
```
|
||
|
||
---
|
||
|
||
## Проверка зависимостей
|
||
|
||
```bash
|
||
# Проверьте, что все зависимости установлены правильно
|
||
pip check
|
||
|
||
# Обновите зависимости
|
||
pip install -r requirements.txt --upgrade
|
||
```
|
||
|
||
---
|
||
|
||
## Выполнение тестов
|
||
|
||
```bash
|
||
# Установите зависимости для тестирования (они уже в requirements.txt)
|
||
# Запустите тесты
|
||
pytest test_bot.py -v
|
||
|
||
# С покрытием
|
||
pytest test_bot.py --cov=. --cov-report=html
|
||
```
|
||
|
||
---
|
||
|
||
## Автозагрузка при запуске системы
|
||
|
||
### Linux/macOS (systemd)
|
||
|
||
Создайте файл `/etc/systemd/system/vndb-bot.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=VNDB Telegram Bot
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=your_username
|
||
WorkingDirectory=/path/to/vntgbot
|
||
Environment="PATH=/path/to/vntgbot/venv/bin"
|
||
ExecStart=/path/to/vntgbot/venv/bin/python bot.py
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
Затем:
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable vndb-bot
|
||
sudo systemctl start vndb-bot
|
||
```
|
||
|
||
### Windows (Планировщик задач)
|
||
|
||
1. Откройте Планировщик задач
|
||
2. Создайте новую задачу
|
||
3. Установите триггер "При запуске"
|
||
4. Установите действие: запустить `python.exe` с аргументом `C:\path\to\bot.py`
|
||
5. Сохраните задачу
|
||
|
||
---
|
||
|
||
## Нужна помощь?
|
||
|
||
- 📖 Прочитайте [README.md](README.md)
|
||
- 🐛 Проверьте [логи](#логирование)
|
||
- 📝 Посмотрите примеры команд в `/help`
|
||
- 🌐 Посетите https://api.vndb.org/kana для справки по API
|
||
|
||
Удачи! 🚀
|