rospanel

README

РосПанель

Простая self-hosted панель управления VPN на Xray-core.

---

Что это

РосПанель — это лёгкая панель для самостоятельного хостинга личного VPN-сервера. Под капотом один процесс Xray-core, который сразу поднимает несколько протоколов, а панель даёт удобный веб-интерфейс: пользователи, подписки, тарифы и приём платежей, маршрутизация, статистика, бэкапы, брендинг и тема — без правки конфигов руками.

Главное отличие от Marzban / 3x-ui — радикальная простота: вся панель это один статический бинарник (фронтенд вшит через go:embed), без Docker-обвязки, без внешней БД, без отдельного веб-сервера. Поставил, открыл, добавил юзера.

Это панель управления (control plane), а не VPN-клиент и не «волшебная кнопка». Она лишь настраивает и обслуживает ваш собственный сервер: генерирует конфиг Xray, выдаёт ссылки/подписки и показывает статистику. Назначение — образовательное и исследовательское: изучение сетевых технологий, CTF-соревнования, авторизованный пентест и управление личной инфраструктурой. Проект не предназначен для обхода законных ограничений; ответственность за установку, настройку и использование несёт оператор (см. Дисклеймер).

---

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

🔐 Протоколы (один Xray-конфиг, один набор учёток)

• VLESS-Vision — TCP/443 + uTLS-fingerprint
• Trojan-WS — через fallback на 443
• Hysteria2 — UDP с port-hopping
• VLESS-gRPC-REALITY — отдельный порт, маскировка под чужой TLS

🎭 Маскировка

• Панель спрятана за секретным путём
• Любой другой путь отдаёт сайт-заглушку — сервер неотличим от обычного хостинга
• 11 готовых шаблонов заглушек

🔑 TLS из коробки

• ACME: Let's Encrypt и ZeroSSL
• Self-signed fallback, пока не выпустится настоящий сертификат
• Авто-продление

🧭 Маршрутизация и выходы

• Категории block / direct / proxy / WARP / Opera с настраиваемым приоритетом
• geosite/geoip пресеты (авто-загрузка баз)
• Cloudflare WARP (WireGuard) — выход через WARP по правилам
• Opera VPN — бесплатный выход с выбором региона (Европа / Азия / Америка)
• Прокси — список из URL или вручную, балансировка по живым (Observatory)

📊 Пользователи и статистика

• Лимиты трафика и срок действия с авто-отключением, авто-сброс (день/неделя/месяц/год)
• Лимит устройств на пользователя — по уникальным публичным IP (одно устройство = один IP); при превышении юзер автоматически отключается, пока число активных IP не упадёт
• Учёт трафика через Xray Stats API, онлайн-статус, список IP подключений (онлайн/офлайн)
• Поиск, фильтр по статусу и сортировка (по имени/трафику/сроку/онлайну) + пагинация — список не тормозит и на сотнях пользователей
• Групповые операции: выделение нескольких пользователей и одним действием включить / выключить / сбросить трафик / продлить срок / удалить — на сервере это один проход и одна перезагрузка конфига Xray вместо операции на каждого
• Дашборд: CPU / RAM / swap / диск / сеть / VPN-трафик в реальном времени, аптайм

📲 Подписки

• /<путь>/<токен> — base64-список + страница с QR и deep-links
• Кнопки импорта в популярные VPN-клиенты
• Авто-роутинг-заголовки (Happ / INCY / Mihomo)
• Имя пользователя в заголовке подписки (опционально) — удобно, когда у клиента несколько профилей
• Свои названия узлов — на каждый протокол своя метка вместо дефолтной (VLESS-TCP-TLS, VLESS-GRPC-REALITY…); видна в клиенте и на странице подписки. Меняется в Настройки → Подключения, без перезагрузки Xray
• Дата обновления лимита на странице подписки — когда обнулится трафик, если у тарифа задан период сброса
• Сброс ссылки подписки (ротация токена) — старая ссылка мгновенно перестаёт работать, при этом UUID и пароли протоколов не меняются

