Впервые здесь? Прочтите это первым 👋

Никогда не слышали про Marzban, «VPS» или «панель»? Отлично — здесь вся суть объясняется простыми словами. Опыт не нужен совсем.

Аналогия с магазином

Если вы представляете, как держать небольшой магазин, вы уже понимаете NexusPanel. Вот как всё устроено:

Как на самом деле движутся деньги

1. Кому-то нужен приватный или разблокированный интернет, и он платит вам (принимайте криптовалюту автоматически через встроенный Telegram-бот или берите оплату любым удобным способом).
2. Вы открываете NexusPanel и создаёте для него пользователя — задаёте срок действия и объём трафика. Занимает около 10 секунд.
3. Вы отправляете ему ссылку-подписку.
4. Он вставляет её в бесплатное приложение и нажимает «подключиться». Он в сети через ваш сервер.
5. В следующем месяце он платит снова, чтобы оставаться активным. Повторяйте с любым числом клиентов.

Готовы? Выберите точку старта

Перейдите к разделу С чего начать и выберите один из трёх путей: попробовать бесплатный период (без установки), установить с нуля на новом сервере или перейти с Marzban.

Слова, которые вам встретятся 📖

Каждый термин из этой документации, объяснённый одним простым предложением. Пробегитесь по нему сейчас; возвращайтесь всякий раз, когда какое-то слово вас собьёт с толку.

VPS virtual private server

Компьютер, который вы арендуете в дата-центре помесячно. На нём работает ваша панель. ~$4–6/месяц вполне достаточно для старта.

Панель

Веб-панель, в которую вы заходите, чтобы всем управлять — это и есть сам NexusPanel. Он живёт на вашем VPS.

Нода

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

Пользователь он же клиент

Один человек, которому вы продаёте доступ. У каждого есть дата окончания, лимит трафика и собственная ссылка-подписка.

Ссылка-подписка «sub-ссылка»

Единственная ссылка, которую вы даёте клиенту. Его приложение читает её, чтобы понять, как подключиться. Если вы переходите с Marzban, эти ссылки продолжают работать.

Клиентское приложение

Бесплатное приложение, которое устанавливает клиент — например, Happ, v2rayNG, Streisand, Hiddify. Он один раз вставляет в него sub-ссылку.

Marzban

Более старая, бесплатная панель «сделай сам», с которой начинали многие операторы. NexusPanel — её обновлённый преемник с поддержкой, и он умеет импортировать конфигурацию Marzban одной командой.

Remnawave

Ещё одна панель управления VPN. NexusPanel умеет импортировать пользователей из живой Remnawave-панели по её API одной командой, сохраняя их ссылки-подписки рабочими.

Лицензия

Ваш ключ для запуска NexusPanel. Возьмите бесплатный 14-дневный пробный период или платный тариф через Telegram-бот. Без неё панель работает в пробном режиме.

Домен

Имя вроде panel.yoursite.com, указывающее на ваш VPS. Нужно для замочка в браузере (HTTPS). Необязательно, но настоятельно рекомендуется.

SSL / HTTPS

Замочек в браузере — шифрование, которое защищает входы в систему. NexusPanel настраивает его автоматически, если у вас есть домен.

Xray

Бесплатный движок «под капотом», который и перемещает зашифрованный трафик. Напрямую вы его почти не трогаете.

VLESS / VMess / Trojan / Shadowsocks

Разные виды туннелей, которые может использовать Xray. Как разные марки машин — все довезут вас до места. VLESS обычно используется по умолчанию.

Reality / XHTTP / ECH / Finalmask

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

Hysteria 2

Другой, очень быстрый тип туннеля, который особенно хорош на плохих или урезанных сетях. Необязателен; работает рядом с Xray.

Middle-сервер

Дешёвый ретранслятор, поставленный перед вашим основным сервером, чтобы обходить блокировки. Продвинутая тема — игнорируйте, пока это реально не понадобится.

Inbound / Хост

Конкретная «входная дверь» в ваш сервер (протокол + порт + настройки). В панели уже есть разумные; добавляйте новые по желанию.

Администратор / Реселлер

Дополнительные учётные записи, которые вы создаёте. Реселлер управляет своими клиентами в рамках заданных вами лимитов — удобно, когда под вами продают другие.

Лимит IP / устройств

Ограничение на количество телефонов или компьютеров, которые один клиент может использовать одновременно — мешает делиться паролем и съедать ваш трафик.

С чего начать

Три пути. Выберите тот, что подходит вам, и вы запуститесь меньше чем за 10 минут.

NexusPanel — это мультиарендная VPN-панель: вы продаёте субаккаунты, ваши клиенты подключаются через любой v2ray-клиент, а вы держите всё в одной панели. Если вы новичок, самый быстрый способ увидеть, что она умеет, — бесплатный пробный период. Если вы уже используете Marzban, инструмент миграции перенесёт всё одной командой — пользователей, администраторов, хосты, сертификаты, и даже ваши существующие ссылки-подписки продолжат работать. Если вы используете Remnawave — то же самое, отдельной командой (см. Миграция с Remnawave).

Что вам понадобится

• VPS с Ubuntu 20.04+ (или любым дистрибутивом семейства Debian), минимум 1 ГБ ОЗУ, рекомендуется 2 ГБ
• Root-доступ по SSH к этому VPS
• Домен, направленный на VPS (необязательно — даёт настоящий сертификат HTTPS без предупреждений; без него всё равно будет HTTPS, но с самоподписанным сертификатом, который один раз покажет предупреждение в браузере)
• Лицензия NexusPanel (возьмите её в Telegram-боте, подойдёт бесплатный 14-дневный пробный период)

Как получить помощь

Если что-то не работает, попробуйте по порядку:

1. Проверьте логи панели: cd /opt/panel && docker compose logs --tail 100
2. Прочтите нужный раздел этой документации (боковое меню слева)
3. Напишите нам в Telegram — ссылка в боте, отвечаем за часы, а не за дни

Что такое NexusPanel

NexusPanel — это современная, многофункциональная панель управления прокси, созданная для VPN-провайдеров и сетевых администраторов. Она даёт единую панель для управления пользователями, нодами, подписками и аналитикой на нескольких серверах.

«Под капотом» полный набор возможностей включает:

• Поддержку нескольких протоколов — VMess, VLESS, Trojan, Shadowsocks через Xray-core, плюс Hysteria 2 как отдельный сайдкар. Расширения транспорта и обфускации (XHTTP, Reality, ECH, фрагментация TLS, Finalmask) настраиваются для каждого хоста в панели.
• Распределённые ноды — подключайте неограниченное число удалённых серверов из одной панели
• Реальные лимиты на пользователя — трафик, срок действия, ограничения по IP и устройствам действительно применяются за счёт разбора access-лога Xray
• Роли администраторов и привязку хостов — уровни «владелец», «администратор», «реселлер» с квотами трафика; назначайте конкретные хосты конкретным администраторам
• REST API — 75+ эндпоинтов для автоматизации и интеграции
• Аналитику в стиле Grafana — трафик во времени, рост числа пользователей, кольцевые диаграммы по протоколам/статусам, топ-потребители, нагрузка по трафику на ноды (с автообновлением)
• Telegram-бот — платёжный бот для клиентов (криптовалюта через NOWPayments) плюс уведомления для администраторов
• Систему лицензий — пробный → платные тарифы с heartbeat раз в 6 часов и уведомлениями об обновлениях Docker-образов
• Зашифрованные Happ-ссылки — настоящие deeplink-и happ://crypt4/ на RSA-4096, скрывающие исходный URL подписки
• 2FA — TOTP с QR-кодом и резервными кодами
• Готовность к мобильным устройствам — адаптивная панель с нижней навигацией и выезжающим меню
• Защиту кода — чувствительные Python-модули скомпилированы Cython в бинарники .so
• Действенные уведомления внутри приложения — истекающие пользователи, лимиты трафика, офлайн-ноды, истечение лицензии

Требования

Быстрая установка

Выполните эту единственную команду на чистом VPS, чтобы установить NexusPanel с настройками по умолчанию:

curl -sL https://nexuspanel.store/install | bash

Скрипт запросит у вас:

1. License Key и Client ID — от @nexuspanelpayment_bot (бесплатный 14-дневный пробный ключ тоже подходит, но установщик всегда требует ключ — установки без лицензии не бывает)
2. Домен — для SSL через Let's Encrypt (пропустите для работы только по IP)
3. Имя пользователя и пароль администратора — для панели
4. Порт панели — по умолчанию 8443

Затем он:

