mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-05-02 16:20:26 +00:00
254 lines
8 KiB
Markdown
254 lines
8 KiB
Markdown
# Aplikace OmniRoute Electron pro stolní počítače
|
||
|
||
Tento adresář obsahuje obalovou aplikaci Electron pro desktopovou aplikaci OmniRoute.
|
||
|
||
## Architektura (v1.6.4)
|
||
|
||
```
|
||
electron/
|
||
├── main.js # Main process — window, tray, server lifecycle, CSP, IPC
|
||
├── preload.js # Preload script — secure IPC bridge with disposer pattern
|
||
├── package.json # Electron-specific dependencies & electron-builder config
|
||
├── types.d.ts # TypeScript definitions (AppInfo, ServerStatus, ElectronAPI)
|
||
└── assets/ # Application icons and resources
|
||
|
||
src/shared/hooks/
|
||
└── useElectron.ts # React hooks — useSyncExternalStore, zero re-renders
|
||
```
|
||
|
||
## Klíčová rozhodnutí o designu
|
||
|
||
Rozhodnutí | Odůvodnění
|
||
--- | ---
|
||
dotazování `waitForServer()` | Zabraňuje zobrazení prázdné obrazovky při studeném startu — před načtením se ozve `http://localhost:PORT`
|
||
`stdio: 'pipe'` | Zachycuje stdout/stderr serveru pro logování + detekci připravenosti ( `inherit` )
|
||
Vzor drtiče odpadu | `onServerStatus()` vrací `() => void` pro přesné vyčištění listeneru (ne `removeAllListeners` )
|
||
`useSyncExternalStore` | Nulové renderování pro `useIsElectron()` — žádný cyklus `useState` + `useEffect`
|
||
CSP prostřednictvím záhlaví relace | `Content-Security-Policy` omezuje `script-src` , `connect-src` atd. dle osvědčených postupů Electron.
|
||
Podmíněný titulek pro platformu | `titleBarStyle: 'hiddenInset'` pouze v systému macOS; `default` ve Windows/Linuxu
|
||
|
||
## Rozvoj
|
||
|
||
### Předpoklady
|
||
|
||
1. Nejprve sestavte aplikaci Next.js:
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
1. Instalace závislostí Electronu:
|
||
|
||
```bash
|
||
cd electron
|
||
npm install
|
||
```
|
||
|
||
### Spuštěno ve vývoji
|
||
|
||
1. Spusťte vývojový server Next.js:
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
1. V jiném terminálu spusťte Electron:
|
||
|
||
```bash
|
||
cd electron
|
||
npm run dev
|
||
```
|
||
|
||
### Spuštění v produkčním režimu
|
||
|
||
1. Sestavení Next.js v samostatném režimu:
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
1. Spuštění elektronu:
|
||
|
||
```bash
|
||
cd electron
|
||
npm start
|
||
```
|
||
|
||
## Budova
|
||
|
||
### Sestavení pro aktuální platformu
|
||
|
||
```bash
|
||
cd electron
|
||
npm run build
|
||
```
|
||
|
||
### Vytvořte pro specifické platformy
|
||
|
||
```bash
|
||
# Windows
|
||
npm run build:win
|
||
|
||
# macOS (x64 + arm64)
|
||
npm run build:mac
|
||
|
||
# Linux
|
||
npm run build:linux
|
||
```
|
||
|
||
## Výstup
|
||
|
||
Vytvořené aplikace jsou umístěny v `dist-electron/` :
|
||
|
||
- Windows: `.exe` instalační program (NSIS) + přenosný `.exe`
|
||
- macOS: instalační soubor `.dmg` (Intel + Apple Silicon)
|
||
- Linux: `.AppImage`
|
||
|
||
## Instalace
|
||
|
||
### macOS
|
||
|
||
1. Stáhněte si nejnovější soubor `.dmg` ze stránky [Verze](https://github.com/diegosouzapw/OmniRoute/releases) .
|
||
2. Otevřete soubor `.dmg` .
|
||
3. Přetáhněte `OmniRoute.app` do složky Aplikace.
|
||
4. Spustit z Aplikací.
|
||
|
||
> ⚠️ **Poznámka:** Aplikace zatím není podepsána certifikátem Apple Developer. Pokud macOS aplikaci blokuje, spusťte:
|
||
>
|
||
> ```bash
|
||
> xattr -cr /Applications/OmniRoute.app
|
||
> ```
|
||
>
|
||
> Nebo klikněte pravým tlačítkem myši na aplikaci → Otevřít → Otevřít (pro obejití Gatekeeperu při prvním spuštění).
|
||
|
||
### Windows
|
||
|
||
**Instalační program (doporučeno):**
|
||
|
||
1. Stáhněte si `OmniRoute.Setup.*.exe` z [Releases](https://github.com/diegosouzapw/OmniRoute/releases) .
|
||
2. Spusťte instalační program.
|
||
3. Spuštění z nabídky Start nebo zástupce na ploše.
|
||
|
||
**Přenosné (bez instalace):**
|
||
|
||
1. Stáhněte si soubor `OmniRoute.exe` ze [sekce Vydání](https://github.com/diegosouzapw/OmniRoute/releases) .
|
||
2. Spouštět přímo z libovolné složky.
|
||
|
||
### Linux
|
||
|
||
1. Stáhněte si soubor `.AppImage` ze [sekce Releases](https://github.com/diegosouzapw/OmniRoute/releases) .
|
||
2. Udělejte z něj spustitelný soubor:
|
||
```bash
|
||
chmod +x OmniRoute-*.AppImage
|
||
```
|
||
3. Běh:
|
||
```bash
|
||
./OmniRoute-*.AppImage
|
||
```
|
||
|
||
## Funkce
|
||
|
||
- **Připravenost serveru** – Před zobrazením okna čeká na kontrolu stavu
|
||
- **Systémový zásobník** — Minimalizace do systémového zásobníku s rychlými akcemi (otevřít, změnit port, ukončit)
|
||
- **Správa portů** — Změna portu z nabídky v systémové liště (server se automaticky restartuje)
|
||
- **Ovládací prvky oken** — Vlastní minimalizace, maximalizace, zavření přes IPC
|
||
- **Zásady zabezpečení obsahu** – Omezující CSP prostřednictvím záhlaví relací
|
||
- **Offline podpora** — Samostatný server Next.js v balíčku
|
||
- **Jedna instance** – V daném okamžiku může běžet pouze jedna instance aplikace.
|
||
|
||
## Konfigurace
|
||
|
||
### Proměnné prostředí
|
||
|
||
Proměnná | Výchozí | Popis
|
||
--- | --- | ---
|
||
`OMNIROUTE_PORT` | `20128` | Port serveru
|
||
`OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64–16384 MB)
|
||
`NODE_ENV` | `production` | Nastavit na `development` pro vývojářský režim
|
||
|
||
### Vlastní ikona
|
||
|
||
Umístěte ikony do `assets/` :
|
||
|
||
- `icon.ico` — ikona Windows (256×256)
|
||
- `icon.icns` — balíček ikon pro macOS
|
||
- `icon.png` — Linux/obecné použití (512×512)
|
||
- `tray-icon.png` — Ikona na systémové liště (16×16 nebo 32×32)
|
||
|
||
## Kanály IPC
|
||
|
||
### Vyvolání (Renderer → Hlavní, asynchronní)
|
||
|
||
Kanál | Vrácení zboží | Popis
|
||
--- | --- | ---
|
||
`get-app-info` | `AppInfo` | Název aplikace, verze, platforma, isDev, port
|
||
`open-external` | `void` | Otevřít URL ve výchozím prohlížeči (pouze http/https)
|
||
`get-data-dir` | `string` | Získat cestu k adresáři userData
|
||
`restart-server` | `{ success }` | Zastavení + restart serveru (časový limit 5 s + SIGKILL)
|
||
|
||
### Odeslat (Renderer → Hlavní, spustit a zapomenout)
|
||
|
||
Kanál | Popis
|
||
--- | ---
|
||
`window-minimize` | Minimalizovat okno
|
||
`window-maximize` | Přepnout maximalizaci/obnovení
|
||
`window-close` | Zavřít okno (minimalizovat do zásobníku)
|
||
|
||
### Příjem (Hlavní → Renderer, události)
|
||
|
||
Kanál | Užitečné zatížení | Vydáno, když
|
||
--- | --- | ---
|
||
`server-status` | `ServerStatus` | Server se spouští, zastavuje, dochází k chybám nebo se restartuje
|
||
`port-changed` | `number` | Změna portu přes menu zásobníku
|
||
|
||
> **Poznámka** : Posluchače vracejí funkce pro přesné čištění. Viz hooky `useServerStatus` a `usePortChanged` .
|
||
|
||
## Zabezpečení
|
||
|
||
Funkce | Implementace
|
||
--- | ---
|
||
Izolace kontextu | `contextIsolation: true` — renderer nemůže přistupovat k Node.js
|
||
Integrace uzlů | `nodeIntegration: false` — v rendereru není `require()`
|
||
Bílý seznam IPC | Názvy kanálů ověřené při předběžném načítání pomocí `safeInvoke` / `safeSend` / `safeOn`
|
||
Ověření URL adresy | `shell.openExternal()` povoluje pouze protokoly `http:` / `https:`
|
||
CSP | Záhlaví `Content-Security-Policy` nastavené pomocí `session.webRequest.onHeadersReceived`
|
||
Zabezpečení webu | `webSecurity: true` – vynucena politika stejného původu
|
||
|
||
## React Hooky
|
||
|
||
Háček | Vrácení zboží | Popis
|
||
--- | --- | ---
|
||
`useIsElectron()` | `boolean` | Detekce nulového renderování pomocí `useSyncExternalStore`
|
||
`useElectronAppInfo()` | `{ appInfo, loading, error }` | Informace o aplikaci z hlavního procesu
|
||
`useDataDir()` | `{ dataDir, loading, error }` | Adresář uživatelských dat
|
||
`useWindowControls()` | `{ minimize, maximize, close }` | Akce ovládání oken
|
||
`useOpenExternal()` | `{ openExternal }` | Otevřít URL adresy v prohlížeči
|
||
`useServerControls()` | `{ restart, restarting }` | Řízení restartu serveru
|
||
`useServerStatus(cb)` | Drtič odpadu | Poslouchejte události stavu serveru
|
||
`usePortChanged(cb)` | Drtič odpadu | Poslouchejte události změny portu
|
||
|
||
## Odstraňování problémů
|
||
|
||
### Aplikace se nespustí
|
||
|
||
1. Zkontrolujte, zda je port 20128 dostupný: `lsof -i :20128`
|
||
2. Zkontrolujte protokoly konzole pro prefix `[Electron]`
|
||
3. Ověřte, zda výstup sestavení existuje v souboru `.next/standalone`
|
||
|
||
### Bílá obrazovka
|
||
|
||
1. Ověření existence buildu Next.js – čekání na připravenost serveru maximálně 30 sekund
|
||
2. Zkontrolujte výstup protokolů `[Server]` a `[Server:err]`
|
||
3. Hledání porušení CSP v konzoli pro vývojáře
|
||
|
||
### Selhání sestavení
|
||
|
||
Ujistěte se, že máte nainstalované nástroje pro sestavení:
|
||
|
||
- Windows: Nástroje pro sestavení ve Visual Studiu
|
||
- macOS: Nástroje příkazového řádku Xcode
|
||
- Linux: `build-essential` , `libsecret-1-dev`
|
||
|
||
## Licence
|
||
|
||
MIT
|