🎨 Брендинг и тема

• Название и логотип панели — своё имя вместо «РосПанель» и кастомный логотип (PNG/JPEG, ≤ 512 КБ); применяются и в панели, и на странице подписки. Настраивается в Настройки → Брендинг
• Редактор цветовой схемы — пять токенов: акцент, текст, приглушённый текст, фон и поверхность. Акцент одним цветом перекрашивает весь интерфейс (кнопки, ссылки, вкладки, рамки, графики); можно выбрать готовый пресет или любой #RRGGBB
• Полноценная тёмная тема — задаёте тёмные фон/поверхность, и всё (текст, статусы, бейджи, графики, страница подписки) автоматически подстраивается под светлоту, сохраняя контраст для любого сочетания цветов
• Всё попадает в резервную копию: имя и цвета — в БД, логотип — файлом в каталоге данных

💳 Биллинг и тарифы (опционально)

• Тарифные планы: цена (₽), срок действия, лимиты трафика и устройств. Редактируются в Настройки → Оплата. Цена 0 — бесплатный тариф: не истекает, а квота трафика обнуляется каждый срок действия (например, раз в 30 дней). Платный истекает по сроку и требует продления
• Пробный период и бесплатный тариф-фоллбэк: новые регистрации в пользовательском боте получают триал, затем автоматически переходят на бесплатный; истёкшие платные тоже даунгрейдятся на бесплатный. Тариф, назначенный «пробным» в настройках, всегда истекает по сроку — в том числе при ручной выдаче
• Назначение тарифа вручную — из карточки пользователя в панели или из админ-бота; режим «вручную» снимает тариф и обнуляет лимиты. При выключенном биллинге всё работает как раньше
• Продление, отмена, миграция: активный платный тариф можно продлить (время добавляется к текущему сроку) или отменить; при выводе тарифа из линейки всех его пользователей переносят на другой одним действием

💰 Приём платежей (опционально)

• ЮКасса (карты, ₽) и CryptoBot (крипта в Telegram) — настраиваются в Настройки → Оплата → Приём платежей (ключи шифруются в БД)
• Авто-активация: в боте или на странице подписки клиент видит текущий тариф, выбирает план и способ оплаты → получает ссылку → после оплаты тариф включается сам, боту приходит подтверждение. Пока активен платный тариф, показывается только продление/отмена, а не переключение на другой
• Подтверждение двумя путями: мгновенный вебхук (ЮКасса перепроверяется запросом к API, CryptoBot — по HMAC-подписи) + поллинг каждые 25 c как страховка, если вебхук не дошёл. Обработка идемпотентна
• Вебхук висит на случайном секретном пути — фиксированный URL для кабинета провайдера, но он не раскрывает скрытую панель (готовый URL с кнопкой копирования показан в настройках)
• Тестовые режимы: CryptoBot → testnet (@CryptoTestnetBot); ЮКасса → тестовый магазин
• Без провайдеров — ручной режим: создаётся заказ, админ подтверждает оплату (с вводом своего пароля) из раздела «Ожидают оплаты»

🔌 REST API (опционально)

• Внешний API для управления панелью из своих систем (биллинг, магазин-бот, скрипты провижининга): создание / удаление / изменение пользователей, тарифы, заказы, статистика трафика. Вызывает ту же логику, что и панель, — поведение не расходится
• Именованные ключи с авторизацией Authorization: Bearer <ключ>. Ключ показывается один раз при создании, в БД хранится только его HMAC-хэш (с тем же per-install-«перцем», что и сессии) и префикс для опознания; ключи можно отзывать
• Свой стабильный адрес /<путь>/v1/... — отдельный от секретного пути панели, поэтому ротация секрета не ломает интеграции; адрес можно сменить или выключить. Настраивается в Настройки → API
• OpenAPI-спека из кода — /<путь>/v1/openapi.json генерируется рефлексией по Go-типам (не расходится с реализацией) + Swagger UI на /<путь>/v1/docs для живых вызовов из браузера
• Вебхуки — панель сама шлёт POST на ваши адреса при событиях (создание/удаление юзера, истечение, исчерпание трафика, оплата) вместо опроса. Каждая доставка подписана HMAC-SHA256 (заголовок X-RosPanel-Signature), с ретраями и бэкоффом; получатель может быть и во внутренней сети. Настройка — Настройки → API → Вебхуки. Полное описание — в docs/api.md

