PopuGate

PopuGate

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

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

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

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

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

Поддерживаемые платформы: 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

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

Примечание: По умолчанию бэкенд сервер доступен на порту 8080, а прокси-движок внутри 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)

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

• 8080 (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. Переменная окружения POPUGATE_DATA_DIR
    2. Директория, в которой находится запущенный бинарный файл
    3. Текущая рабочая директория (CWD)
    4. Стандартный путь /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 сервера (по умолчанию: 8080).
• -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 прокси. Ниже приведено описание основных разделов:

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

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

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

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

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

🔑 Секреты (Secrets)

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

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

🔀 Upstreams

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

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

Возможность запуска нескольких независимых экземпляров прокси-движка на разных портах. Каждый инстанс имеет свои настройки и метрики.

🔌 Управление прокси (Proxy)

Прямое управление процессом прокси: запуск, остановка, перезапуск и горячая перезагрузка конфигурации. Здесь же доступен просмотр логов движка в реальном времени.

🐳 Docker

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

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

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

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

📈 Трафик (Traffic)

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

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

🤖 Telegram Bot

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

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

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

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

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

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

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

Создание и восстановление полных бэкапов конфигурации и базы данных. Поддерживается скачивание файлов бэкапа на локальный компьютер.

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

Тонкая настройка параметров сервера:

• Порты прокси и метрик.
• Домен для маскировки трафика (Fake TLS).
• Ограничения CPU и памяти для контейнера.
• Настройка PROXY протокола (для работы за балансировщиками, например HAProxy).
• Параметры маскировки трафика и рекламный тег (Ad Tag).
• Включение режима отладки (Debug Mode) для логирования запросов.

---

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

В текущей версии репозитория исходный код фронтенда находится в директории 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. Model-валидация (internal/model/*_test.go) — тестируют бизнес-правила моделей
3. Pkg-утилиты (pkg/*/*_test.go) — тестируют вспомогательные функции

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

Проект использует SQLite. При первым запуске база данных settings.db создается автоматически, и в ней выполняются все необходимые миграции. Исходные файлы миграций находятся в директории 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.
  • logger/ — Собственная система логирования с уровнями и scope.
  • promutil/, qrutil/ — Работа с метриками Prometheus и генерация QR-кодов.
  • telemt/ — Интеграция с движком MTProxy.
• web/ — Исходный код фронтенда (Vue 3, Vite, TypeScript).
• migrations/ — SQL-файлы миграций базы данных.
• scripts/ — Вспомогательные shell-скрипты для сборки и автоматизации.
• bin/ — Директория для скомпилированных бинарных файлов и локальных данных (бэкапы, конфиги).
• Makefile — Сценарии для сборки, тестирования и развертывания проекта.