Files
luci-app-owrt-remote/docs/TACHYON_INTEGRATION.md
T
kzolotarev95 70a4705e67
OpenWrt IPK and APK / Validate source and resolve stable SDKs (push) Waiting to run
Release v122 with Tachyon integration and resilient Xray downloads
2026-11-21 22:53:52 +04:00

242 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tachyon в карточке роутера
Интеграция включена в Remote Hub v122. Обновить нужно Hub на VPS и агент
на роутере; Tachyon устанавливается отдельно и автоматически не загружается.
## Обнаружение
Агент проверяет установленные пакеты tachyon и luci-app-tachyon через
действующий менеджер пакетов: APK либо opkg. Проверка не обращается к репозиториям
и не устанавливает зависимости. Открытый порт без установленного пакета
не создаёт интеграцию.
Короткая проверка procd и HTTP различает наличие пакета и доступность интерфейса.
Для ветки 2.x порт берётся из tachyon.settings.listen_port, по умолчанию 1680.
Для старых версий используется LuCI через существующий вход Админки. В старой
ветке listen_port может относиться к прокси, поэтому этот параметр не принимается
за порт веб-интерфейса.
Результат включается в защищённый Heartbeat. Кэш обнаружения находится только
в /tmp/owrt-remote-tachyon, обновляется не реже раза в 30 секунд и не содержит
конфигураций или секретов. Временные файлы удаляются; размер файла ограничен.
Неудачная проверка пакетов не считается удалением Tachyon. Hub сохраняет
последний подтверждённый факт установки, но показывает Offline.
У каждого роутера отдельное состояние. После успешной проверки отсутствующего
пакета блок исчезает. После новой установки он появляется автоматически. Смена
только состояния службы не перезапускает серверный Xray.
## Удалённый доступ
Кнопка открывает /tachyon/ROUTER_ID/ в отдельной вкладке. Проверяется вход
в Hub и право Админки A именно на выбранный роутер. Изменяющие запросы
дополнительно проверяют Origin/Referer. Пароли и токены не добавляются в URL.
Для отдельного веб-сервера Hub выделяет свободный вход Xray, доступный только
на 127.0.0.1 VPS. Он использует уже существующий аутентифицированный reverse
канал Админки. В клиенте добавляется правило только для обнаруженного TCP-порта
127.0.0.1:PORT и соответствующего reverse-тега. Остальной HTTP и SSH идут
по прежним правилам. Адрес назначения фиксирован; HTTP-запрос не может выбрать
другой хост или порт.
При установке, удалении или смене порта Tachyon агент обновляет конфигурацию
только своего Xray. Возможен короткий разрыв обратного туннеля. Heartbeat
продолжает работать; ручная остановка Xray через Remote сохраняется. Автоматическая
операция использует общую блокировку с Remote управлением Xray.
Настройки Tachyon, WAN, DNS, Podkop, firewall и policy routing не меняются.
HTML, LuCI-ресурсы, fetch/XHR и REST-пути переписываются с префиксом выбранного
роутера. Cookies Tachyon получают собственный путь; сессионные cookies Hub
не отправляются на роутер. Старый Tachyon открывается через существующий
авторизованный прокси LuCI.
Online означает свежий Heartbeat, запущенный процесс Xray и доступность
интерфейса по локальной проверке агента. Это не заменяет фактическую проверку
открытия страницы: внешняя проблема туннеля может проявиться при переходе.
Offline сохраняет кнопку, чтобы не путать недоступность с удалением пакета.
## Реальные интерфейсы Tachyon
Изучены [main](https://github.com/Dushnilin/tachyon) и исходники установленной
у пользователя версии
[v2.0.0-beta.8](https://github.com/Dushnilin/tachyon/tree/v2.0.0-beta.8) и
[v2.0.0-beta.14](https://github.com/Dushnilin/tachyon/tree/v2.0.0-beta.14).
Архитектура этих веток различается, поэтому одного README недостаточно.
В beta.8 Rust HTTP-сервер отдаёт LuCI SPA и ubus-мост на 1680. REST API находится
в /api/agent/v1, включая health и openapi.json; CGI-подобный alias
/cgi-bin/tachyon-agent обслуживается этим же Rust-сервером. Он не означает,
что такой CGI-файл есть у uhttpd на 80. API проверяет сессию, Bearer token либо
доверенный локальный адрес. Интеграция не извлекает и не сохраняет API-токены:
открытие происходит через авторизованный Hub, а оригинальная авторизация
Tachyon сохраняется.
В другой изученной ветке CGI /cgi-bin/tachyon-agent относится к uhttpd.
Агент проверяет существование файла и успешный read-only health-ответ перед
передачей метаданных API. Для Rust API на обнаруженном порту проверяется
типизированное поле core_running; остановленное ядро не приравнивается
к отсутствию REST API. Если OpenAPI сообщает версию работающей программы,
она отображается в карточке; версия пакета сохраняется отдельно в package_version.
Управление Tachyon через отдельные Hub-команды
в эту реализацию не входит.
## Локальная установка и откат
Сначала обновить VPS, затем агент роутера:
~~~powershell
$Fix = Join-Path $env:USERPROFILE 'Documents\openwrt overlay\vps\deploy-tachyon.ps1'
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Install
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Router root@192.168.2.1 -Action Install
~~~
Пароль вводится в SSH, не передаётся в аргументах. Скрипт проверяет синтаксис,
создаёт резервную копию, сверяет установленные файлы и проверяет запуск
Heartbeat либо ревизию работающего Hub. База и конфиг owrtremote сохраняются.
Миграция базы добавляет один совместимый столбец для внутреннего порта.
Откат в обратном порядке:
~~~powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Router root@192.168.2.1 -Action Rollback
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Rollback
~~~
Копия на каждом устройстве: /root/owrt-remote-backup-before-tachyon-integration-v121.
При откате VPS прежний генератор пересоздаёт конфигурацию Xray без нового входа.
Дополнительный столбец базы безвреден для прежнего Hub и не удаляется.
Проверка после установки:
~~~powershell
ssh root@192.168.2.1 'owrt-remote tachyon-status'
~~~
Дождаться одного Heartbeat и обновить страницу Hub через Ctrl+F5. При обычном
интервале обнаружение занимает до 30–60 секунд. Для проверки локального кода
использовать этот скрипт, поскольку опубликованная сборка GitHub пока другая.
## Проверки
По предоставленному пользователем выводу реального роутера: пакет
tachyon 2.0.0~beta.8-1, служба tachyon запущена, uhttpd на 80,
tachyon.settings.listen_port=1680, HTTP 200 на loopback и LAN:1680,
старый LuCI URL возвращает 403. CGI REST на uhttpd не найден.
Дополнительные GET-запросы с компьютера подтвердили HTTP 200 для корневой
страницы, /api/agent/v1/health и /api/agent/v1/openapi.json на порту 1680.
Health сообщил core_running=true; OpenAPI и заголовок страницы сообщили
2.0.0-beta.14, хотя пакетный менеджер показывает beta.8. Эти версии намеренно
не смешиваются. Переустановка или обновление Tachyon не выполнялись.
Локальные тесты проверяют opkg/APK, старый LuCI, собственный порт, остановку,
ошибку инвентаризации, удаление/переустановку, независимость роутеров,
потерю/восстановление Heartbeat, запрещённые адреса/порты и ручную остановку Xray.
HTTP-тесты проверяют 401/403, выбор роутера, изоляцию cookies, REST POST/PUT/DELETE
и защиту Origin. Node проверяет появление/исчезновение блока, Offline,
экранирование и обе реализации карточек.
Настоящие Xray 26.6.27 (клиент) и 26.10.21 (сервер) успешно провели одновременно
HTTP Админки, SSH и отдельный HTTP Tachyon с разными ответами. Проверены оба
генератора конфигурации. Это стенд на loopback, не реальный удалённый роутер.
Дополнительно прошли 41 регрессия WAN/Heartbeat, 22 проверки пакетов и проверки
Remote управления Xray. Установку/удаление и остановку Tachyon на рабочем
роутере ради теста не выполняли; установка локальной интеграции на него
и проверка через рабочую VPS ещё предстоят.
Четыре сценария обнаружения и генерации выполнены в Linux на BusyBox ash 1.36.1.
Пять сценариев установщика проверяют повторную установку, откат с удалением
ранее отсутствовавшего helper, ошибки preflight и восстановление после отказа
перезапуска. Дополнительные команды пакетов на рабочем роутере не выполнялись.
В отдельной Ubuntu 24.04 выполнены установка нового Hub и откат этим же
PowerShell-скриптом: работающая ревизия подтверждена в обоих случаях.
Проверено также переписывание настоящего HTML интерфейса с роутера и синтаксис
встроенных скриптов после переписывания.
Изменённые и добавленные файлы: files/usr/sbin/owrt-remote,
files/usr/lib/owrt-remote/tachyon.sh, install.sh, uninstall.sh, vps/owrt-remote-hub.py,
vps/deploy-tachyon.ps1, vps/diagnose-tachyon.ps1, tests/test_tachyon.py,
tests/test_tachyon_ui.cjs, tests/test_tachyon_deploy.py, tests/test_xray_reverse_transport.py,
README.md и этот документ.
## Исправление для VPS с Xray 26.3.27
На рабочем сервере подтверждён Xray 26.3.27. Этот выпуск принимает имя
протокола tunnel, но использует исходные настройки network/address/port,
игнорируя новые allowedNetwork/rewriteAddress/rewritePort. Поэтому в reverse
передавался порт входа VPS вместо 1680, правило клиента не совпадало и запрос
получал обычную Админку. Это объясняет переход на /cgi-bin/luci/.
Генератор Hub теперь выдаёт оба набора полей с одинаковыми значениями.
На настоящем Xray 26.3.27 ошибка воспроизведена до исправления: отдельный вход
Tachyon возвращал ответ HTTP-стенда Админки. После исправления он возвращает
ответ именно Tachyon; HTTP Админки и SSH продолжают работать.
Для уже установленной локальной интеграции нужно применить исправление на VPS:
~~~powershell
$Fix = Join-Path $env:USERPROFILE 'Documents\openwrt overlay\vps\deploy-tachyon-route-fix.ps1'
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Install
~~~
Скрипт сохраняет текущие файлы Hub и Xray, дополняет только настройки
управляемых Remote входов, проверяет JSON установленным Xray, затем применяет
изменения и перезапускает Hub и серверный Xray. Остальные параметры JSON,
включая порт VLESS, клиентов и посторонние службы, сохраняются.
На время перезапуска возможен короткий разрыв туннелей. Бинарники Xray
и файлы роутера не меняются.
Откат именно этого исправления:
~~~powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Rollback
~~~
Оба файла восстанавливаются из
/root/owrt-remote-backup-before-tachyon-route-fix-v121. Неудачная проверка Xray
останавливает установку до замены файлов; отказ перезапуска вызывает
восстановление копии текущей попытки.
Дополнительно добавлены vps/deploy-tachyon-route-fix.ps1,
vps/diagnose-tachyon-vps.ps1 и tests/test_tachyon_route_deploy.py.
Диагностика VPS передаёт код в base64, чтобы Windows PowerShell не повреждал
завершение Python heredoc. По первоначальному выводу данные были собраны
полностью; завершающий NameError: PY относится к передаче скрипта, а не к Xray.
## Пустое место над интерфейсом
Общий обработчик оформления Hub первоначально исключал /access/, но не новый
маршрут /tachyon/. В страницу Tachyon попадало правило общих эффектов,
устанавливающее position:relative для прямых дочерних элементов body.
Оно переопределяло position:fixed у .tachyon-bg-layer. Фон становился обычным
блоком и сдвигал панель ниже первого экрана; в браузере воспроизведён отступ 720 px.
Обработка /tachyon/ теперь сохраняет собственные CSS и JavaScript Tachyon.
Переписывание URL для удалённого доступа продолжает работать.
Принудительная прокрутка и дополнительные отступы не добавляются.
Для уже установленной интеграции:
~~~powershell
$Fix = Join-Path $env:USERPROFILE 'Documents\openwrt overlay\vps\deploy-tachyon-layout.ps1'
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Install
~~~
Откат:
~~~powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $Fix -Vps root@132.243.19.232 -Action Rollback
~~~
Установка меняет только файл Hub и перезапускает его веб-службу. Копия:
/root/owrt-remote-backup-before-tachyon-layout-v121. Файлы роутера и конфигурация
Xray при установке этого исправления не меняются.
Проверки: два теста общих тем, два HTTP-теста прокси и 18 браузерных сочетаний
1280x900 / 390x844 / 844x390 с сохранёнными режимами default / winter / lite.
В браузере проверены самостоятельный пример и настоящий HTML Tachyon beta.14:
фон имеет position:fixed, верх maincontent находится на 0 px, прокрутка равна
нулю, дополнительный canvas Hub отсутствует. Загрузка RPC в этой проверке
отключена, поэтому параметры роутера не изменяются.
Дополнительно добавлены vps/deploy-tachyon-layout.ps1 и tests/test_tachyon_layout.cjs;
обновлены tests/test_hub_design_global.py и tests/test_tachyon.py.