Add native OpenWrt IPK/APK packages and release build workflow
OpenWrt IPK and APK / Validate source and resolve stable SDKs (push) Waiting to run

This commit is contained in:
kzolotarev95 committed 2026-11-07 16:03:39 +04:00
1 parent edbc86697a
commit 9736aa82a8
13 files changed
+1413

No files matched your search

+189
View File
@@ -0,0 +1,189 @@
# Пакеты 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](https://github.com/kzolotarev95/luci-app-owrt-remote/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`:
```powershell
$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` и выполни:
```powershell
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`:
```powershell
# Для 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, затем перезапусти службу:
```powershell
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+:
```powershell
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:
```sh
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
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:
```sh
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):
```sh
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 устанавливается локальным файлом обычным способом.
Новый случайный ключ на каждом запуске не создаётся.
## Проверки перед публикацией
```sh
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](https://openwrt.org/docs/guide-developer/toolchain/using_the_sdk),
[пакетный Makefile OpenWrt](https://github.com/openwrt/openwrt/blob/openwrt-25.12/include/package-pack.mk),
[жизненный цикл пакетов](https://github.com/openwrt/openwrt/blob/openwrt-25.12/package/base-files/files/lib/functions.sh).
+48
View File
@@ -0,0 +1,48 @@
# Локальная проверка пакетной установки
Дата: 07.11.2026. Версия приложения: v121, ревизия пакета: 1.
Проверки выполнялись локально; push и публикация Release не выполнялись.
Реальные роутеры и VPS не изменялись.
| Среда | Менеджер | Результат |
| --- | --- | --- |
| OpenWrt 23.05.6 x86_64, QEMU TCG | opkg, IPK `all` | Успешно |
| OpenWrt 24.10.8 x86_64, QEMU TCG | opkg, IPK `all` | Успешно |
| OpenWrt 25.12.6 x86_64, QEMU TCG | apk, APK v3 `noarch` | Успешно |
В каждой VM проверены:
- Чистая установка и загрузка зависимостей из репозиториев соответствующей прошивки.
- Создание приватного ключа панели, доступность CGI и пунктов LuCI.
- Синтаксис всех shell-файлов пакета штатным BusyBox ash.
- Работа службы журналов и сохранение выключенного по умолчанию Remote.
- Обновление с ревизии 1 на отдельный пакет ревизии 2.
- Побайтовое сохранение изменённого UCI, ключа панели, Xray JSON и бинарника-заглушки.
- Удаление файлов пакета и сохранение изменённой конфигурации/сгенерированных данных.
- Повторная установка с конфигурацией, не принадлежащей менеджеру пакетов.
Дополнительно:
- 16 автоматических тестов сборочного инструмента прошли.
- `actionlint v1.7.12` не обнаружил ошибок workflow.
- Проверены все 30 URL SDK и их записи SHA256 в официальных индексах:
10 целевых архитектур для каждой из трёх веток.
- Подтверждён отказ штатного apk от неподписанного APK без `--allow-untrusted`.
- APK подписан отдельным тестовым RSA-ключом; после добавления публичного
ключа штатный apk принял его без `--allow-untrusted` в проверке `--simulate`.
Тестовый приватный ключ не входит в исходники или установочные артефакты.
- Установка не вызывала скачивание/замену рабочего Xray внутри пакетной транзакции.
Локальные IPK созданы переносимым сборщиком из тех же исходников; APK создан
настоящим `apk-tools 3.0.9 mkpkg` в изолированной VM. Полная компиляция через
30 официальных SDK здесь не запускалась: она подготовлена в GitHub Actions.
Доступность SDK не равнозначна успешной сборке; публикация workflow зависит
от успешного завершения SDK-матрицы и последующих VM-тестов.
Физические ARM/MIPS-устройства, действующий Heartbeat, WAN direct и туннель
Xray с реальным Hub в этой проверке не тестировались. Код этих механизмов
не изменён пакетной доработкой.
Локальные протоколы находятся в `.test-output/vm-23.05/`,
`.test-output/vm-24.10/`, `.test-output/vm-25.12/`. Готовые тестовые пакеты —
в `artifacts/openwrt-packages/`. Эти каталоги исключены из Git.