ayako/INSTALLATION.md

Руководство по установке 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: Установка бота

# Скачайте проект
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: Запуск бота

python bot.py

Если все настроено правильно, вы должны увидеть сообщение о том, что бот запущен.

---

Подробная установка

Linux/macOS

# 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)

# 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)

# 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 (рекомендуется)

# 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 напрямую

# 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
• Попробуйте уменьшить количество запрашиваемых полей
• Убедитесь, что ваше интернет соединение стабильно

Ошибка импорта модулей

# Убедитесь, что виртуальное окружение активировано и зависимости установлены
pip install -r requirements.txt --upgrade

SSL Certificate Error

# На некоторых системах может потребоваться:
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 для изменения других параметров:

MAX_RESULTS_PER_PAGE = 100  # Максимум результатов на странице
DEFAULT_RESULTS_PER_PAGE = 10  # По умолчанию результатов на странице
MAX_QUOTES_AT_ONCE = 5  # Максимум цитат за раз
API_TIMEOUT = 10  # Timeout для API запросов (в секундах)
BOT_TIMEOUT = 30  # Timeout для бота (в секундах)

---

Проверка зависимостей

# Проверьте, что все зависимости установлены правильно
pip check

# Обновите зависимости
pip install -r requirements.txt --upgrade

---

Выполнение тестов

# Установите зависимости для тестирования (они уже в requirements.txt)
# Запустите тесты
pytest test_bot.py -v

# С покрытием
pytest test_bot.py --cov=. --cov-report=html

---

Автозагрузка при запуске системы

Linux/macOS (systemd)

Создайте файл /etc/systemd/system/vndb-bot.service:

[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

Затем:

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
• 🐛 Проверьте логи
• 📝 Посмотрите примеры команд в /help
• 🌐 Посетите https://api.vndb.org/kana для справки по API

Удачи! 🚀