1. Установит Docker и Docker Compose, если их нет
2. Скачает ghcr.io/haitovs/nexus:latest (защищённый Cython продакшен-образ)
3. Создаст /opt/panel/ с .env и docker-compose.yml (имя контейнера: nexus-panel)
4. Заполнит xray_config.json с включённым access-логом (нужно для применения лимитов IP/устройств)
5. Запустит панель и выведет URL панели и учётные данные

Установка одной командой (подробно)

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

# Рекомендуется — передайте свой License Key + Client ID (от @nexuspanelpayment_bot)
curl -sL https://nexuspanel.store/install | bash -s -- \
  --license YOUR_LICENSE_KEY \
  --client YOUR_CLIENT_ID \
  --domain panel.example.com \
  --port 8443

# То же самое через переменные окружения вместо флагов
curl -sL https://nexuspanel.store/install | LICENSE_ID=YOUR_LICENSE_KEY CLIENT_ID=YOUR_CLIENT_ID DOMAIN=panel.example.com bash

# Только по IP (без домена) — просто опустите --domain, HTTPS всё равно будет (самоподписанный сертификат)
curl -sL https://nexuspanel.store/install | bash -s -- \
  --license YOUR_LICENSE_KEY \
  --client YOUR_CLIENT_ID

License Key и Client ID обязательны — получите их у @nexuspanelpayment_bot. Запустите bash -s -- --help, чтобы увидеть все флаги (--port по умолчанию 8443, а также --username, --password, --ssl, --migrate).

Когда скрипт завершится, он напечатает URL панели, имя администратора и пароль — используйте их для входа. Не используйте примеры из этой документации (вроде myadmin/securepass123) — они не сработают.

Панель доступна по адресу https://YOUR_DOMAIN:8443/dashboard/ (или https://YOUR_IP:8443/dashboard/ при установке только по IP).

Первые шаги в панели

После входа в панель — вот самый быстрый путь к первому рабочему подключению:

1. Создайте пользователя — Панель → Users → Add User. Задайте дату окончания и лимит трафика, затем скопируйте ссылку подписки и передайте её в клиентское приложение (Happ, v2rayNG, Streisand…).
2. Добавьте ноду (по желанию) — Панель → Nodes → Add New Node, скопируйте сгенерированную команду быстрой установки, выполните её на сервере ноды, затем вернитесь и заполните Name + Address, чтобы подключить её. Подробнее в разделе Установка ноды.
3. Настройте домен подписки — если ссылки подписки должны отдаваться с другого хоста/домена, чем сама панель, задайте XRAY_SUBSCRIPTION_URL_PREFIX в редакторе окружения (Settings → Env) и используйте Save & Restart — эта настройка применяется только после полного перезапуска.

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

Скрипт установки выше — поддерживаемый способ: он сам аутентифицируется в приватном реестре образов, пишет рабочий .env и настраивает файрвол. Чтобы собрать всё вручную:

# 1. Образ приватный — обычный `docker pull` вернёт "denied", пока вы не
#    авторизуетесь. Обменяйте лицензию на короткоживущий токен для pull:
curl -s -X POST https://nexuspanel.store/api/registry-token \
  -H 'Content-Type: application/json' \
  -d '{"license_id":"YOUR_LICENSE_KEY","client_id":"YOUR_CLIENT_ID"}'
# → {"token": "...", "username": "..."} — войдите с ним:
echo $TOKEN | docker login ghcr.io -u $USERNAME --password-stdin

# 2. Скачать образ
docker pull ghcr.io/haitovs/nexus:latest

# 3. Написать /opt/panel/.env — все ключи см. в разделе Env Reference ниже.
#    Минимум: UVICORN_PORT, SUDO_USERNAME, SUDO_PASSWORD, SQLALCHEMY_DATABASE_URL,
#    LICENSE_ID, CLIENT_ID
mkdir -p /opt/panel /var/lib/panel /var/lib/nexus
nano /opt/panel/.env

# 4. Запустить с docker-compose.yml из раздела "Примеры Docker Compose" ниже
cd /opt/panel
docker compose up -d

# Посмотреть логи
docker compose logs -f

С SSL (Certbot)

Чтобы включить HTTPS с бесплатным сертификатом Let's Encrypt:

# Установить certbot
apt install -y certbot

# Получить сертификат (сначала остановите панель, если используется порт 80)
docker compose down
certbot certonly --standalone -d panel.example.com

# Добавить в .env
UVICORN_SSL_CERTFILE="/etc/letsencrypt/live/panel.example.com/fullchain.pem"
UVICORN_SSL_KEYFILE="/etc/letsencrypt/live/panel.example.com/privkey.pem"

# Примонтировать сертификаты в docker-compose.yml и перезапустить
docker compose up -d

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

0 3 * * * certbot renew --quiet && docker compose -C /opt/nexuspanel restart

С PostgreSQL

Для продакшен-развёртываний PostgreSQL предпочтительнее SQLite. Установите BACKEND_MODE=modern и используйте драйвер, который реально входит в поставку панели — psycopg2 (синхронный), а не asyncpg:

# Задать в .env
BACKEND_MODE=modern
SQLALCHEMY_DATABASE_URL="postgresql+psycopg2://nexus:${POSTGRES_PASSWORD}@127.0.0.1:5432/nexus"
REDIS_URL="redis://127.0.0.1:6379/0"
POSTGRES_PASSWORD=$(openssl rand -hex 24)

Не пишите compose-файл вручную — используйте поддерживаемый docker-compose.modern.yml из корня репозитория: он поднимает Postgres 16 + Redis 7 рядом с панелью на network_mode: host:

# Из каталога установки (например /opt/panel)
cp docker-compose.modern.yml docker-compose.yml
docker compose up -d

Примеры Docker Compose

Classic (SQLite) — то, что реально пишет установщик

