214 lines
13 KiB
Markdown
214 lines
13 KiB
Markdown
# ProxyWarden
|
||
|
||
ProxyWarden — standalone Windows desktop-приложение для маршрутизации выбранных программ через SOCKS5-прокси. Оно управляет обязательным ProxiFyre и, при необходимости, локальным `sing-box`, но само не является VPN-драйвером, proxy server или облачным control plane.
|
||
|
||
Все системные действия остаются явными: `apply` только проверяет и применяет конфигурацию; установка, обновление, запуск, остановка, перенос и удаление компонентов выполняются отдельными командами пользователя.
|
||
|
||
## Главное
|
||
|
||
- 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 | 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 |
|
||
|
||
Версии, SHA-256 и лицензии offline payloads зафиксированы в packaged component catalog. Установка Control App не запускает routing-компоненты: нужный компонент устанавливается отдельным действием в UI.
|
||
|
||
В UI и части внутренних DTO ProxiFyre может иметь исторический id `proxyfier`. Это не продукт Proxifier.
|
||
|
||
## Маршруты
|
||
|
||
Внешний SOCKS5:
|
||
|
||
```text
|
||
выбранные приложения -> ProxiFyre -> внешний SOCKS5 proxy
|
||
```
|
||
|
||
Local sing-box:
|
||
|
||
```text
|
||
выбранные приложения -> ProxiFyre -> Local sing-box 127.0.0.1:1080 -> выбранный subscription-сервер
|
||
```
|
||
|
||
Во втором маршруте ProxiFyre по-прежнему отвечает за выбор приложений. Local sing-box только предоставляет локальный SOCKS5 endpoint и соединяется с выбранным сервером.
|
||
|
||
## Установка и системные пути
|
||
|
||
Tauri NSIS installer устанавливает Control App per-machine. Managed runtime-компоненты лежат только под текущим app root:
|
||
|
||
```text
|
||
C:\Program Files\ProxyWarden
|
||
C:\Program Files\ProxyWarden\components\ProxiFyre
|
||
C:\Program Files\ProxyWarden\components\sing-box
|
||
```
|
||
|
||
Службы:
|
||
|
||
```text
|
||
ProxiFyreService
|
||
ProxyWardenSingBox
|
||
```
|
||
|
||
ProxyWarden управляет службой только после точной проверки `PathName`, marker/receipt и canonical component root. Похожее имя службы или найденная папка сами по себе не дают права на start/stop/delete.
|
||
|
||
## Релиз одной командой
|
||
|
||
В 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
|
||
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\...
|
||
```
|
||
|
||
`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 блокируется до безопасного завершения.
|
||
|
||
## Права администратора
|
||
|
||
Без UAC можно редактировать настройки, выбирать приложения и proxy, загружать subscription, смотреть статус и генерировать конфигурацию.
|
||
|
||
UAC требуется для явных действий, которые меняют Windows:
|
||
|
||
- install/update/uninstall ProxiFyre или Local sing-box;
|
||
- установка Windows Packet Filter и VC++ Runtime при необходимости;
|
||
- start/stop/create/delete Windows-служб;
|
||
- подтверждённый legacy component cutover и его cleanup.
|
||
|
||
Elevated mode принимает только заранее записанный typed job ID либо один из фиксированных NSIS modes. UI не передаёт произвольную команду, script text или install path.
|
||
|
||
## Типовые сценарии
|
||
|
||
### Внешний SOCKS5
|
||
|
||
1. Установите ProxiFyre явной кнопкой, если он отсутствует.
|
||
2. На вкладке `VPN / Прокси` выберите внешний proxy и укажите `host:port` или `socks5://host:port`.
|
||
3. Добавьте приложения в ProxiFyre route.
|
||
4. Нажмите `Применить`.
|
||
|
||
Local sing-box для этого сценария не нужен.
|
||
|
||
### Local sing-box с подпиской
|
||
|
||
1. Явно установите ProxiFyre и Local sing-box.
|
||
2. Добавьте subscription URL, загрузите список и выберите сервер.
|
||
3. Добавьте приложения и примените маршрут.
|
||
|
||
## Разработка
|
||
|
||
Целевая платформа — Windows 10/11 x64. Для сборки нужны Node.js/npm, Rust через rustup, Visual Studio Build Tools с MSVC и Windows SDK. PowerShell 7 используется только для build/release/QA tooling; установленному приложению PowerShell не нужен.
|
||
|
||
```powershell
|
||
Set-Location D:\repos\ProxyWarden
|
||
npm ci
|
||
npm run tauri -- dev
|
||
```
|
||
|
||
Browser preview не доказывает работу Tauri commands, UAC или Windows-служб:
|
||
|
||
```powershell
|
||
npm run dev -- --host 127.0.0.1
|
||
```
|
||
|
||
## Проверка
|
||
|
||
Frontend и Rust:
|
||
|
||
```powershell
|
||
npm run format:check
|
||
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
|
||
```
|
||
|
||
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 -- build
|
||
```
|
||
|
||
`PlanOnly` и `CheckOnly` возвращают structured JSON с `changed: false`. Обновление packaged component catalog — отдельная release-команда и не является runtime action.
|
||
|
||
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.
|
||
|
||
## Ограничения
|
||
|
||
- Основной routing protocol — SOCKS5.
|
||
- Link subscriptions поддерживают только форматы, которые явно принимает текущий parser; неизвестные поля/форматы отклоняются, а не теряются молча.
|
||
- Local sing-box остаётся optional.
|
||
- x86 и ARM64 не входят в текущий release contract.
|
||
- Реальные Windows service, UAC, driver и offline installer сценарии нельзя считать подтверждёнными без VM evidence.
|