# OmniRoute Fly.io Deployment Guide (Čeština) 🌐 **Languages:** 🇺🇸 [English](../../../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇹 [am](../../../am/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) --- Tento dokument popisuje skutečný proces nasazení OmniRoute na Fly.io a zahrnuje následující scénáře: - První nasazení aktuálního projektu na Fly.io - Publikování následných aktualizací kódu - Nové projekty používající stejný postup nasazení Tato příručka vychází z ověřené funkční konfigurace aktuálního projektu. Název aplikace je `omniroute`. --- ## 1. Cíle nasazení - Platforma: Fly.io - Metoda nasazení: Přímé publikování pomocí lokálního nástroje `flyctl` - Běhové prostředí: Použití existujících souborů `Dockerfile` a `fly.toml` v repozitáři - Trvalé ukládání dat: Fly Volume připojený k `/data` - Přístupová URL: `https://omniroute.fly.dev/` --- ## 2. Klíčová konfigurace aktuálního projektu Bylo potvrzeno, že soubor `fly.toml` v aktuálním repozitáři obsahuje následující klíčové položky: ```toml app = 'omniroute' primary_region = 'sin' [[mounts]] source = 'data' destination = '/data' [processes] app = 'node run-standalone.mjs' [http_service] internal_port = 20128 [env] TZ = "Asia/Shanghai" HOST = "0.0.0.0" HOSTNAME = "0.0.0.0" BIND = "0.0.0.0" ``` Poznámky: - `app = 'omniroute'` určuje, na kterou aplikaci Fly je nasazení cíleno - `destination = '/data'` určuje adresář, do kterého se připojí trvalý svazek - Tento projekt musí mít nastaveno `DATA_DIR=/data`, jinak budou databáze a klíče zapsány do dočasného adresáře kontejneru --- ## 3. Předpoklady ### 3.1 Instalace Fly CLI Windows PowerShell: ```powershell pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex" ``` Pokud instalační skript ve vašem prostředí selže, můžete také ručně stáhnout binární soubor `flyctl` a přidat jej do proměnné `PATH`. ### 3.2 Přihlášení k účtu Fly ```powershell flyctl auth login ``` ### 3.3 Ověření stavu přihlášení ```powershell flyctl auth whoami flyctl version ``` --- ## 4. První nasazení aktuálního projektu ### 4.1 Klonování kódu a přechod do adresáře ```powershell git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute ``` ### 4.2 Potvrzení názvu aplikace Otevřete soubor `fly.toml` a ověřte následující řádek: ```toml app = 'omniroute' ``` Pokud provádíte nasazení do vlastní nové aplikace, můžete název změnit na globálně jedinečný, například: ```toml app = 'omniroute-yourname' ``` Poznámka: - Ujistěte se, že aplikace zobrazená v konzoli odpovídá hodnotě `app` v souboru `fly.toml` - Pokud jste dříve používali jiný název, například `oroute`, nezaměňujte jej s `omniroute` ### 4.3 Vytvoření aplikace Pokud aplikace ještě neexistuje: ```powershell flyctl apps create omniroute ``` Pokud jste změnili název aplikace, nahraďte `omniroute` zvoleným názvem. ### 4.4 První nasazení ```powershell flyctl deploy ``` --- ## 5. Povinné parametry Pro tento projekt se na Fly.io doporučuje nakonfigurovat alespoň následující parametry. ### 5.1 Ověřené parametry Tyto parametry byly použity při skutečných nasazeních aktuální aplikace `omniroute`: - `API_KEY_SECRET` - `DATA_DIR` - `JWT_SECRET` - `MACHINE_ID_SALT` - `NEXT_PUBLIC_BASE_URL` - `OMNIROUTE_WS_BRIDGE_SECRET` (povinné v produkčním prostředí — používá se k ověřování mostu WebSocket) - `STORAGE_ENCRYPTION_KEY` ### 5.2 Informace o `INITIAL_PASSWORD` Aktuální projekt nenastavuje `INITIAL_PASSWORD`, protože jej toto nasazení nevyžaduje. Pokud není nastaveno: - Protokol při spuštění uvede, že výchozí heslo je `CHANGEME` - Po nasazení byste měli co nejdříve změnit přihlašovací heslo v nastavení systému Pokud chcete heslo backendu inicializovat bez obsluhy, můžete jej přidat později: - `INITIAL_PASSWORD` --- ## 6. Doporučené parametry ### 6.1 Konfigurace tajných údajů Pro Fly Secrets jsou doporučeny následující proměnné: | Proměnná | Doporučení | Popis | | ------------------------------------- | ------------------ | -------------------------------------------------------- | | `API_KEY_SECRET` | Povinné | Používá se ke generování a ověřování API klíčů | | `JWT_SECRET` | Povinné | Používá se pro přihlašovací relace a podepisování JWT | | `OMNIROUTE_WS_BRIDGE_SECRET` | Povinné v produkci | Tajný údaj pro ověřování mostu WebSocket | | `STORAGE_ENCRYPTION_KEY` | Důrazně doporučeno | Šifruje citlivé informace o připojení uložené v úložišti | | `MACHINE_ID_SALT` | Doporučeno | Generuje stabilní identifikátor stroje | | `INITIAL_PASSWORD` | Volitelné | Nastaví počáteční heslo backendu při prvním nasazení | | Soukromé přihlašovací údaje OAuth/API | Podle potřeby | Konfigurace ověřování pro externí platformy | ### 6.2 Doporučené hodnoty pro aktuální projekt | Proměnná | Doporučená hodnota | | ---------------------- | --------------------------- | | `DATA_DIR` | `/data` | | `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` | Poznámky: - `DATA_DIR=/data` je zásadní a musí odpovídat přípojnému bodu svazku Fly Volume - `NEXT_PUBLIC_BASE_URL` používá plánovač, zpětná volání frontendu a podobné scénáře ### 6.3 Konfigurace adresy URL zpětného volání OAuth Pokud potřebujete v nasazení na Fly.io povolit poskytovatele využívající OAuth (např. Antigravity, Gemini, Cursor), ujistěte se o následujících dvou bodech: 1. **Nastavte `NEXT_PUBLIC_BASE_URL` na svou veřejnou doménu HTTPS** ```powershell flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute ``` Pokud používáte vlastní doménu, nahraďte ji odpovídající doménou (např. `https://omniroute.yourdomain.com`). 2. **Nakonfigurujte adresu URL zpětného volání v konzoli poskytovatele** Všichni poskytovatelé OAuth sdílejí jedinou cestu zpětného volání `/callback` — pro jednotlivé poskytovatele NEEXISTUJÍ samostatné trasy zpětného volání: ```text /callback ``` Například bez ohledu na to, zda jde o Gemini, Antigravity, Cursor nebo GitLab Duo: - `https://omniroute.fly.dev/callback` Pokud `NEXT_PUBLIC_BASE_URL` neodpovídá adrese URL zpětného volání registrované u poskytovatele, tok OAuth selže při přesměrování v prohlížeči. --- ## 7. Nastavení tajných údajů jedním příkazem Následující příkazy vygenerují bezpečné náhodné hodnoty a v jediném kroku zapíší všechny požadované parametry aktuálního projektu do Fly Secrets. Poznámky: - Nezahrnuje `INITIAL_PASSWORD` - Určeno pro aktuální projekt `omniroute` ```powershell $apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $wsBridgeSecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() flyctl secrets set ` API_KEY_SECRET=$apiKeySecret ` JWT_SECRET=$jwtSecret ` MACHINE_ID_SALT=$machineIdSalt ` STORAGE_ENCRYPTION_KEY=$storageKey ` OMNIROUTE_WS_BRIDGE_SECRET=$wsBridgeSecret ` DATA_DIR=/data ` NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev ` -a omniroute ``` V systémech Linux / macOS můžete také použít `openssl rand -hex 32`: ```bash flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute ``` Poznámky: - `OMNIROUTE_WS_BRIDGE_SECRET` je v produkci povinný; pokud chybí, navázání spojení mostu WebSocket nebude fungovat Pokud chcete nastavit také počáteční heslo: ```powershell flyctl secrets set INITIAL_PASSWORD=your-strong-password -a omniroute ``` --- ## 8. Zobrazení aktuálních parametrů ```powershell flyctl secrets list -a omniroute ``` Pokud stránka `Secrets` v konzoli nezobrazuje očekávané proměnné, zkontrolujte: - Zda máte otevřenou aplikaci `omniroute` - Zda hodnota `app` v souboru `fly.toml` odpovídá aplikaci v konzoli --- ## 9. Následné aktualizace a vydání Po aktualizaci kódu je proces vydání jednoduchý: ```powershell git pull flyctl deploy ``` Pokud potřebujete pouze aktualizovat parametry bez změny kódu: ```powershell flyctl secrets set KEY=value -a omniroute ``` Fly automaticky provede postupnou aktualizaci strojů. ### 9.1 Sledování aktualizací upstream repozitáře při zachování souboru `fly.toml` ve vašem forku Pokud je aktuální repozitář forkem a chcete synchronizovat aktualizace z upstream repozitáře `https://github.com/diegosouzapw/OmniRoute`, postupujte podle níže uvedeného pracovního postupu. Nejprve ověřte své vzdálené repozitáře: ```powershell git remote -v ``` Měli byste vidět alespoň: - `origin` odkazující na váš vlastní fork - `upstream` odkazující na původní repozitář Pokud `upstream` není nakonfigurován, přidejte jej: ```powershell git remote add upstream https://github.com/diegosouzapw/OmniRoute.git ``` Před synchronizací s upstream repozitářem načtěte nejnovější commity a tagy: ```powershell git fetch upstream --tags ``` Zkontrolujte aktuální verzi a tagy upstream repozitáře: ```powershell git describe --tags --always git show --no-patch --oneline v3.4.7 ``` > Poznámka: Aktuální verze projektu je `v3.8.0`. Níže uvedené odkazy na `v3.4.7` jsou zachovány pouze jako historické příklady. Pro skutečná vydání použijte `:latest` nebo tag aktuální verze (např. `:v3.8.0`). Pokud chcete sloučit nejnovější větev `main` z upstream repozitáře a zároveň vynuceně zachovat soubor `fly.toml` svého forku, postupujte takto: ```powershell git merge upstream/main git checkout HEAD~1 -- fly.toml git add -- fly.toml git commit -m "chore(deploy): keep fork fly.toml" git push origin main ``` Poznámky: - `git merge upstream/main` synchronizuje nejnovější kód z původního repozitáře - `git checkout HEAD~1 -- fly.toml` obnoví vlastní soubor `fly.toml` vašeho forku do stavu před sloučením - Pokud upstream repozitář soubor `fly.toml` nezměnil, tento krok nezpůsobí žádné rozdíly - Pokud upstream repozitář soubor `fly.toml` změnil, tento krok zajistí, že název vaší aplikace Fly, připojení svazku, region a další konfigurace nasazení specifická pro váš fork nebudou přepsány Pokud chcete provést synchronizaci s konkrétním tagem vydání (např. `v3.4.7`), nejprve ověřte, že je daný tag již zahrnut ve větvi `upstream/main`: ```powershell git merge-base --is-ancestor v3.4.7 upstream/main ``` Úspěšný návratový stav znamená, že větev `upstream/main` již tuto verzi obsahuje; můžete tedy jednoduše sloučit větev `upstream/main`. ### 9.2 Standardní postup vydání po synchronizaci s upstream repozitářem Po synchronizaci s původním repozitářem dodržujte toto doporučené pořadí vydání: 1. `git fetch upstream --tags` 2. `git merge upstream/main` 3. Obnovte soubor `fly.toml` forku 4. `git push origin main` 5. `flyctl deploy` 6. `flyctl status -a omniroute` 7. `flyctl logs --no-tail -a omniroute` Toto je skutečný pracovní postup použitý při upgradu aktuálního projektu na verzi `v3.4.7` (příklad odkazuje na historickou verzi; aktuální skutečná verze je `v3.8.0`). --- ## 10. Kontroly po nasazení ### 10.1 Kontrola stavu aplikace ```powershell flyctl status -a omniroute ``` ### 10.2 Zobrazení spouštěcích protokolů ```powershell flyctl logs --no-tail -a omniroute ``` ### 10.3 Ověření dostupnosti webu ```powershell try { (Invoke-WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).StatusCode } catch { if ($_.Exception.Response) { $_.Exception.Response.StatusCode.value__ } else { throw } } ``` Návratová hodnota `200` znamená, že web odpovídá správně. --- ## 11. Ukazatele úspěšného nasazení Po úspěšném nasazení by protokoly měly obsahovat podobný obsah: ```text [bootstrap] Secrets persisted to: /data/server.env [DB] SQLite database ready: /data/storage.sqlite ``` Tyto dva body jsou zásadní: - `/data/server.env` potvrzuje, že tajné údaje běhového prostředí jsou zapsány do trvalého svazku - `/data/storage.sqlite` potvrzuje, že databáze je zapsána do trvalého svazku Pokud se místo toho zobrazí `/app/data/...`, proměnná `DATA_DIR` je nesprávně nakonfigurována a musí být okamžitě opravena. --- ## 12. Běžné problémy ### 12.1 Stránka `Secrets` je prázdná Obvykle existují dva důvody: - Ještě jste nespustili `flyctl secrets set` - Prohlížíte jinou aplikaci (např. `oroute` namísto `omniroute`) ### 12.2 `flyctl deploy` hlásí `app not found` Nejprve aplikaci vytvořte: ```powershell flyctl apps create omniroute ``` ### 12.3 Analýza souboru `fly.toml` selže Zkontrolujte následující: - Zda komentáře neobsahují poškozené znaky - Zda jsou uvozovky a odsazení TOML správné ### 12.4 Data nejsou trvale ukládána Ověřte obě následující položky: - `fly.toml` obsahuje `destination = '/data'` - `DATA_DIR` je nastavena na `/data` ### 12.5 Lze aplikaci spustit bez `INITIAL_PASSWORD`? Ano, lze. Použije se výchozí heslo `CHANGEME`. V produkčním prostředí se doporučuje heslo backendu co nejdříve změnit. --- ## 13. Opakované použití pro nové projekty Pokud podle tohoto dokumentu nasazujete nový projekt, stačí změnit následující položky: 1. Změňte hodnotu `app` v souboru `fly.toml` 2. Změňte `NEXT_PUBLIC_BASE_URL` 3. Ponechte `DATA_DIR=/data` 4. Znovu vygenerujte `API_KEY_SECRET`, `JWT_SECRET`, `MACHINE_ID_SALT` a `STORAGE_ENCRYPTION_KEY` 5. Po prvním nasazení ověřte, že jsou protokoly zapisovány do `/data` Nepoužívejte znovu klíče z předchozího projektu. --- ## 14. Minimální kontrolní seznam pro vydání aktuálního projektu Nejčastěji používané příkazy pro následná vydání jsou: ```powershell flyctl auth whoami flyctl status -a omniroute flyctl secrets list -a omniroute flyctl deploy flyctl logs --no-tail -a omniroute ``` Pro běžné vydání je hlavním příkazem jednoduše: ```powershell flyctl deploy ``` Při prvním nasazení v novém prostředí jsou hlavní kroky následující: 1. `flyctl auth login` 2. `flyctl apps create omniroute` 3. `flyctl secrets set ... -a omniroute` 4. `flyctl deploy` 5. `flyctl logs --no-tail -a omniroute`