🤖 Telegram-боты

• Админ-бот: список пользователей, добавление, удаление, вкл/выкл, сброс трафика, назначение тарифа, QR-подписка по юзеру; бэкапы по расписанию (cron) и по команде. Привязка чата одноразовым кодом (/start <код>) — бот отвечает только привязанным чатам. Уведомления о событиях (настраиваются переключателями в Настройки → Telegram): новая регистрация, истечение подписки, исчерпание трафика, превышение лимита устройств, сбой/перезапуск Xray, продление или ошибка TLS-сертификата, новые заказы и оплаты
• Пользовательский бот (отдельный токен): открытый бот для клиентов — саморегистрация (получают подписку сами), личное меню с подпиской, QR и статистикой, выбор и покупка тарифа; привязка существующего аккаунта по одноразовой ссылке — короткоживущий код вместо постоянного токена. Саморегистрацию можно включать/выключать. Ссылка на бота прокидывается в клиенты как support-url (кнопка поддержки в Happ)

🧰 Эксплуатация

• Диагностика — кнопка в разделе «Управление» на дашборде открывает модальное окно со сводкой здоровья: процесс Xray, последнее применение конфига, TLS-сертификат (срок/тип), свободное место на диске и ОЗУ, свежесть geo-баз, состояние выходных каналов. Каждая проверка — ОК / предупреждение / проблема с подсказкой, что делать
• Бэкап / восстановление и сброс к заводским — из дашборда и из CLI
• Логи приложения с ротацией + просмотрщик прямо в панели
• Брутфорс-защита: бан по iptables за перебор на SOCKS/HTTP-инбаунде
• Обновление из GitHub Releases (rospanel update)
• Режим прокси: socks/http forward-inbound для цепочек РосПанель↔РосПанель

🔒 Безопасность

• Шифрование секретов в БД (AES-GCM): токены ботов, приватные ключи WARP/REALITY, пароли пользователей хранятся зашифрованными. Ключ — secrets.key в каталоге данных (входит в бэкап, поэтому восстановление на новом сервере работает «из коробки»)
• Step-up-аутентификация: чувствительные операции (подтверждение оплаты) требуют повторного ввода пароля администратора
• HMAC-сессии: токены сессий хешируются с per-install-«перцем» (session pepper)
• SSRF-защита исходящих запросов (списки прокси, шаблоны авто-роутинга): только https, запрет приватных/link-local/metadata-адресов и защита от DNS-rebinding
• Одноразовые коды привязки Telegram с коротким сроком жизни

---

🚀 Быстрый старт

Вариант 1 — установочный скрипт (рекомендуется)

Одной командой: скачает релиз, поставит systemd-сервис, запустит и покажет логин.

curl -Ls https://raw.githubusercontent.com/AppsGanin/rospanel/main/install.sh | sudo bash

Скрипт спросит домен: укажите его — панель запросит TLS-сертификат через ACME; оставьте пустым — будет работать по IP. Можно задать заранее, тогда вопроса не будет: curl -Ls … | sudo ROSPANEL_HOST=vpn.example.com bash.

Xray, geo-базы и TLS-сертификат панель подтянет сама. Откройте https://<ваш-домен-или-IP>/<секрет>/ и войдите. Поддерживаются linux/amd64 и linux/arm64 — скрипт сам выберет нужный бинарь по архитектуре.

Вариант 2 — бинарник + systemd вручную

