Files
luci-app-owrt-remote/docs/OPENWRT_PACKAGES.md
T
kzolotarev95 9736aa82a8
OpenWrt IPK and APK / Validate source and resolve stable SDKs (push) Waiting to run
Add native OpenWrt IPK/APK packages and release build workflow
2026-11-07 16:03:39 +04:00

13 KiB
Raw Blame History

Пакеты OpenWrt Remote

Исходники пакета luci-app-owrt-remote находятся в package/luci-app-owrt-remote/. Пакет содержит агент, CGI-панель, LuCI, Heartbeat, управление Xray, WAN direct и журнал. Файлы берутся непосредственно из files/, которую использует install.sh; отдельная копия агента не ведётся.

Это пакеты проекта для OpenWrt, а не включение проекта в официальный feed OpenWrt. Публикация в Releases произойдёт только после отправки workflow и выпуска тега.

Какой файл выбрать

OpenWrt Файл Архитектура пакета
23.05.x luci-app-owrt-remote_121-r1_openwrt-23.05_all.ipk all
24.10.x luci-app-owrt-remote_121-r1_openwrt-24.10_all.ipk all
25.12.x luci-app-owrt-remote_121-r1_openwrt-25.12_noarch.apk noarch

В пакете нет ELF-бинарников. Один файл своей ветки подходит aarch64_cortex-a53, aarch64_cortex-a72, aarch64_generic, ARM, MIPS, MIPSEL, MIPS64, x86, x86_64 и другим архитектурам с доступными зависимостями. Формат определяется менеджером пакетов: opkg использует IPK, apk использует APK; они не взаимозаменяемы.

Xray загружается отдельно существующим агентом при применении конфигурации Hub. Его версия, ABI, SHA256 и загрузочный кэш проверяются существующим механизмом. Установка пакета не запускает вложенный opkg/apk и не загружает Xray, пока менеджер пакетов удерживает свою блокировку.

Установка и обновление через LuCI

  1. Скачай пакет своей ветки из GitHub Releases.
  2. Открой Система → Программное обеспечение, обнови списки пакетов.
  3. Нажми Загрузить пакет, выбери файл и подтверди установку.
  4. Открой Службы → OpenWrt Remote и примени OpenWrt config из своей VPS-панели.

Обновление выполняется загрузкой пакета новой версии тем же способом. Перезагрузка роутера не требуется. Зависимости устанавливает менеджер пакетов: luci-base, rpcd-mod-file, uhttpd, jsonfilter, curl, ca-bundle, etherwake. Для их первичной загрузки нужны доступные репозитории своей прошивки.

На OpenWrt 25.12 штатная LuCI принимает сторонний APK только с доверенной подписью. Для подписанных выпусков один раз установи опубликованный публичный ключ проекта в /etc/apk/keys/owrt-remote-packages.pem, проверив его отпечаток по доверенному каналу. Далее подписанные APK устанавливаются через LuCI. Без ключа штатная LuCI отклоняет пакет; для локального неподписанного APK используй SSH-команду ниже. Глобально отключать проверку подписей не нужно.

Установка по SSH из PowerShell Windows 11

Пример для OpenWrt 24.10 и основного роутера 192.168.2.1:

$Repo = "C:\Users\k.zolotarev95\Documents\openwrt overlay"
$Package = Join-Path $Repo "artifacts\openwrt-packages\24.10\luci-app-owrt-remote_121-r1_openwrt-24.10_all.ipk"
ssh root@192.168.2.1 'sysupgrade -b /root/owrt-before-package.tar.gz'
if ($LASTEXITCODE -ne 0) { throw 'Резервная копия не создана' }
scp -O -- "$Package" 'root@192.168.2.1:/tmp/owrt-remote.ipk'
if ($LASTEXITCODE -ne 0) { throw 'Не удалось загрузить пакет' }
ssh root@192.168.2.1 'opkg update && opkg install /tmp/owrt-remote.ipk'
if ($LASTEXITCODE -ne 0) { throw 'Установка не завершена; смотри ошибку выше' }

На OpenWrt 23.05 выбери файл из каталога 23.05. Для OpenWrt 25.12 загрузи файл из 25.12 как /tmp/owrt-remote.apk и выполни:

ssh root@192.168.2.1 'apk update && apk add --allow-untrusted /tmp/owrt-remote.apk'

--allow-untrusted нужен только неподписанному локальному APK. Для подписанного APK с установленным доверенным ключом используется apk add без этого флага. После установки проверь owrt-remote status и owrt-remote doctor. На чистой установке Remote выключен до ввода своего Hub config — это штатно.

Сохранение настроек и откат

/etc/config/owrtremote объявлен conffile. Обновление сохраняет изменённые UCI, ключ /etc/owrt-remote/web.key, Xray, JSON, постоянный кэш и журнал. Ключ панели создаётся только при его отсутствии, с правами 0600, через атомарную замену.

Удаление пакета останавливает и отключает его procd-службы. Пакет не очищает сгенерированные данные пользователя и не запускает uninstall.sh:

