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

Никогда не слышали про 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, nexus-redis (очередь, слушает только loopback) и nexus-worker. Воркер не опционален: без него не выполняется ничего по расписанию — подписки не публикуются, здоровье каналов не проверяется, упавший канал не переключается, статистика нод пустая, CDN-фронты не согласуются, — при этом панель продолжает считаться здоровой.
4. Заполнит xray_config.json с включённым access-логом (нужно для применения лимитов IP/устройств) и откроет в файрволе все указанные в нём порты
5. Запустит панель и выведет URL панели и учётные данные
6. Выполнит quick-start (отключается через QUICKSTART=0): создаст демо-пользователя test, установит совмещённую ноду на этом же сервере и подключит её
7. И только после того, как эта нода сообщит статус connected, установит DISABLE_LOCAL_XRAY=true и перезапустит панель, чтобы инбаунд-портами владела нода, а собственный Xray-ядро панели остановилось. Если после перезапуска панель не достучится до ноды, инсталлятор вернёт ядро обратно, вместо того чтобы оставить сервер вообще без трафика.

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

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

# Рекомендуется — передайте свой 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 --deploy-hook 'docker restart nexus-panel'

С 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-файл на такой, который поднимает Postgres 16 и Redis 7 рядом с панелью и воркером. docker-compose.modern.yml из репозитория на вашем сервере отсутствует — инсталлятор его не пишет, и в образ он не входит, так что копировать нечего. Redis и воркер уже есть в compose, который написал инсталлятор, так что добавить нужно только Postgres. Оставьте panel, redis и worker как есть, а панель направьте на Postgres через SQLALCHEMY_DATABASE_URL в .env:

  postgres:
    image: postgres:16-alpine
    container_name: nexus-postgres
    restart: always
    network_mode: host
    environment:
      POSTGRES_DB: nexus
      POSTGRES_USER: nexus
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      PGPORT: 5432
    command: [postgres, -c, listen_addresses=127.0.0.1]
    volumes:
      - /var/lib/nexus/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U nexus -d nexus"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s

Примеры 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

  redis:
    image: redis:7-alpine
    container_name: nexus-redis
    restart: always
    network_mode: host
    command: ["redis-server", "--appendonly", "yes", "--bind", "127.0.0.1", "--port", "6379"]
    volumes:
      - /var/lib/nexus/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-h", "127.0.0.1", "-p", "6379", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s

  worker:
    image: ghcr.io/haitovs/nexus:latest
    container_name: nexus-worker
    restart: always
    env_file: .env
    network_mode: host
    depends_on: [redis]
    command: ["python", "-m", "arq", "app.worker.WorkerSettings"]
    healthcheck:
      test: ["CMD", "python", "-c", "import redis; redis.from_url('redis://127.0.0.1:6379').ping()"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    volumes:
      - /var/lib/panel:/var/lib/panel
      - /var/lib/nexus:/var/lib/nexus
      - ./.env:/app/env.live
    environment:
      NEXUS_HOST_ENV_FILE: /app/env.live

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 выше — classic-compose уже содержит Redis и воркер, поэтому полный стек — это тот же файл плюс один сервис 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.

Протоколы и кастомные inbound

NexusPanel не ограничена набором inbound, с которым она поставляется. Любой протокол, который поддерживает сам бинарник Xray, можно добавить как новый inbound и выдать пользователям — без изменения кода и без передеплоя. Это sudo-only workflow через JSON-редактор, а не фиксированный список протоколов.

Не поддерживается вообще: SSH, SlowDNS, ZIVPN и udp-custom — это не протоколы Xray, и добавить их таким способом нельзя, что бы вы ни вставили в конфиг.

Добавление протокола

Откройте модальное окно Core Settings в шапке дашборда (JSON-редактор всего конфига Xray) или вызовите PUT /api/v1/core/config напрямую. Только для sudo-администраторов — не-sudo администраторы не могут редактировать core-конфиг. Списка разрешённых протоколов нет: что принимает бинарник Xray, то принимает и панель.

Отправка нового конфига безопасна по построению:

• Дублирующиеся теги inbound/outbound отклоняются до того, как что-либо записано.
• Кандидат проверяется запуском настоящего бинарника Xray; при отклонении возвращается HTTP 400 с собственным текстом ошибки Xray.
• Предыдущий конфиг сохраняется как соседний файл .prev и восстанавливается автоматически, если ядро не переживает рестарт.
• Ноды перезапускаются поочерёдно (NODE_ROLLING_RESTART_DELAY, по умолчанию 3с между нодами), так что у клиентов всегда есть рабочая нода для переключения.
• Побайтово идентичная отправка — это no-op, рестарта не происходит.

При первом появлении нового тега inbound строка хоста создаётся для него автоматически с адресом {SERVER_IP} — добавлять её вручную не обязательно, хотя обычно вы захотите отредактировать её под свой домен/CDN.

При свежей установке создаётся 8 inbound, все VLESS, на портах 443, 80, 82, 1024, 2008, 2010, 2015, 2016. Любой порт вне этого списка свободен для нового inbound.

Охват уже существующих пользователей

Вот момент, который чаще всего путает:

• Добавление ещё одного inbound протокола, который у пользователей уже есть, автоматически охватывает их всех — пустой список inbounds в прокси пользователя означает «все inbound этого протокола».
• Добавление нового протокола так не работает, потому что каждому пользователю нужна отдельная строка proxy для него. Чтобы добавить его одним вызовом, используйте bulk-эндпоинт ниже.

{
  "tag": "trojan-ws-2020",
  "listen": "0.0.0.0",
  "port": 2020,
  "protocol": "trojan",
  "settings": {
    "clients": []
  },
  "streamSettings": {
    "network": "ws",
    "security": "none",
    "wsSettings": {
      "path": "/",
      "heartbeatPeriod": 20
    },
    "sockopt": {
      "tcpKeepAliveInterval": 20
    }
  },
  "sniffing": {
    "enabled": false,
    "destOverride": ["http", "tls"]
  }
}

Добавьте этот объект в массив inbounds вашего текущего core-конфига (порт 2020 свободен при свежей установке) и сохраните.

# Выдать новый протокол пользователям, у которых его ещё нет
curl -X POST /api/v1/users/bulk/update \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["alice","bob"],"add_proxies":["trojan"]}'

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