services:
  panel:
    image: ghcr.io/haitovs/nexus:latest
    container_name: nexus-panel
    restart: always
    env_file: .env
    network_mode: host
    dns: [8.8.8.8, 1.1.1.1]
    volumes:
      - /var/lib/panel:/var/lib/panel
      - /var/lib/nexus:/var/lib/nexus
      - ./.env:/app/env.live
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      NEXUS_HOST_ENV_FILE: /app/env.live
    healthcheck:
      test: ["CMD", "curl", "-skf", "http://127.0.0.1:8443/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 30s
      retries: 3

network_mode: host обязателен — панель и любой совмещённый нод/middle-relay привязывают порты напрямую на хосте, а монтирование docker-сокета (только для чтения) нужно для one-click SSH-установки нод и middle-серверов. /var/lib/nexus — не опциональный том: там лицензионный модуль кеширует своё состояние, без него панель не может подтвердить лицензию. Замените 8443 в healthcheck на ваш UVICORN_PORT; при обслуживании домена также примонтируйте /etc/letsencrypt:/etc/letsencrypt:ro и укажите UVICORN_SSL_CERTFILE/UVICORN_SSL_KEYFILE на выданный сертификат.

Полный стек (PostgreSQL + Redis)

См. раздел С PostgreSQL выше — используйте поддерживаемый docker-compose.modern.yml вместо ручного compose-файла для Postgres.

Справочник по конфигурации

NexusPanel полностью настраивается через переменные окружения. Задавайте их в файле .env или передавайте напрямую в Docker.

Сервер

База данных

Xray

Подписка

Шаблоны

Telegram

Уведомления

Брендинг (White-Label)

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

Логирование

Метрики (Prometheus)

Дополнительные переменные

Панель управления

Панель управления NexusPanel — это современное веб-приложение на React, доступное по адресу /dashboard/. Она предоставляет полный интерфейс для управления вашей прокси-инфраструктурой.

Страница обзора

Главная страница панели показывает статистику в реальном времени с одного взгляда:

• Всего пользователей — количество активных, истёкших, ограниченных, отключённых
• Использование трафика — суммарная отдача/загрузка с графиками тренда
• Статус нод — индикаторы онлайн/офлайн с процентом нагрузки
• Недавняя активность — последние создания пользователей, подключения и действия администраторов
• Распределение по протоколам — круговая диаграмма используемых протоколов

Управление пользователями

Страница «Пользователи» поддерживает полное управление жизненным циклом:

• Создание пользователя — задайте имя, лимит трафика, дату окончания, протоколы, лимит устройств, лимит IP
• Редактирование пользователя — меняйте все поля, включая статус (активен, отключён, на удержании)
• Массовые операции — выбирайте нескольких пользователей для массового обновления, сброса трафика или удаления
• Поиск и фильтрация — фильтруйте по статусу, администратору, протоколу или ищите по имени
• Ссылки-подписки — копирование URL подписки, генерация QR-кода
• Статистика использования — отдача/загрузка по каждому пользователю с историческими данными

Ноды

Управляйте удалёнными нодами Xray, подключёнными к панели:

• Добавление ноды — укажите адрес, порт и коэффициент использования
• Статус подключения — онлайн/офлайн в реальном времени с задержкой
• Флаги стран — автоматическое отображение флага по локации ноды (60+ стран)
• Изменение порядка — перетаскивайте или используйте стрелки, чтобы задать порядок отображения
• Сертификат — просмотр и копирование SSL-сертификата ноды для удалённой настройки
• Отслеживание аптайма — исторический процент аптайма по каждой ноде

Хосты и расширенные настройки TLS

У каждого inbound Xray есть одна или несколько строк-хостов, которые говорят генератору подписок, какой адрес, порт и параметры TLS выдавать в клиентских конфигах. Полный набор полей по каждому хосту:

ECH (Encrypted Client Hello)

ECH скрывает SNI от пассивных наблюдателей — расширение TLS-рукопожатия шифруется с помощью открытого ключа, опубликованного в DNS. Включается для каждого хоста: переключите ECH и вставьте блоб ECHConfig от вашего провайдера CDN/DNS. Требуется клиент с поддержкой ECH (Happ, Chrome 117+).

Фрагментация TLS

Разбивает TLS ClientHello на меньшие TCP-сегменты, обходя сопоставление DPI с шаблоном по первому пакету. Используйте, когда активна блокировка по SNI, но CDN недоступен.

• Размер фрагмента — байт на фрагмент, например 100-200 (случайный диапазон)
• Задержка фрагмента — мс между фрагментами, например 10-20

Фрагментация записей TLS

Фрагментирует на уровне записей TLS, а не TCP. Более агрессивно, чем фрагментация ClientHello; используйте, когда стандартная фрагментация TLS всё ещё определяется по отпечатку.

Настройки Noise

Вставляет случайные шумовые пакеты перед настоящим TLS-рукопожатием, чтобы сбить снятие отпечатка по потоку. Поле JSON:

[{"type": "rand", "packet": "10-50", "delay": "5-10"}]

Тип rand отправляет случайные байты; тип str отправляет буквальную hex-строку. Размер пакета и задержка принимают запись диапазоном.

Случайный User-Agent

Делает HTTP User-Agent случайным при каждом запросе, чтобы избежать снятия отпечатка клиента на транспортах WS/HTTP.

Сессии

Отслеживайте активные подключения устройств и управляйте ими:

• Активные сессии — просмотр всех подключённых в данный момент устройств
• Сессии по пользователю — смотрите, какие устройства использует конкретный пользователь
• Отключение — принудительно завершайте отдельные сессии
• История IP — отслеживайте историю подключений пользователя по IP

Аналитика

Комплексная панель аналитики с:

• Сводкой — всего пользователей, активные подключения, трафик, обзор выручки
• Распределением по протоколам — разбивка использования по протоколам (VMess, VLESS и т. д.)
• Нагрузкой на ноды — число подключений и использование трафика по каждой ноде
• Аптаймом нод — процент аптайма за периоды 24 ч, 7 д, 30 д
• Топ-пользователями — крупнейшие потребители трафика
• Истекающими пользователями — пользователи, у которых срок истекает в течение настраиваемого числа дней

Управление администраторами

Ролевая система администраторов с тремя уровнями:

У каждого администратора могут быть квоты:

• max_users — максимальное число пользователей, которое администратор может создать
• max_traffic_bytes — общая квота трафика по всем его пользователям

Настройки

• Двухфакторная аутентификация — включение/отключение TOTP 2FA со страницы настроек
• Конфигурация ядра Xray — редактирование сырого JSON Xray в 2-колоночном виде (редактор слева, живые логи и статус справа)
• Редактор Env — редактирование SMTP, токенов, флагов функций прямо в интерфейсе с маскировкой секретов; Save & Restart перезапускает панель
• Hysteria2 — управление inbound-ами hy2 со страницы настроек (Standard+)
• Информация о лицензии — тариф, оставшиеся дни, текущее/максимальное число пользователей/нод

Группы пользователей

Группы пользователей (называемые Squads в Remnawave) позволяют сегментировать пользователей для управления видимостью inbound-ов и переопределения подписок. Лицензия Pro, только для sudo.

Каждая группа может делать что-то одно или всё из перечисленного:

• Фильтр inbound (applies_to_inbounds) — CSV тегов inbound. Пользователи в группе получают записи подписки только для соответствующих inbound-ов. Пусто = все inbound-ы.
• Переопределение шаблона (override_template_id) — использовать другой шаблон подписки для участников этой группы.
• Переопределение хостов (override_hosts) — внедрять другие строки-хосты в подписки участников (например, дать VIP-группе хост с прямым IP, скрытый от всех остальных).

Добавляйте пользователей в группу со страницы деталей пользователя или через API. Пользователь может состоять не более чем в одной группе.

# Список групп
curl /api/v1/user-groups -H "Authorization: Bearer TOKEN"

# Создать VIP-группу, которая получает только inbound-ы hy2 + VLESS-Reality
curl -X POST /api/v1/user-groups \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP","applies_to_inbounds":"hy2-main,vless-reality"}'

# Добавить пользователя в группу
curl -X POST /api/v1/user-groups/1/members \
  -d '{"username":"alice"}' -H "Authorization: Bearer TOKEN"

Наборы inbound

Набор inbound — это именованный CSV тегов inbound, который вы назначаете ноде. Когда у ноды есть набор inbound, на ней активируются только эти inbound-ы — остальные подавляются. Используйте это, чтобы запускать разные наборы протоколов на разных нодах: например, нода A получает VLESS+Trojan, нода B — VLESS+hy2.

Лицензия Pro, только для sudo.

# Создать набор inbound
curl -X POST /api/v1/inbound-sets \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"UDP nodes","tags":"hy2-main,vmess-ws"}'

# Назначить ноде (задать inbound_set_id у ноды)
curl -X PUT /api/v1/node/1 \
  -d '{"inbound_set_id": 2}' -H "Authorization: Bearer TOKEN"

Правила ответа подписки

Правила подписок позволяют настраивать, как выглядит ответ подписки пользователя, в зависимости от его клиента. Правила сопоставляются со свойствами запроса и применяют действие.

Примеры:

• Сопоставление user_agent contains "Happ" → действие template = happ-custom — выдавать оптимизированный под Happ шаблон клиентам Happ
• Сопоставление client_os equals "iOS" → действие headers = {"Content-Type": "text/plain"}
• Глобальные правила (только для sudo, admin_id = NULL) применяются ко всем пользователям независимо от того, какому администратору они принадлежат

Правила вычисляются по возрастанию priority. Побеждает первое совпадение.

# Создать правило: выдавать шаблон sing-box клиентам Karing
curl -X POST /api/v1/sub-rules \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Karing","match_field":"user_agent","match_op":"contains",
     "match_value":"Karing","action":"template","action_arg":"singbox-default"}'

Webhooks

NexusPanel доставляет подписанные HTTP POST-события на любой зарегистрированный вами URL. Каждая доставка содержит заголовок X-Nexus-Signature — HMAC-SHA256 тела с секретом вашего эндпоинта.

Области событий

Оставьте области пустыми, чтобы получать все события. Доставка повторяется с экспоненциальной задержкой; после максимального числа попыток событие помечается как неудачное и отбрасывается.

# Зарегистрировать эндпоинт
curl -X POST /api/v1/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://my-server/hook","scopes":"user.*,node.*"}'
# Ответ содержит секрет (показывается один раз)

# Отправить тестовую доставку
curl -X POST /api/v1/webhooks/1/test -H "Authorization: Bearer TOKEN"

# Проверить подпись в вашем обработчике (пример на Python)
# expected = hmac.new(secret, body, sha256).hexdigest()
# assert expected == request.headers["X-Nexus-Signature"]

Страница клиентов

Панель → Клиенты показывает подобранный список рекомендуемых VPN-клиентов со значками платформ, ссылками для скачивания и заметками по использованию. Операторы делятся URL этой страницы с конечными пользователями.

Система лицензий

NexusPanel использует центральный лицензионный сервер (nexuspanel.store) для проверки установок и доставки обновлений. Так клиенты распределяются по тарифам, тарифицируются и поддерживаются в актуальном состоянии.

Как работает heartbeat

• Каждые 6 часов панель вызывает POST /api/validate на лицензионном сервере, передавая свои license_id, client_id и полную телеметрию (версия панели, версия Xray, имя хоста, ОС, IP, всего/активных пользователей, всего/активных нод, суммарный трафик, аптайм).
• Лицензионный сервер сохраняет это и отвечает {tier, expires_at, latest_version, update_available, docker_image}.
• Если update_available истинно и включён AUTO_UPDATE (по умолчанию), панель в фоне выполняет docker compose pull && docker compose up -d --force-recreate — вам ничего делать не нужно.

