Expand README with architecture and setup details

2026-07-08 09:58:26 +03:00
parent 81be7e186c
commit c5120669d2
109 changed files with 22311 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,142 @@
 # ProxyWarden

+ProxyWarden - это Windows-приложение для маршрутизации выбранных программ через прокси или VPN-сервер. Оно не меняет глобальные настройки прокси в Windows: вы сами выбираете, какие приложения должны идти через маршрут, например Discord, Telegram, браузер, игру или конкретный `.exe`.
+
+## Что умеет приложение
+
+- добавлять приложения по имени процесса, папке или конкретному EXE-файлу;
+- отправлять выбранные приложения через внешний SOCKS5-прокси;
+- при необходимости поднимать локальный `sing-box` и использовать сервер из подписки;
+- показывать состояние компонентов: установлен ли ProxiFyre, запущены ли службы, выбран ли сервер;
+- генерировать конфиги для ProxiFyre и `sing-box` из сохраненных настроек;
+- не устанавливать скрыто лишние компоненты при применении профиля.
+
+## Из чего состоит ProxyWarden
+
+ProxyWarden разделен на три независимые части.
+
+**Control App** - само desktop-приложение. В нем вы настраиваете маршрут, выбираете приложения, смотрите статус и запускаете явные действия.
+
+**ProxiFyre** - обязательный слой для маршрутизации отдельных Windows-приложений. Он заставляет выбранные программы ходить через SOCKS5-прокси даже тогда, когда сами программы не умеют работать с прокси.
+
+**Local sing-box** - необязательный локальный VPN/proxy runtime. Он нужен только если вы хотите вставить subscription URL, выбрать сервер и получить локальный SOCKS5 endpoint `127.0.0.1:1080`. Если у вас уже есть внешний SOCKS5-прокси, `sing-box` можно не устанавливать.
+
+## Типичный сценарий с внешним прокси
+
+1. Запустите ProxyWarden.
+2. Установите или проверьте ProxiFyre.
+3. На вкладке `VPN / Прокси` выберите `Внешний прокси`.
+4. Введите адрес в формате `host:port` или `socks5://host:port`.
+5. На вкладке `ProxiFyre` добавьте приложения, которые нужно маршрутизировать.
+6. Нажмите `Применить в ProxiFyre`.
+
+Результат: выбранные приложения идут через внешний SOCKS5-прокси. Local sing-box для этого сценария не нужен.
+
+## Типичный сценарий с Local sing-box
+
+1. Запустите ProxyWarden.
+2. Установите ProxiFyre.
+3. Установите Local sing-box.
+4. Вставьте subscription URL, загрузите список серверов и выберите сервер.
+5. Добавьте приложения для маршрутизации.
+6. Примените маршрут.
+
+Результат: выбранные приложения идут по цепочке:
+
+```text
+Приложения -> ProxiFyre -> Local sing-box 127.0.0.1:1080 -> выбранный сервер
+```
+
+## Где хранятся настройки
+
+Пользовательские настройки хранятся в `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-файлы. При записи настроек приложение создает backup рядом с исходным JSON.
+
+## Установка из исходников
+
+Нужны:
+
+- Windows 10/11;
+- Node.js и npm;
+- Rust через rustup;
+- Visual Studio Build Tools с MSVC и Windows SDK;
+- Microsoft Edge WebView2 Runtime.
+
+Команды:
+
+```powershell
+cd D:\repos\ProxyWarden
+npm install
+npm run tauri -- dev
+```
+
+Собрать установочный пакет:
+
+```powershell
+npm run tauri -- build
+```
+
+Запустить только browser-preview без нативных Tauri-команд:
+
+```powershell
+npm run dev -- --host 127.0.0.1
+```
+
+В browser-preview можно проверить интерфейс, но нельзя управлять Windows-службами и нативными компонентами.
+
+## Явные installer-скрипты
+
+В репозитории есть отдельные entrypoint-скрипты:
+
+```powershell
+& .\scripts\install-control-app.ps1 -PlanOnly
+& .\scripts\install-proxyfier.ps1 -PlanOnly
+& .\scripts\install-singbox.ps1 -PlanOnly
+```
+
+`-PlanOnly` показывает план в JSON и ничего не устанавливает. Реальная установка требует прав администратора. Компоненты устанавливаются отдельно: применение профиля не должно незаметно устанавливать Control App, ProxiFyre или Local sing-box.
+
+## Проверка для разработчика
+
+Frontend:
+
+```powershell
+npm run build
+```
+
+Rust-тесты:
+
+```powershell
+cd D:\repos\ProxyWarden\src-tauri
+cargo test
+```
+
+Информация Tauri:
+
+```powershell
+npm run tauri -- info
+```
+
+## Ограничения текущей версии
+
+- Поддерживается основной путь через SOCKS5.
+- ProxiFyre является текущим backend-слоем маршрутизации; архитектура оставляет место для другого proxy-router adapter.
+- Local sing-box остается опциональным и не требуется для внешнего SOCKS5-прокси.
+- Реальные elevated-операции установки, удаления и управления Windows-службами нужно проверять на Windows с правами администратора.