# скачать последний релиз (замените amd64 на arm64 для ARM-серверов)
curl -fsSL -o rospanel \
  https://github.com/AppsGanin/rospanel/releases/latest/download/rospanel-linux-amd64
chmod +x rospanel

# установить как сервис (копирует бинарь в /usr/local/bin, пишет systemd-юнит, стартует)
sudo ./rospanel install
#   сразу с доменом:  sudo ROSPANEL_HOST=vpn.example.com ./rospanel install

# логин и секретный путь печатаются ОДИН раз:
journalctl -u rospanel | grep -A6 FIRST-RUN

Вариант 3 — Docker

docker run -d --name rospanel \
  --network host \
  --cap-add NET_ADMIN \
  -v rospanel-data:/data \
  ghcr.io/appsganin/rospanel:latest

docker logs rospanel | grep -A6 FIRST-RUN

--network host нужен, чтобы Xray слушал 443/TCP, 80/TCP и UDP-порты Hysteria2 напрямую; NET_ADMIN — для port-hopping и бана по iptables.

🔑 Вход по умолчанию

Поле	Значение
Логин	admin
Пароль	admin
Путь панели	/rospanel/

То есть сразу после установки панель доступна по адресу https://<домен-или-IP>/rospanel/. Точная ссылка дублируется в логе (journalctl -u rospanel | grep -A6 FIRST-RUN или docker logs rospanel | grep -A6 FIRST-RUN).

При первом входе мастер настройки принудительно потребует сменить пароль и предложит сменить путь панели на случайный секрет — дефолтные admin/admin и /rospanel/ работают только до этого шага.

⚠️ После смены панель доступна только по секретному пути — корень отдаёт страницу-обманку. Без знания /<secret>/ форму логина не найти.

---

🛠️ CLI

rospanel                     запустить панель (обычно через systemd)
rospanel install             установить systemd-сервис и запустить (root)
rospanel uninstall [-y]      снять сервис (данные сохраняются)
rospanel start|stop|restart  управление сервисом
rospanel status              статус сервиса
rospanel update [-y]         обновиться до последнего релиза с GitHub
rospanel backup [файл]       снапшот .tar.gz (БД + ключ шифрования + сертификаты + конфиг Xray)
rospanel restore [-y] <файл> восстановить из снапшота (применится при старте)
rospanel host [-y] [домен|IP] показать/сменить адрес (перевыпуск TLS)
rospanel path                показать URL панели и проверить secrets.key / БД
rospanel reset [-y]          сброс к заводским настройкам (стирает БД)
rospanel version             версия
rospanel help                полная справка

Деструктивные команды (reset, restore, host, uninstall) спрашивают подтверждение; флаг -y его пропускает.

---

🧱 Архитектура

Единственный источник правды — SQLite; конфиг Xray всегда генерируется из неё и применяется супервизором. Веб-панель встроена в бинарник.