Тарифы

Пробный

Без банковской карты, без регистрации — откройте Telegram-бот и введите /start. Вы получите бесплатный 14-дневный Pro-триал без ограничений по пользователям и нодам. Все протоколы и аналитика доступны сразу — достаточно, чтобы оценить на реальном трафике.

Standard — $10/месяц

Для операторов, у которых работает живой сервис. Продолжение работы после пробного периода — до 10 нод, и открывает:

• Протокол Hysteria 2 на всех нодах
• Массовые операции (включить/отключить/сбросить/удалить сотни пользователей разом)
• Доступ к API для автоматизации и интеграций
• Оплату на несколько месяцев (3/6/12 месяцев со скидкой 5%/10%/15%)

Pro — $30/месяц

Всё из Standard, плюс отсутствие ограничения на ноды и полный набор возможностей:

• Неограниченное число нод в любом количестве стран
• ECH (Encrypted Client Hello) — скрывает SNI от DPI
• Finalmask — транспортный слой защиты от снятия отпечатков
• White-label брендинг (свой домен панели + логотип)
• Группы пользователей и наборы inbound для сегментации уровня реселлеров
• Ретрансляцию через Middle-сервер с автогенерируемыми правилами iptables
• Приоритетную поддержку

Сравнение возможностей

Покупка лицензии

Откройте @nexuspanelpayment_bot в Telegram. Нажмите View Plans, выберите тариф, выберите срок (1/3/6/12 месяцев с растущими скидками), выберите криптовалюту (USDT TRC20, BTC, ETH, LTC, TRX и 200+ других) и отправьте точную показанную сумму на указанный кошелёк. Как только NOWPayments подтвердит платёж, бот выдаст ваши License Key и Client ID.

Льготный период

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

Применение лимитов IP и устройств

NexusPanel применяет лимиты IP и устройств по каждому пользователю в реальном времени, разбирая access-лог Xray — а не только при импорте подписки. Именно это заставляет ip_limit и device_limit действительно работать.

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

1. Xray пишет по одной строке в $XRAY_ACCESS_LOG на каждое принятое подключение.
2. Задание enforce_limits запускается каждые 60 секунд, читает хвост лога (с учётом смещения и ротации) и извлекает пары (user_id, client_ip) за последние LIMIT_WINDOW_SECONDS (по умолчанию 600 = 10 минут).
3. Для каждого пользователя подсчитываются уникальные IP. Если их число превышает ip_limit (или device_limit, если ip_limit не задан) и пользователь сейчас active и ip_limit_mode == "limit", пользователь переводится в статус limited.
4. Все увиденные IP записываются в user_ip_history. Просмотреть IP по пользователю можно через GET /api/v1/user/{username}/ips.

Необходимая конфигурация xray

При установке по умолчанию это включается автоматически. Для существующих установок панель при запуске автоматически правит ваш xray_config.json, добавляя путь к access-логу. Конфигурация вручную:

{
  "log": {
    "loglevel": "warning",
    "access": "/var/lib/panel/xray-access.log"
  }
}

Настраиваемые параметры

Резервные копии

NexusPanel выполняет автоматическое резервное копирование базы данных каждый день в 03:00 UTC через задание backup APScheduler.

Куда сохраняются копии

• Локальные файлы: /var/lib/panel/backups/backup_YYYYMMDD_HHMMSS.sqlite3 (или .sql для PostgreSQL)
• Хранятся последние 7 копий; более старые автоматически удаляются
• Если настроены TELEGRAM_API_TOKEN и TELEGRAM_ADMIN_ID, каждая копия также отправляется вам в Telegram документом, чтобы у вас была копия вне сервера

Резервное копирование вручную

# SQLite
docker exec nexus-panel cp /var/lib/panel/db.sqlite3 /var/lib/panel/backups/manual.sqlite3

# Или возьмите файл напрямую с хоста
cp /var/lib/panel/db.sqlite3 ~/panel-backup-$(date +%F).sqlite3

Восстановление

1. Остановите панель: cd /opt/panel && docker compose down
2. Замените файл БД: cp /path/to/backup.sqlite3 /var/lib/panel/db.sqlite3
3. Перезапустите: docker compose up -d

Зашифрованные подписки Happ

Кнопка «H» у каждого пользователя в панели генерирует настоящий deeplink happ://crypt4/<base64> с использованием RSA-4096 PKCS1v15 и официального открытого ключа Happ. После добавления в клиент Happ пользователь не может посмотреть, изменить или поделиться исходным URL подписки.

URL подписки длиннее 501 байта (лимит RSA-4096 + PKCS1v15) автоматически переходят на обычный формат happ://add/<base64>.

Ведение бизнеса

Ваш первый клиент

1. Панель → Пользователи → Добавить пользователя.
2. Укажите имя пользователя, выберите дату истечения и лимит трафика (или оставьте оба без ограничений), выберите протоколы.
3. Сохраните — панель сразу сгенерирует ссылку на подписку.
4. Отправьте клиенту ссылку. Он вставляет её в клиентское приложение (см. страницу Клиенты с рекомендациями) и подключается.

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

Лимиты устройств и IP

Лимиты устройств и IP (см. как работает контроль) — это не только защита от злоупотреблений, но и рычаг для ценообразования. Частая структура:

Установите device_limit (или ip_limit) при создании или редактировании пользователя. Клиенты, превысившие лимит, автоматически переводятся в статус limited — следить за этим вручную не нужно.

Админы и реселлеры

Если под вами продают другие люди — друзья, сотрудники или суб-реселлеры — выдайте каждому отдельный логин администратора вместо того, чтобы делиться своим. Полное описание см. в разделе Управление администраторами; коротко:

• Владелец (вы) — видит всё, управляет остальными админами.
• Админ — управляет пользователями, но не настройками панели и не другими админами.
• Реселлер — управляет только своими пользователями, в рамках лимитов max_users и max_traffic_bytes, которые вы задаёте.

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

Самообслуживание через Telegram

После подключения Telegram-бота клиенты сами проверяют свой трафик (/usage), заново получают ссылку (/sub) и смотрят подключённые устройства (/devices) — без обращения к вам. Это снимает большую часть обращений в поддержку вида «а работает ли ещё мой VPN».

Ценообразование

NexusPanel не устанавливает ваши цены — это полностью на ваше усмотрение и зависит от вашего рынка. Для старта большинство операторов учитывают:

• Ваши расходы — VPS панели, ноды, ваша лицензия NexusPanel (см. тарифы и цены), а также трафик, если провайдер берёт за него плату.
• Ваше отличие от конкурентов — больше слотов на устройства, больше локаций нод, приоритетная поддержка, или просто стабильность, когда у конкурентов её нет.
• Ваш рынок — сколько берут похожие сервисы там, где живут ваши клиенты. Пакетные многомесячные тарифы (по аналогии со скидками 3/6/12 месяцев у самой панели) — частый способ повысить удержание клиентов.

Принимайте оплату так, как удобно вам — вручную через Telegram или мессенджеры, через бота для оплаты, или через собственный магазин, который вызывает API пользователей и создаёт аккаунт автоматически после оплаты.

Ноды

Что такое нода

Нода — это удалённый сервер с ядром Xray, который подключается обратно к вашему экземпляру NexusPanel. Ноды позволяют распределять прокси-точки по нескольким серверам и географическим локациям, управляя всем из одной панели.

Панель общается с нодами по защищённому gRPC-соединению с использованием взаимного TLS. Через этот канал передаются конфигурации пользователей и данные о трафике.

Установка ноды

Панель → Ноды → Добавить новую ноду открывает окно с двумя вкладками — выберите подходящую в зависимости от того, есть ли у панели SSH-доступ к серверу ноды.

Auto install (рекомендуется)

Вставьте IP свежего VPS и данные SSH-входа (пароль root или приватный ключ) — панель сделает всё остальное: подключится по SSH, установит Docker и агент ноды со встроенным mTLS-сертификатом, зарегистрирует ноду и дождётся подключения. Ничего копировать и запускать вручную не нужно — пароль/ключ SSH используется один раз и нигде не сохраняется.

Manual (резервный вариант — если панель не может достучаться до ноды по SSH)

Вкладка Manual вместо этого генерирует готовую к вставке однострочную команду со встроенным сертификатом панели. Никакой записи файла сертификата вручную.

1. Панель → Ноды → Добавить новую ноду → вкладка Manual
2. Нажмите Copy Install Command — команда включает сертификат, порт, порт API и URL панели
3. Вставьте и выполните на сервере ноды
4. Введите IP ноды и порты в панели → Add Node

