Подписка (Subscription)

Подписка позволяет во время загрузки конфигурации подтянуть внешние фрагменты и объединить их с текущим конфигом.

Сейчас есть три типа:

full: зарезервировано, пока не реализовано (пишет warning и игнорируется)
outbound: реализовано, подтягивает и объединяет outbounds
database: реализовано, скачивает и перезаписывает geodata базы (geoip.dat / geosite.dat)

SubscriptionObject

jsonc

{
  "subscription": {
    "subscription-inbound": "sub-in",
    "outbound": [
      {
        "name": "mySub",
        "url": "https://example.com/sub",
        "format": "auto",
        "tagPrefix": "sub-",
        "insert": "tail",
        "interval": "30m",
        "enabled": true
      }
    ],
    "database": [
      {
        "type": "geoip",
        "url": "https://example.com/geoip.dat",
        "interval": "24h",
        "enabled": true
      },
      {
        "type": "geosite",
        "url": "https://example.com/geosite.dat",
        "cron": "0 3 * * *",
        "enabled": true
      }
    ]
  }
}

TIP

subscription.outbound, subscription.full и subscription.database могут задаваться как одним объектом, так и массивом.

subscription-inbound: string

(Опционально) Виртуальный inboundTag для трафика загрузки/обновления подписок. При задании, HTTP-запросы подписок выполняются через внутренний роутер Xray:

правила маршрутизации могут матчить этот трафик через inboundTag и выбирать outbound (например, заставить подписки ходить через прокси)
если не задано: HTTP-загрузка выполняется обычным net/http напрямую (без маршрутизации через Xray)

OutboundSubscriptionObject

subscription.outbound разбирает содержимое подписки в список outbounds и объединяет их с текущей конфигурацией.

name: string

Имя подписки (используется для генерации тегов по умолчанию и в логах).

url: string

Источник подписки:

поддерживается http:// / https://
поддерживаются локальные пути к файлам (абсолютные и относительные)
stdin: не допускается

Приоритет разрешения относительных путей:

каталог из xray run -confdir <dir>
каталог конфигурации (один файл: каталог файла; несколько файлов: только если у всех общий каталог)
cwd (рабочий каталог при старте)

format: string

Формат содержимого:

auto (по умолчанию): определение по расширению (.json/.jsonc -> json, .yaml/.yml -> yaml), иначе по умолчанию json; при ошибке разбора будет автоматически выполнен fallback к стандартной share-подписке
json: JSON / JSONC
yaml / yml: YAML (сначала конвертируется в JSON; имена полей должны соответствовать JSON schema)
xray / share / sharelink / base64: стандартная share-подписка (см. ниже)

WARNING

Подписки пока не поддерживают TOML. Даже при расширении .toml format=auto не сможет корректно разобрать содержимое.

tagPrefix: string

Префикс, добавляемый к tag каждого outbound, созданного из подписки (рекомендуется, чтобы избежать конфликтов тегов).

insert: "head" | "tail"

Позиция слияния:

tail (по умолчанию, также принимает append): добавить в конец текущих outbounds
head (также принимает prepend): вставить перед текущими outbounds

enabled: true | false

Включена ли подписка. По умолчанию true.

interval: string

(Опционально) Интервал runtime-обновления (например "10m" / "1h"). Взаимоисключающе с cron/crontab.

cron: string

(Опционально) Расписание runtime-обновления (стандартное crontab из 5 полей: мин час день месяц день-нед, например "0 3 * * *"). Также поддерживаются дескрипторы @daily / @weekly / @every 1h.

Алиас: crontab.

TIP

Если задан subscription.subscription-inbound или настроен interval/cron/crontab, подписка обновляется в runtime; иначе она загружается/сливается при загрузке конфигурации.

DatabaseSubscriptionObject

subscription.database скачивает и перезаписывает geodata базы:

geoip.dat (используется правилами geoip:)
geosite.dat (используется правилами geosite:)

type: "geoip" | "geosite"

Тип базы:

geoip: перезаписывает geoip.dat
geosite: перезаписывает geosite.dat

url: string

Источник подписки. Поддерживает http:// / https:// / локальные пути к файлам (разрешение относительных путей как у subscription.outbound.url).

