seedex-box

Эта страница описывает, как устроен репозиторий seedex-openwrt и как его собирать и линтить.

Требования

  • Docker для сборки. В нём работает apk-tools, который собирает пакеты.
  • shfmt 3.13 и shellcheck 0.11 для линта.
  • Роутер на OpenWrt 24.10.2 или новее, чтобы установить сборку.
  • По желанию — ключи подписи: ключ apk в ~/.seedex/apk-sign.key и пара usign в ~/.seedex/opkg-sign.key и opkg-sign.pub. Без них пакеты не подписаны, и install.sh ставит их без проверки подписи.

Структура проекта

seedex-box/files/ содержит пакет роутера:

  • usr/bin/sdx: команда: диспетчер, статус и help.
  • usr/bin/seedex-router-watchdog: проверяет туннели и переключает overlay.
  • usr/lib/seedex/common.sh: общие вспомогательные функции: UCI, наборы nftables, проверки и строки статуса.
  • usr/lib/seedex/service.sh: общее для всех сервисов: записи, apply, enable и import.
  • usr/lib/seedex/vpn.sh, proxy.sh, router.sh и dns.sh: по библиотеке на сервис.
  • usr/lib/seedex/vpn/awg.sh и wg.sh: модули VPN-протоколов. Каждый определяет vpn_<proto>_detect, _validate, _endpoints, _up и _down; оба опираются на usr/lib/seedex/wireguard.sh. Сервис VPN и импорт находят протоколы через эти модули и не знают их имён.
  • usr/lib/seedex/link.sh: линк: соединение, синхронизация, выбор и удалённые команды.
  • etc/init.d/seedex: объединяющий сервис, который запускает остальные по порядку.
  • etc/init.d/seedex-*: по procd-сервису на модуль. В init-скрипте только то, что запускает и останавливает его сервис, и функции, которые больше никто не вызывает; всё, что нужно второму скрипту или sdx, лежит в usr/lib/seedex/.
  • etc/config/seedex-*: документированные UCI-конфиги, по умолчанию пустые.
  • etc/hotplug.d/net/50-seedex-proxy: подключает интерфейс Proxy, когда sing-box его поднимает.

seedex-box/package/ содержит скрипты пакета для установки, обновления и удаления. Они входят и в apk-, и в ipk-пакеты.

luci-app-seedex/files/ содержит приложение для LuCI:

  • usr/libexec/rpcd/luci.seedex: rpcd-бэкенд, с которым общается LuCI. Он запускает sdx.
  • www/luci-static/resources/seedex/api.js: JavaScript-клиент бэкенда и общие виджеты.
  • www/luci-static/resources/view/seedex/*.js: по представлению на вкладку.

На верхнем уровне build.sh собирает пакеты, install.sh — скрипт, который запускают пользователи, version хранит версию.

Сборка

Выполните команду:

make build

Команда собирает seedex-box и luci-app-seedex в build/noarch/ как .apk для OpenWrt 25.x и .ipk для 24.10, вместе с обоими индексами фида, и кладёт публичные ключи в build/keys/.

Чтобы установить сборку на роутер, скопируйте install.sh, build/keys и build/noarch на роутер и выполните там sh install.sh noarch/*.apk, а на 24.10 — sh install.sh noarch/*.ipk.

Линт

make lint прогоняет shfmt и shellcheck по всем shell-файлам, проверяет синтаксис JavaScript и валидирует JSON-файлы.

Участие

Сообщения об ошибках, предложения и пул-реквесты приветствуются. Оригинал этого раздела на английском — CONTRIBUTING.md в репозитории.

Сообщить об ошибке

Откройте issue и укажите:

  • Версию OpenWrt и модель роутера.
  • Вывод sdx version, sdx и sdx logs.
  • Что вы сделали, чего ожидали и что произошло вместо этого.

Перед публикацией уберите из вывода ключи, токены, отпечатки сертификатов и публичные IP-адреса.

Предложить изменение

Для небольшого исправления откройте пул-реквест. Для новой функции или изменения поведения сначала откройте issue, чтобы договориться о подходе до того, как вы потратите на него время.

Стиль кода

  • Пакет роутера работает на BusyBox ash. Пишите на POSIX sh: без массивов, без [[ ]], без local вне функций — ничего, чего нет в ash. build.sh — единственный скрипт, который выполняется на машине разработчика, и он использует bash.
  • Форматирование задают shfmt и .editorconfig: табы в shell, два пробела в остальном, строки до 100 символов.
  • Каждый shell-файл проходит shellcheck с правилами из .shellcheckrc. Не добавляйте # shellcheck disable, чтобы заглушить предупреждение, которое можно исправить.
  • Представления LuCI — обычный JavaScript, который браузер выполняет как есть: без сборки и без зависимостей. Бэкенд rpcd — такой же shell-скрипт, как и остальное.
  • Следуйте окружающему коду: именованию, плотности комментариев и способу сообщать об ошибках.

Проверка

Перед пушем запустите make lint (см. Линт); CI выполняет ту же цель на каждый push и пул-реквест. Автоматических тестов нет: соберите пакеты, установите их на роутер, проверьте изменение: затронутые команды sdx, а также страницу LuCI, если оно её касается. Напишите в пул-реквесте, что вы проверили и на какой версии OpenWrt.

Коммиты

  • Одна тема на коммит. Последующие исправления складывайте в тот коммит, который они исправляют, а не добавляйте вторым.
  • Заголовок — строчными буквами, в настоящем времени, начинается с области: router: list matchers replace, add-, del-, link: menu keeps only offered configs, install: reinstall local ipk of the same version. Области — сервисы (vpn, proxy, router, dns, link), import, install, package, luci и docs.
  • Не меняйте version. Мейнтейнеры поднимают версию через make bump при релизе; тег v* собирает фид.

Пул-реквесты

  • Целевая ветка — main; изменение должно быть достаточно небольшим, чтобы его можно было просмотреть за один раз.
  • Опишите, что делает изменение и зачем. Если есть issue, сошлитесь на него.
  • Изменение видимого пользователю поведения меняет и документацию: README в репозитории и страницы в seedex-docs, где русская версия зеркальна английской.
  • CI должен проходить.

Лицензия

Вклад принимается на условиях лицензии проекта GPL-2.0. Название и логотип Seedex регулируются политикой товарных знаков, а не лицензией.

Последнее обновление