← H1

H1Cloud VLESS · Общий гайд

Установка и настройка VLESS-сервера на Pterodactyl с нуля.

guide · ru

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

Скрипт скачивает Xray, поднимает Reality+Vision на выделенном TCP-порту, WS на отдельном порту, HTTP API и subscription-сервер. Всё работает на Pterodactyl без рута.

1. Что нужно

Pterodactyl-сервер с bash/python и доменом, привязанным через Pterodactyl Domains.

bash В любом bash-egg'е (например, generic Linux).
curl Нужен чтобы скачать Xray и сам скрипт.
python3 Используется для JSON, генерации ключей, API/sub серверов.
домен Публичный домен для WS и Reality-ссылок. Subscription может использовать авто-определённый публичный host.
Без рута. Скрипт не использует sudo и не пишет в системные пути. Биндимся только на порты, выделенные птеродактилем твоему серверу.

2. Установка

Одна команда в консоль птеродактиля.

  1. 1

    Скачай и запусти

    В консоли сервера выполни:

    curl -fsSL https://raw.githubusercontent.com/h1gurodev/h1cloud-vless/refs/heads/main/main.sh -o start.sh && chmod +x start.sh && bash start.sh

    Скрипт скачает Xray-linux-64.zip, распакует xray и подготовит базовый WS-конфиг. Ключи Reality (x25519) генерятся при включении vpn reality PORT.

  2. 2

    Сделай авто-запуск

    При запуске сервера нажми 3 и введи:

    bash start.sh
END

    Теперь после рестарта сервера всё поднимется само.

3. Первый запуск и домен

При первом старте скрипт попросит ввести домен.

  1. 1

    Привяжи домен в Pterodactyl Domains

    В панели Pterodactyl зайди в раздел Domains и привяжи поддомен к своему серверу (это даст тебе TLS-сертификат и проксирование на твой порт).

  2. 2

    Введи домен в консоли

    При первом запуске скрипт выведет:

    Enter domain connected in Pterodactyl Domains:

    Введи домен без https://, например vpn.example.com. Домен сохранится в domain.txt.

  3. 3

    Проверь, что всё поднялось

    После запуска ты увидишь шапку h1cloud vless is ready с портами и доменом. Если что-то не запустилось — ищи ошибку выше.

Поменять домен потом: 
vpn domain vpn.example.com

4. Команды vpn

Печатай прямо в консоли сервера. Можно также запускать как ./main.sh vpn ....

CREATE vpn add NAME DAYS

Создать клиента на DAYS дней. Сразу выведет VLESS-ссылки: WS всегда, Reality и subscription только если они включены.

vpn add test 30
vpn add test 30 100 3

Optional: after days pass GB quota and device limit. Example above means 100 GB and 3 devices.

LIMIT vpn limit NAME ...

Set or change traffic quota and HWID/device limit for an existing client. Traffic is counted by Xray Stats; devices are counted when the client app sends HWID/device-id to subscription.

vpn limit test 100 3
vpn limit test traffic 50
vpn limit test devices 2
vpn limit test reset-traffic
vpn limit test reset-devices
vpn limit test off
LIST vpn list

Список активных клиентов с UUID, датой окончания и оставшимся временем.

INFO vpn info NAME

Полная инфа по клиенту + готовые ссылки.

LINK vpn link NAME

Только ссылки клиента: WS всегда, Reality и subscription при активной настройке.

RENEW vpn renew NAME DAYS

Продлить клиента на DAYS дней (прибавляется к текущей дате истечения).

vpn renew test 15
DEL vpn del NAME

Удалить клиента.

BAN vpn ban NAME [REASON]

Disable client without deleting the row. The banned client is removed from Xray config, key.txt and public subscription responses.

vpn ban test chargeback
vpn unban test
KEYS vpn keys

Вывести key.txt: все клиенты с ссылками + последние логи.

LOGS vpn logs [COUNT]

Показать последние COUNT (по умолчанию 50) строк лога действий.

DOMAIN vpn domain DOMAIN

Сменить публичный домен. После смены все ссылки пересоберутся.

PORTS vpn ports

Показать, какие локальные и публичные порты сейчас нужны серверу. На свежей установке автоматически стартуют WS, API и subscription.

UPDATE vpn update

Download latest main.sh from the saved update URL, validate it with bash -n, back up the current script and replace it. Auto-update is enabled by default and checks once per hour.

vpn version
vpn update
vpn update url https://raw.githubusercontent.com/h1gurodev/h1cloud-vless/refs/heads/main/main.sh
vpn update auto on
vpn doctor fix
SSL vpn ssl on/off/status

HTTPS для API и subscription. Включён по умолчанию: self-signed сертификат генерируется автоматически. Свой сертификат: vpn ssl cert CERT_PEM KEY_PEM, перевыпуск self-signed: vpn ssl renew.