curl -sL https://nexuspanel.store/install-node | bash -s -- \
  --port 62060 \
  --api-port 62061 \
  --panel-url 'https://panel.example.com:8443' \
  --cert-b64 '<base64-cert>'

Установщик автоматически ждёт снятия блокировок apt/dpkg — его безопасно запускать на только что развёрнутом VPS. Не пропускайте --panel-url: без него аутентификация Hysteria 2 на этой ноде останется отключённой, пока вы не зададите её позже.

Сертификат и порты

NexusNode аутентифицируется в панели с помощью подписывающего сертификата панели:

• Порт подключения к панели: 62060
• Порт API Xray: 62061
• CN сертификата: Panel — значение ssl_target_name в конфиге ноды должно совпадать
• Сертификат один раз запрашивается из GET /api/v1/node/settings (или встраивается командой установки) и сохраняется в /var/lib/nexus-panel-node/ssl_client_cert.pem

Docker Compose для ноды

Это реальный compose-файл, который генерирует установщик в /opt/nexus-panel-node/docker-compose.yml — для справки, если настраиваете его вручную:

services:
  node:
    image: ghcr.io/haitovs/nexus-node:latest
    container_name: nexus-panel-node
    restart: always
    network_mode: host
    environment:
      SERVICE_PORT: 62060
      XRAY_API_PORT: 62061
      SSL_CERT_FILE: /var/lib/nexus-panel-node/ssl_cert.pem
      SSL_KEY_FILE: /var/lib/nexus-panel-node/ssl_key.pem
      SSL_CLIENT_CERT_FILE: /var/lib/nexus-panel-node/ssl_client_cert.pem
      # Sidecar Hysteria2 — пусто отключает его, пока не передан --panel-url
      PANEL_HY2_AUTH_URL: "https://panel.example.com:8443/api/v1/hy2-auth"
    volumes:
      - /var/lib/nexus-panel-node:/var/lib/nexus-panel-node
      - /etc/hysteria:/etc/hysteria

network_mode: host означает, что раздела ports: в Docker нет — нода привязывает все порты (сервисный, API и все инбаунды Xray/Hysteria, к которым подключаются пользователи) напрямую на хосте.

Несколько нод

Чтобы добавить ноды в разных локациях:

1. Установите сервис ноды на каждый сервер с помощью сгенерированной однострочной команды
2. В панели добавьте каждую ноду с её публичным IP и портами
3. Назначьте флаг страны — он управляет и визуальной сеткой, и региональным переупорядочиванием подписки
4. Перетаскиванием задайте порядок отображения в сетке
5. Задайте коэффициент использования для каждой ноды (например, 1.5 означает, что трафик считается с множителем 1.5×)

Устранение неполадок нод

Справочник API

Все эндпоинты API находятся под /api/v1/. Включите интерактивный Swagger UI, задав DOCS=true и зайдя на /docs.

Аутентификация

Получите JWT access-токен, отправив учётные данные:

curl -X POST https://panel.example.com:8443/api/v1/admin/token \
  -d "username=admin&password=admin&grant_type=password"

# Ответ:
# {"access_token": "eyJ...", "token_type": "bearer"}

# Используйте токен в последующих запросах:
curl -H "Authorization: Bearer eyJ..." https://panel.example.com:8443/api/v1/system

Если для администратора включена 2FA, передайте TOTP-код в заголовке X-TOTP-Code.

Пользователи

Создать нового пользователя с протоколами, лимитом трафика, сроком действия, лимитом устройств и лимитом IP.

Список всех пользователей. Автоматически ограничивается по администратору для несудо-аккаунтов.

Получить детальную информацию о пользователе, включая статистику использования и ссылки-подписки.

Обновить поля пользователя (лимит трафика, срок действия, статус, протоколы и т. д.).

Безвозвратно удалить пользователя и все связанные данные.

Массовые операции

Экспорт

Скачать всех пользователей в виде CSV-файла.

Экспортировать все ссылки-подписки в виде обычного текста.

Администраторы

Создать нового администратора с ролью (owner, admin, reseller), max_users и max_traffic_bytes.

Список всех учётных записей администраторов.

Ноды

Список всех протокольных inbound-ов.

Получить конфигурации хостов (только sudo).

Аналитика

Сводная статистика для обзора панели.

Разбивка распределения по протоколам.

Число подключений и трафик по каждой ноде.

Проценты аптайма нод.

Пользователи, у которых срок истекает в течение указанного числа дней.

Топ-пользователи по потреблению трафика.

Сессии

Активные сессии устройств за последние N часов.

Сессии конкретного пользователя.

Принудительно отключить сессию устройства.

Система

Системная статистика, включая CPU, память и трафик. Несудо-администраторы видят обнулённые значения для чувствительных метрик.

Эндпоинт проверки работоспособности, возвращающий статус базы данных и ядра Xray.

Эндпоинт метрик, совместимый с Prometheus. Требует METRICS_ENABLED=true и METRICS_TOKEN для аутентификации.

Telegram-бот

Настройка

1. Откройте Telegram и напишите @BotFather
2. Отправьте /newbot и следуйте подсказкам, чтобы создать бота
3. Скопируйте токен бота (например, 123456789:AAAA...)
4. Узнайте свой ID пользователя Telegram (напишите @userinfobot)
5. Добавьте в ваш .env:

TELEGRAM_API_TOKEN="123456789:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
TELEGRAM_ADMIN_ID="987654321"
TELEGRAM_LOGGER_CHANNEL_ID=-1001234567890

Перезапустите панель после добавления токена. Бот запустится автоматически.

Команды бота

Настройки уведомлений

Telegram-бот отправляет уведомления о различных событиях, когда это настроено. Управляйте каждым типом уведомлений по отдельности через переменные .env (см. конфигурацию уведомлений).

Уведомления отправляются:

• На ID администраторов — личные сообщения каждому администратору из TELEGRAM_ADMIN_ID
• В канал логов — все события в TELEGRAM_LOGGER_CHANNEL_ID

Поля, включаемые в уведомления о создании / изменении

Уведомления о создании и изменении пользователя включают следующие поля, если они заданы у пользователя:

Каналы доставки подписок

Доставляйте sub URL через инфраструктуру, которую цензоры не могут заблокировать.

Когда домен вашей панели заблокирован в России, Иране, Китае или Туркменистане, клиенты не могут получить обновления своих подписок. Каналы доставки подписок решают это, публикуя конфиг каждого пользователя в статический файл на инфраструктуре Google / Cloudflare / GitHub / Telegram — на хостах, которые цензоры не могут заблокировать целиком, не сломав массовые приложения, которыми пользуются миллионы.

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

1. Вы настраиваете один или несколько каналов в Настройки → Каналы доставки подписок.
2. Каждый пользователь получает стабильный публичный URL на этом канале (например, https://firebasestorage.googleapis.com/…?alt=media&token=…).
3. Значок ⊞ (сетка) в каждой строке пользователя в таблице открывает поповер со всеми доступными URL — Direct, зашифрованный Happ и каждый настроенный канал. Копирование или показ QR в два клика.
4. Когда вы редактируете хосты или конфиг Xray, панель автоматически переопубликовывает всех активных пользователей в Firebase (и другие каналы) в течение ~10–30 секунд через фоновый воркер. Ручной Backfill после рутинных правок конфига не нужен.

Доступные каналы

Firebase Storage

Рекомендуемый первый канал. Бесплатный лимит покрывает ~50K запросов подписки в день. Размещён в IP-пространстве Google — цензоры не могут заблокировать его целиком, не сломав Google Maps, Gmail и множество других приложений.

Однократная настройка на console.firebase.google.com

1. Создайте проект — Add project → назовите его (например, nexus-subs) → план Spark (бесплатный) → Create.
2. Включите Storage — Build → Storage → «Get started» → «Start in production mode» → выберите локацию → Done.
3. Задайте правила хранилища — Storage → Rules → замените на:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /sub_{file=**} {
      allow read: if true;
      allow write: if false;
    }
  }
}

4. Сгенерируйте ключ сервисного аккаунта — Project Settings (⚙) → Service accounts → «Generate new private key» → Download. Относитесь к нему как к паролю.
5. Найдите имя бакета — Storage → вверху показано gs://your-project.firebasestorage.app. Скопируйте часть после gs://.

В панели

1. Настройки → Каналы доставки подписок → Firebase Storage → ⚙
2. Вставьте имя бакета и JSON сервисного аккаунта (всё содержимое файла)
3. Включите Enabled, задайте Priority (меньше = предпочтительнее; 10 — хорошее начало)
4. Сохраните → нажмите Test (значок обновления)

