Release v2.0.0
CI / Windows baseline (push) Canceled after 0s

This commit is contained in:
2026-09-10 20:59:52 +03:00
parent 9c987df6e9
commit efda8eb98f
142 changed files with 68308 additions and 9333 deletions
+129 -183
View File
@@ -1,35 +1,36 @@
# ProxyWarden
ProxyWarden - это standalone Windows desktop-приложение для маршрутизации выбранных программ через SOCKS5-прокси. По сути это удобная оболочка управления над внешними компонентами: обязательным маршрутизатором приложений ProxiFyre и, опционально, локальным runtime `sing-box`.
ProxyWarden standalone Windows desktop-приложение для маршрутизации выбранных программ через SOCKS5-прокси. Оно управляет обязательным ProxiFyre и, при необходимости, локальным `sing-box`, но само не является VPN-драйвером, proxy server или облачным control plane.
ProxyWarden сам не является VPN-драйвером, прокси-сервером или отдельным gateway/server. Он хранит настройки, показывает состояние компонентов, генерирует конфиги и запускает только явные действия пользователя: установить, запустить, остановить, удалить или применить конфиг.
Все системные действия остаются явными: `apply` только проверяет и применяет конфигурацию; установка, обновление, запуск, остановка, перенос и удаление компонентов выполняются отдельными командами пользователя.
## Главное
- Работает как Windows-клиент: Tauri 2 + React/TypeScript UI + Rust backend.
- Маршрутизирует не всю систему, а выбранные приложения: процесс, папку или конкретный `.exe`.
- Не меняет глобальный proxy в Windows.
- Для per-app routing нужен ProxiFyre.
- Local sing-box нужен только для сценария с подпиской и локальным SOCKS5 endpoint.
- Внешний SOCKS5-прокси работает без Local sing-box.
- Применение профиля не устанавливает и не чинит компоненты скрыто.
- Tauri 2 + React/TypeScript UI + Rust backend.
- Маршрутизируются выбранные процессы, папки или `.exe`, а не вся система.
- Глобальный Windows proxy не меняется.
- Внешний SOCKS5 работает без Local sing-box.
- Production runtime не запускает PowerShell: service/install/UAC orchestration принадлежит native Rust.
- x64 installer содержит проверенные offline payloads компонентов и WebView2 Offline Installer; сеть для baseline-установки не нужна.
## Из чего состоит
## Компоненты
| Компонент | Что это | Нужен когда | Откуда берется |
| --- | --- | --- | --- |
| ProxyWarden Control App | Окно управления, настройки, status/readiness, генерация конфигов | Всегда | Этот репозиторий |
| [ProxiFyre](https://github.com/wiresock/proxifyre) | Windows-приложение/служба для перехвата трафика выбранных процессов и отправки его в SOCKS5 | Всегда для маршрутизации приложений | GitHub releases `wiresock/proxifyre` |
| [Windows Packet Filter / NDISAPI](https://github.com/wiresock/ndisapi) | Сетевой драйвер, который нужен ProxiFyre | Устанавливается вместе с ProxiFyre, если отсутствует | GitHub releases `wiresock/ndisapi` |
| [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist) | Runtime-зависимость для `ProxiFyre.exe` | Устанавливается вместе с ProxiFyre, если отсутствует | Официальный `vc_redist` Microsoft |
| [sing-box](https://github.com/SagerNet/sing-box) | Локальный proxy/VPN runtime, который слушает `127.0.0.1:1080` | Только для маршрута через subscription/выбранный сервер | GitHub releases `SagerNet/sing-box` |
| [WinSW](https://github.com/winsw/winsw) | Wrapper, который запускает Local sing-box как Windows-службу | Только для Local sing-box | GitHub releases `winsw/winsw` |
| Компонент | Роль | Когда нужен |
| --- | --- | --- |
| ProxyWarden Control App | UI, storage, validation, config generation и orchestration | Всегда |
| [ProxiFyre](https://github.com/wiresock/proxifyre) | Перехватывает трафик выбранных приложений и направляет его в SOCKS5 | Для любого per-app routing |
| [Windows Packet Filter / NDISAPI](https://github.com/wiresock/ndisapi) | Сетевой драйвер ProxiFyre | Устанавливается вместе с ProxiFyre, если отсутствует |
| [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist) | Runtime-зависимость ProxiFyre | Устанавливается при необходимости |
| [sing-box](https://github.com/SagerNet/sing-box) | Создаёт локальный SOCKS5 endpoint для выбранного subscription-сервера | Только для Local sing-box flow |
| [WinSW](https://github.com/winsw/winsw) | Запускает sing-box как Windows-службу | Только для Local sing-box flow |
В UI и коде компонент ProxiFyre иногда проходит через внутренний id `proxyfier`. Это не отдельный продукт Proxifier; текущий backend adapter работает именно с ProxiFyre.
Версии, SHA-256 и лицензии offline payloads зафиксированы в packaged component catalog. Установка Control App не запускает routing-компоненты: нужный компонент устанавливается отдельным действием в UI.
## Как идут маршруты
В UI и части внутренних DTO ProxiFyre может иметь исторический id `proxyfier`. Это не продукт Proxifier.
Внешний SOCKS5-прокси:
## Маршруты
Внешний SOCKS5:
```text
выбранные приложения -> ProxiFyre -> внешний SOCKS5 proxy
@@ -38,192 +39,140 @@ ProxyWarden сам не является VPN-драйвером, прокси-с
Local sing-box:
```text
выбранные приложения -> ProxiFyre -> Local sing-box 127.0.0.1:1080 -> выбранный сервер из подписки
выбранные приложения -> ProxiFyre -> Local sing-box 127.0.0.1:1080 -> выбранный subscription-сервер
```
Во втором сценарии ProxiFyre все равно обязателен: именно он делает маршрутизацию конкретных Windows-приложений. Local sing-box только дает локальный SOCKS5 endpoint и ходит дальше к выбранному серверу.
Во втором маршруте ProxiFyre по-прежнему отвечает за выбор приложений. Local sing-box только предоставляет локальный SOCKS5 endpoint и соединяется с выбранным сервером.
## Что устанавливается
## Установка и системные пути
### Control App
Обычная сборка Tauri создает desktop-приложение ProxyWarden. Отдельный скрипт `scripts/install-control-app.ps1` сейчас подготавливает стандартные директории:
Tauri NSIS installer устанавливает Control App per-machine. Managed runtime-компоненты лежат только под текущим app root:
```text
C:\Program Files\ProxyWarden\ControlApp
C:\ProgramData\ProxyWarden\config
C:\ProgramData\ProxyWarden\state
C:\ProgramData\ProxyWarden\generated
C:\Program Files\ProxyWarden
C:\Program Files\ProxyWarden\components\ProxiFyre
C:\Program Files\ProxyWarden\components\sing-box
```
### ProxiFyre
Явная установка ProxiFyre из приложения выполняется через elevated PowerShell и ставит/обновляет:
Службы:
```text
C:\Tools\ProxiFyre
C:\Tools\ProxiFyre\ProxiFyre.exe
C:\Tools\ProxiFyre\app-config.json
Windows service: ProxiFyreService
ProxiFyreService
ProxyWardenSingBox
```
Если на машине не найдены зависимости, установщик также скачивает и ставит Microsoft Visual C++ Redistributable и Windows Packet Filter / NDISAPI.
ProxyWarden управляет службой только после точной проверки `PathName`, marker/receipt и canonical component root. Похожее имя службы или найденная папка сами по себе не дают права на start/stop/delete.
### Local sing-box
## Релиз одной командой
Явная установка Local sing-box ставит:
В PowerShell из корня проекта:
```powershell
.\release.cmd
```
То же действие доступно как `npm run release`. Сценарий показывает изменения Git и предлагает patch/minor/major, произвольную версию или текущую ещё не выпущенную версию. Можно сразу ввести номер вроде `1.2.1`.
После выбора он синхронизирует версии в package.json, package-lock.json, tauri.conf.json, Cargo.toml и Cargo.lock, проверяет frontend/Rust/offline bundle, собирает NSIS и готовит папку `releases/proxywarden-vX.Y.Z`. Затем создаёт commit со всеми текущими отслеживаемыми и неигнорируемыми новыми файлами, annotated tag `vX.Y.Z` и одним atomic push отправляет текущую ветку и этот тег в `origin`. При отсутствии изменений новый commit не нужен. Артефакты не попадают в Git.
В папке релиза: `artifacts/nsis/ProxyWarden_X.Y.Z_x64-setup.exe`, `SHA256SUMS.txt`, `release-manifest.json` с точным commit/hash и `release-notes.md`. EXE загружается на сайт вручную; GitHub/Gitea release page автоматически не создаётся.
Нужны Git с настроенной identity и доступом к origin, Node, установленные frontend-зависимости (`npm ci` один раз), Rust/MSVC/Windows SDK. Сам сценарий сборки использует Node напрямую и не требует npm в PATH. Запуск от администратора не нужен.
```powershell
.\release.cmd -PlanOnly # только JSON-план: без записи, сборки и сети
.\release.cmd -Version 1.2.1 # версия без вопроса
.\release.cmd -Version 1.2.1 -Resume # повторить только неудачный push
```
Не меняйте исходники во время сборки. Существующие теги не перезаписываются; при расхождении с удалённой веткой сценарий останавливается до изменения версий. При ошибке сборки изменения версии остаются локально для исправления, commit/tag/push не выполняются. При неудачном push готовая папка и локальный commit/tag сохраняются; `-Resume` проверяет исходники и SHA-256 перед повторной отправкой.
Для локальной подготовки без commit/tag/push остаётся `scripts/prepare-release.ps1 -Version X.Y.Z`. Автоматические проверки не заменяют Windows VM/UAC/driver/routing acceptance: в manifest это отмечается отдельно.
## Данные и source of truth
Настройки и состояние лежат под `C:\ProgramData\ProxyWarden`:
```text
C:\Program Files\ProxyWarden\sing-box\sing-box.exe
C:\Program Files\ProxyWarden\sing-box\ProxyWardenSingBox.exe
C:\Program Files\ProxyWarden\sing-box\ProxyWardenSingBox.xml
C:\Program Files\ProxyWarden\sing-box\config.json
Windows service: ProxyWardenSingBox
config\profiles.json
config\targets.json
config\local-singbox.json
config\storage-meta.json
state\activity.json
state\component-layout.json
state\component-updates.json
state\migrations\...
packages\...
```
`ProxyWardenSingBox.exe` - это WinSW wrapper. Он нужен только чтобы запускать `sing-box.exe` как Windows-службу.
`config\components.json` не является текущим источником статуса компонентов. Это только legacy input: migration может проверить, сохранить snapshot/archive и затем перестать использовать его. Фактический install/service/version status читается из native inventory Windows и проверенных receipts.
Generated artifacts можно пересоздать:
```text
generated\proxifyre-app-config.json
generated\sing-box-config.json
```
Не редактируйте generated-файлы как основной источник правды. Subscription URL, userinfo, credentials, proxy password и внутренние migration/job records нельзя выводить целиком в UI, logs или diagnostics.
## Миграция старой установки
- Startup выполняет только безопасную storage adoption/migration: backup, validation, atomic commit и повторный no-op.
- Старые component roots и службы сначала обнаруживаются read-only.
- Перенос компонента — отдельное UAC-действие с exact identity checks, rollback journal и quarantine.
- Foreign или incomplete installation не управляется автоматически.
- Пока cutover journal активен, требует recovery или quarantine ещё не подтверждён к удалению, upgrade/uninstall блокируется до безопасного завершения.
## Права администратора
Без прав администратора можно открыть приложение, редактировать настройки, добавлять приложения, вводить внешний proxy, загружать/выбирать подписку и смотреть состояние.
Без UAC можно редактировать настройки, выбирать приложения и proxy, загружать subscription, смотреть статус и генерировать конфигурацию.
Права администратора или UAC confirmation нужны для операций, которые меняют систему:
UAC требуется для явных действий, которые меняют Windows:
- установка или удаление ProxiFyre;
- установка Windows Packet Filter / NDISAPI;
- установка Microsoft Visual C++ Redistributable, если его нет;
- установка или удаление Local sing-box;
- создание, запуск и остановка Windows-служб;
- удаление install folder для managed-компонентов.
- install/update/uninstall ProxiFyre или Local sing-box;
- установка Windows Packet Filter и VC++ Runtime при необходимости;
- start/stop/create/delete Windows-служб;
- подтверждённый legacy component cutover и его cleanup.
Применение профиля не запускает установку. Оно генерирует derived config и пытается записать его в найденную установку ProxiFyre. Если прав на запись в папку установки не хватает, операция должна завершиться ошибкой, а не устанавливать что-то скрыто.
## Поддержанная среда
Подтверждено вручную сейчас:
```text
Windows 11
PowerShell 7 как пользовательская shell для запуска команд разработки
```
Важно: Rust backend и elevated-операции сейчас запускают именно `powershell.exe` с `-NoProfile` и `-ExecutionPolicy Bypass`. На Windows это обычно Windows PowerShell 5.1. Скрипты используют стандартные команды вроде `Get-CimInstance`, `Invoke-WebRequest`, `Expand-Archive`, `Get-FileHash`, `Start-Service`, `Stop-Service`, `ConvertTo-Json`, поэтому должны быть близки к Windows PowerShell 5.1, но полный ручной тест пока был только на Windows 11 с PowerShell 7 в окружении разработки.
Ожидаемая, но не полностью подтвержденная область:
- Windows 10/11 desktop;
- x64 как основной сценарий;
- x86 и ARM64 частично учтены в installer-логике через выбор release assets, но не считаются проверенными;
- обычный desktop/laptop без специальных требований к GPU;
- доступ в интернет к GitHub releases и Microsoft download endpoints для установки компонентов.
Linux/macOS не являются целевой платформой для этого клиента.
## Где лежат настройки
Source of truth лежит в JSON под `C:\ProgramData\ProxyWarden`:
```text
C:\ProgramData\ProxyWarden\config\profiles.json
C:\ProgramData\ProxyWarden\config\targets.json
C:\ProgramData\ProxyWarden\config\components.json
C:\ProgramData\ProxyWarden\config\local-singbox.json
C:\ProgramData\ProxyWarden\state\activity.json
C:\ProgramData\ProxyWarden\state\singbox-subscription-cache.json
```
Сгенерированные файлы лежат отдельно и могут быть пересозданы:
```text
C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json
C:\ProgramData\ProxyWarden\generated\sing-box-config.json
```
Не редактируйте generated-файлы как основной источник правды. При следующей генерации они могут быть перезаписаны.
Subscription URL считается секретом. UI и diagnostics должны показывать только редактированную/сокращенную версию ссылки.
При загрузке подписки ProxyWarden отправляет провайдеру стандартные идентификационные заголовки приложения и `X-HWID` - случайный постоянный UUID этой установки. Это не серийный номер оборудования, но провайдер может использовать его для связывания запросов одной установки. Проверка маршрута делает HTTPS-запросы через выбранный proxy к Cloudflare и ipify, чтобы подтвердить выход и определить внешний IP.
Elevated mode принимает только заранее записанный typed job ID либо один из фиксированных NSIS modes. UI не передаёт произвольную команду, script text или install path.
## Типовые сценарии
### Внешний SOCKS5
1. Запустите ProxyWarden.
2. Установите или проверьте ProxiFyre.
3. На вкладке `VPN / Прокси` выберите внешний proxy.
4. Введите `host:port` или `socks5://host:port`.
5. На вкладке `ProxiFyre` добавьте приложения.
6. Нажмите `Применить в ProxiFyre`.
1. Установите ProxiFyre явной кнопкой, если он отсутствует.
2. На вкладке `VPN / Прокси` выберите внешний proxy и укажите `host:port` или `socks5://host:port`.
3. Добавьте приложения в ProxiFyre route.
4. Нажмите `Применить`.
Local sing-box для этого сценария не нужен.
### Local sing-box с подпиской
1. Запустите ProxyWarden.
2. Установите ProxiFyre.
3. Установите Local sing-box.
4. Вставьте subscription URL.
5. Загрузите список серверов и выберите сервер.
6. Добавьте приложения.
7. Сгенерируйте/примените маршрут.
1. Явно установите ProxiFyre и Local sing-box.
2. Добавьте subscription URL, загрузите список и выберите сервер.
3. Добавьте приложения и примените маршрут.
## Установка и запуск из исходников
## Разработка
Нужны:
- Windows 11 для подтвержденного пути разработки;
- Node.js и npm;
- Rust через rustup;
- Visual Studio Build Tools с MSVC и Windows SDK;
- Microsoft Edge WebView2 Runtime;
- PowerShell 7 удобно использовать как shell разработки, но elevated runtime-команды приложения запускаются через `powershell.exe`.
Установка зависимостей и запуск:
Целевая платформа — Windows 10/11 x64. Для сборки нужны Node.js/npm, Rust через rustup, Visual Studio Build Tools с MSVC и Windows SDK. PowerShell 7 используется только для build/release/QA tooling; установленному приложению PowerShell не нужен.
```powershell
cd D:\repos\ProxyWarden
npm install
Set-Location D:\repos\ProxyWarden
npm ci
npm run tauri -- dev
```
Собрать frontend:
```powershell
npm run build
```
Собрать установочный пакет Tauri:
```powershell
npm run tauri -- build
```
Запустить только browser-preview без нативных Tauri-команд:
Browser preview не доказывает работу Tauri commands, UAC или Windows-служб:
```powershell
npm run dev -- --host 127.0.0.1
```
Browser-preview годится для проверки интерфейса, но не доказывает работу Windows-служб, elevated-операций и Tauri command handlers.
## Проверка
## Installer-скрипты
В репозитории есть явные entrypoint-скрипты:
```powershell
& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly
```
`-PlanOnly` возвращает structured JSON и не должен иметь side effects.
Реальная установка через эти скрипты требует прав администратора. `scripts/install-proxyfier.ps1` как standalone boundary сейчас ожидает локальный `-PackagePath`; путь установки из UI/backend использует отдельный elevated-скрипт, который скачивает ProxiFyre, Windows Packet Filter и runtime-зависимости сам.
## Проверка для разработчика
Frontend/UI:
Frontend и Rust:
```powershell
npm run format:check
@@ -231,37 +180,34 @@ npm run lint
npm run typecheck
npm test -- --run
npm run build
Push-Location src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
Pop-Location
```
Rust/backend:
```powershell
cd D:\repos\ProxyWarden\src-tauri
cargo test
```
Tauri/toolchain:
Build/release/QA boundaries:
```powershell
& .\scripts\check-runtime-powershell-boundary.ps1 -CheckOnly
& .\scripts\update-component-bundle.ps1 -PlanOnly
& .\scripts\update-component-bundle.ps1 -CheckOnly
& .\scripts\audit-windows-smoke.ps1 -Mode PlanOnly
& .\scripts\prepare-release.ps1 -PlanOnly -SkipBuild
npm run tauri -- info
npm run tauri -- dev
npm run tauri -- build
```
Installer boundaries:
`PlanOnly` и `CheckOnly` возвращают structured JSON с `changed: false`. Обновление packaged component catalog — отдельная release-команда и не является runtime action.
```powershell
& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly
```
Unit tests и build не подтверждают реальный UAC/SCM/driver/routing flow. Для release candidate нужны Windows VM smoke-сценарии: fresh offline install, legacy upgrade/rollback, foreign same-name service refusal и uninstall/reboot behavior.
## Ограничения текущей версии
## Ограничения
- Основной поддержанный маршрут - SOCKS5.
- Link-подписки разбирают VLESS, VMess, Trojan и Shadowsocks; sing-box JSON также принимает поддержанные proxy outbounds. Неизвестные форматы отклоняются явно.
- Для VLESS outbound без собственного `packet_encoding` генератор добавляет `xudp`; значение, заданное провайдером подписки, не перезаписывается.
- ProxiFyre является текущим backend-слоем для per-app routing.
- Local sing-box остается опциональным и не требуется для внешнего SOCKS5.
- Elevated install/start/stop/uninstall операции считаются реализованными, но требуют дополнительной проверки на реальной Windows-машине с UAC/admin confirmation.
- Windows 10, Windows PowerShell 5.1, ARM64 и x86 нужно отдельно подтвердить перед тем, как называть их официально поддержанными.
- Основной routing protocol — SOCKS5.
- Link subscriptions поддерживают только форматы, которые явно принимает текущий parser; неизвестные поля/форматы отклоняются, а не теряются молча.
- Local sing-box остаётся optional.
- x86 и ARM64 не входят в текущий release contract.
- Реальные Windows service, UAC, driver и offline installer сценарии нельзя считать подтверждёнными без VM evidence.