174 lines
14 KiB
Markdown
174 lines
14 KiB
Markdown
# RKNboost
|
||
|
||
[github.com/maeneko/rknboost](https://github.com/maeneko/rknboost)
|
||
|
||
## Требования
|
||
|
||
- Node.js 20+ (проверено на 24)
|
||
- npm 10+
|
||
|
||
## Команды
|
||
|
||
```bash
|
||
npm install # зависимости + скачивание бинарника Electron
|
||
npm run dev # dev-режим: HMR для UI, авто-рестарт main-процесса
|
||
npm run start # запуск собранной версии без упаковки
|
||
npm run build # typecheck + сборка main/preload/renderer в out/
|
||
npm run lint # ESLint
|
||
npm run format # Prettier
|
||
npm run typecheck # tsc для node- и web-частей отдельно
|
||
|
||
npm run build:unpack # быстрая проверка: приложение без установщика (release/*-unpacked)
|
||
npm run build:mac # .dmg + .zip (x64 + arm64)
|
||
npm run build:win # NSIS .exe (x64; arm64 не собираем — нет подписанного WinDivert)
|
||
npm run build:linux # AppImage + .deb
|
||
```
|
||
|
||
> Установщики под чужую ОС локально собрать нельзя — для этого есть CI
|
||
> (`.github/workflows/ci.yml` собирает все три платформы и кладёт артефакты в Actions).
|
||
|
||
> Если после `npm install` команда `npm run dev` падает с `Error: Electron uninstall` —
|
||
> бинарник Electron не докачался; исправляется повторным запуском
|
||
> `node node_modules/electron/install.js`.
|
||
|
||
## Структура
|
||
|
||
```
|
||
src/
|
||
main/ # Node-процесс: окна, меню, доступ к ОС
|
||
index.ts lifecycle приложения, single instance
|
||
window.ts createWindow / createPopupWindow, настройки безопасности
|
||
ipc.ts все ipcMain.handle
|
||
preload/ # мост между main и renderer (sandbox, contextBridge)
|
||
shared/ # ipc-contract.ts — типы каналов, общие для всех процессов
|
||
renderer/ # React-приложение (обычный браузерный код, без Node API)
|
||
build/ # иконки и entitlements для electron-builder
|
||
resources/ # файлы, попадающие в собранное приложение (иконка окна)
|
||
out/ # результат electron-vite build
|
||
release/ # готовые установщики
|
||
```
|
||
|
||
## Как добавить свой IPC-канал
|
||
|
||
1. Опишите канал в `src/shared/ipc-contract.ts` (аргументы и результат).
|
||
2. Зарегистрируйте обработчик в `src/main/ipc.ts` через хелпер `handle(...)` — типы проверятся.
|
||
3. Добавьте метод в объект `api` в `src/preload/index.ts`.
|
||
4. Вызывайте из React как `window.api.мойМетод()` — тип подтянется автоматически.
|
||
|
||
События из main в renderer описываются в `IpcEvents` и подписываются через `subscribe(...)`
|
||
(пример — `onThemeChanged`, возвращает функцию отписки для `useEffect`).
|
||
|
||
## Что показывают демо-карточки
|
||
|
||
| Карточка | Каналы | Что демонстрирует |
|
||
| ---------------- | ----------------------------------------- | ------------------------------------------------------------- |
|
||
| Система | `app:info` | версии Electron/Chromium/Node, платформа, путь к userData |
|
||
| IPC ping | `ping` | минимальный invoke/handle |
|
||
| Нативный диалог | `dialog:open-file` | системный выбор файла + `fs.stat` в main |
|
||
| Всплывающее окно | `dialog:message-box`, `window:open-popup` | модальный диалог ОС и второе `BrowserWindow` |
|
||
| Тема оформления | `theme:*` | `nativeTheme` как источник правды, реакция на смену темы в ОС |
|
||
|
||
Тайтлбар системный на всех платформах — окно создаётся без `frame`/`titleBarStyle`, рамку
|
||
и кнопки свернуть/развернуть/закрыть рисует сама ОС.
|
||
|
||
## Безопасность
|
||
|
||
- `sandbox: true`, `contextIsolation: true`, `nodeIntegration: false`;
|
||
- renderer не имеет доступа к `ipcRenderer` — только к методам из `window.api`;
|
||
- `setWindowOpenHandler` и `will-navigate` не дают уйти на внешний origin, ссылки открываются
|
||
в системном браузере, причём только с протоколами из `ALLOWED_EXTERNAL_PROTOCOLS`;
|
||
- в `index.html` задан CSP без внешних источников.
|
||
|
||
## Иконки
|
||
|
||
`build/icon.png` (1024×1024) — исходник, из него electron-builder делает иконки для всех платформ;
|
||
`build/icon.icns` и `build/icon.ico` лежат рядом как готовые варианты. `resources/icon.png` —
|
||
иконка окна для Linux. Замените эти файлы своими, имена оставьте прежними.
|
||
|
||
## Подпись и нотаризация
|
||
|
||
По умолчанию выключены (`notarize: false`), сборки неподписанные — их можно запускать локально,
|
||
но macOS покажет предупреждение Gatekeeper при переносе на другую машину.
|
||
|
||
Чтобы включить:
|
||
|
||
- **macOS**: переменные окружения `CSC_LINK` (base64 сертификата Developer ID) и `CSC_KEY_PASSWORD`,
|
||
плюс `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` и `notarize: true`
|
||
в `electron-builder.yml`.
|
||
- **Windows**: `CSC_LINK` и `CSC_KEY_PASSWORD` с .pfx-сертификатом.
|
||
|
||
В CI эти значения передаются секретами GitHub — место уже отмечено комментарием в
|
||
`.github/workflows/ci.yml`.
|
||
|
||
## Обход блокировок (zapret)
|
||
|
||
Движки и данные — из двух сторонних проектов, оба MIT, оба скачиваются `npm run zapret:fetch`
|
||
(вызывается автоматически из `npm run build`) в `resources/zapret/` (в git не хранится):
|
||
|
||
- **[bol-van/zapret](https://github.com/bol-van/zapret)** — сами движки: `tpws` (macOS, SOCKS5-прокси
|
||
без root) и `winws.exe` + драйвер **WinDivert** (Windows, служба с правами администратора).
|
||
WinDivert — LGPLv3/GPLv2 на выбор; лицензии обоих проектов кладутся рядом с бинарниками
|
||
(`LICENSE.zapret.txt`, `LICENSE.WinDivert.txt`).
|
||
- **[Flowseal/zapret-discord-youtube](https://github.com/Flowseal/zapret-discord-youtube)** —
|
||
списки сайтов (`resources/zapret/lists/`) и fake-пакеты (`resources/zapret/fakes/`). Версия
|
||
зафиксирована по sha коммита в `scripts/fetch-zapret.mjs` (`FLOWSEAL_COMMIT`), лицензия —
|
||
`LICENSE.flowseal.txt`.
|
||
|
||
Свои сгенерированные стратегии для Windows (`src/main/zapret/strategies.win32.generated.ts`,
|
||
22 варианта) — не батники: `scripts/import-flowseal-strategies.mjs` разбирает `general*.bat`
|
||
из того же репозитория Flowseal и переносит аргументы `winws` в TypeScript. Файл коммитится;
|
||
перегенерировать и свериться через `git diff` нужно вручную при обновлении `FLOWSEAL_COMMIT`.
|
||
На macOS `tpws` не умеет ни fake-пакетов, ни UDP — там свои профили
|
||
(`src/main/zapret/strategies.ts`, раздел `DARWIN_DEFINITIONS`) поверх тех же списков.
|
||
|
||
Списки сайтов пользователь может редактировать полностью (включая встроенные) — рабочая копия
|
||
живёт в `userData/zapret-lists` и переживает обновление приложения; `tpws`/`winws` сами
|
||
перечитывают список при изменении файла, перезапуск обхода не нужен (`src/main/zapret/lists.ts`).
|
||
|
||
### Windows: служба и права
|
||
|
||
`winws` требует драйвер WinDivert и права администратора, поэтому на Windows он работает не как
|
||
обычный дочерний процесс, а как служба Windows `rknboost-zapret` (`src/main/zapret/service.win32.ts`).
|
||
Устанавливает и настраивает её само приложение — не инсталлятор, — потому что аргументы `winws`
|
||
зависят от выбранной пользователем стратегии.
|
||
|
||
- **Приложение запрашивает права администратора при каждом запуске**
|
||
(`win.requestedExecutionLevel: requireAdministrator` в `electron-builder.yml`). Поэтому все
|
||
действия со службой выполняются напрямую, без отдельных запросов UAC по ходу работы.
|
||
Если приложение почему-то запущено без прав (dev-режим — там манифеста нет), включается
|
||
запасной путь: `outer.ps1` через `Start-Process -Verb RunAs` поднимает само приложение
|
||
с флагом `--elevated-service-task`, и UAC запрашивается на него, а не на `powershell.exe` —
|
||
в окне UAC пользователь должен видеть имя приложения, а не постороннюю программу.
|
||
При установке службы обычным пользователям выдаётся право на `start`/`stop` именно этой
|
||
службы (`sc sdset`), так что и без прав включение-выключение обхода работает.
|
||
- **Автозапуск с системой** включён по умолчанию (`sc config start= auto`) — обход работает и
|
||
после перезагрузки, не дожидаясь запуска приложения. Отключается переключателем в настройках
|
||
(тоже через UAC). Выключение обхода кнопкой на главном экране действует только до следующей
|
||
перезагрузки, если автозапуск остался включён — служба поднимется вместе с системой заново.
|
||
- **arm64 не поддерживается**: у WinDivert нет подписанной сборки под arm64 (только x64 через
|
||
эмуляцию на Windows 11), поэтому `electron-builder.yml` собирает Windows-инсталлятор только
|
||
для x64.
|
||
- Установщик — **per-user** (ставится в `%LocalAppData%`, один клик, без UAC на саму установку).
|
||
|
||
> ⚠️ Известный компромисс. Каталог установки доступен на запись обычному пользователю, а exe
|
||
> при этом требует администратора — значит подмена `RKNboost.exe` даёт злоумышленнику права
|
||
> администратора с подтверждения самого пользователя. Это осознанный выбор владельца проекта
|
||
> в пользу быстрой установки без UAC. Безопасный вариант — `perMachine: true`, тогда exe лежит
|
||
> в защищённом от записи `Program Files`, но установка снова требует UAC и мастера.
|
||
|
||
Служба работает от `LocalSystem`, и её `binPath` не должен указывать в каталог, куда обычный
|
||
пользователь может писать без прав администратора — поэтому при первом включении обхода
|
||
приложение копирует `winws.exe` и WinDivert в защищённый ACL'ом
|
||
каталог в `%ProgramData%` (`protectedWinwsPath()` в `src/main/zapret/paths.ts`) и указывает
|
||
службе именно на эту копию, а не на оригинал в папке установки. При удалении приложения
|
||
деинсталлятор (`build/installer.nsh`) сам останавливает и снимает службу вместе с этой копией.
|
||
|
||
- На одну машину служба одна: её конфиг (`%ProgramData%\rknboost\zapret\strategy.cfg`) хранит
|
||
стратегию того пользователя, который последним её менял, — с несколькими пользователями на
|
||
одной машине это разделяется некорректно.
|
||
|
||
## Авто-обновления
|
||
|
||
Не подключены. Если понадобятся: `npm i electron-updater`, добавить секцию `publish`
|
||
в `electron-builder.yml` и вызвать `autoUpdater.checkForUpdatesAndNotify()` в `src/main/index.ts`.
|