Как читать результат теста

Успешный тест выглядит так:

firebase: end-to-end OK in 1840ms
✓ creds   (180ms): bucket reachable
✓ upload  (650ms): published to https://firebasestorage.googleapis.com/…
✓ fetch   (820ms): GET 200 (87 bytes, attempt 1)
✓ match     (1ms): content matches
✓ cleanup (180ms): test blob deleted

Применить к существующим пользователям

После того как тест пройдёт, нажмите Backfill внизу карточки «Каналы доставки подписок». Это немедленно запустит загрузки в Firebase для всех активных пользователей через фоновый воркер. Для 200 пользователей ожидайте 30–120 секунд.

Cloudflare R2

S3-совместимое объектное хранилище без платы за исходящий трафик. Используйте как вторичный канал наряду с Firebase — иной поставщик означает, что региональная блокировка одного не выводит из строя оба.

Настройка на dash.cloudflare.com

1. R2 (левое меню) → Create bucket → назовите его (например, nexus-subs).
2. Откройте бакет → Settings → Public access → включите. Скопируйте URL https://pub-<id>.r2.dev.
3. Вверху справа страницы R2 → Manage R2 API tokens → Create token → Object Read & Write (ограничьте вашим бакетом) → сохраните Access Key ID + Secret.
4. Ваш Account ID — это 32-символьный hex внизу справа страницы панели R2.

В панели

Настройки → Каналы доставки подписок → Cloudflare R2 → ⚙:

GitHub Gist

Бесплатно, размещено на GitHub (IP Microsoft). Крайне живучий вариант — хороший низкоприоритетный запасной канал, который ничего не стоит.

Настройка

1. github.com/settings/tokens → Personal access tokens → Tokens (classic) → Generate new token.
2. Имя: nexus-gists. Область: отметьте ТОЛЬКО gist. Срок: 1 год (поставьте напоминание о продлении).
3. Скопируйте токен ghp_… — увидеть его снова не получится.

В панели

Настройки → Каналы доставки подписок → GitHub Gist → ⚙ → вставьте PAT → Сохранить → Test.

Доставка через Telegram

Доступен в IR/RU/TM именно в те периоды, когда другие каналы недоступны. Это запасной канал из разряда «панель горит, и у пользователя больше ничего нет».

Настройка — отдельный бот (рекомендуется)

1. Напишите @BotFather в Telegram → /newbot → выберите имя и username (должен заканчиваться на bot).
2. Скопируйте токен, который выдаст BotFather.
3. Настройки → Каналы доставки подписок → Telegram → ⚙:
   • Username бота: без @
   • Токен бота: вставьте из BotFather
4. Сохраните → Test. Тест вызывает getMe и проверяет, что возвращённый username совпадает с тем, что вы вставили.

Если у вас уже задан TELEGRAM_API_TOKEN в .env для доставки уведомлений, поле токена бота можно оставить пустым — канал использует эту переменную окружения. Не рекомендуется по соображениям безопасности: утечка токена бота уведомлений раскрыла бы и файлы подписок.

Пул Nginx-прокси

Когда все каналы статического хранилища отключаются или блокируются по регионам, переходите на собственный парк дешёвых ретрансляторов-VPS. Каждый хост в пуле получает свой домен; панель распределяет пользователей по хостам по весу.

Предварительная подготовка

Поднимите дешёвые VPS (Hetzner CCX13 / Contabo и т. п. — €4–5/месяц каждый). На каждом:

# Запустить от root на каждом новом прокси-хосте
curl -sSL https://your-panel.tld/setup_proxy.sh | bash

В панели

Настройки → Каналы доставки подписок → Nginx-прокси → ⚙. Конфигурация в JSON:

{
  "hosts": [
    { "host": "alpha.shop",  "subscription_path": "sub", "weight": 1 },
    { "host": "beta.shop",   "subscription_path": "sub", "weight": 1 },
    { "host": "gamma.shop",  "subscription_path": "sub", "weight": 5 }
  ]
}

Хост с weight: 5 получает в 5 раз большую долю пользователей, чем хост с weight: 1. Сохраните → Test проверяет TLS-рукопожатие для каждого члена пула.

Каналы доставки подписок — интерфейс панели

Поповер подписки (для каждого пользователя)

В каждой строке таблицы пользователей есть значок ⊞ (сетка). Нажатие на него открывает поповер со списком всех URL, которые оператор может дать клиенту:

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

Бейджи состояния каналов

Каждая строка канала в Настройки → Каналы доставки подписок показывает бейдж состояния по последней проверке. Cron запускается каждые 15 минут. Принудительно запустить свежую проверку можно в любой момент кнопкой Test.

Автопереопубликация при изменении конфигурации

Редактирование хостов или конфига ядра Xray запускает автоматическую рассылку: все активные пользователи, у которых изменилось содержимое подписки, переопубликовываются на каждый настроенный канал в течение ~10–30 секунд. Воркер пропускает пользователей, у которых отрендеренный конфиг не изменился (короткое замыкание по хэшу содержимого), поэтому правка хоста, затрагивающая только 50 из 200 пользователей, вызывает всего 50 записей в Firebase.

Backfill

Кнопка Backfill (внизу карточки «Каналы доставки подписок») немедленно загружает всех активных пользователей на все включённые каналы. Используйте её один раз после добавления нового канала — после этого автопереопубликация поддерживает всё в актуальном состоянии.

Hysteria2

Hysteria2 — это протокол на базе QUIC/UDP, который даёт в 3–5× большую пропускную способность, чем TCP, на сетях «последней мили» с потерями (мобильная связь, 4G в СНГ, Иран). Он работает как отдельный демон рядом с Xray — а не как inbound Xray — потому что Xray-core не поддерживает протокол hysteria2 нативно.

Ограничение по лицензии: Standard и выше. На пробном тарифе записи подписки hy2 видны, но создавать и управлять inbound-ами нельзя.

Добавить inbound Hysteria2

Панель → Настройки → Hysteria2 → Add Inbound

Создание inbound синхронизирует конфигурацию на каждую подключённую ноду и запускает демон hysteria на каждой. SSH не требуется.

Добавить хосты для каждой ноды

Панель → Хосты → нажмите карточку inbound Hysteria2 → Add Host

Добавьте по одной строке-хосту на каждую ноду, на которой хотите открыть hy2:

Генераторы подписок автоматически выдают записи hy2:// для каждого включённого хоста наряду с существующими ссылками VLESS/VMess. Клиенты увидят их при следующем обновлении подписки.

Через API (требуются учётные данные sudo-администратора):

# 1. Получить токен с помощью имени и пароля суперадминистратора
TOKEN=$(curl -s -X POST /api/v1/admin/token \
  -d "username=YOUR_ADMIN&password=YOUR_PASSWORD" \
  | jq -r .access_token)

# 2. Список inbound-ов hy2
curl /api/v1/hy2-inbounds -H "Authorization: Bearer $TOKEN"

# 3. Добавить хост к inbound id=1
curl -X POST /api/v1/hy2-inbounds/1/hosts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"remark":"DE Frankfurt","address":"de.example.com","port":2053,"country_code":"DE"}'

Проверка и устранение неполадок

После добавления хоста запросите URL подписки — вы должны увидеть запись hy2:// наряду со ссылками VLESS. Импортируйте в Nekobox, sing-box или Happ и подключитесь.

Middle-сервер (NAT-ретранслятор)

Middle-сервер — это дешёвый VPS, который стоит между вашими пользователями и нодами. Он ретранслирует трафик через iptables DNAT, поэтому пользователи подключаются к одному стабильному IP независимо от того, какая нода их обслуживает. Полезно, когда IP ноды блокируют в какой-то стране — замените ноду, заново сгенерируйте NAT на middle-сервере, обновите одну запись хоста.

Первоначальная настройка

Сгенерируйте одноразовую команду установки из панели, затем вставьте её на новом VPS от root:

1. В панели перейдите в Настройки → Middle-серверы и нажмите Generate install command.
2. Скопируйте показанную команду — она выглядит так:

curl -fsSLk https://panel.example.com:8443/api/v1/middle-server/i/<token> | sudo bash

Токен одноразовый и истекает через 30 минут. В истории shell не появляется никаких учётных данных.

read -p "Panel URL: " _P
read -p "Admin username: " _U
read -sp "Admin password: " _W; echo
curl -fsSL -k -u "$_U:$_W" "$_P/api/v1/middle-server/bootstrap.sh" | sudo bash
unset _P _U _W

Скрипт генерируется из вашего текущего списка нод и inbound-ов Hysteria 2, поэтому перезапускайте его каждый раз, когда добавляете или удаляете что-либо из них.

