Провайдерам · In English

V2pn для провайдеров: ваша вкладка в V2pn

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

Вкладка V2pn — обычный V2pn: все серверы человека, в том числе ваши, и ничего ни от одного провайдера. У человека, который не пришёл ни от одного провайдера, вкладок нет вовсе, а подписка провайдера для него — просто подписка: работают стандартные заголовки и заголовки Happ, INCY и v2RayTun, и больше ничего (ни оформления, ни кнопок, ни закрытых настроек, ни проверенных файлов, ни запросов к API).

Человек пришёл от вас, если:

  • он скачал V2pn с вашей страницы или поставил его вашей командой (раздел 12): у этой копии V2pn рядом с программой лежит v2pn-partner.txt с вашим id, и ваша вкладка остаётся, пока лежит файл;
  • или он вошёл через вас по коду (раздел 9): V2pn запоминает это в своих настройках, а ваша вкладка пропадает, когда человек удаляет последнюю подписку с ваших доменов.

Если человек сам вставил ссылку на вашу подписку, вкладки нет: это обычная подписка.

Партнёров ведёт владелец V2pn: оформление каждого партнёра лежит в репозитории V2pn, владелец его проверяет и публикует вместе с релизами V2pn, а с ним и пакеты партнёра (V2pn-<id>-windows-x64.zip и другие: сам V2pn с вашей меткой). Провайдеру не нужны ни ключи, ни сертификаты, ни свой хостинг: он присылает владельцу логотипы и цвета.

Что получает провайдер

Любая панельПартнёр, в своей вкладке
Название подписки, трафик, срок, объявление, кнопки поддержки и кабинета (стандартные заголовки)дада
Баннеры, напоминание о продлении, подключение при запуске, порядок серверов, обновление и проверка при запуске (заголовки Happ, INCY и v2RayTun, раздел 7)дада
Вкладка в V2pn и страница загрузки, которая её приносит (раздел 12)нетда
Ссылки v2pn://add с сайта или из бота провайдерадада, и в вашей вкладке V2pn говорит, что провайдер — партнёр V2pn
Переезд подписки на другой ваш домен (new-url, new-domain)нетда
Знак провайдера на его подписке в списке V2pnнетда
«Акцент»: ваш логотип, ваш цвет, карточка вашей подписки (раздел 5)нетда, у каждого партнёра
«Сцена»: ваш фон за панелью подключения и ваш тариф на нём (раздел 5)нетда, если в теме есть фон
Тариф, состояние серверов по вашей проверке, устройства, сбоинетс правом account и API (раздел 9)
Вход по коду: человек подтверждает вход в вашем боте, и V2pn сам добавляет его подписку, ничего не копируянетс API и "login": true (раздел 9)
Описание серверов (группы, страны, назначение) и до четырёх своих кнопокнетс правом actions (раздел 3)
Закрытые настройки: адреса серверов скрыты, ссылку нельзя переслатьнетс правом lock, после проверки (раздел 4)
Свои маршруты, фрагментация, дополнительные серверы и балансировканетс правами routing, transport, core, после проверки каждого файла (раздел 6)

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

  1. Владелец V2pn держит каждого партнёра в папке partners/<id>/ репозитория V2pn: listing.json (кто партнёр, домены его подписки, права, до какого числа) и пакет (partner.json с картинками).
  2. С каждым релизом или отдельно между релизами владелец публикует их командой tools/partner.cs publish: partner-index.json — список всех партнёров, подписанный корневым ключом партнёров V2pn, и partner-<id>.zip на каждого партнёра. С релизом tools/partner-packages.cs ещё и собирает пакеты каждого партнёра из подписанных пакетов V2pn: V2pn-<id>-windows-x64.zip, V2pn-<id>-windows-arm64.zip, V2pn-<id>-macos-arm64.zip и V2pn-<id>-macos-x64.zip — те же файлы плюс v2pn-partner.txt с вашим id (на macOS внутри V2pn.app/Contents/MacOS). Всё это лежит рядом с установщиками V2pn, на той же странице релизов, откуда V2pn берёт обновления.
  3. V2pn берёт partner-index.json только у человека, который пришёл от партнёра: при запуске и дальше не чаще раза в шесть часов, и проверяет подпись ключами, встроенными в приложение. Для остальных он ничего не спрашивает, кроме случая, когда человек открывает «Войти через провайдера»: для этого нужен список провайдеров.
  4. В вашей вкладке подписка ваша, если домен её ссылки есть среди ваших доменов (example.com или любой адрес под *.example.com). Заголовок для этого не нужен. Во вкладке V2pn и во вкладке другого партнёра ваши подписки — обычные подписки.
  5. Человеку, который пришёл от вас, V2pn сразу скачивает ваш zip, ещё до того, как появилась ваша подписка, сверяет размер и SHA-256 с partner-index.json, распаковывает только простые файлы картинок и JSON в пределах лимитов и сверяет каждый файл с partner.json. Пакет, который не прошёл проверку, не используется: V2pn оставляет последний хороший или не показывает вашу вкладку, пока не придёт хороший, а серверы в любом случае работают как обычно.
  6. Вкладки переключаются сразу, по щелчку, и V2pn открывается на той, где человек остановился. Копия с вашей меткой открывается на вашей вкладке, пока человек не выберет другую. Ctrl+Tab и Ctrl+Shift+Tab перебирают вкладки; в мини-окне на вашей вкладке только знак, а название — во всплывающей подсказке.
  7. Всё ваше действует только в вашей вкладке и только для ваших подписок: оформление, карточка, кнопки, закрытые настройки, маршруты, настройки подключения и запросы к API. Переключение вкладок не трогает идущее подключение; ваши настройки подключения действуют со следующего подключения.
  8. Копия с вашей меткой — обычный V2pn в своей обычной папке, с настройками V2pn и его запуском вместе с системой. Она обновляется с того же подписанного релиза и сохраняет v2pn-partner.txt при каждом обновлении.

Как стать партнёром

