popugate

PopuGate

Описание проекта

PopuGate — это современный менеджер прокси-серверов Telegram MTProto. В его основе лежит высокопроизводительный движок telemt 3.x (написанный на Rust и работающий в Docker), которым управляет мощный бэкенд на языке Go (с REST API). Также для него предусмотрен удобный фронтенд на Vue 3, TypeScript и SCSS (исходный код находится в директории web/ данного репозитория).

PopuGate предоставляет огромный функционал для управления, мониторинга и масштабирования MTProto прокси с удобным пользовательским интерфейсом.

Дисклеймер: PopuGate вдохновлен проектом MTProxyMax — спасибо автору за идею. Проект разрабатывается с активным использованием нейросетей (AI-assisted development) и может содержать недоработки — он находится в стадии активной разработки. Буду признателен за bug-репорты и pull requests.

Основные возможности

• Индивидуальный контроль доступа: Гибкое управление пользователями, генерация секретов (ключей доступа) и добавление заметок.
• Мониторинг трафика: Подробный сбор и анализ статистики по потреблению трафика.
• Master-Slave репликация: Возможность масштабирования прокси-сети с помощью подчиненных (slave) узлов.
• Цепочки прокси (Proxy chaining): Подключение к Telegram через промежуточные серверы (Upstreams).
• Гео-блокировка (Geo-blocking): Ограничение доступа к прокси по географическому признаку с использованием актуальных CIDR баз списка адресов.
• Интеграция с Telegram Bot: Удобное управление прокси, получение статистики, создание секретов и генерация QR-кодов для подключения напрямую из Telegram.
• Автоматические обновления: Система следит за актуальностью всех компонентов. Поддерживается обновление как бинарного файла (через скачивание с GitHub и перезапуск systemd-службы), так и Docker-контейнера (pull нового образа и пересоздание контейнера через sidecar). Веб-интерфейс автоматически определяет режим и отображает соответствующие элементы управления.
• Управление планировщиком: Включение/отключение фоновых задач, изменение расписаний, просмотр истории выполнения с ошибками — через веб-интерфейс, API и Telegram-бота.
• Резервное копирование: Автоматическое ежедневное создание бекапов с настраиваемой ротацией по количеству дней хранения.
• Шифрование бекапов: Опциональное AES-256-GCM шифрование бекапов для защиты данных в покое.
• Шаблоны секретов: Создание предустановок лимитов для быстрого применения к секретам.
• Аудит: Журнал действий пользователей с историей всех ключевых операций.
• Мониторинг ресурсов: Отслеживание CPU, памяти и диска в реальном времени через WebSocket.
• Проверка здоровья upstream: Автоматический мониторинг доступности upstream-серверов.

Поддерживаемые платформы: Linux (Ubuntu, Debian, CentOS, RHEL, Fedora, Rocky, AlmaLinux, Alpine).

Архитектура

Бэкенд приложения написан на Go и использует следующие технологии:

• Веб-фреймворк: Gin
• База данных: Встроенная SQLite (modernc.org/sqlite, собирается без CGo для удобной кросс-компиляции)
• Авторизация: JWT-токены (github.com/golang-jwt/jwt/v5) и шифрование паролей через bcrypt
• Docker: Управление контейнером движка через Docker Engine SDK
• SSH/Криптография: Синхронизация и генерация ключей через golang.org/x/crypto/ssh
• Планировщик задач: Cron-система через robfig/cron/v3
• Движок: Мультиархитектурный Docker-образ telemt (ghcr.io/fussraider/popugate-telemt)

В процессе работы приложения вся конфигурация (база данных, сгенерированные конфиги движка, базы гео-зон) по умолчанию хранится в рабочей директории приложения (автоопределение или /opt/popugate/ на Linux).

---

🐳 Запуск в Docker (рекомендуется)

Вы можете запустить PopuGate в Docker-контейнере. Это удобно, так как все зависимости уже упакованы в образ, и вам нужно только смонтировать docker.sock для управления движком прокси.

Использование Docker Compose (Полный стек)