Скрипт:

• Установит iptables-persistent
• Применит тюнинг ядра (BBR, большие буферы, conntrack)
• Построит все правила DNAT из текущего состояния БД панели
• Выведет таблицу записей-хостов для добавления в панели

После завершения скрипта перейдите на страницу Хостов и добавьте по одной записи-хосту на каждую выведенную скриптом строку, используя IP middle-сервера и выведенный порт.

Переход на новый middle-сервер

Когда текущий middle-сервер заблокирован или вы хотите перейти на другой VPS:

1. Подключитесь по SSH к новому VPS и выполните ту же единственную команду выше
2. В панели → страница Хостов отредактируйте каждый хост, чей адрес указывает на старый IP middle-сервера, и смените его на новый IP. Порты остаются прежними.
3. Готово — никаких изменений нод, никакой перенастройки у пользователей

Фронтинг и обход блокировок

IP-Defender NexusPanel делает всё это за вас: следит за каждым фронтинг-хостом, определяет блокировку и заменяет адрес на рабочий — автоматически или в один клик. Открывается из Панель → Defender, устроенного как конвейер:

Использовать все провайдеры не обязательно. Начните с одного — Cloudflare проще всего и бесплатен — и добавляйте остальные позже, если нужна избыточность или вы обслуживаете регионы с разной картиной блокировок.

IP-Defender

IP-Defender — это фоновая задача, которая непрерывно проверяет, работает ли ещё каждый фронтинг-хост. Она не ждёт жалобы от клиента.

1. Healthy (здоров) — хост опрашивается и отвечает нормально.
2. Suspect (подозрителен) — опросы начинают проваливаться. Одна неудачная проверка ничего не запускает; нужна устойчивая серия сбоев, прежде чем защитник воспримет это всерьёз — так короткий сетевой сбой не приведёт к лишней замене.
3. Blocked (заблокирован) — сбои продолжаются. Защитник выбирает рабочий адрес того же вида (хост Cloudflare заменяется только на другой адрес Cloudflare, хост AWS — только на другой AWS; смешивание видов ломает сертификат, который ожидает клиент) и обновляет его автоматически.
4. Cooldown (охлаждение) — после замены старый адрес какое-то время не используется повторно, чтобы хост не «дёргался» туда-сюда.

Поскольку Xray сам по себе не пишет трафик в разрезе по хостам, защитник опирается на активные опросы, а не на графики трафика. Это нормально — вы увидите время «последней проверки» на каждом хосте, а не счётчики трафика в реальном времени.

Cloudflare

Самый простой провайдер для старта — бесплатного тарифа достаточно для фронтинга. Через edge-узлы Cloudflare проходит огромное количество обычных сайтов, поэтому их блокировка задевает много легитимного трафика, и сети на это неохотно идут. Cloudflare в NexusPanel решает две разные задачи, и открываются они по-разному:

1. В Cloudflare создайте API-токен с правом редактирования DNS для домена, через который будете фронтить.
2. Панель → Defender → Setup → добавьте учётные данные, провайдер cloudflare, вставьте API-токен.
3. Фронтинг самого VPN-трафика: Панель → Defender → Hosts (Pipeline, шаг 3) → добавьте хост, указывающий на ваш домен за Cloudflare (DNS-запись с «оранжевым облаком»). Отдельную дистрибуцию создавать не нужно — Cloudflare это просто DNS + прокси, и IP-Defender следит за этим хостом как за любым другим.
4. Доступность ссылки на подписку: Панель → Defender → Shield → карточка Cloudflare открывает отдельную страницу, которая ротирует домен, с которого раздаются ссылки на подписку (PRIMARY/STANDBY, с автоматическим escape, если этот домен заблокируют). Это другая задача, не связанная с фронтингом VPN-трафика — она про то, чтобы клиенты могли обновлять конфиг.

AWS CloudFront

CDN от Amazon — другой вендор, отличный от Cloudflare, и это важно: если вы используете оба, сети, заблокировавшей один, придётся отдельно разбираться и со вторым.

1. В AWS создайте IAM-пользователя с правами CloudFront + Route 53 и сгенерируйте access key.
2. Панель → Defender → Setup → добавьте учётные данные, провайдер aws, вставьте access key ID и secret.
3. Панель → Defender → Shield → карточка AWS CloudFront, чтобы создать дистрибуцию CloudFront и увидеть её текущий входной IP и статус.

Тарификация AWS CloudFront зависит от использования (в основном от исходящего трафика) — следите за ней, если гоните через неё серьёзный объём трафика.

Google (Cloud Run)

Фронтинг через инфраструктуру Google run.app — те же хостнеймы, что используют бесчисленные обычные приложения Cloud Run.

1. В Google Cloud создайте сервисный аккаунт с правами Cloud Run + DNS и скачайте его JSON-ключ.
2. Панель → Defender → Setup → добавьте учётные данные, провайдер google, вставьте ключ сервисного аккаунта.
3. Панель → Defender → Shield → карточка Google Cloud Run, чтобы развернуть и управлять фронтинг-сервисом.

Сервисы Cloud Run должны быть публично доступны, чтобы работать как фронт — панель делает это сама при развёртывании сервиса.

Fastly

Fastly — провайдер с подключением в один клик, точно как Cloudflare, AWS и Google: вы даёте edge-IP, панель строит всё остальное.

1. В Fastly создайте API-токен с областью действия global (нужна, чтобы создавать CDN-сервисы).
2. Панель → Defender → Setup → добавьте учётные данные, провайдер fastly, вставьте токен.
3. Панель → Defender → Shield → карточка Fastly → вставьте свои edge-IP Fastly (по одному на строку или через запятую) и нажмите Create CDN. Панель поднимет сервис Fastly, настроенный как ваш текущий, и сама подключит нужный inbound и по одному хосту на каждый edge-IP.

У Fastly нет быстрой ротации: если edge-IP заблокирован, заново запустите Create CDN с новыми edge-IP, а не ждите автоматическую замену.

Bunny CDN

Bunny работает иначе, чем остальные провайдеры: не панель создаёт CDN за вас, а вы создаёте его на bunny.net, а панель его адаптирует.

1. На bunny.net создайте одну pull zone на тарифе Standard с включёнными WebSockets.
2. Добавьте в эту pull zone правило для каждой ноды (Edge Rule): Host == bunny-<node>.<ваш-домен>, переопределяющее Origin URL на http://<ip-ноды>:2009 (inbound VLESS BUNNY WS этой ноды). Одно правило на каждую ноду.
3. Панель → Defender → Setup → добавьте учётные данные, провайдер bunny, вставьте API-ключ вашего аккаунта Bunny.
4. Панель → Defender → Shield → карточка Bunny CDN → нажмите Auto-wire per node. Панель прочитает правила вашей pull zone, сопоставит каждый origin IP с нодой в панели и создаст по одному управляемому хосту Bunny на каждую совпавшую ноду. Перезапускайте при добавлении ноды или исправлении правила.
5. Нажмите Refresh edge IPs, чтобы засеять опубликованные edge-IP Bunny в пул ротации.

Как и у Fastly, у Bunny нет быстрой ротации — заблокированный edge означает починку pull zone и повторный auto-wire, а не мгновенную замену.

Azure

Azure — это не CDN-фронт вроде остальных: он разворачивает ротируемую VM-ретранслятор (та же идея, что Middle-сервер, только Azure сам поднимает VM и меняет её IP), чтобы у заблокированной ноды появился свежий входной IP без изменений на самой ноде.

1. Создайте Service Principal: az ad sp create-for-rbac --role Contributor --scopes /subscriptions/<id>.
2. Панель → Defender → Shield → карточка Azure → вставьте tenant ID, client ID, client secret и subscription ID, затем нажмите Verify & connect. У Azure своя форма учётных данных прямо здесь — она не проходит через Setup, как у остальных провайдеров.
3. Выберите регион (панель предлагает вариант, определённый по вашим подпискам) и нажмите Create relay — это развернёт небольшую VM на Ubuntu со статическим IP, размер выбирается автоматически как самый дешёвый.
4. Установите middle-агент на полученный IP и переведите его в промоут, как для любого middle-сервера (см. Middle-сервер → Первоначальная настройка).

Если IP ретранслятора позже заблокируют, нажмите Rotate IP на странице Azure, затем заново запустите установку middle-сервера на новом IP и перепроверьте из-под заблокированной сети.

Миграция с Marzban

Инструмент nexus cli migrate переносит живую установку Marzban в NexusPanel без какой-либо перенастройки у конечных пользователей. Он работает на том же хосте, что и Nexus, читает каталог данных Marzban напрямую и использует атомарный конечный автомат из 9 этапов с полным откатом вплоть до команды finalize.

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