cmd/rospanel/        запуск сервера + CLI (main / service / cli)
internal/
  model/             доменные типы (User, Settings, RoutingConfig, …)
  store/             SQLite + миграции
  auth/              argon2id, секреты/токены, сессии
  datasec/           шифрование секретов в БД (AES-GCM, ключ secrets.key)
  netguard/          SSRF-safe HTTP (валидация исходящих URL)
  tlsmgr/ tlsutil/   ACME (Let's Encrypt / ZeroSSL) + self-signed
  decoy/             сайт-заглушка (шаблоны)
  geo/               geoip.dat / geosite.dat
  hop/               nftables port-hopping (Hysteria2)
  xray/              типизированный конфиг + генератор + supervisor + stats
  warp/              Cloudflare WARP (WireGuard outbound)
  opera/             хелпер Opera VPN (загрузка бинаря + supervisor)
  proxypool/         пул прокси + health-check (Observatory)
  proxyproto/        PROXY-протокол листенер (реальный IP клиента)
  logbuf/            кольцевой лог-буфер + ротация в файл
  link/ sub/         сборка ссылок и подписок
  backup/            tar.gz снапшоты
  updater/           обновление из GitHub
  sysstat/ netinfo/  метрики хоста + определение публичного IP
  tuning/            включение TCP BBR
  core/              сервисный слой (reconcile, квоты, тарифы, TLS, трафик, роутинг)
  server/            маскировка-роутер + API + rate-limit + step-up-аутентификация
web/                 React + Vite + Tailwind (встраивается через go:embed)
install.sh           установщик: релизный бинарь + systemd-юнит (`rospanel install`)

Стек: Go 1.26 · Xray-core · SQLite (modernc, без CGO) · React + Vite + Tailwind.

---

⚠️ Дисклеймер

Программное обеспечение предоставляется «как есть» (as is), без каких-либо гарантий, явных или подразумеваемых.

Назначение проекта — образовательное и исследовательское. Он создан для изучения принципов работы сетевых протоколов, TLS и прокси-технологий; для проведения CTF-соревнований и лабораторных работ по сетевой безопасности; для авторизованного тестирования на проникновение и для управления собственной инфраструктурой. Это учебный и исследовательский инструмент, а не средство для какой-либо противоправной деятельности.

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

Всю ответственность за установку, настройку и эксплуатацию, а также за соблюдение законов своей юрисдикции несёт оператор сервера. Авторы и контрибьюторы проекта не несут ответственности за способы его использования третьими лицами.

---

🧑‍💻 Разработка

# фронтенд (после изменений в web/)
npm --prefix web install
npm --prefix web run build      # → web/dist (вшивается в бинарник)

# бинарник
go build -o rospanel ./cmd/rospanel
./rospanel

Полезные переменные окружения (все опциональны): ROSPANEL_DATA (каталог данных), ROSPANEL_ADMIN_ADDR (loopback-адрес панели, по умолчанию 127.0.0.1:8080), XRAY_BIN, ROSPANEL_HOST, ROSPANEL_ACME_EMAIL.

PR и issue приветствуются. Коммиты — в стиле Conventional Commits: на их основе release-please собирает релиз и публикует бинарь + Docker-образ в GHCR.

---

💝 Поддержать проект

РосПанель развивается в свободное время и распространяется бесплатно. Если панель оказалась полезной — можно поддержать разработку.

Удобнее всего — через DonationAlerts или Boosty (картой РФ, разово или регулярно). Либо донатом в USDT — выберите удобную сеть и внимательно скопируйте адрес (сеть отправителя и получателя должны совпадать):

Сеть	Токен	Адрес
TRC20 (Tron)	USDT	TJwyrPVEZVZ1YrcmDiZTyFjLo3Q2DmEGzs
ERC20 (Ethereum)	USDT	0xf9d663146ce902da91911b214c71cc73a5269d1d
Solana	USDT	2qAZRTbaUMTfYuZbD1dCYHjkYgxkw4dUYE9XY3JhC2Cs
TON	USDT	UQDoat731MLYuIw8ayL3Vhhw7zTBbLvRaQFmDvab--CNNI7e

Если у вас тоже Bybit — проще всего перевести по UID (мгновенно и без комиссии):

Биржа	UID
Bybit	136462734

Дешевле всего комиссия в сетях TRON (TRC20) и TON. Отправляйте только USDT и только в указанной сети — перевод по неверной сети невозвратен.

Спасибо за поддержку! 🙏

Нет возможности поддержать?

Если поддержать проект напрямую не получается — вы всё равно можете помочь, арендуя серверы по этим реферальным ссылкам:

• VDSina
• Aeza
• NetGrid
• Serv.host
• u1Host
• Waicore

---

📄 Лицензия

GNU Affero General Public License v3.0 (AGPL-3.0).

Проект свободен для использования, изменения и self-hosting. Если вы предоставляете доступ к изменённой версии панели по сети (в т.ч. как сервис), вы обязаны открыть исходный код своих изменений на тех же условиях.