# Для IPK:
ssh root@192.168.2.1 'opkg remove luci-app-owrt-remote'
# Для APK:
ssh root@192.168.2.1 'apk del luci-app-owrt-remote'

Для отката к прежнему пакетному выпуску сохрани его файл до обновления, удали новый пакет и установи сохранённый IPK/APK. Изменённый UCI при удалении сохраняется. Чтобы вернуть настройки из сделанной выше резервной копии, извлеки только конфигурацию Remote, затем перезапусти службу:

ssh root@192.168.2.1 'tar -xzf /root/owrt-before-package.tar.gz -C / etc/config/owrtremote && /etc/init.d/owrt-remote restart'

sysupgrade -b сохраняет настройки, а не старые программные файлы. При переходе с install.sh сохрани исходный checkout/предыдущий установщик: удаление пакета само по себе не восстанавливает старую ручную установку.

Сборка

Локальный IPK без SDK можно собрать и проверить на Windows с Python 3.11+:

Set-Location "C:\Users\k.zolotarev95\Documents\openwrt overlay"
python scripts/openwrt_package.py local-ipk --output artifacts/remote-local.ipk
python scripts/openwrt_package.py verify artifacts/remote-local.ipk

Локальный APK создаётся настоящим apk-tools v3 mkpkg из host tools SDK 25.12. Целевой apk на роутере может не содержать команду mkpkg. На Linux:

python3 scripts/openwrt_package.py local-apk --apk /path/to/sdk/staging_dir/host/bin/apk --output artifacts/remote-local.apk

Релизная сборка выполняется официальным SDK на Linux x86_64. Скрипт находит имя SDK в индексе OpenWrt, проверяет SHA256, использует feeds этого SDK, собирает пакет и проверяет содержимое, права, владельца, зависимости и conffiles:

sh scripts/build-openwrt-package.sh --release 24.10.3 --target ramips --subtarget mt7621 --arch mipsel_24kc --output artifacts

SDK поддерживаются в форматах .tar.xz и .tar.zst. Для подготовки автономного каталога пакета внутри своего SDK:

python3 scripts/openwrt_package.py prepare --output /path/to/sdk/package/luci-app-owrt-remote

GitHub Actions и подпись APK

Workflow .github/workflows/openwrt-packages.yml запускается на тегах v*, публикации Release, изменениях пакета в pull request и вручную. Вручную и в PR он только собирает и тестирует; в Releases пишет только запуск по тегу. Тег должен совпадать с PKG_VERSION: текущий пример — v121. Следующий выпуск должен получить новую версию или пакетную ревизию в Makefile.

На каждом запуске выбирается последняя стабильная patch-версия веток 23.05, 24.10 и 25.12. Матрица package/openwrt-targets.json содержит 10 SDK на каждую ветку: A53, A72, generic ARM64, ARM A7/A9, MIPS, MIPSEL, MIPS64, x86 и x86_64. Сохраняются отчёты всех 30 сборок.

После сборки универсальные пакеты устанавливаются в три изолированные x86_64 OpenWrt VM. Проверяется первичная установка, настоящая смена пакетной ревизии, работа CGI, BusyBox ash, службы, удаление, сохранность настроек/ключа/Xray и переход с не принадлежащей пакетному менеджеру конфигурации. Тестовая ревизия из test-fixtures/ не публикуется. Только после успешного завершения всей матрицы публикуются три пакета, SHA256SUMS и отчёты SDK.

Для подписанных APK добавь в GitHub Actions secret OPENWRT_APK_SIGNING_KEY постоянный приватный RSA PEM-ключ сопровождающего. Пример создания на доверенной машине (приватный файл не добавлять в Git):

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out /secure/owrt-remote-private.pem
openssl pkey -in /secure/owrt-remote-private.pem -pubout -out owrt-remote-packages.pem

Workflow подписывает APK, проверяет установку с публичным ключом и добавляет owrt-remote-packages.pem в Release. Приватный ключ остаётся secret/временным файлом runner и не попадает в artifacts. Если secret отсутствует, выпуск APK явно помечается в отчёте как неподписанный и устанавливается по SSH с --allow-untrusted. IPK устанавливается локальным файлом обычным способом. Новый случайный ключ на каждом запуске не создаётся.

Проверки перед публикацией

python3 -m unittest discover -s tests -p test_openwrt_package.py -v
python3 scripts/test-openwrt-package-vm.py --release 24.10.3 --package-dir artifacts --output vm-test

Для VM-теста нужны QEMU, SSH и один основной пакет плюс пакет следующей ревизии в test-fixtures/. SDK-сборка создаёт такой набор с --upgrade-fixture. VM использует только loopback и не подключается к реальным роутерам.

Проверка установки на x86_64 не доказывает работу конкретного Xray на каждом физическом CPU. Xray, Heartbeat с реальным Hub, WAN direct и аппаратные особенности требуют отдельной проверки на устройствах.

Основа реализации: OpenWrt SDK, пакетный Makefile OpenWrt, жизненный цикл пакетов.