• Marzban версии 0.6.0–0.8.4 (официальный скрипт установки, marzban или marzban_cli)
• NexusPanel установлен на том же хосте или может читать /var/lib/marzban/
• Свободное место на диске для снимка SQLite-базы Marzban

Шаг 1: Пробный прогон

Всегда сначала делайте пробный прогон. Он делает снимок базы Marzban, повторяет каждый импорт в черновую копию и завершается за секунды. В Nexus или Marzban ничего не записывается.

# Посмотреть, что было найдено
nexus cli migrate discover

# Репетиция: снимок + импорт + проверка на черновой БД, без побочных эффектов
nexus cli migrate run --dry-run

Прочтите отчёт о пробном прогоне в /var/lib/nexus/migration/dryrun-<ts>.json. Подтвердите число пользователей, список администраторов и что MARZBAN_LEGACY_JWT_SECRET был извлечён. Исправьте все отмеченные ошибки перед продолжением.

Шаг 2: Боевое переключение

# Боевой прогон — останавливает Marzban, импортирует, перезапускает Nexus
nexus cli migrate run --yes

Критический путь (MARZBAN_STOP → NEXUS_RESTART) занимает ~15–30 секунд. VPN-трафик нод продолжается без перерыва — ноды работают независимо от панели. Недоступен лишь ненадолго эндпоинт URL подписки.

Если VERIFY не проходит, срабатывает автооткат: конфигурации Nexus восстанавливаются, а Marzban перезапускается. Проверьте docker logs nexus-panel --tail 200, чтобы найти первопричину, затем перезапустите.

# После наблюдения за продакшеном в течение нескольких часов:
nexus cli migrate finalize    # освобождает снимок, закрывает прогон

# Если нужно отменить (только до finalize):
nexus cli migrate rollback

Что переносится

Чек-лист после миграции

После завершения nexus cli migrate run --yes CLI выводит таблицу перенесённых хостов. Проверьте их, а затем:

1. Проверьте старый URL-подписку Marzban — он должен вернуть валидный конфиг (проверка совместимости JWT)
2. Проверьте число пользователей: docker exec nexus-panel sqlite3 /var/lib/panel/db.sqlite3 'SELECT COUNT(*) FROM users;'
3. Выполните nexus cli migrate post-cutover, чтобы найти оставшиеся демоны Marzban (marzguard, cron-хуки certbot)
4. Если используете Hysteria2: добавьте inbound + по одному хосту на ноду (см. раздел Hysteria2)
5. Добавьте ноды заново через Панель → Ноды (новый сертификат, порты 62060/62061)
6. Выполните nexus cli migrate finalize, чтобы освободить снимок, когда всё стабильно

# Здоровье
curl -sk https://<your-domain>/api/v1/health

# Старый sub URL должен вернуть 200 с содержимым конфига
curl -sk "https://<your-domain>/sub/<marzban-token>" | head -c 200

# Поиск остатков Marzban
nexus cli migrate post-cutover

Миграция с Remnawave

Инструмент nexus cli migrate remnawave подключается к живой панели Remnawave по её API (URL и логин/пароль администратора) и импортирует пользователей в NexusPanel.

# По умолчанию — пробный прогон: подключается, извлекает и показывает, что будет
# импортировано и какие имена конфликтуют, ничего не пишет
nexus cli migrate remnawave run --url https://ваша-remnawave-панель --username ADMIN --password ...

# Применить изменения
nexus cli migrate remnawave run --url https://ваша-remnawave-панель --username ADMIN --password ... --run

--yes нужен, только если такое имя пользователя уже есть в NexusPanel — без него боевой прогон откажется выполняться, а не перезапишет данные. --insecure пропускает проверку TLS-сертификата (для Remnawave с самоподписанным сертификатом). --page-size (по умолчанию 250) задаёт размер страницы при обращении к API Remnawave.

# Откат — удаляет ровно тех пользователей и алиасы, которые создал прогон
nexus cli migrate remnawave rollback

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

Двухфакторная аутентификация (2FA)

NexusPanel поддерживает 2FA на базе TOTP (совместимо с Google Authenticator, Authy и т. д.):

1. Перейдите в Настройки в панели
2. Нажмите Enable 2FA
3. Отсканируйте QR-код приложением-аутентификатором
4. Введите 6-значный код для подтверждения
5. Сохраните резервные коды в безопасном месте

Через API:

# Сгенерировать TOTP-секрет и резервные коды
curl -X POST /api/v1/admin/2fa/setup -H "Authorization: Bearer TOKEN"

# Активировать 2FA (укажите TOTP-код для проверки)
curl -X POST /api/v1/admin/2fa/enable \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# Вход с 2FA
curl -X POST /api/v1/admin/token \
  -H "X-TOTP-Code: 123456" \
  -d "username=admin&password=admin&grant_type=password"

Защита капчей

Защитите страницу входа от атак перебором с помощью капчи:

Cloudflare Turnstile

CAPTCHA_PROVIDER="turnstile"
TURNSTILE_SITE_KEY="0x4AAAAAAA..."
TURNSTILE_SECRET_KEY="0x4AAAAAAA..."

Встроенная капча

CAPTCHA_PROVIDER="builtin"

Встроенная капча не требует внешних сервисов и генерирует простые математические задачи.

Ограничение частоты запросов

Ограничение частоты запросов к эндпоинту входа включено по умолчанию:

LOGIN_RATE_LIMIT="10/minute"
LOGIN_LOCKOUT_THRESHOLD=10
LOGIN_LOCKOUT_DURATION_MINUTES=30

После 10 неудачных попыток IP блокируется на 30 минут. Ограничитель частоты работает в памяти (в рамках процесса) и сбрасывается при перезапуске сервера.

SSL / TLS

Для продакшен-развёртываний всегда используйте HTTPS. Варианты:

• Прямой SSL — задайте UVICORN_SSL_CERTFILE и UVICORN_SSL_KEYFILE
• Обратный прокси — используйте Nginx или Caddy впереди с терминацией SSL
• Cloudflare — проксируйте через Cloudflare в режиме Full (Strict) SSL

Пример обратного прокси Nginx

server {
    listen 443 ssl http2;
    server_name panel.example.com;

    ssl_certificate     /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

FAQ

Как сменить пароль администратора

Вариант 1: Обновите переменную окружения SUDO_PASSWORD и перезапустите панель.

Вариант 2: Используйте API:

curl -X PUT /api/v1/admin/admin \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "newSecurePassword123"}'

Как сделать резервную копию

SQLite

# Сначала остановите панель для чистой копии
docker compose stop panel
cp /var/lib/nexuspanel/db.sqlite3 /backups/db-$(date +%Y%m%d).sqlite3
docker compose start panel

# Или используйте онлайн-бэкап SQLite (без простоя)
sqlite3 /var/lib/nexuspanel/db.sqlite3 ".backup /backups/db-$(date +%Y%m%d).sqlite3"

PostgreSQL

docker compose exec db pg_dump -U nexus nexuspanel > /backups/db-$(date +%Y%m%d).sql

Как обновить

cd /opt/nexuspanel

# Скачать последние образы
docker compose pull

# Перезапустить с новой версией
docker compose up -d

# Проверить логи на статус миграций
docker compose logs -f panel

Миграции базы данных выполняются автоматически при запуске. Всегда делайте резервную копию базы перед обновлением.

Как добавить свои шаблоны

Свои шаблоны позволяют управлять выводом подписки для разных клиентов:

1. Создайте файлы шаблонов в каталоге шаблонов:

mkdir -p /var/lib/nexuspanel/templates/clash
nano /var/lib/nexuspanel/templates/clash/custom.yml

2. Укажите шаблон в .env:

CUSTOM_TEMPLATES_DIRECTORY="/var/lib/panel/templates/"
CLASH_SUBSCRIPTION_TEMPLATE="clash/custom.yml"

Шаблоны поддерживают синтаксис Jinja2 с доступом к данным пользователя, конфигам прокси и настройкам панели.

Настройка страницы подписки

Страница подписки для пользователя (показывается при открытии ссылки-подписки в браузере) полностью настраиваема:

1. Скопируйте шаблон по умолчанию как отправную точку:

cp -r /opt/nexuspanel/app/templates/subscription \
  /var/lib/nexuspanel/templates/subscription

2. Отредактируйте /var/lib/nexuspanel/templates/subscription/index.html
3. Задайте в .env:

SUBSCRIPTION_PAGE_TEMPLATE="subscription/index.html"

Доступные переменные шаблона включают: user, sub_url, clash_url, singbox_url, usage, expire_date и brand_name.