Пошагово

1. Добавьте inbound (модальное окно Core Settings или PUT /api/v1/core/config) — панель проверяет его настоящим бинарником Xray и перезапускает ноды поочерёдно.
2. Проверьте страницу Hosts — строка хоста для нового тега создана автоматически; отредактируйте адрес/SNI под ваш CDN или домен.
3. Если это совершенно новый протокол, выдайте его существующим пользователям через POST /api/v1/users/bulk/update с add_proxies. Если это просто ещё один inbound протокола, который у них уже есть, этот шаг не нужен — они уже его получили.

Сессии

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

• Активные сессии — просмотр всех подключённых в данный момент устройств
• Сессии по пользователю — смотрите, какие устройства использует конкретный пользователь
• Отключение — принудительно завершайте отдельные сессии
• История 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 со страницы настроек (Pro/Business/Пробный)
• Информация о лицензии — тариф, оставшиеся дни, текущее/максимальное число пользователей/нод

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

Группы пользователей (называемые 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, ОС и версия Python, всего/активных пользователей, активные ноды, общий трафик, аптайм хоста и результат самопроверки целостности. Имя хоста и список ваших серверов не передаются.
• Лицензионный сервер сохраняет это и отвечает {tier, expires_at, latest_version, update_available, docker_image}.
• AUTO_UPDATE по умолчанию выключен — инсталлятор пишет AUTO_UPDATE=false. Когда update_available приходит истинным, панель лишь запоминает это; обновление вы применяете сами командой nexus update. Включить автоматический путь можно через nexus auto-update on — тогда на следующем хартбите панель в фоне выполнит docker compose pull && docker compose up -d --force-recreate.

Тарифы

Четыре публичных тарифа. Именно их вы увидите сегодня в платёжном боте:

Free — $0

Вся панель, на одной ноде, навсегда — без карты, без отсчёта дней триала. Та же задача, что бесплатно решают Marzban или Remnawave, только под управлением NexusPanel. Проверено на живой панели: вторая нода отклоняется с License limit reached (1/1 nodes), второй админ — так же на 1/1, а /api/v1/defender/* отвечает 403. Пользователи не ограничены — продавайте сколько угодно на этой одной ноде. Пункт IP-Defender вообще не появляется в боковом меню на Free — он не показан-и-заблокирован, его там просто нет.

Пробный — Pro Trial

Без банковской карты, без регистрации — откройте Telegram-бот и введите /start. Вы получите бесплатный 14-дневный Pro-триал: пользователи и ноды без ограничений, карта не нужна. Одну возможность Pro он всё же не даёт: лимит админов остаётся равным 1, и создание второго аккаунта отклоняется с License admin limit reached (1/1 admins) — проверено на живой триальной панели. Полный доступ к дашборду, включая IP-Defender. Достаточно, чтобы оценить на реальном трафике перед выбором между Pro и Business.

Pro — $30/месяц

Неограниченное число нод, пользователей и админов, плюс IP-Defender: проверено — 200 на каждом маршруте /api/v1/defender/* на живой панели Pro. Также включено:

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

White-label брендинг (свой домен панели + логотип) — не привилегия Pro: это одна общая настройка, которая уже есть у всех тарифов, включая Free.

Business — $60/месяц

Всё из Pro, плюс бот для реселлеров, через который продают ваши реселлеры: проверено — /api/v1/seller/* подключён и отвечает на живой панели Business, и 404 — маршрута просто нет, а не ошибка доступа — на любом другом тарифе. Это тариф именно для реселлинга: реселлеры технически являются строками таблицы админов, поэтому Business также не имеет ограничения на число админов.

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

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

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

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

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

Обновление уже работающей панели

Покупка выдаёт новые LICENSE_ID и CLIENT_ID — покупка Pro или Business взамен Free или Пробного не продлевает уже имеющуюся у вас лицензию. Если у вас уже работает панель, не запускайте установщик заново — он ставится поверх работающей панели, это не путь обновления. Правильные шаги:

nexus edit-env      # укажите новые LICENSE_ID и CLIENT_ID
nexus restart

nexus edit-env открывает файл .env панели для правки LICENSE_ID и CLIENT_ID; nexus restart подхватывает новую лицензию на следующем heartbeat.

Применение лимитов 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 пользователей и создаёт аккаунт автоматически после оплаты.

Бот для реселлеров

Бот для реселлеров — это то, через что реально продают ваши реселлеры: Telegram-бот для модели реселлинга, а не для конечных пользователей. Это отдельный сервис, свой контейнер, не часть образа панели. Поэтому его API-поверхность на других тарифах просто отсутствует, а не отвечает ошибкой доступа: /api/v1/seller/* подключается к панели только когда лицензия явно называет функцию seller.

Проверенная рабочая поверхность:

• Баланс и леджер реселлера — у каждого реселлера есть баланс и текущий журнал пополнений и трат.
• Жизненный цикл конфигов — выдача, продление и удаление клиентских конфигов прямо из бота.
• Тарифы — планы, которые продают реселлеры; цены и управление ими — на вашей стороне.
• Способы пополнения — как реселлеры пополняют баланс (ручное подтверждение, крипта и другие настроенные каналы) и просмотр ожидающих пополнений.

Бот обращается к вашей панели через тот же API реселлинга (PANEL_API_URL + логин админа панели) и требует собственный SELLER_BOT_TOKEN от BotFather. Это отдельный деплой от самой панели — см. seller_bot/ в репозитории, если разворачиваете его; эта страница не даёт пошаговую инструкцию по настройке контейнера — это операционная деталь, зависящая от конкретного развёртывания.

Ноды

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

Нода — это удалённый сервер с ядром 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.

Запрос выше работает как есть на установке по умолчанию: капча при входе выключена (CAPTCHA_PROVIDER=disabled), потому что это защита только для дашборда, а её включение заставляет любой скриптовый логин получать 400 Captcha required. От перебора уже защищает блокировка после неудачных попыток (LOGIN_LOCKOUT_THRESHOLD / LOGIN_LOCKOUT_DURATION_MINUTES), а не LOGIN_RATE_LIMIT, который не читается кодом. Если вы всё же включите CAPTCHA_PROVIDER, скрипты должны сначала вызвать GET /api/v1/admin/captcha и вернуть X-Captcha-Id и X-Captcha-Answer.

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

Создать нового пользователя с протоколами, лимитом трафика, сроком действия, лимитом устройств и лимитом 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/месяц каждый). Этот канал ничего не разворачивает за вас — он лишь распределяет пользователей по хостам, которые у вас уже работают, поэтому каждый участник пула должен быть готов до того, как вы пропишете его здесь.

Участник пула — это обычный nginx-фронт с TLS: свой домен, свой сертификат Let's Encrypt и один блок location /sub/, который проксирует на панель, подставляя домен самой панели в заголовок Host — панель сверяет его с XRAY_SUBSCRIPTION_URL_PREFIX, чтобы разобрать токен. Всё остальное отдаёт 404, так что наружу открыт только подписочный путь.

В панели

Настройки → Каналы доставки подписок → 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 нативно.

Ограничение по лицензии: создание и управление inbound-ами hy2 требует функции hysteria2_manage — Pro, Business и 14-дневный Pro Trial (он выдаётся с полным набором функций Pro); легаси-лицензии Standard/Growth тоже её имеют. На Free этой функции нет. Панель без лицензии откатывается к базовому набору и видит записи подписки hy2, но не может управлять inbound-ами. Выдача hy2 пользователям никогда не ограничивается.

Добавить 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"

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

Блокировка входа

Эндпоинт входа защищён блокировкой по IP, она включена по умолчанию:

LOGIN_LOCKOUT_THRESHOLD=10
LOGIN_LOCKOUT_DURATION_MINUTES=30

# Не подключён: не читается кодом, задавать его бессмысленно.
LOGIN_RATE_LIMIT="10/minute"

После 10 неудачных попыток с одного IP клиента этот IP блокируется на POST /api/v1/admin/token на 30 минут. Блокировка хранится в памяти (в рамках процесса) и сбрасывается при перезапуске сервера.

LOGIN_RATE_LIMIT показан выше только потому, что он есть в поставляемых файлах .env. Он не реализован — его никто не читает, и он не ограничивает число попыток входа в минуту. Настраивайте вместо него LOGIN_LOCKOUT_THRESHOLD.

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.