Skip to content

Latest commit

 

History

History
184 lines (153 loc) · 16.4 KB

index.md

File metadata and controls

184 lines (153 loc) · 16.4 KB

Индекс репозитория плагинов

Спецификация v1 (schema 1). Схема — schema/index.schema.json, образец — examples/index.json.

Что такое репозиторий

Репозиторий — набор файлов по HTTPS:

<база>/index.json            индекс: все плагины, все версии, все архитектуры
<база>/index.json.sig        подпись индекса (usign)
<база>/<id>/<версия>/<id>-<версия>-<арх>.s2p
  • В одном репозитории сколько угодно плагинов, у плагина — сколько угодно версий, у версии — архивы под разные архитектуры. Репозиториев на роутере тоже сколько угодно (решение 6).
  • Официальный репозиторий — splify2/plugins: GitHub Pages плюс зеркало jsDelivr, как у списков splify2 (splify2/files/usr/lib/splify2/fetch.sh:45-48, PLUGINS.md 3.5). Индекс собирает и подписывает CI этого репозитория из выпусков плагинов; публикация — тем же путём, что releases/scripts/publish.py.
  • Сторонний репозиторий устроен так же. Подключает его человек (steer plugin repo add <url> <ключ>, раздел «Плагины» splify2); интерфейс прямо говорит, что репозиторий не официальный и splify2 за него не отвечает (решение В6).

Поля индекса

Поле Что
schema 1. Неизвестная — индекс не принимается, причина: «индекс репозитория X нового формата — обновите ядро»
repo.id имя пространства: splify2 у официального. Совпадает с именем в repos.d
repo.name, homepage, description для человека
generated время сборки (UTC). Менеджер не принимает индекс старее уже виденного из этого репозитория (последнее generated — в /etc/steer/plugins/repos.d/<имя>.json): защита от отката на старый индекс с уязвимой версией
expires после этого времени индекс не принимается. CI переподписывает индекс раньше срока (умолчание: срок 30 дней, переподпись раз в неделю)
mirrors базовые адреса HTTPS; относительные path архивов приклеиваются к ним, перебор по порядку
plugins.<id> плагин: общее описание и versions[]

plugins.<id>:

Поле Что
name, description, type, tags, homepage, license для каталога
default ставится при первой установке ядра и при переходе на 2.1 (протоколы, решение 7)
key_role только официальный: protocols или plugins — каким ключом подписаны архивы этого плагина. Индекс подписан ключом index, поэтому привязка роли к плагину защищена: утечка ключа plugins не даёт подписать поддельный vless
versions[] версии, порядок любой (менеджер сортирует по semver)

versions[]:

Поле Что
version semver; совпадает с version манифеста в архиве
released дата выпуска
compat копия compat манифеста этой версии: отбор идёт без скачивания архивов
requires, conflicts копии из манифеста
provides.kinds какие виды регистрирует версия (tunnel:vless, awg, warp) — по ним steer plugin migrate и отказ «нужен плагин vless» находят плагин по виду из спеки
provides.commands, provides.languages подкоманды и языки — для поиска и отказов
changelog что изменилось, для человека
yanked {why, security} — версия отозвана: не ставится; стоящая показывается с причиной, автообновление меняет её первой, а при security: true — сразу, не дожидаясь ночного окна
assets.<арх> архив под архитектуру или all; assets.<арх>@lite — облегчённый вариант (manifest.md, «Варианты»), standalone: true — работает и без steer-core: path (относительно mirrors) или url[] (полные адреса), sha256, size (байт .s2p), installed (байт после распаковки)

Копии compat/requires в индексе обязаны совпадать с манифестом в архиве. Менеджер сверяет их после скачивания; расхождение — отказ («индекс и архив vless 2.1.1 не совпадают»). s2p index в SDK строит индекс из самих архивов, так что руками их никто не пишет.

Подпись индекса

  • index.json.sig — подпись usign/signify (Ed25519) над байтами index.json как они лежат на сервере. Формат и проверка — s2p.md, «Подпись».
  • Официальный индекс подписан ключом роли index (решение В8: ключи индекса, протоколов и прочих плагинов — разные). Сторонний — ключом репозитория, отпечаток которого человек принял при подключении.
  • Сначала проверяется подпись, затем schema, expires, generated. Индекс без годной подписи не разбирается вовсе.
  • Ротация: в файле подписи может быть несколько блоков usign (на время перехода CI подписывает двумя ключами), годится любой блок доверенного ключа нужной роли. Подробно — s2p.md.

Репозитории на роутере

/etc/steer/plugins/repos.d/<имя>.json:

{
  "id": "splify2",
  "url": "https://splify2.github.io/plugins/",
  "mirrors": ["https://cdn.jsdelivr.net/gh/splify2/plugins@gh-pages/"],
  "official": true,
  "priority": 0,
  "keys": ["b5c0e2a1d4f39788"],
  "last_generated": "2026-11-02T10:00:00Z",
  "auto_update": true
}
  • official: true ставят только наши пакеты (таблица ниже). Ключи официальных репозиториев — в /usr/share/steer/keys/ пакета steer-core, а не здесь.
  • keys — номера ключей usign (8 байт, 16 знаков hex, как печатает usign -F); сами ключи — /etc/steer/plugins/keys/<repo>/<номер>.pub.
  • priority — меньше раньше. Поиск по имени идёт по всем репозиториям в этом порядке.
  • Кэш индекса — /var/run/steer/plugins/<repo>/index.json (tmpfs) с ETag/Last-Modified; повторная загрузка — условным запросом.

Репозитории по умолчанию