enabled: true | false

Включена ли подписка. По умолчанию true.

interval: string

(Опционально) Интервал runtime-обновления (например "24h"). Взаимоисключающе с cron/crontab.

cron: string

(Опционально) Расписание runtime-обновления. Алиас: crontab.

Куда устанавливается:

При успешной загрузке файл записывается в каталог ресурсов (asset) и перезаписывает существующий. Каталог задается через xray.location.asset / XRAY_LOCATION_ASSET.

WARNING

Перезапись .dat файлов не пересоздает автоматически уже работающие правила маршрутизации. Обычно требуется перезапуск core или перезагрузка конфигурации, чтобы применить новые geodata.

Форматы содержимого

JSON / JSONC

Поддерживаются два варианта:

Список outbounds:

jsonc

[
  { "protocol": "freedom", "tag": "direct" },
  { "protocol": "blackhole", "tag": "block" }
]

Объект-обертка (читается только outbounds):

jsonc

{
  "outbounds": [{ "protocol": "freedom", "tag": "direct" }]
}

YAML

YAML сначала конвертируется в JSON и затем разбирается как JSON; имена полей должны совпадать с JSON schema (например, streamSettings, tlsSettings).

Пример (список outbounds):

yaml

- protocol: freedom
  tag: direct
- protocol: blackhole
  tag: block

Многие серверы подписок отдают Base64-строку. После декодирования это несколько share-ссылок, например:

text

vless://...
vmess://...
trojan://...
ss://...

Xray автоматически:

пробует Base64-декодирование (поддерживает Base64(JSON/YAML) и Base64(share links))
разбирает распознанные share-ссылки и преобразует их в outbounds

Поддерживаемые схемы:

vless://
vmess:// (распространенный base64(json) формат)
trojan://
ss:// (параметр plugin пока игнорируется)

WARNING

Нераспознанные строки пропускаются с предупреждениями. Если не найдено ни одной поддерживаемой share-ссылки, Xray завершится с ошибкой.

Base64 URL

Если url сам по себе закодирован в Base64, используйте:

base64:<BASE64>
b64:<BASE64>
base64://<BASE64>
b64://<BASE64>

Сначала Xray декодирует строку в реальный URL/путь и затем загружает содержимое.

Правила слияния и тегов

Если у сгенерированного outbound пустой tag, Xray создаст "<name>-<index>" (если name пустое, используется subscription).
Если задан tagPrefix, он добавляется в начало итогового тега.
Слияние выполняется по tag: одинаковые теги перезаписывают существующие; новые теги вставляются в начало/конец в зависимости от insert.
Для управления подписками каждый outbound, созданный из подписки, автоматически получает поле managed (а также поле subscription как эквивалентный алиас) со значением имени подписки. Значение берется из subscription.outbound.name (автозаполняется, если не задано). При следующей загрузке конфигурации Xray сначала удаляет outbounds с тем же managed/subscription, затем сливает новый результат подписки, поэтому удаления/добавления/обновления в подписке начинают работать корректно.

TIP

Всегда используйте tagPrefix, чтобы избежать конфликтов тегов между подпиской и локальными outbounds.

Поведение -dump

xray run -dump выполняет загрузку/объединение подписок:

когда подписки разворачиваются при загрузке конфигурации, блок subscription {} удаляется из вывода (разворачивается в outbounds)
когда включено runtime-обновление (subscription-inbound / interval / cron), блок subscription {} сохраняется, а вывод не будет содержать outbounds, обновленные в runtime

Подписка (Subscription) ​

SubscriptionObject ​

OutboundSubscriptionObject ​

DatabaseSubscriptionObject ​

Форматы содержимого ​

JSON / JSONC ​

YAML ​

Стандартные Share-подписки (Base64) ​

Base64 URL ​

Правила слияния и тегов ​

Поведение -dump ​

Подписка (Subscription)

SubscriptionObject

OutboundSubscriptionObject

DatabaseSubscriptionObject

Форматы содержимого

JSON / JSONC

YAML

Стандартные Share-подписки (Base64)

Base64 URL

Правила слияния и тегов

Поведение -dump