Support pinned AWG 3.1 module on NanoPi R3S FriendlyWrt 6.1.141

docs/friendlywrt-awg.md

@@ -0,0 +1,51 @@
+# AmneziaWG 3.1 на NanoPi R3S с FriendlyWrt
+
+Эта адаптация основана на [StressOzz/Zapret-Manager](https://github.com/StressOzz/Zapret-Manager), commit `46eb923f414f5ac2b5bba1f79519696ea57f3b9a`, версия панели 4.68. Версия адаптации — 4.68.1. Изменена установка AWG в LuCI/Web; остальные компоненты продолжают использовать прежние источники.
+
+## Поддерживаемый образ
+
+- NanoPi R3S / R3S LTS, архитектура `aarch64_generic`, цель `rockchip/armv8`.
+- `R3S-Series-FriendlyWrt-25.12.img.gz` из выпуска производителя `FriendlyWrt-2026-10-13`.
+- Пользовательская часть OpenWrt 25.12.5, реально работающее ядро **6.1.141**.
+- SHA256 образа: `3cf37e2b91f80f51dd54d601efc3af8c9f2c69256488b874f9324aa54c34e74a`.
+
+Пакет `kernel` в базе APK этой прошивки сообщает версию 6.12.94. Официальный `kmod-amneziawg` под 6.12.94 на работающем ядре 6.1.141 не загружается. Адаптация проверяет `uname -r`, модель и SHA256 штатных `configs.ko` и `udp_tunnel.ko`.
+
+## Установка панели
+
+Сначала сохранить настройки панели её штатной кнопкой резервного копирования. Затем выполнить по SSH:
+
+```sh
+curl -fL -o /tmp/ZapretManager_LuCI.sh https://gitea.bvrdo.online/wenil/Zapret-Manager/raw/branch/main/ZapretManager_LuCI.sh &&
+sh /tmp/ZapretManager_LuCI.sh
+```
+
+После обновления открыть вкладку **AmneziaWG** и нажать установку или переустановку.
+
+Панель скачает только ядровой модуль из фиксированного тега на Gitea и проверит встроенный SHA256. Утилиты `amneziawg-tools`, протокол LuCI, импорт конфигурации и настройка сети проходят через существующий установщик. Зависимость APK удовлетворяется тем же механизмом виртуального `kmod-amneziawg`, который уже был предусмотрен автором панели для вручную установленного модуля.
+
+При ошибке загрузки, несовпадении SHA256 или отпечатков прошивки установка прекращается. Перехода к модулю официального ядра 6.12.94 для этого профиля нет. Действующая сборка модуля закреплена: обновление утилит через панель не заменяет её случайным новым kmod.
+
+## Автозагрузка, удаление и обновление
+
+Создаётся `/etc/init.d/zm-awg-r3s`, который до запуска сети проверяет ядро и отпечатки файлов, затем загружает штатные зависимости и AWG. Он не меняет маршруты, ключи и firewall. Признак ручной установки хранится в существующем `/etc/zm-awg/kmod-manual`.
+
+Удаление AmneziaWG через панель удаляет также этот init-скрипт. При неудачной записи файлов или регистрации виртуального пакета прежние файлы восстанавливаются. Штатная резервная копия панели сохраняет настройки, а не всю прошивку или бинарный модуль; при восстановлении установщик должен заново получить подходящий модуль.
+
+Обновления самой панели и команда `zmw` получают адаптированную версию с Gitea, чтобы не потерять эту поддержку при обычном обновлении. Автоматическая синхронизация с GitHub автора не настроена: новые версии автора нужно переносить с сохранением изменений AWG. Старый SSH-менеджер `zms` остаётся исходной версией автора; эта адаптация относится к LuCI/Web.
+
+После смены прошивки нужна новая проверка совместимости. Установщик не выбирает модуль только по номеру ядра.
+
+## Проверки и ограничения
+
+Модуль AWG `3.1.20260906` собран из официального тега с поправкой совместимости `timer_delete` для vendor-ядра. Совпали vermagic и CRC всех 198 импортируемых символов; конфигурация извлечена из точного образа. Исходники для пересборки, конфигурация, таблица CRC и подробности находятся в `vendor/awg/r3s-fw20261013/`.
+
+На настоящем R3S загрузка, handshake, скорость и температура пока не проверены. Использован GCC 13.3 вместо GCC 11.3 производителя; точное совпадение commit исходников ядра с commit сборки производителя не подтверждено. Проверки CRC не заменяют испытание на устройстве. Первый тест проводить с возможностью локального восстановления роутера.
+
+Тесты установщика выполняются без роутера и не загружают ядровые модули:
+
+```sh
+python3 tests/check_friendlywrt_awg.py
+```
+
+Они проверяют установку, повторное обновление закреплённого модуля, удаление, порядок загрузки зависимостей, отказ при повреждённой загрузке или другой прошивке, откат при ошибке APK и сохранение обычного пути для официального OpenWrt. Также проверяется синтаксис сгенерированного backend.