Официальных репозиториев три (решение владельца: steer-core-plugins, splify2-core-plugins, splify2-extended-plugins). Каждый — ветка gh-pages своего репозитория GitHub с зеркалом jsDelivr; файлы repos.d кладут пакеты, которым они нужны:

id в repos.d Что в нём Индекс (Pages) Кладёт priority Ключ архивов (key_role)
splify2 (steer-core-plugins) протоколы и общие библиотеки ядра: vless, hysteria2, proxy, xsteer, obfs, warpbox, awg, net1 splify2/plugins steer-core (splify2.json) 0 protocols
splify2-core-plugins «из коробки» splify2: andromeda, lang-ru, lang-en, subscriptions, lists-catalog, node-check, group-check, autoapply, backup, updater splify2/splify2-core-plugins splify2 10 plugins
splify2-extended-plugins по желанию: recheck, tgws, warpbox-ui и прочее splify2/splify2-extended-plugins splify2 20 plugins
  • extended — официальный, а не сторонний: это наш репозиторий, подписан ключами splify2 (индекс — ключом роли index, архивы — plugins), и пометка «репозиторий не официальный, splify2 за него не отвечает» (В6) к нему не относится. Её получают только репозитории, подключённые человеком (official: false, свой ключ в /etc/steer/plugins/keys/<repo>/).
  • Плагины extended не ставятся сами (default в индексе нет): человек выбирает их во вкладке «Плагины». Плагины core-plugins помечены default: true — их ставит семя пакета splify2 (splify2-seed), затем они обновляются из сети.
  • steer-core без splify2 (например, только с box-connector) знает лишь splify2. extended к нему подключается файлом repos.d/splify2-extended-plugins.json (тем же, что в пакете splify2) — тогда он официальный и проверяется ключами steer-core; steer plugin repo add подключил бы его как сторонний, со своим ключом и пометкой.
  • Индексы собирает и подписывает CI выпусков (tools/publish-index.sh: steer → splify2/plugins, splify2 и andromeda → splify2/splify2-core-plugins, splify2-extended-plugins → свой gh-pages) и раз в неделю переподписывает по расписанию: индекс живёт 30 дней (expires).

Отбор версии

Цель — то, что даёт роутер: {api, abi, core, host, splify2, arch} (steer version --json и build-id.txt splify2; host и splify2 пусты, если splify2 нет).

выбрать(plugin, цель, откуда):
  для версий plugin из репозитория «откуда» по убыванию semver:
    если версия yanked                       → дальше (запомнить причину)
    вариант = full, если есть steer-core и хватает места на full с библиотеками; иначе lite
    если нет assets[цель.arch(@вариант)] и assets.all → дальше («нет сборки под aarch64_cortex-a53»)
    для каждой оси compat:
      ось host-api или splify2, а splify2 нет → ось не мешает (UI просто не загрузится)
      иначе диапазон не содержит цель[ось]    → дальше («требует steer-api ^1.4, у ядра 1.3»)
    если requires.plugins не разрешаются выбрать(…) рекурсивно → дальше
    если conflicts пересекается с поставленными → дальше
    вернуть версию
  нет ни одной → причина от самой новой версии
  • Установка — самая новая совместимая версия; несовместимые видны в интерфейсе с причиной.
  • Обновление плагина — тот же отбор только из репозитория, из которого плагин поставлен. Одноимённый плагин другого репозитория молча не подменяет поставленный.
  • Обновление ядра — отбор для каждой стоящей версии с целью «новое ядро», план показывается до установки (PLUGINS.md 6.2). Несовместимые с новым ядром отключаются с причиной в state.json.
  • Ядро при старте само сверяет теги стоящих плагинов: несовместимый (например, положенный руками) не регистрируется, причина — в steer plugin status и в событии plugin.
  • Зависимость requires.plugins ищется сначала в репозитории самого плагина, затем во всех по priority.

Сборка индекса (CI репозитория)

s2p index <каталог архивов> -o <каталог репозитория> --repo <id> --mirror <url>… --expires 30d --pub <ключ архивов> --key <ключ index> в SDK (поля, которых нет в манифесте — default, key_role, tags, changelog, — берутся из файла --meta: {"plugins": {"<id>": {"default": true, "key_role": "protocols", "tags": [...], "changelog": {"<версия>": "…"}}}}):

  1. читает каждый .s2p, проверяет MANIFEST и MANIFEST.sig, берёт из манифеста compat, requires, conflicts, provides (виды — из steer.kinds[].name, подкоманды — из steer.commands[].name, языки — из i18n.host);
  2. считает sha256, size, installed;
  3. сливает с прежним индексом: прежние версии остаются, пока их не убрали явно (s2p index --drop <id>@<версия>); отзыв — --yank <id>@<версия> --why "…";
  4. пишет index.json и подписывает его тем же usign-форматом (--key; ключ — секрет Actions, решение В8; несколько --key — несколько блоков), раскладывает архивы в <id>/<версия>/ под -o и проверяет готовый индекс по index.schema.json.

Отказы сборки: архив не подписан доверенным ключом (--pub), lint архива не прошёл, у одной версии расходятся compat, requires, conflicts или provides между архитектурами и вариантами («варианты обязаны совпадать»), у той же версии и архитектуры другие байты, чем в прежнем индексе (сборка воспроизводима, расхождение — повод разобраться; --replace заменяет), время сборки раньше прежнего индекса. Проверка готового индекса — s2p verify index.json --pub <ключ> [--base <каталог>]: подпись раньше остального, затем схема и expires, с --base — ещё sha256 и size каждого архива.

Официальные протоколы (дерево steer) выпускает конвейер steer: архивы под 11 архитектур кладутся в splify2/plugins, CI которого и строит индекс. Тег ядра у них больше не ставится (В10): протоколы выходят отдельно от ядра.