Рекомендуемый способ запуска со встроенным веб-интерфейсом и проксированием через Nginx:

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

services:
  popugate-backend:
    image: ghcr.io/fussraider/popugate:latest
    container_name: popugate-backend
    restart: unless-stopped
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ADMIN_PASSWORD=mysecretpassword
      - POPUGATE_DATA_DIR=/data
      - TZ=Europe/Moscow
      - HOSTNAME=popugate-backend
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "9090:9090" # Метрики по умолчанию (дополнительные порты добавьте по необходимости)

  popugate-web:
    image: ghcr.io/fussraider/popugate-web:latest
    container_name: popugate-web
    restart: unless-stopped
    ports:
      - "80:80"     # Веб-интерфейс (HTTP)
      - "8443:8443" # Веб-интерфейс (HTTPS)
    environment:
      - DOMAIN_NAME=your-domain.com
    volumes:
      - ./certbot/conf:/etc/letsencrypt:ro
      - ./certbot/www:/var/www/certbot:ro
    depends_on:
      - popugate-backend

  certbot:
    image: certbot/certbot
    container_name: certbot
    volumes:
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

1. Запустите стек:

docker compose up -d

Сборка образов вручную

Если вы хотите собрать образы самостоятельно:

# Бэкенд
DOCKER_BUILDKIT=1 docker buildx build -t popugate . --load

# Фронтенд
cd web && DOCKER_BUILDKIT=1 docker buildx build -t popugate-web . --load

---

🚀 Быстрый старт (Бинарный файл)

Перед запуском убедитесь, что на сервере установлен и запущен Docker. Для корректной работы приложение необходимо запускать от имени суперпользователя (root), чтобы иметь права на взаимодействие с iptables и демоном Docker.

1. Установите/скачайте последнюю версию (latest release) для вашей архитектуры (к примеру, amd64):

wget -O popugate https://github.com/fussraider/PopuGate/releases/latest/download/popugate-linux-amd64

1. Выдайте права на выполнение файла:

chmod +x popugate

1. Установите первоначальный пароль администратора:

sudo ./popugate setup

(Вам будет предложено ввести пароль для входа в панель управления).

1. Запустите бэкенд сервер:

sudo ./popugate server

(Сервер запустится в текущей сессии. Для запуска в фоновом режиме используйте системную службу, как описано ниже).

Примечание: По умолчанию бэкенд сервер доступен на порту 8090, а прокси-движок внутри Docker — на стандартном порту 443. При использовании Docker Compose веб-интерфейс доступен на стандартном HTTP порту 80. Все рабочие данные сохраняются в директорию, где находится бинарный файл, или в /opt/popugate/ (в зависимости от прав доступа и ОС).

Важные особенности работы в Docker

• Network Host: Прокси-движок (telemt) запускается бэкендом в режиме network: host. Это необходимо для корректной работы MTProxy и минимизации накладных расходов на сеть.
• Порты: Из-за использования network: host, прокси-движок занимает порты (443 и другие) непосредственно на хост-машине.
  • ⚠️ ВНИМАНИЕ: Не пытайтесь переназначить веб-интерфейс (popugate-web) на порт 443 в docker-compose.yml, если вы используете стандартный порт для прокси. Это приведет к конфликту портов.
  • Не пробрасывайте порты прокси в секции ports для сервиса popugate-backend, так как движок сам откроет их на хосте.
• Docker Socket: Бэкенду необходим доступ к /var/run/docker.sock для управления контейнерами движка.
• Связь с хостом: Для того чтобы бэкенд в Docker мог собирать метрики с прокси (которые работают в сети хоста), в docker-compose.yml должна быть настроена секция extra_hosts с параметром host.docker.internal:host-gateway.

---

🌐 Сетевые настройки (Firewall)

Для полноценной работы приложения необходимо открыть следующие порты:

• 8090 (TCP): Веб-интерфейс и REST API (при запуске бинарным файлом).
• 80 (TCP): Веб-интерфейс по HTTP (при запуске через Docker Compose).
• 8443 (TCP): Веб-интерфейс по HTTPS (при настройке SSL в Docker Compose).
• 443 (TCP): Стандартный порт для входящих подключений пользователей MTProto (занят прокси-движком). Может быть изменен или добавлено несколько портов в настройках инстансов.
• 9090 (TCP): Порт для сбора метрик Prometheus по умолчанию. Если вы используете несколько инстансов, порты метрик также необходимо открыть.

---

⚙️ Конфигурация и переменные окружения

Настройка работы бэкенд сервера возможна через переменные окружения (Environment Variables) и флаги командной строки:

Переменные окружения (ENV)

• POPUGATE_DATA_DIR — задает главную рабочую директорию, где будут храниться база данных SQLite (settings.db), кэши, конфигурации для движка (mtproxy/config.toml) и прочих сгенерированных файлов.
  • Порядок приоритета директории:
    1. Флаг -data (наивысший приоритет)
    2. Переменная окружения POPUGATE_DATA_DIR
    3. Директория, в которой находится запущенный бинарный файл
    4. Текущая рабочая директория (CWD)
    5. Стандартный путь /opt/popugate/ (fallback)
