hteppl/4vps-billing repository overview

⁠4vps-billing

Сервис мониторинга баланса 4VPS⁠ с уведомлениями в Telegram. Отправляет ежедневные отчёты о балансе с прогнозом платежей и уведомляет о пополнениях в реальном времени.

⁠Возможности

• Ежедневные отчёты - Отправка отчёта о балансе в заданное время
• Прогноз платежей - Расчёт предстоящих списаний на N дней вперёд
• Предупреждения - Уведомление о недостатке средств для оплаты серверов
• Отслеживание пополнений - Мгновенные уведомления о пополнении баланса
• Мультиязычность - Поддержка русского и английского языков
• Поддержка топиков - Работа с форумными чатами Telegram

⁠Требования

Перед началом убедитесь, что у вас есть:

• Аккаунт 4VPS с активными серверами
• API ключ 4VPS - Получите на странице API⁠
• Telegram бот - Создайте через @BotFather⁠
• Chat ID - Получите через @username_to_id_bot⁠

⁠Конфигурация

Скопируйте .env.example⁠ в .env и заполните значения:

# Telegram бот токен
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# ID чата для уведомлений
TELEGRAM_CHAT_ID=your_chat_id_here

# ID топика для форумных чатов (опционально)
TELEGRAM_TOPIC_ID=

# API ключ 4VPS
FOURVPS_API_KEY=your_api_key_here

# Язык сообщений (ru, en)
LOCALE=ru

# Время отправки ежедневного отчёта (24-часовой формат)
NOTIFICATION_TIME=09:00

# Количество дней для прогноза платежей
PREDICTION_DAYS=7

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

# Интервал проверки баланса для отслеживания пополнений (в секундах)
BALANCE_CHECK_INTERVAL=1800

⁠Описание параметров

⁠Установка

⁠Docker (рекомендуется)

1. Создайте docker-compose.yml:

services:
  4vps-billing:
    build: .
    container_name: 4vps-billing
    restart: unless-stopped
    env_file:
      - .env
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

1. Создайте и настройте .env файл:

cp .env.example .env
nano .env

1. Запустите контейнер:

docker compose up -d && docker compose logs -f

⁠Ручная установка

1. Клонируйте репозиторий:

git clone https://github.com/hteppl/4vps-billing.git
cd 4vps-billing

1. Создайте виртуальное окружение:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# или
.venv\Scripts\activate     # Windows

1. Установите зависимости:

pip install -r requirements.txt

1. Создайте и настройте .env файл:

cp .env.example .env

1. Запустите приложение:

python -m src

⁠Как это работает

1. Запуск - При старте сервис отправляет начальный отчёт о балансе с прогнозом платежей

2. Ежедневные отчёты - В заданное время (NOTIFICATION_TIME) отправляется отчёт с текущим балансом и предстоящими списаниями

3. Мониторинг пополнений - Сервис периодически проверяет баланс и отправляет уведомление при обнаружении пополнения

4. Предупреждения - Если баланса не хватит для оплаты серверов, в отчёте будет предупреждение с датой

⁠Логи

Для диагностики проблем используйте логи:

# Docker
docker compose logs -f

# Ручная установка
# Логи выводятся в stdout с временными метками

⁠Лицензия

Проект распространяется под лицензией GNU General Public License v3.0⁠.