Пришлите владельцу V2pn:

  • имя, которое видят люди, до 40 символов, без «V2pn»;
  • домены, на которых ваши ссылки подписки (example.com, *.example.com);
  • широкий логотип для тёмного фона и для светлого (PNG с прозрачностью, от 2:1 до 8:1, высота 32–256 px; подойдёт 340×96);
  • квадратный знак для карточки подписки (64–512 px, прозрачный фон; подойдёт 128×128);
  • цвет бренда (#RRGGBB);
  • если нужна «Сцена»: от двух до четырёх цветов градиента или картинку (сторона 640–3200 px, не шире 3:1);
  • если нужны: кнопки и описание серверов (раздел 3), адрес вашего API (раздел 9), ссылки на кабинет и поддержку;
  • как с вами связаться.

Всё это можно собрать на странице «Собрать оформление»: на ней видно окно V2pn в вашем оформлении («Акцент» и «Сцена», светлое и тёмное, три размера окна) и то, что скажет partner-check, а готовые partner.json и listing.json скачиваются оттуда. Страница ничего никуда не отправляет: файлы и картинки вы пришлёте сами.

Что делает владелец: собирает из этого partners/<id>/, проверяет командой tools/partner-check.cs partners/<id>, решает, какие права дать, и публикует со следующим релизом или сразу, отдельно. Как оформление доходит до людей, сказано в разделе 10.

1. listing.json

Пишет владелец, по одному на партнёра; в таком виде он не публикуется.

{
  "id": "kestrel",
  "name": "Kestrel",
  "domains": ["kestrel.example", "*.kestrel.example"],
  "grants": ["account", "actions"],
  "until": "2027-11-16",
  "contact": "@kestrel_admin"
}
Поле
idимя папки: строчные буквы, цифры и дефис, 2–32 символа
nameимя, которое видят люди, до 40 символов, без «V2pn»
domainsдомены подписки: example.com — сам этот адрес, *.example.com — все адреса под ним (кроме самого домена). Нужны хотя бы имя и зона, поэтому *.com невозможен. Двум партнёрам один домен не дают
grantsaccount (API), actions (кнопки и описание серверов), lock (закрытые настройки), routing, transport, core (проверенные файлы). edition — само оформление — есть у каждого партнёра
untilпоследний день партнёрства; после него оформление пропадает
contactкак владелец связывается с провайдером; остаётся в репозитории и никогда не публикуется

2. Пакет

В partners/<id>/ лежат partner.json и его файлы:

partners/kestrel/
  listing.json       владельца
  partner.json       оформление
  logo-light.png     картинки, названные в partner.json
  logo-dark.png
  mark.png
  routing.json       необязательно, после проверки (раздел 6)
  transport.json
  core.json

partner.json (JSON-схема):

{
  "schema": 1,
  "id": "kestrel",
  "name": "Kestrel",
  "brand": {
    "accent": "#2F7BFF",
    "logo": "logo-light.png",
    "logoOnLight": "logo-dark.png",
    "mark": "mark.png"
  },
  "theme": {
    "palette": { "brand": ["#2F7BFF"] },
    "background": { "type": "gradient", "colors": ["#1E3A8A", "#2F7BFF"] }
  },
  "links": { "cabinet": "https://kestrel.example/cabinet", "support": "https://t.me/kestrel_support" },
  "api": "https://kestrel.example/v2pn/api/",
  "assets": [
    { "name": "logo-light.png", "size": 10913, "sha256": "f602…cf08" }
  ]
}
ПолеЧто делает V2pn
idдолжен совпадать с именем папки и с listing.json
nameпоказывается в окне подписки, на карточке и в пояснениях; не длиннее 40 символов, без «V2pn»
brand.accent#RRGGBB; цвет бренда, если в theme.palette.brand его нет
brand.logo, brand.logoOnLightширокий логотип для тёмного и светлого фона («Сцена»)
brand.markквадратный знак на вашей вкладке, на карточке подписки и в списке V2pn
themeцвет бренда и фон «Сцены» (раздел 5)
links.cabinet, links.supportссылки «Продлить» и «Поддержка» на карточке, если их нет в заголовках подписки
apiбазовый адрес вашего API (с правом account, на домене из списка)
logintrue: V2pn предлагает войти через вас по коду (раздел 9). Нужен api
assetsвсе картинки и проверенные файлы с размером и SHA-256; заполняет tools/partner.cs pack partners/<id>

Картинку, которая не подходит под своё место, V2pn там не показывает (будет имя или ничего), а tools/partner-check.cs говорит, какую и почему; остальной пакет работает.

Ограничения: partner.json до 64 КБ; не больше 8 картинок, только PNG, WebP или JPEG, до 1 МБ каждая; кроме картинок — только routing.json, transport.json и core.json, до 64 КБ каждый. Имена файлов простые: латинские буквы, цифры, - и _, одно расширение, без папок. publish не примет папку с любым другим файлом или partner.json, в assets которого не те файлы, что лежат в папке.

Чего пакет не задаёт, и это намеренно: раскладку, размеры, отступы, шрифт, скругления и цвета интерфейса. V2pn сам раскладывает окно и выводит все цвета светлой и тёмной темы из цвета бренда, проверяя, что текст читается (WCAG AA, 4,5:1). Эти рамки и держат оформление рабочим при любом размере окна, в светлой и тёмной теме, у любого провайдера.

Поля прежних пакетов V2pn читает без ошибки и не использует: edition (variants, default, art) и в theme — connect, window, template, font, corners, density, blocks, art, palette.tone. tools/partner-check.cs их перечисляет.

3. Серверы и кнопки

С правом actions пакет описывает серверы подписки и задаёт до четырёх своих кнопок. Кнопка — это подпись, значок и действие из каталога V2pn: своей логики в приложении у провайдера нет. Решение о сервере принимает либо V2pn по своим замерам, либо ваш API.

Описание серверов

"servers": [
  { "name": "🇩🇪 Германия 2", "group": "Основные", "country": "DE", "city": "Берлин",
    "purpose": ["youtube"], "priority": 5, "note": "Быстрый канал до Европы" },
  { "host": "nl1.example.com", "group": "Для игр", "purpose": ["games"] },
  { "name": "Резерв", "hidden": true }
]
ПолеЧто делает V2pn
name или hostнаходит сервер вашей подписки: по точному имени (как в ссылке) или по адресу; хотя бы одно из двух обязательно
groupдо 24 символов; заголовок в списке серверов подписки. Группы идут в том порядке, в каком впервые встречаются в пакете, серверы без группы — в конце, под «Другие»
countryкод ISO 3166 из двух букв: флаг и место на карте вместо догадки по имени
cityдо 32 символов, строкой под именем
purposeдля чего сервер: youtube, games, mobile, whitelist, streaming, ai, torrents. V2pn пишет это словами («YouTube», «Игры», «Мобильный интернет», «Белые списки», «Стриминг», «Нейросети», «Торренты») меткой на строке сервера. Другие значения пропускает
priorityцелое от −1000 до 1000; при равных замерах выбирается сервер с большим
hiddentrue: сервер не показывается и не предлагается. Подключиться к нему можно только по рекомендации вашего API
noteдо 60 символов, строкой под именем

Поле длиннее предела V2pn не показывает (обрезанной строки не будет), а partner-check скажет какое. Записей не больше 300.

Кнопки

"actions": [
  { "id": "fast",   "label": "Самый быстрый",    "icon": "bolt",   "do": "connect.best", "strategy": "ping" },
  { "id": "stable", "label": "Самый стабильный", "icon": "shield", "do": "connect.best", "strategy": "stable", "scope": { "group": "main" } },
  { "id": "yt",     "label": "Для YouTube",      "icon": "play",   "do": "connect.recommend", "purpose": "youtube" },
  { "id": "renew",  "label": "Продлить",         "icon": "card",   "do": "open.renew" }
]

id — строчные буквы, цифры, - и _, до 32 символов; label — до 24 символов; icon — один из значков V2pn: bolt, shield, play, game, card, chat, globe, star, refresh, check, info, gift (с другим кнопка будет без значка).

doЧто делает V2pn
connect.bestпроверяет серверы и подключает к лучшему по strategy: ping — наименьшая задержка сейчас; stable — больше всего ответов за последние 10 проверок V2pn, потом наименьшая медиана, потом наименьший разброс; load — наименьшая нагрузка из GET servers (без чисел нагрузки — по пингу). scope сужает выбор: group, purpose или список servers (имена или адреса)
connect.recommendспрашивает GET <api>recommend?purpose=<purpose> и подключает к первому серверу из ответа, который есть в подписке и отвечает. Если API не ответил или никто из названных не отвечает — к самому быстрому серверу с этим назначением. Нужен API
connect.serverк серверу server (имя или адрес)
connect.groupк самому быстрому серверу группы group
open.cabinet, open.renew, open.supportоткрывает кабинет, продление или поддержку: ссылки из заголовков подписки, иначе links пакета
open.linkоткрывает url: https на домене из списка партнёра или t.me, либо tg:
subscription.updateобновляет подписку
check.servicesпроверяет через текущее подключение, открываются ли YouTube, Telegram и ChatGPT, и показывает результат
info.cardпоказывает карточку из GET <api>card?id=<id кнопки> в рамке с вашим именем. Нужен API

Кнопки — стеклянные капсулы под панелью подключения в вашей вкладке; в узком окне они идут одной строкой с прокруткой. На экране не больше четырёх кнопок: V2pn берёт первые четыре, которые может выполнить, а неизвестное действие, кнопку без нужного поля или кнопку, которой нужен API, когда его нет, пропускает. После подключения V2pn пишет, куда подключился и почему: «Германия 2 — самый быстрый», «Нидерланды — по проверке <провайдер>». Повторное нажатие той же кнопки раньше чем через 3 секунды ничего не делает.

4. Закрытые настройки

С правом lock провайдер может закрыть настройки своей подписки, как в Happ и INCY: заголовок hide-settings: 1 или "lock": true в пакете. Владелец даёт это право после проверки: объясните, от чего вы защищаете серверы. Без права заголовки и поле ничего не делают, иначе любая подписка могла бы спрятать от человека, куда идёт его трафик.

Для серверов этой подписки V2pn тогда:

  • не показывает адреса, порты и ключи (в списке, таблице, карточке подключения, поиске по адресу);
  • не открывает редактор сервера, не даёт поделиться им, скопировать ссылку, показать QR-код, выгрузить конфиг или перенести сервер в другую подписку;
  • не кладёт эти серверы в резервную копию (после восстановления их вернёт обновление подписки);
  • не даёт менять ссылку подписки, её User-Agent, заголовки и конвертацию и держит ваши значения подключения при запуске и порядка серверов;
  • пишет на карточке подписки и в её окне: «Настройки закрыл провайдер <имя>».

hide-url: 1 (тоже только с правом lock) прячет и саму ссылку подписки.

Что у человека остаётся всегда: подключиться и отключиться, выбрать любой сервер подписки, удалить подписку, перейти во вкладку V2pn, свои серверы и маршруты рядом с вашими, kill switch и обновления V2pn. Во вкладке V2pn ничего не закрыто: там ваша подписка обычная.

Защита не абсолютная: конфиг ядра лежит на диске, и опытный человек его прочитает. Цель та же, что у Happ: чтобы адреса нельзя было переслать в два нажатия.

5. Оформление: «Акцент» и «Сцена»

У вашей вкладки один вид, в двух формах. Во вкладке V2pn нет ни той, ни другой:

ФормаКогдаЧто это
«Акцент»всегдараскладка самого V2pn (боковая панель, стеклянная панель подключения, карточка состояния, карта мира за ними) в вашем бренде: ваш знак и название на вашей вкладке в заголовке окна, кнопка подключения в вашем цвете с чёрной или белой подписью — какая читается; карточка вашей подписки в боковой панели (знак, имя, тариф, сколько дней осталось, устройства, полоса трафика, баннер, «Продлить» и «Поддержка» в вашем цвете); ваши кнопки под панелью подключения
«Сцена»если theme.background — градиент или картинка«Акцент», где вместо карты мира ваш фон, а тариф стоит на нём, а не на карточке в боковой панели: под панелью подключения и вашими кнопками — ваш логотип (в широком окне), крупно дни, тариф, трафик, баннер, «Продлить» и «Поддержка». Где тарифу на сцене не хватает места, как в мини-окне, ваш фон стоит за панелью подключения, а тариф остаётся на карточке сразу под ней

Без тарифа (в ваших заголовках и API нет ни срока, ни трафика) «Сцена» показывает на месте дней ваше имя, и кнопки «Продлить» нет. Цвета состояния («Защищено», «Не защищено», «Подключение») всегда цвета V2pn, на своей плашке, поверх любого фона.

Тема

Поле theme в partner.json (пример — в разделе 2):

ПолеЗначенияПо умолчанию
palette.brand1–3 цвета, #RRGGBB. Первый — цвет бренда: кнопка подключения, ссылки, карточка. Остальные V2pn сейчас не рисуетbrand.accent
backgroundна чём стоит «Сцена»: {"type": "gradient", "colors": [от 2 до 4 цветов]} — градиент из угла в угол, 135°; {"type": "image", "art": "<картинка пакета>"}; {"type": "solid"} или без фона — только «Акцент»нет

Места для картинок:

МестоРазмер
brand.logoлоготип для тёмного фона: от 2:1 до 8:1, высота 32–256 px, прозрачный фон
brand.logoOnLightтот же логотип для светлого фона, те же размеры
brand.markквадратный знак на прозрачном фоне: 64–512 px
theme.background.artкартинка «Сцены»: сторона 640–3200 px, не шире 3:1

Цвета. Вы даёте цвет бренда (и цвета фона), остальное V2pn выводит сам для светлой и тёмной темы:

  • текст везде читается по WCAG AA: 4,5:1 для текста, 3:1 для кнопок и полей;
  • где цвет бренда становится текстом или фоном под текстом, V2pn делает его ровно настолько темнее или светлее, чтобы читалось;
  • цвет, который можно спутать с зелёным «Защищено», жёлтым «Внимание» или красным «Не защищено», V2pn уводит от них;
  • в тёмной теме градиент становится глубже, чтобы большое пятно не слепило;
  • на «Сцене» текст белый или почти чёрный — какой читается на всём фоне; поверх картинки V2pn кладёт затемнение, которого хватает, чтобы текст читался, что бы ни было на картинке.

Поле темы, которое V2pn не может взять (цвет в другом формате, картинка не по размеру), заменяется значением по умолчанию, и оформление продолжает работать; tools/partner.cs pack и tools/partner-check.cs говорят, что и почему. Неизвестные поля V2pn пропускает.

tools/edition-matrix.ps1 -Partner <id> снимает вкладку V2pn рядом с вашей и вашу вкладку в «Акценте» и «Сцене», в светлой и тёмной теме при трёх размерах окна (-Theme <папка> — с другой темой); без -Partner снимает V2pn человека, который не пришёл ни от одного партнёра: без вкладок и без всего вашего. Примеры тем лежат в tools/demo/themes/.

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

6. Проверенные файлы: маршруты, транспорт, конфиг ядра

Три файла пакета меняют то, как идёт трафик, поэтому V2pn использует их только после ручной проверки. Владелец V2pn читает файл и добавляет его право в listing.json; publish записывает SHA-256 файла в partner-index.json, в поле reviewed. Поменяли файл — V2pn перестаёт его использовать, пока владелец не проверит его снова и не опубликует новый хэш, а в окне подписки пишет: «Маршруты <провайдер> изменились после проверки и не используются». Остальной пакет работает как прежде.

ФайлПравоЧто делает
routing.jsonroutingваш режим в меню «Что идёт через VPN»
transport.jsontransportфрагментация и шум при подключении к вашим серверам
core.jsoncoreдополнительные серверы, цепочки, балансировка и правила к ним для ваших серверов

Файлы лежат в папке пакета рядом с картинками и перечислены в assets с размером и SHA-256, как картинки. Имена ровно такие, каждый файл до 64 КБ. Все три работают только с серверами вашей подписки; чужие подписки и свои серверы человека их не видят.

"reviewed": {
  "routing.json": "16732e2a91e3d657874fa65783b5f98f8ff09caa505c174325eaaeb833187e74",
  "transport.json": "7fa0471883888fa10c85491b3a5fd116d72193e98ebde400f76fec3a81fa4760"
}

Маршруты: routing.json

{
  "name": "YouTube, Telegram и ИИ через VPN",
  "rules": [
    { "domains": ["geosite:youtube", "geosite:telegram", "domain:chatgpt.com"], "ips": ["geoip:telegram"], "to": "proxy" },
    { "domains": ["domain:gosuslugi.ru", "domain:sberbank.ru"], "to": "direct" },
    { "domains": ["geosite:category-ads-all"], "to": "block" }
  ],
  "default": "direct"
}
Поле
nameподпись режима в меню, до 40 символов (необязательно)
rulesдо 50 правил по порядку, до 500 записей в правиле и 2000 всего
rules[].domainsexample.com или domain:example.com (сайт и поддомены), full: (только этот адрес), keyword: (от 3 символов), geosite: (список из файлов геоданных)
rules[].ipsадрес, сеть (91.108.4.0/22) или geoip:
rules[].toproxy — через ваш сервер, direct — напрямую, block — не открывать
defaultкуда идёт всё остальное: proxy или direct

Регулярных выражений нет: проверяющий должен прочитать каждую запись. Первыми V2pn сам ставит правила «локальная сеть напрямую». block нельзя для широкого: geoip:, целая зона (domain:ru), сеть шире /16, локальная сеть. Списки geosite: и geoip: V2pn берёт из файлов runetfreedom, как для своих российских режимов, и скачивает их, когда человек выбирает ваш режим; тег, которого там нет, остановит ядро.

В V2pn это ещё один режим в меню «Что идёт через VPN» — «Маршруты <провайдер>», в вашей вкладке. V2pn один раз сообщает, что режим появился, но сам его не включает: выбирает человек. При уходе из вашей вкладки режим убирается; если он был включён, его место занимает «Всё через VPN». Если партнёрство закончилось (срок истёк, владелец убрал партнёра) или файл изменился после проверки, режим пропадает, а если он был выбран, V2pn переключается на «Всё через VPN».

Транспорт: transport.json

{
  "fragment": { "packets": "tlshello", "length": "100-200", "interval": "10-20" },
  "noise": [ { "rand": "10-20", "delay": "10-16" } ]
}
Поле
fragment.packetstlshello или диапазон пакетов от 1 до 10 (1-3)
fragment.lengthразмер кусков в байтах, от 1 до 1500
fragment.intervalпауза между кусками в миллисекундах, от 0 до 200
noiseдо 8 записей: rand — случайные байты (от 1 до 1024), delay — пауза в миллисекундах (от 0 до 200)
  • Xray: фрагментация на ваших серверах с TLS и REALITY, которые подключаются напрямую (для REALITY V2pn ставит packets 1-3, tlshello с ним не работает); шум — на серверах mKCP и Hysteria.
  • sing-box: включается его фрагментация TLS, размеры кусков он выбирает сам; шума у него нет.
  • Для ваших серверов это заменяет фрагментацию из настроек человека, для остальных подключений ничего не меняется.
  • mux не принимается: у Xray и sing-box это разные протоколы, и обоим нужна поддержка на сервере.

Конфиг ядра: core.json

{
  "core": "xray",
  "outbounds": [
    { "tag": "ai-us", "protocol": "vless",
      "settings": { "vnext": [ { "address": "us.example.com", "port": 443, "users": [ { "id": "…", "encryption": "none" } ] } ] },
      "streamSettings": { "network": "raw", "security": "tls", "tlsSettings": { "serverName": "us.example.com" } } }
  ],
  "balancers": [ { "tag": "ai", "selector": ["ai-us", "proxy"], "strategy": "leastPing" } ],
  "observatory": { "probeUrl": "https://www.gstatic.com/generate_204", "probeInterval": "5m" },
  "rules": [ { "domains": ["geosite:openai", "domain:claude.ai"], "to": "ai" } ]
}
Поле
corexray или sing-box: файл добавляется только в конфиги этого ядра
outboundsдо 8 outbound в формате ядра. Xray: vless, vmess, trojan, shadowsocks, socks, http, hysteria, wireguard; цепочка — через streamSettings.sockopt.dialerProxy. sing-box: те же и hysteria2, tuic, anytls, а также urltest для выбора самого быстрого; цепочка — через detour
dialerтег outbound, через который подключаются все серверы вашей подписки (необязательно)
balancersтолько Xray, до 4: selector — ваши теги или proxy, strategy — random, roundRobin, leastPing или leastLoad
observatoryтолько Xray: probeUrl (https) и probeInterval (от 10s до 1h) для leastPing и leastLoad
rulesдо 32 правил с domains и ips, как в routing.json; to — ваш outbound, балансировщик или proxy
allowTopтолько sing-box: ntp, certificate — что может оставить подписка, которая отдаёт целый конфиг sing-box (файлы из них V2pn всё равно убирает)
  • Ваши теги получают приставку partner-<id>-, поэтому не пересекаются с тегами V2pn. proxy — сервер вашей подписки, к которому подключился человек.
  • Каждый outbound проходит фильтр подписок V2pn без изменений: никаких файлов, слушающих портов, API, tor, reverse, своего domain_resolver. Иначе файл не принимается.
  • Правила стоят после всех правил человека (закреплённых программ, правил выбранного режима, правил, которые человек добавил в режим «Маршруты <провайдер>») и только перед правилом по умолчанию в конце режима. Поэтому сайт, который человек пускает напрямую или блокирует, так и останется, что бы ни было в ваших правилах. Они ведут только на ваши outbound и балансировщики: что идёт напрямую или блокируется, решает routing.json. Адреса локальной сети в них запрещены.
  • Если в outbounds есть TLS и вы прислали transport.json, V2pn фрагментирует и их.
  • Человек может выключить переключатель «Настройки соединения <провайдер>» в окне подписки: тогда V2pn не использует ни transport.json, ни core.json.

Как файл проходит проверку

  1. Пришлите владельцу V2pn файлы и короткое описание: что они делают и зачем.
  2. Владелец запускает dotnet run tools/partner.cs -- review partners/<id>: команда перечисляет простыми словами, что делает каждый файл (каждое правило, каждую настройку, каждый outbound, блокировки и всё, что касается DNS), и проверяет формат и фильтр так же, как V2pn.
  3. Если всё в порядке, владелец добавляет право файла в listing.json и публикует. Любое изменение файла — новая проверка; право действует, пока длится партнёрство, и раз в год проверка повторяется.

Что смотрит проверяющий:

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

7. Заголовки подписки

Заголовок
v2pn-account-token: <токен>необязательный; свой у каждой подписки, до 200 символов из A–Z a–z 0–9 - _ . ~; уходит в ваш API как bearer-токен
profile-title, subscription-userinfo, profile-update-interval, support-url, profile-web-page-url, announceстандартные; V2pn показывает их и в обычном виде, и в вашем оформлении

Другие клиенты v2pn-account-token пропускают. Заголовок v2pn-partner прежних версий V2pn больше не читает: подписку делает вашей её домен.

Если подписка отдаёт целиком конфиг Xray, sing-box или Clash, а не ссылки на серверы, V2pn запускает его только после фильтра. Остаются серверы, маршрутизация между ними, DNS и балансировка. Локальные порты слушают только на 127.0.0.1. Убирается:

  • API ядра, статистика и внешняя панель управления;
  • журналы в файлы;
  • пути к любым файлам на компьютере;
  • TUN: его включает сам V2pn;
  • reverse в Xray, а в sing-box — tor и tailscale.

Конфиг для других ядер V2pn из подписки не запускает. Проще всего отдавать V2pn ссылки на серверы.

Заголовки Happ, INCY и v2RayTun

V2pn читает и те заголовки, которые провайдеры уже отдают для Happ, INCY и v2RayTun, так что панель, настроенная под них, работает в V2pn без изменений. Всё это работает для любой подписки, партнёра или нет, кроме переезда подписки. Регистр в именах заголовков не важен. Текст можно отдавать как есть или как base64:<UTF-8 в base64> (кириллицу — только так). Ссылки — только https: и tg:, остальные V2pn отбрасывает.

ЗаголовокЧто делает V2pn
announce-urlкнопка «Подробнее» под объявлением (announce)
sub-info-text, sub-info-color, sub-info-button-text, sub-info-button-link (Happ)баннер под подпиской в списке, над её серверами, в окне подписки и в вашем оформлении: до 200 символов, кнопка до 25. red, blue и green выбирают красный, синий или зелёный из цветов V2pn, всё остальное — синий. sub-info-text: 0 убирает баннер.
banner-text, banner-button-text, banner-button-url или banner-url, premium-url (INCY)тот же баннер, если баннера Happ нет. Кнопка ведёт на banner-button-url, иначе на banner-url, иначе на premium-url. Цвета INCY (banner-bg-color и другие) V2pn не берёт.
sub-expire, sub-expire-button-link (Happ); expiry-banner-text, expiry-banner-button-text, expiry-banner-button-url или expiry-banner-url (INCY)напоминание о продлении вместо баннера: за 3 дня до конца срока из subscription-userinfo и после него. Ваш текст, если вы отдаёте expiry-banner-text, иначе текст V2pn: «Подписка закончится через 2 дн.», «Подписка закончилась». Кнопка «Продлить» ведёт на вашу ссылку продления, иначе на profile-web-page-url, иначе кнопки нет. V2pn показывает напоминание и без sub-expire; sub-expire: 0 его выключает.
subscription-autoconnect: 1, subscription-autoconnect-type: lastused, lowestdelay или randomподключение, когда V2pn запускается выключенным: к последнему серверу этой подписки, к самому быстрому (V2pn сначала проверяет серверы и берёт самый быстрый из ответивших) или к случайному. Работает, если выбранный сервер из этой подписки или сервер не выбран и подписка первая в списке. V2pn, который оставили подключённым, подключается как раньше, а сервер, добавленный человеком вручную, остаётся его выбором. Человек может выключить это для подписки.
subscriptions-sort-type: ping, alphabet или without (Happ); sort-order: ping, name или none (INCY)порядок серверов этой подписки: быстрые сверху, по имени или как вы их отдаёте. Человек может выбрать другой.
subscription-ping-onopen-enabled: 1проверка серверов этой подписки при запуске V2pn
update-always: true (v2RayTun), subscription-auto-update-open-enable: 1 (Happ)обновление этой подписки при запуске V2pn. Только этой: Happ обновляет все.
new-url, new-domainпереезд подписки на новый адрес. Только для партнёра V2pn, в списке доменов которого есть новый адрес, и только в HTTP-заголовках ответа с серверами. Только https; new-url важнее new-domain, и при ошибке в new-url V2pn не переходит к new-domain; new-domain сохраняет порт, путь и параметры; переезд на тот же домен или на адрес другой подписки V2pn пропускает. Для остальных заголовки не действуют: иначе подписку мог бы увести любой, кто отвечает по старому адресу. В журнале человек видит, куда переехала подписка.
ping-type, check-url-via-proxyV2pn их читает и хранит, но пока не применяет: он проверяет каждый сервер через сам сервер по адресу проверки, который выбрал человек
hide-settings, hide-urlзакрытые настройки подписки, только для партнёра с правом lock (раздел 4); для остальных V2pn их только хранит

В теле подписки. Как Happ и INCY, V2pn читает строки #ключ: значение в начале подписки, которая отдаёт список ссылок, обычным текстом или в base64:

#profile-title: base64:S2VzdHJlbCBWUE4=
#sub-info-text: base64:0KHQutC40LTQutCwIDMwJSDQvdCwINCz0L7QtCDQtNC+INC/0Y/RgtC90LjRhtGL
#subscription-autoconnect: 1
vless://…

Заголовок важнее той же строки в теле. Только из заголовков: new-url, new-domain, баннеры INCY и v2pn-account-token. В полном конфиге Xray, sing-box или Clash таких строк V2pn не ищет.

Что V2pn не берёт. routing, фрагментацию, шум, fronting и другие настройки в заголовках, которые меняют трафик: им нужна проверка владельца, как проверенным файлам (раздел 6). Цветовые профили, change-user-agent и остальные настройки чужих приложений V2pn пропускает.

User-Agent V2pn. V2pn скачивает подписку с User-Agent v2rayN/7.25.6 V2pn/1.0.3: сначала агент v2rayN, потому что по нему панели выбирают формат, а V2pn читает те же форматы, потом имя и версия V2pn. Если человек задал подписке свой User-Agent, уходит он.

Правило ответа в Remnawave. Правила проверяются сверху вниз до первого совпадения, поэтому ставьте это правило выше правил для v2rayN. v2pn-account-token у каждого человека свой, его отдаёт панель, а не правило.

{
  "name": "V2pn",
  "description": "Баннеры и настройки для V2pn",
  "enabled": true,
  "operator": "AND",
  "conditions": [
    { "headerName": "user-agent", "operator": "CONTAINS", "value": "v2pn", "caseSensitive": false }
  ],
  "responseType": "XRAY_BASE64",
  "responseModifications": {
    "applyHeadersToEnd": true,
    "headers": [
      { "key": "announce-url", "value": "https://example.com/news" },
      { "key": "sub-info-text", "value": "base64:0KHQutC40LTQutCwIDMwJSDQvdCwINCz0L7QtCDQtNC+INC/0Y/RgtC90LjRhtGL" },
      { "key": "sub-info-color", "value": "green" },
      { "key": "sub-info-button-text", "value": "base64:0JrRg9C/0LjRgtGM" },
      { "key": "sub-info-button-link", "value": "https://t.me/example_bot" },
      { "key": "sub-expire", "value": "1" },
      { "key": "sub-expire-button-link", "value": "https://example.com/renew" },
      { "key": "subscription-autoconnect", "value": "1" },
      { "key": "subscription-autoconnect-type", "value": "lowestdelay" },
      { "key": "subscriptions-sort-type", "value": "ping" }
    ]
  }
}

8. Ссылки

v2pn://add?url=<ссылка на подписку, в URL-кодировке>&name=<имя> открывает V2pn, и он спрашивает, добавить ли подписку. V2pn принимает и ссылки Happ (happ://add/<ссылка>), v2RayTun (v2raytun://import/<ссылка>) и Hiddify (hiddify://import/<ссылка>). Если такая подписка уже есть, V2pn просто говорит об этом. В Windows схему v2pn регистрирует установленное приложение, на macOS — пакет приложения. Ссылка добавляет вашу подписку как обычную; вкладку она не создаёт.

9. API (необязательно)

С правом account и адресом api на домене из списка партнёра V2pn спрашивает:

GET <api>account с заголовком Authorization: Bearer <v2pn-account-token>, когда открывается ваша вкладка, и дальше раз в 30 минут, пока она на экране:

{
  "plan": "Личный",
  "status": "ACTIVE",
  "servers": { "healthy": 11, "total": 14 },
  "devices": { "count": 2, "limit": 5 },
  "until": "2027-01-31",
  "note": "В воскресенье ночью плановые работы."
}

GET <api>status без токена, раз в 15 минут:

{ "incidents": [ { "title": "Германия не отвечает", "text": "Уже чиним.", "severity": "major" } ] }

Для кнопок и описания серверов (право actions) V2pn спрашивает ещё, всегда с токеном подписки, если он есть:

GET <api>servers — так же часто, как account: при открытии вашей вкладки или когда выбран сервер вашей подписки, и не чаще раза в 30 минут. Те же поля, что в servers пакета, плюс load (0–100) и healthy. Значения API важнее значений пакета, поле за полем:

{ "servers": [ { "name": "🇩🇪 Германия 2", "load": 31, "healthy": true }, { "host": "nl1.example.com", "load": 90, "healthy": false } ] }

GET <api>recommend?purpose=youtube — при нажатии кнопки connect.recommend: серверы по порядку, лучший первым (имена или адреса, до 50):

{ "servers": ["🇳🇱 Нидерланды", "🇩🇪 Германия 2"] }

GET <api>card?id=plan — при нажатии кнопки info.card с этим id: заголовок до 60 символов и простой текст до 600, переносы строк сохраняются, разметки нет:

{ "title": "Тариф «Семья»", "text": "5 устройств, без ограничения трафика.\nОплачено до 31 января 2027." }

Все поля необязательны: V2pn берёт то, что знает, остальное пропускает. Ответ — JSON до 64 КБ с кодом 200, всё остальное считается отсутствием ответа. С токеном V2pn не идёт по редиректам. Если ваш сайт там, где человек, заблокирован, V2pn повторит запрос через VPN. servers.healthy/total заменяют в оформлении счёт по пингу V2pn («11 из 14 по проверке <провайдер>»). Отдавайте только числа, без адресов серверов и учётных данных.

Вход по коду

С "login": true в пакете (а значит, и с api) человек добавляет вашу подписку, ничего не копируя: «У меня подписка от провайдера» в первом запуске или «Войти через провайдера» в меню добавления («+»). Оба пункта есть у всех; список провайдеров V2pn спрашивает, только когда один из них открыт. В копии с вашей меткой первый запуск ставит вход через вас первым, с вашим знаком, и ведёт сразу к вам. Удачный вход запоминает, что человек пришёл от вас, и открывает вашу вкладку. V2pn показывает ваш знак и название, QR-код ссылки на бота, шесть цифр и кнопку «Открыть бота»; человек подтверждает вход в вашем боте, а V2pn добавляет подписку, обновляет её и выбирает её первый сервер (подключается человек сам). V2pn получает только собственную ссылку этого человека: она добавляется так же, как вставленная.

POST <api>login/start — когда открывается вход и по кнопке «Новый код», с телом JSON:

{ "device": "Windows · DESKTOP-7Q2", "app": "V2pn 1.2.0" }

device — система и имя компьютера (до 60 символов), чтобы ваш бот сказал, кто просит войти. Ответ:

{ "code": "482913", "token": "<непрозрачный, от 32 до 256 символов, безопасных для адреса>", "url": "https://t.me/kestrel_bot?start=v2pn-482913", "expires": 600 }
  • code — ровно шесть цифр, не повторяется среди ваших ещё ждущих кодов.
  • token — с ним V2pn спрашивает о входе; он остаётся на этом компьютере и нигде не показывается. Символы A–Z a–z 0–9 - _ . ~.
  • url — необязательно; из него QR-код и кнопка «Открыть бота». Только https на t.me или на ваших доменах из списка; иначе V2pn покажет только цифры.
  • expires — сколько секунд живёт код; обычно 600 (V2pn держит от 60 до 1800 и считает с момента ответа).

GET <api>login/poll?token=<токен> — раз в 2 секунды, пока вход открыт, до конца срока кода или пока человек его не закроет:

{ "state": "waiting" }
{ "state": "done", "subscription": "https://sub.kestrel.example/s/<ссылка человека>", "name": "Kestrel" }
{ "state": "expired" }

404 значит то же, что expired; отказ человека в боте — тоже. subscription V2pn берёт, только если это https на ваших доменах из списка, без имени и пароля; иначе показывает ошибку как есть. name необязательно (до 40 символов). Токену положен один done: забудьте его, как только этот ответ ушёл, и V2pn после него больше не спрашивает. Неизвестное V2pn состояние считается waiting.

В боте: /start v2pn-<код> (из QR-кода) или шесть цифр, набранные вручную. Скажите, кто просит войти («Войти в V2pn на «Windows · DESKTOP-7Q2»? Подтверждайте, только если этот код сейчас на вашем экране.»), с кнопками «Войти» и «Это не я»; по «Войти» отдайте собственную постоянную ссылку человека (не общую). Ограничьте login/start по адресу, а login/poll по токену, закрепляйте код за первым аккаунтом, который о нём спросил, и ограничьте, сколько кодов может перебрать один аккаунт, чтобы коды нельзя было подобрать. Готовый пример — бот Configra.

10. Как изменения доходят до людей

  • Изменили оформление. Владелец меняет partners/<id> и публикует. Запущенный V2pn человека, который пришёл от вас, спрашивает partner-index.json не чаще раза в шесть часов и при каждом запуске; если хэш вашего zip изменился, он один раз скачивает новый. У zip, файлы которого не менялись, хэш прежний, поэтому повторная публикация никого не заставляет качать его снова.
  • Новая установка. Копия с вашей меткой скачивает ваш пакет при первом запуске, ещё до входа и до подписки; после входа по коду V2pn скачивает его сразу.
  • Срок. Партнёрство длится до until в listing.json. V2pn проверяет срок при запуске и раз в час; когда он прошёл, ваша вкладка закрывается с пояснением и открывается вкладка V2pn. tools/partner-check.cs предупреждает за месяц; владелец продлевает срок и публикует.
  • Уход. Когда владелец убирает партнёра из partners/ и публикует, V2pn закрывает его вкладку при следующем обращении к списку, с пояснением, и новых пакетов партнёра больше не выходит. Метка остаётся: если партнёр вернётся в список, вернётся и вкладка.
  • Человек уходит. Если человек вошёл по коду и удалил последнюю подписку с ваших доменов, ваша вкладка пропадает вместе с ней. Метку удаление подписок не отменяет.
  • V2pn 1.2.1 и старше. Эти версии одевали V2pn в оформление партнёра, пока был выбран его сервер. Теперь каждый релиз публикует ещё и partners.json — подписанный и пустой, его они и читают: снимают партнёра, которого держали, и остаются обычными. Новый V2pn читает вместо него partner-index.json.
  • Если что-то не так. Список без подписи ключа V2pn или старее того, что уже есть у V2pn, пропускается; zip, который не совпал, не используется. V2pn оставляет то, что было, и пишет причину в журнал.

11. Проверка

dotnet run tools/partner-check.cs -- partners/<id>
dotnet run tools/partner-check.cs -- https://example.com/s/<настоящий токен подписки>

Первая команда проверяет папку партнёра до публикации, без сети: listing.json, пакет, упакованный так же, как его пакует publish, и прочитанный обратно тем же кодом, что в V2pn, картинки и их места, «Акцент» или «Сцену» и цвета, которые выведет V2pn, старые поля, которые он пропускает, описание серверов и кнопки (что V2pn пропустит и почему), закрытые настройки, проверенные файлы (формат, фильтр, право).

Вторая проверяет живую подписку по опубликованному списку так, как её видит V2pn во вкладке этого партнёра: заголовки подписки, подпись partner-index.json, какому партнёру принадлежит ссылка, zip и все проверки выше, а ещё API, включая servers, recommend и card для ваших кнопок. С login она один раз спрашивает login/start и проверяет вид ответа (шесть цифр, токен, ссылка, срок), но никогда не спрашивает login/poll, так что вход не завершается. --index partners/out берёт локальную публикацию вместо страницы релизов; --key <открытый ключ> проверяет список, подписанный тестовым корневым ключом.

Пример пакета с серверами, кнопками и тремя проверенными файлами и локальный сервер с подпиской, страницей релизов и API для предпросмотра лежат в tools/demo/partner/, tools/demo/demo_partner.py и tools/demo/try-partner.ps1.

12. Страница загрузки

python tools/partner-page.py partners/<id>

Собирает из папки партнёра страницу, которая ведёт его людей в V2pn с вкладкой партнёра, в partners/out/site/<id>/ (index.html, page.js, шрифт и картинки). На ней логотип и цвета партнёра (фон «Сцены» — в шапке), «Скачать для Windows» и «Скачать для macOS» — пакет партнёра из последнего релиза (V2pn-<id>-windows-x64.zip, V2pn-<id>-macos-arm64.zip и версии для ARM и Intel: V2pn с вашей меткой; для macOS это zip, без .dmg), сильная кнопка — под систему посетителя, установка одной командой ($env:V2PN_PARTNER='<id>'; irm …/install.ps1 | iex в Windows, curl -fsSL …/install.sh | V2PN_PARTNER=<id> bash на macOS: она ставит V2pn туда же, куда всегда, и добавляет метку, а поверх установленного V2pn только добавляет метку, серверы и настройки остаются), три шага (с login — вход по коду) и «Открыть бота», когда links.support ведёт в t.me или задан --bot. Русский и английский (?lang=en), светлая и тёмная тема; на телефоне вместо загрузки — «Отправить ссылку себе». Цвета считаются по правилам V2pn, и сборка останавливается, если где-то текст читается хуже 4.5:1. Папку можно выложить на свой сайт как есть: внешних скриптов и шрифтов нет, а скрипт лежит отдельным файлом, так что подойдёт и строгий CSP (script-src 'self'). Configra отдаёт её на /v2pn/download/.

Приватность

partner-index.json и ваш пакет V2pn берёт со страницы релизов V2pn, а не с вашего сайта, и только у человека, который пришёл от партнёра (или открыл вход по коду). Ваш сайт получает только то, что получает любая подписка: запрос подписки и, если есть API, его вызовы с User-Agent V2pn и, для account, servers, recommend и card, токеном, который вы выдали. Трафик человека, его другие подписки, устройство и всё, что V2pn измеряет, никуда не уходят. Единственное исключение — вход по коду, когда человек его открывает: login/start получает систему и имя компьютера, чтобы ваш бот назвал, кто просит войти.