vpn ssl status
vpn ssl cert /path/fullchain.pem /path/privkey.pem
vpn ssl off
REALITY vpn reality PORT [PUBLIC_PORT] [SNI] [DEST]

Настроить Reality. PORT — выделенный TCP-порт xray, PUBLIC_PORT — внешний порт, если он отличается, SNI — домен-маска (по умолчанию proxy11.h1guro.ovh). Отключение: vpn reality off.

vpn reality 30001 proxy11.h1guro.ovh
RESTART vpn restart

Перезапустить xray (пересобрать конфиг). Делается автоматически при add/del/renew.

STOP vpn stop

Остановить сервер (xray + API + sub).

5. HTTP API и Subscription

Опциональные сервисы. Можно поднять оба, или только один, или ни одного.

HTTP API

Поднимает HTTP-сервер для управления клиентами через JSON.

vpn api 25626
vpn api token
vpn api status
vpn api stop

Подробное описание методов — в API Docs.

Subscription

HTTP-сервер для клиентских приложений (v2rayN, NekoBox и т.д.). Отдаёт base64-список ссылок по токену.

vpn sub 25627
vpn sub token
vpn sub status
vpn sub name Germany-VPN
vpn sub stop

URL: https://IP:PORT/sub/CLIENT_UUID

Порты в Pterodactyl. Свежий сервер сам стартует Reality, WS, API и subscription. По умолчанию Reality берёт SERVER_PORT + 1, API — SERVER_PORT + 2, subscription — SERVER_PORT + 3. В Reality-ссылке адресом будет домен из domain.txt, а маскировка идёт через proxy11.h1guro.ovh:443. Если аллокации не подряд, задай API_PORT и SUB_PORT в переменных сервера или вручную выполни vpn api PORT / vpn sub PORT.
SSL. API и subscription работают по HTTPS. Self-signed сертификат генерируется автоматически при первом запуске; свой сертификат ставится через vpn ssl cert CERT_PEM KEY_PEM. Выключить можно командой vpn ssl off. Для управления из браузера открывай встроенную панель API: https://IP:API_PORT/panel (браузер предупредит о self-signed сертификате — это нормально).
Авто-подключение нод. На мастере возьми join token: vpn join-token. На новой локации выполни vpn join https://MASTER_IP:API_PORT/api JOIN_TOKEN Germany. Нода сама сохранит upstream, а мастер сам добавит её в peers как /sub/{uuid}/local.
Где создавать клиентов. Если нода подключена к master через federation upstream, команды vpn add, vpn renew, vpn del и vpn ban автоматически пишут в master API. После этого нода сразу синхронизирует базу обратно, поэтому общая subscription-ссылка получает ключи всех peers, а не только текущего сервера.
  1. 1

    Мастер хранит пользователей

    Выбери один сервер главным. На нём создаются клиенты, продления и удаления. Проверь API и subscription, затем сохрани токены.

    vpn node Master
vpn api status
vpn api token
vpn sub status
vpn sub token
  2. 2

    Локации тянут базу с мастера

    На каждом сервере-локации задай имя, подключи upstream к мастер API и сделай первый ручной sync.

    vpn node Germany
vpn federation upstream https://MASTER_IP:API_PORT/api MASTER_API_TOKEN
vpn federation sync

    После этого нода будет сама обновлять users.json и перезапускать Xray при изменениях.

  3. 3

    Мастер собирает ссылки всех локаций

    На мастере добавь каждую ноду как peer. В URL оставляй {uuid} и используй /local.

    vpn peer add de https://DE_IP:DE_SUB_PORT/sub/{uuid}/local
vpn peer add nl https://NL_IP:NL_SUB_PORT/sub/{uuid}/local
vpn peer list
  4. 4

    Клиент получает одну подписку

    Создай клиента на мастере и отдай ему только мастер-ссылку. Внутри будут WS/Reality ссылки всех подключённых локаций. Клиентский кабинет: /sub/CLIENT_UUID/page, Clash: /sub/CLIENT_UUID/clash, sing-box: /sub/CLIENT_UUID/sing-box.

    vpn add lol123 30
https://MASTER_IP:MASTER_SUB_PORT/sub/CLIENT_UUID
Как проверить. Открой https://MASTER_IP:MASTER_SUB_PORT/sub/CLIENT_UUID/raw. В ответе должны быть ссылки с названиями нод, например Master WS, Germany Reality, Netherlands WS.

6. Reality vs WS — что выбрать

Reality включён по умолчанию, использует домен из domain.txt и выделенный TCP-порт. WS остаётся доступным на отдельном публичном порту.

WS

WebSocket inbound от Xray. WS использует отдельный публичный порт и по умолчанию генерируется без TLS.

  • Порт — PUBLIC_PORT, по умолчанию основной SERVER_PORT
  • Путь /xray
  • Для TLS-режима нужен отдельный корректно проксируемый HTTPS-порт

Reality + Vision