• POPUGATE_DEPLOYMENT — (автоматически) указывает тип развертывания. Значение docker автоматически устанавливается в Docker-образе и определяет режим обновления (pull образа вместо скачивания бинарного файла).
• DEBUG — (опционально) включает режим отладки Gin (true или false). По умолчанию false (Release mode). Имеет приоритет над настройками в БД.
• GIN_MODE — стандартная переменная Gin. debug эквивалентен DEBUG=true, release — DEBUG=false.
• TELEMT_VERSION — (опционально) переопределяет версию движка telemt (по умолчанию: 3.3.39).
• TELEMT_COMMIT — (опционально) переопределяет конкретный commit/ref для сборки движка (по умолчанию: bc69153).
• TELEMT_REPO — (опционально) переопределяет URL git-репозитория для сборки движка (по умолчанию: https://github.com/telemt/telemt.git).

Флаги командной строки

При запуске бинарного файла popugate, вы можете передать следующие флаги:

• -port <число> — устанавливает порт для запуска HTTP сервера (по умолчанию: 8090).
• -data <путь> — явно переопределяет директорию хранения рабочих данных, имеет наивысший приоритет над POPUGATE_DATA_DIR.
• -db <путь> — задает конкретный путь до SQLite файла базы данных (по умолчанию: <data-dir>/settings.db).

Команда setup также поддерживает флаг -data для инициализации в конкретной директории.

Пример запуска с аргументами и настройкой движка:

# Инициализация пароля в кастомной директории
sudo ./popugate setup -data /var/lib/popugate

# Запуск с кастомной версией движка, портом и в режиме отладки
export TELEMT_VERSION="3.4.0"
export DEBUG=true
sudo -E ./popugate server -port 9090 -data /var/lib/popugate

---

🔒 Настройка HTTPS (SSL) для веб-интерфейса

При использовании Docker Compose вы можете настроить автоматический выпуск SSL-сертификатов Let's Encrypt для вашего домена. Веб-интерфейс будет доступен по адресу https://your-domain.com:8443.

1. В файле docker-compose.yml (или через .env файл) укажите ваш домен:

   environment:
     - DOMAIN_NAME=your-domain.com
   

2. Запустите скрипт для первичного выпуска сертификата:

   sudo ./scripts/init-ssl.sh your-domain.com your-email@example.com
   

3. Скрипт автоматически запустит Certbot, выпустит сертификат и перезагрузит Nginx. Сертификаты будут автоматически обновляться сервисом certbot каждые 12 часов.

Примечание: Для работы Let's Encrypt порт 80 вашего сервера должен быть доступен из интернета.

---

🖥️ Веб-интерфейс

PopuGate предоставляет интуитивно понятный веб-интерфейс для управления всеми аспектами MTProto прокси. Поддерживается светлая и тёмная тема (переключатель в верхней панели), а также двуязычный интерфейс (Русский / English). Ниже приведено описание основных разделов:

📊 Панель управления (Dashboard)

Центральный хаб мониторинга, где отображается текущий статус прокси, количество активных секретов, число подключений и статистика трафика. Здесь также доступны быстрые действия для запуска, остановки и перезагрузки сервиса, а также показатели "здоровья" системы (Docker, контейнер, порты, метрики).

🖥️ Системное меню (System)

Управление приложением как системной службой. Позволяет:

• Установить/Удалить службу: Автоматическая генерация и установка unit-файла systemd.
• Управление: Перезапуск и просмотр статуса службы прямо из интерфейса.
• Информация: Просмотр версии ОС и текущего состояния системы.

🔑 Секреты (Secrets)

Управление ключами доступа пользователей.

• Добавление/удаление: Создание новых секретов с возможностью ручного ввода или автогенерации.
• Ограничения: Установка лимитов по количеству одновременных подключений, уникальных IP-адресов и квот на трафик (в МБ).
• Срок действия: Установка даты истечения ключа.
• Ротация: Возможность быстрой смены секретного ключа для существующей метки.
• QR-коды: Генерация QR-кодов для удобного подключения в Telegram.
• Переименование: Изменение метки (label) существующего секрета.
• Продление: Продление срока действия ключа на указанное количество дней с автоматическим повторным включением.
• Клонирование: Создание точной копии секрета с новой меткой и автосгенерированным ключом.
• Теги: Присвоение секрету произвольных тегов для группировки и фильтрации.
• Архивация: Временное скрытие секретов из основного списка без удаления.
• Массовые операции: Одновременное продление и ротация ключей для группы секретов.
• Поиск: Быстрый поиск секретов по метке или заметкам.
• Топ: Рейтинг секретов по объему потребленного трафика.
• Экспорт/Импорт: Массовый экспорт и импорт секретов в формате JSON.

📋 Шаблоны (Templates)

Отдельный раздел для создания и управления предустановками лимитов. Позволяет:

• Создавать именованные шаблоны с параметрами (макс. подключений, IP, квота, срок действия, теги, заметки).
• Применять шаблон к существующему секрету одним нажатием — все лимиты обновляются автоматически.
• Управление шаблонами: создание, удаление и применение через веб-интерфейс или REST API.

🔀 Upstreams

Настройка цепочек прокси. Позволяет перенаправлять трафик от вашего сервера к Telegram через промежуточные SOCKS4/SOCKS5 серверы. Поддерживается балансировка весов и привязка к конкретным сетевым интерфейсам.

🖥️ Инстансы (Instances)

Центральная страница управления прокси. Каждый инстанс — это полностью независимый прокси с собственным портом, доменом маскировки, настройками FakeTLS и тегами доступа. Поддерживается:

• Глобальное управление: запуск, остановка, перезапуск и горячая перезагрузка всех инстансов разом.
• Мультидоменность: один инстанс может обслуживать несколько TLS-доменов на одном порту (primary + дополнительные).
• FakeTLS: включение/выключение TLS-эмуляции и маскировки трафика для каждого инстанса отдельно.
• Теги доступа: ограничение доступа к инстансу по тегам — секрет получит ссылку только на те инстансы, чьи теги пересекаются с его тегами.
• Индивидуальное управление: старт, стоп и горячая перезагрузка каждого инстанса независимо от других.
• Массовые операции: групповой запуск, остановка, перезагрузка и включение/отключение выбранных инстансов.
• Логи: просмотр логов каждого инстанса в реальном времени (SSE).
• Мониторинг: собственные метрики (порт, трафик, подключения) для каждого инстанса.
• Мульти-ссылки: при генерации ссылки создаются все комбинации (инстанс × домен), что даёт пользователю несколько вариантов подключения.

🐳 Docker

Управление инфраструктурой Docker. Позволяет проверить наличие установленного Docker в системе, установить его при необходимости, а также собрать или обновить образ движка telemt.

🌍 Гео-блокировка (Geoblock)

Управление доступом на основе географии пользователей. Поддерживаются два режима:

• Blacklist: Блокировка трафика из указанных стран.
• Whitelist: Разрешение трафика только из списка доверенных стран. Изменения применяются мгновенно на уровне iptables.

📈 Трафик (Traffic)

Детальная статистика использования ресурсов:

• Global: Общий объем входящего и исходящего трафика сервера.
• Live Metrics: Текущие активные подключения в разрезе каждого пользователя.
• Per-User: Суммарная статистика потребления трафика каждым секретом.

🤖 Telegram Bot

Настройка сервисного бота для управления прокси прямо из мессенджера. Поддерживает уведомления, отчеты по трафику, команды для управления секретами и команду /tasks для просмотра расписания и статуса фоновых задач.

🔄 Репликация (Replication)

Инструментарий для создания Master-Slave конфигураций. Позволяет синхронизировать настройки и секреты между несколькими серверами через SSH, обеспечивая масштабируемость и отказоустойчивость.

🆙 Обновления (Updates)

Система автоматической проверки и ручного применения обновлений PopuGate. Интерфейс автоматически определяет режим работы:

• Бинарный режим: Скачивает новый бинарный файл с GitHub Releases (с проверкой SHA256), делает резервную копию текущего и перезапускает службу через systemd.
• Docker-режим: Загружает новый образ контейнера из GHCR и пересоздаёт контейнер с сохранением всех настроек (тома, переменные окружения, сеть, политика перезапуска). Страница автоматически обновляется после перезапуска.

💾 Резервные копии (Backups)

Создание и восстановление полных бэкапов конфигурации и базы данных. Поддерживается скачивание файлов бэкапа на локальный компьютер. Автоматическое ежедневное создание бекапов (по умолчанию в 3:00) с настраиваемой ротацией — устаревшие бекапы удаляются автоматически (по умолчанию старше 7 дней).

Что входит в бэкап

Бэкап содержит полную копию всех данных приложения:

Компонент	Описание
База данных	SQLite settings.db с полной схемой (см. ниже)
Конфигурация движка	mtproxy/config-<port>.toml — настройки telemt (по одному на инстанс)
SSH-ключи	mtproxy/ssh_host_key — ключ для репликации
Версия движка	.telemt_version — версия telemt для восстановления
Manifest	manifest.json — метаданные бэкапа (версия, контрольные суммы)

Таблицы базы данных (schema_version 10):

• settings — общие настройки приложения
• secrets — пользовательские секреты (ключи доступа)
• upstreams — цепочки прокси (SOCKS5/4)
• instances — конфигурации прокси-инстансов (порт, домены, FakeTLS, маскировка, теги)
• slaves — узлы репликации (Master-Slave)
• templates — шаблоны секретов
• traffic_history — история трафика
• traffic_user — текущий трафик пользователей (по метке + инстансу)
• audit_log — журнал аудита действий
• scheduler_tasks — задачи планировщика

Шифрование

Бэкапы могут быть защищены AES-256-GCM шифрованием:

• Ключ шифрования задаётся через переменную окружения BACKUP_ENCRYPTION_KEY (64 hex-символа = 32 байта) при запуске сервера
• Статус шифрования доступен через поле encryption_enabled в ответе GET /api/v1/backups (сам ключ не передаётся)
• При восстановлении ключ автоматически применяется к расшифровке
• Изменить ключ в рантайме нельзя — только через перезапуск с новой переменной окружения

Важно: Без ключа шифрования зашифрованный бэкап невозможно восстановить. Сохраняйте ключ в безопасном месте!

Версионирование и совместимость

Каждый бэкап содержит manifest.json с метаданными:

{
  "format_version": 1,
  "app_version": "1.0.0",
  "app_commit": "abc123",
  "schema_version": 10,
  "created_at": "2024-01-15T10:30:00Z",
  "encryption": "aes-gcm",
  "tables": ["settings", "secrets", ...]
}

При восстановлении проверяется совместимость:

• schema_version ≤ текущая — восстановление разрешено
• schema_version > текущая — ошибка несовместимости
• Старые бэкапы без manifest — работают с предупреждением

Процесс восстановления

1. Остановка движка: Перед восстановлением автоматически останавливается Docker-контейнер telemt
2. Расшифровка: Если включено шифрование, архив расшифровывается
3. Проверка целостности: Проверяется SHA256 контрольная сумма
4. Восстановление: База данных и конфиги восстанавливаются атомарно (через temp-файлы)
5. Ротация JWT: После восстановления генерируется новый jwt_secret (все старые токены становятся недействительными)
6. Запуск движка: Контейнер автоматически запускается

Безопасность: JWT-ротация защищает от межокружных атак — даже при компрометации бэкапа злоумышленник не получит доступ к текущим токенам.

Управление через API

Метод	Эндпоинт	Описание
POST	/api/v1/backups	Создать новый бэкап
GET	/api/v1/backups	Список доступных бэкапов
GET	/api/v1/backups/download/{filename}	Скачать бэкап
POST	/api/v1/backups/restore	Восстановить из бэкапа
DELETE	/api/v1/backups/{filename}	Удалить бэкап

Корректный снимок SQLite

Для обеспечения целостности базы данных используется VACUUM INTO:

• Создаётся временная копия БД с чистой схемой
• Исключаются WAL-файлы и временные данные
• Гарантирует восстановление в любой момент

---

🕐 Планировщик (Scheduler)

Управление фоновыми задачами сервера в реальном времени. Доступны следующие возможности:

• Включение/отключение отдельных задач без перезапуска сервера.
• Изменение расписания (cron-выражения с точностью до секунд) — с возможностью сброса к значению по умолчанию.
• Ручной запуск любой задачи нажатием одной кнопки.
• История выполнения: просмотр записей о каждом запуске с статусом (успех/ошибка), временем и длительностью.
• Детали ошибок: при сбое задачи отображается текст ошибки.

Управление доступно через веб-интерфейс (/scheduler), REST API и команду /tasks в Telegram-боте.

Стандартные задачи: traffic-flush, quota-check, expiry-check, health-check, telegram-report, replication-sync, update-check, telemt-check, token-cleanup, daily-backup, backup-cleanup, history-cleanup, quota-reset (ежемесячный сброс трафика), auto-rotate (авторотация ключей).

📋 Аудит (Audit)

Журнал действий пользователей. Все ключевые операции (создание, удаление, ротация секретов, изменение настроек) записываются в лог аудита с указанием пользователя, действия и деталей.

⚙️ Настройки (Settings)

Тонкая настройка глобальных параметров сервера:

• Ограничения CPU и памяти для Docker-контейнеров.
• Кастомный IP-адрес сервера (для генерации ссылок за NAT).
• Длина фейкового сертификата (fake_cert_len).
• Настройка PROXY протокола (для работы за балансировщиками, например HAProxy).
• Кастомные URL Telegram для работы в регионах с ограничениями.
• Рекламный тег (Ad Tag).
• Настройки движка telemt (версия, commit, репозиторий).
• Авторотация секретов (указание количества дней, после которых ключи обновляются автоматически).
• Режим обслуживания (Maintenance Mode).
• Настройка ротации бекапов (срок хранения в днях).
• Включение режима отладки (Debug Mode) для логирования запросов.

Примечание: Порты, домены маскировки, параметры FakeTLS и маскировки трафика теперь настраиваются отдельно для каждого инстанса (раздел "Инстансы").

---

🏗 Сборка и запуск фронтенда

В текущей версии репозитория исходный код фронтенда находится в директории web/ (Vue 3, Vite, TypeScript).

Для сборки и запуска интерфейса:

1. Перейдите в папку: cd web
2. Установите зависимости: pnpm install
3. Соберите проект: pnpm run build

Собранные файлы (web/dist) в данной версии необходимо отдавать внешним веб-сервером (например, Nginx) или настроить проксирование запросов к бэкенду.

---

🛠 Системная служба (Systemd)

PopuGate поддерживает нативную установку в качестве системной службы systemd на Linux. Это обеспечивает автоматический запуск приложения при загрузке сервера и его перезапуск в случае сбоя.

Управление службой доступно:

• Через веб-интерфейс: В разделе "Настройки" или специальном системном меню.
• Через командную строку: С помощью команд systemctl.

Основные команды для ручного управления (после установки через интерфейс):

sudo systemctl status popugate
sudo systemctl restart popugate
sudo systemctl stop popugate

---

🛠 Разработка и сборка из исходников

Эта инструкция предназначена для разработчиков, желающих собрать бэкенд сервер самостоятельно или внести изменения в кодовую базу.

Предварительные требования

Для сборки вам потребуются:

• Go (версия 1.26.1 или новее)
• Make (для запуска скриптов сборки)

Сборка проекта

Вы можете скомпилировать бинарный файл с помощью утилиты Makefile. Откройте терминал в корне проекта и выполните:

# Установка недостающих зависимостей:
make tidy

# Сборка под текущую ОС:
make build
# Бинарный файл появится в папке bin/ с названием popugate

# Кросс-компиляция сразу под Linux-архитектуры (amd64 и arm64) для деплоя:
make cross-build

Тестирование и линтинг

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

• Запуск всех тестов: make test (Тесты работают полностью изолированно в in-memory базе SQLite и не требуют наличия Docker или настроенного сетевого окружения).
• Запуск тестов отдельного пакета: go test ./internal/store/... -v
• Запуск конкретного теста: go test ./internal/store/... -v -run TestSecretStore_Create
• Проверка покрытия: go test ./... -cover
• Проверка кода линтером: make lint
• Форматирование кода: make fmt

Тесты разделены на четыре уровня:

1. Store-слой (internal/store/*_test.go) — тестируют SQL-операции с in-memory SQLite
2. Service-слой (internal/service/*_test.go) — тестируют бизнес-логику (SecretService, TrafficService, UpstreamService, CheckResources, ResourceMonitor и др.)
3. Model-валидация (internal/model/*_test.go) — тестируют бизнес-правила моделей
4. Pkg-утилиты (pkg/*/*_test.go) — тестируют вспомогательные функции (fmtutil, logger, telemt и др.)

База данных и миграции

Проект использует SQLite. При первым запуске база данных settings.db создается автоматически, и в ней выполняются все необходимые миграции. Исходные файлы миграций находятся в директории internal/database/migrations/ и встроены в бинарный файл (embed.FS).

---

📂 Структура репозитория

• cmd/popugate/ — Точка входа в приложение (Cobra CLI). Содержит команды server, setup, version и др.
• internal/ — Внутренняя бизнес-логика приложения:
  • api/ — Обработчики HTTP-запросов (Gin handlers), роутинг и middleware.
  • auth/ — Механизмы авторизации и работы с JWT.
  • bot/ — Реализация сервисного Telegram-бота.
  • config/ — Глобальная конфигурация и константы.
  • database/ — Инициализация SQLite и управление схемой.
  • model/ — Описания структур данных и сущностей БД.
  • scheduler/ — Планировщик фоновых задач (cron) с поддержкой управления в реальном времени (включение/отключение, изменение расписания, история выполнения).
  • service/ — Ядро бизнес-логики (Docker, GeoIP, Репликация, Трафик, Планировщик).
  • store/ — Слой доступа к данным (Repository pattern).
  • testutil/ — Утилиты для тестирования (in-memory SQLite).
• pkg/ — Вспомогательные библиотеки и обертки:
  • dockerutil/, netutil/, sshutil/ — Утилиты для работы с Docker, сетью (iptables) и SSH.
  • fmtutil/ — Общие форматтеры (например, FormatBytes для человекочитаемых размеров).
  • logger/ — Собственная система логирования с уровнями и scope.
  • promutil/, qrutil/ — Работа с метриками Prometheus и генерация QR-кодов.
  • telemt/ — Интеграция с движком MTProxy.
• web/ — Исходный код фронтенда (Vue 3, Vite, TypeScript).
• scripts/ — Вспомогательные shell-скрипты для сборки и автоматизации.
• bin/ — Директория для скомпилированных бинарных файлов и локальных данных (бэкапы, конфиги).
• Makefile — Сценарии для сборки, тестирования и развертывания проекта.