Документация

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

Начало

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

Скачайте клиент, добавьте ссылку подписки, выберите сервер и подключитесь. Подписку можно вставить из буфера, ввести вручную, отсканировать QR-код или открыть ссылку pingy://import/… — приложение примет её в любом из этих видов.

Android-клиент работает через системный VPN (TUN) и не требует ручной настройки прокси. Windows-клиент поддерживает и TUN, и локальный прокси.

Форматы

Форматы подписок и ключей

Клиент принимает ссылку подписки (текст или base64), JSON-профиль, YAML в формате Clash/Mihomo и отдельные ключи. Поддерживаемые схемы:

vless://TCP, gRPC, WS, HTTPUpgrade, XHTTP/SplitHTTP; TLS, Reality, XTLS-Vision
vmess://Base64-JSON и обычная ссылка
trojan://TLS и transport-параметры
ss://Shadowsocks, включая plugin-параметры
hysteria2://, hy2://, hysteria://QUIC, obfs, bbrProfile и прочие параметры провайдера
tuic://, anytls://QUIC-транспорты
socks5://, socks://, http://Прокси без шифрования
wireguard://, wg://, amneziawg://, awg://WireGuard и AmneziaWG 3.1 (все параметры обфускации)

Неизвестные параметры не отбрасывают узел: клиент сохраняет их и передаёт ядру. Если провайдер добавил собственный ключ в ссылку, сервер всё равно появится в списке.

Интеграция

Правила ответов по User-Agent

Панели Remnawave и 3x-ui отдают разный набор узлов в зависимости от User-Agent. Чтобы подписка работала и там, где правил для Pingy ещё нет, клиент запрашивает её волной запросов и берёт первый пригодный ответ. Порядок запросов:

Pingy/<версия>основной; к нему добавляются X-Client: Pingy, X-Client-Version, X-Pingy-User-Agent
INCY/<версия>/androidсовместимость, Accept: */*
SFA/<версия>, singbox/<версия>правила для sing-box
Happ/<версия>правила Happ
Mihomo/<версия>, Clash/<версия>YAML-конфигурации
свой User-Agentзадаётся в настройках клиента и добавляется в конец волны

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

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

Интеграция

Заголовки ответа подписки

Клиент читает стандартные заголовки подписки. Значения с не-ASCII символами можно передавать с префиксом base64:.

profile-titleназвание подписки в списке источников
announceсообщение провайдера — показывается карточкой на главном экране
subscription-userinfoupload, download, total, expire — трафик и срок в карточке подписки
profile-update-intervalрекомендованный интервал обновления в часах
profile-web-page-urlссылка «Открыть» в карточке сообщения
profile-support-url, support-urlадрес поддержки

Пример ответа:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
profile-title: base64:UGluZ3kgUHJlbWl1bQ==
subscription-userinfo: upload=0; download=747432087512; total=0; expire=1797164756
profile-update-interval: 12
announce: base64:0J/Qu9Cw0L3QvtCy0L7QtSDQvtCx0L3QvtCy0LvQtdC90LjQtQ==
profile-web-page-url: https://example.com/cabinet
Панель

Настройки клиента из панели

Провайдер, подключённый к panel.pingy.top, дополнительно получает настройки оформления и поведения. Клиент запрашивает их отдельно и применяет к своему интерфейсу.

theme.accent, background, surface, text, mutedпалитра; применяется, если контраст текста проходит проверку
theme.radius, cardStyle, buttonStyleскругления и стиль карточек и кнопок: glass / solid / outlined / flat и solid / soft / outline / minimal
theme.logoUrlлоготип провайдера; можно загрузить файл прямо в панели
theme.backgroundImageфон главного экрана с точкой фокуса и затемнением
brandArtwork.android.imageUrlбренд-арт в карточке подключения
banner.enabled, banner.textбаннер провайдера на главном экране
appButtons.site, bot, channel, supportкнопки провайдера под карточкой подключения
widgets, notificationsчто показывают виджет и уведомление
doh.server, dnsProfiles.activeDNS клиента: обычный адрес или DoH-ссылка https://
routingProfiles.activeрежим маршрутизации: профиль сопоставляется со встроенным режимом по mode и directGeoip
recommendedVpnsпобедители еженедельного аукциона; показываются на экране добавления подписки

Все ссылки в настройках должны быть https://. Логотип, фон и бренд-арт по http:// клиент игнорирует.

Клиент

Проверка серверов и автовыбор

Задержку можно измерять пятью способами; метод выбирается в «Настройки → Серверы».

TCPтолько рукопожатие TCP — быстро, годится для больших списков
HTTP HEADзапрос HEAD поверх соединения: отвечает ли TLS/HTTP-фронт
HTTP GETждёт первый байт ответа — ближе всего к ощущаемой задержке
ICMPклассический ping; часто блокируется сетями
Через ядроподнимает изолированный экземпляр ядра и проверяет, что прокси действительно отвечает

Автовыбор сервера работает в двух режимах. «Проверка через ядро» берёт короткий список и подключается только к узлу с подтверждённым ответом прокси. «Реальная задержка (HTTP GET)» измеряет весь список и подключается к самому быстрому — это полезно, когда у провайдера десятки узлов.

Отображение задержки настраивается отдельно: цифры, шкала, шкала с цифрами или точки. Пороги зелёного, жёлтого и красного считаются под каждый метод — 60/150 мс для TCP и ICMP, 120/300 мс для HTTP, 200/500 мс для проверки через ядро.

Маршруты

Маршрутизация

Режим маршрутизации выбирается вручную, поэтому поведение остаётся предсказуемым:

Всё через Pingyвесь трафик идёт в туннель
Локальная сеть напрямуюадреса домашней сети минуют туннель
Российские сайты напрямуюлокальные домены и IP идут мимо туннеля, остальное — через Pingy
Китай напрямую, Иран напрямуюто же самое для соответствующих регионов

Наборы правил принадлежат движку и подписаны вместе с ним, поэтому произвольный список доменов от провайдера или пользователя клиент не исполняет. Профиль маршрутизации из панели применяется как намерение: mode: global включает «Всё через Pingy», а directGeoip с ru, cn, ir или private — соответствующий встроенный режим.

Отдельно настраивается разделение по приложениям: выбранные приложения либо работают напрямую, либо только они идут через Pingy.

DNS применяется полностью: адрес из doh.server или из активного пресета dnsProfiles становится DNS клиента. Ссылка https:// используется как DoH, обычный адрес — как UDP-резолвер на порту 53.

Протокол

AmneziaWG 3.1

Клиент собран на amneziawg-go 3.1 и принимает весь набор параметров обфускации — и в ссылке awg://…?Jc=4&H1=100, и в секции [Interface] конфигурационного файла. Имена нечувствительны к регистру, поддерживаются оба написания (короткое и длинное).

Jc · JunkPacketCountсколько мусорных пакетов слать перед handshake
Jmin · Jmaxграницы размера мусорного пакета
S1 – S4размер мусора в init, response, cookie-reply и transport-пакете
H1 – H4магические заголовки четырёх типов пакетов; принимается диапазон 100-109
I1 – I5цепочки спецпакетов: <b 0x…>, <r N>, <rd N>, <rc N>, <t>
HeaderProtectionKeyключ шифрования заголовка; требует заданных S1–S4
ContentPaddingAdditionдобавочный паддинг полезной нагрузки
RekeyAfterTime · RekeyTimeout · RejectAfterTimeтайминги пересогласования ключей
KeepaliveTimeout · MaxHandshakeAttemptsтаймаут keepalive и число попыток handshake
RandomTrailers 3.1случайный хвост у handshake- и cookie-пакетов: их размер перестаёт быть отпечатком
DisableCookies 3.1не отправлять cookie-reply — сам по себе признак WireGuard под нагрузкой

Два параметра 3.1 включайте только если сервер тоже на 3.1. Узел версии 3.0 сверяет длину пакета точно и молча отбрасывает handshake со случайным хвостом. Поэтому RandomTrailers и DisableCookies уходят ядру только тогда, когда провайдер их явно прислал: если параметра нет в профиле, клиент не отправляет его вовсе — ни со значением on, ни со значением off.

Булевы значения принимаются в любом из написаний on, 1, true, t, yes и, соответственно, off, 0, false, f, no. Любое другое значение — ошибка профиля, а не «выключено»: так опечатка в панели не превращается в тихо отключённую обфускацию.

Подписка

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

Клиент принимает три формы тела ответа. Любую из них Remnawave, Marzban или 3x-ui отдают штатно — выбирать нужно одну и держаться её.

1. Список ссылок, обычный текст

Самая простая и самая надёжная форма: по одной ссылке на строку. Имя узла — во фрагменте после #, в URL-кодировке.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
profile-title: base64:UGluZ3kgUHJlbWl1bQ==
subscription-userinfo: upload=0; download=747432087512; total=0; expire=1797164756
profile-update-interval: 12

vless://11111111-2222-4333-8444-555555555555@nl1.example.com:443?type=tcp&security=reality&sni=www.microsoft.com&fp=chrome&pbk=BASE64URL_PUBLIC_KEY&sid=0a1b2c3d&flow=xtls-rprx-vision#%F0%9F%87%B3%F0%9F%87%B1%20Amsterdam
vless://11111111-2222-4333-8444-555555555555@de1.example.com:443?type=grpc&serviceName=api&security=tls&sni=de1.example.com&alpn=h2#%F0%9F%87%A9%F0%9F%87%AA%20Frankfurt

2. То же самое в base64

Тело целиком закодировано base64 — исторический формат, понимают все клиенты. Заголовки при этом остаются обычными.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
profile-title: base64:UGluZ3kgUHJlbWl1bQ==

dmxlc3M6Ly8xMTExMTExMS0yMjIyLTQzMzMtODQ0NC01NTU1NTU1NTU1NTVAbmwxLmV4YW1wbGUuY29tOjQ0Mw==

3. Полная конфигурация Xray (JSON)

Нужна, когда одной ссылкой не обойтись: балансировщик, наблюдатель, цепочка прокси или собственные правила. Отдавайте с Content-Type: application/json.

{
  "outbounds": [
    { "tag": "nl", "protocol": "vless", "settings": { "address": "nl1.example.com", "port": 443,
      "id": "11111111-2222-4333-8444-555555555555", "flow": "xtls-rprx-vision", "encryption": "none" },
      "streamSettings": { "network": "tcp", "security": "reality",
        "realitySettings": { "serverName": "www.microsoft.com", "fingerprint": "chrome",
          "publicKey": "BASE64URL_PUBLIC_KEY", "shortId": "0a1b2c3d" } } },
    { "tag": "de", "protocol": "vless", "settings": { "address": "de1.example.com", "port": 443,
      "id": "11111111-2222-4333-8444-555555555555", "encryption": "none" },
      "streamSettings": { "network": "grpc", "security": "tls",
        "grpcSettings": { "serviceName": "api" }, "tlsSettings": { "serverName": "de1.example.com", "alpn": ["h2"] } } }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "balancers": [ { "tag": "fast", "selector": ["nl", "de"], "strategy": { "type": "leastPing" } } ],
    "rules": [ { "type": "field", "network": "tcp,udp", "balancerTag": "fast" } ]
  },
  "observatory": { "subjectSelector": ["nl", "de"], "probeURL": "https://www.gstatic.com/generate_204", "probeInterval": "60s" }
}

Что клиент делает с этим JSON: берёт outbounds, routing, balancers, observatory и dns. Входящие соединения, транспортные сокеты и логи задаёт сам клиент — эти секции игнорируются, потому что туннель на устройстве принадлежит приложению. Неизвестные поля внутри принятых секций сохраняются и передаются ядру как есть.

Интеграция

Работа с JSON: профиль маршрутизации

Маршрутизация приходит отдельным JSON — из подписки, по ссылке pingy://routing/add/<данные> или по URL, который клиент перечитывает сам.

{
  "version": 1,
  "mode": "bypass",
  "directGeoip": ["ru", "private"],
  "doh": { "server": "https://dns.example.com/dns-query" },
  "dnsProfiles": [
    { "name": "Основной", "server": "https://dns.example.com/dns-query", "active": true },
    { "name": "Резервный", "server": "1.1.1.1" }
  ]
}
modeglobal — весь трафик в туннель; bypass — встроенный режим по directGeoip
directGeoipru, cn, ir, private — что идёт мимо туннеля
doh.serverhttps:// — DoH; обычный адрес — UDP-резолвер на порту 53
dnsProfilesпресеты DNS; активный становится резолвером клиента

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

Автообновляемая маршрутизация

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

pingy://routing/add/https%3A%2F%2Fexample.com%2Frouting.json

Ссылка должна быть https://. Обычный http:// отклоняется: профиль маршрутизации решает, что идёт мимо туннеля, и принимать его по незащищённому каналу небезопасно.

Диагностика

Если что-то не работает

Подписка добавляется, но серверов нет. Обычно это правило ответов: панель отдала заглушку вместо списка. Проверьте правило для Pingy/* и лимит устройств по HWID.

Задержка не показывается. Проверьте выбранный метод: ICMP и прямой TCP часто блокируются мобильными сетями. HTTP GET и проверка через ядро работают там, где прямые пакеты фильтруются.

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

Диагностический отчёт собирается в «Настройки → Приложение → Отчёт для поддержки». Он не содержит ссылку подписки, ключи и токены. Полные приватные ссылки не отправляйте в публичные чаты.