Современный TLS-стелс от Xray. Маскируется под proxy11.h1guro.ovh по умолчанию, не требует своего TLS-сертификата.

  • Адрес подключения — домен и выделенный TCP-порт, например test1.safetunn.shop:27207
  • Flow xtls-rprx-vision
  • Лучше для обхода блокировок

7. Manual add

Manual add во встроенной панели API (https://IP:API_PORT/panel) конвертирует обычную WS VLESS-ссылку в CDN-вариант без изменения UUID и path.

Как пользоваться

Открой встроенную панель API (https://IP:API_PORT/panel), нажми Manual add у клиента или вставь исходную ссылку вручную.

vless://UUID@de.safetunn.shop:25629?security=&type=ws&path=/xray&host=de.safetunn.shop&encryption=none#Germany WS

Что меняется

  • Адрес подключения: cdn.de.h1cloud.su:443
  • security=tls
  • sni и host: домен, который выдал CDN, например top2355543541.mwscdn.ru
  • Тег ссылки сохраняется и получает суффикс CDN
Пример результата. 
vless://UUID@cdn.gateway.h1cloud.su:443?security=tls&sni=top2355543541.mwscdn.ru&type=ws&path=%2Fh1cdn%2Fnl1%2Fxray&host=top2355543541.mwscdn.ru&encryption=none#Germany-WS-CDN
Global command mode. Manual add in the built-in API panel is only a one-off converter. To add this CDN variant to every current and future client automatically, run: 
vpn cdn cdn.gateway.h1cloud.su top2355543541.mwscdn.ru 443 CDN /h1cdn/nl1/xray
vpn sub name Germany-VPN
After that vpn link NAME, key.txt, API clients and /sub/UUID include ws-cdn. The path is encoded in the VLESS link and can point to a central Nginx gateway route. Disable it with vpn cdn off.
XHTTP-CDN mode. For CDN routes that cannot proxy WebSocket reliably, switch the node to XHTTP and add a public gateway path: 
vpn xhttp on
vpn cdn xhttp proxy.h1cloud.su proxy.h1cloud.su 443 CDN /api/v1/ch1/sync
vpn restart
vpn link test
The local Xray origin listens on the allocated main port with path /api/v1/sync. The public CDN/gateway link uses the path you pass to vpn cdn xhttp, for example /api/v1/ch1/sync. Return to old WS mode with vpn xhttp off.

8. Файлы в рабочей папке

Скрипт хранит всё в текущей папке сервера. Бэкап делается копированием этих файлов.

users.jsonСписок клиентов (имя, UUID, expires_at).
node_name.txtНазвание локации/ноды для тегов в клиентах.
peers.txtRemote subscription URLs других нод для общей подписки.
nodes.jsonRegistry нод, которые подключились через vpn join.
join_token.txtТокен для авто-регистрации нод через vpn join.
upstream_api_url.txtAPI мастера, откуда нода тянет общую базу пользователей.
key.txtСгенерированные VLESS-ссылки для всех клиентов.
logs.txtЖурнал действий (create/delete/renew/api).
api_token.txtТокен для HTTP API. Не публикуй.
sub_token.txtLegacy-токен для старых ссылок /sub/NAME?token=.... Новые ссылки используют /sub/UUID.
reality_enabled.txtФлаг включения Reality: 1 или 0.
reality_private_key.txtПриватный ключ Reality. Не публикуй.
reality_public_key.txtПубличный ключ Reality (pbk в ссылке).
reality_short_id.txtReality short id (sid в ссылке).
domain.txtПубличный домен.
config.jsonСгенерированный конфиг Xray.
tls_enabled.txtФлаг HTTPS для API/subscription: 1 или 0.
tls_cert.pem / tls_key.pemTLS-сертификат и ключ API/subscription. Ключ не публикуй.

9. Частые ошибки

Если что-то не работает — начни отсюда.

ERR cannot generate reality x25519 keys

Xray не смог сгенерить ключи. Обычно — устаревший парсер на новом формате (см. XTLS/Xray-core#5159). Скрипт уже умеет три формата: Private key:, PrivateKey: + Password:, и Password (PublicKey):. Если ошибка всё ещё — обнови скрипт до последней версии.

ERR пустые строки и текст без \n не видно в консоли

Известный баг Pterodactyl wings (panel#4782): строки без содержимого дропаются. В скрипте всё уже починено через blank() + PYTHONUNBUFFERED=1 + python3 -u.

ERR xray failed to start

Чаще всего — конфликт портов: Reality/API/sub поставили на основной WS-порт, или порт не выделен в Pterodactyl. Проверь текущую схему и выключи лишнее:

vpn ports
vpn reality off
vpn restart
ERR клиент не подключается через WS

Проверь, что публичный WS-порт выделен серверу в Pterodactyl и совпадает с портом в ссылке. В дефолтной схеме WS не использует TLS.

ERR api failed to start

Порт не выделен в Pterodactyl или уже занят другим сервисом. Проверь схему и запусти API на свободном allocation:

vpn ports
vpn api 25626