# OmniRoute Fly.io Deployment Guide (Български)

🌐 **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) · 🇧🇩 [bn](../../../bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../../cs/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)

---

Този документ описва действителния процес за внедряване на OmniRoute във Fly.io и обхваща следните сценарии:

- Първоначално внедряване на текущия проект във Fly.io
- Публикуване на последващи актуализации на кода
- Нови проекти, следващи същия процес за внедряване

Това ръководство се основава на проверена и работеща конфигурация за текущия проект. Името на приложението е `omniroute`.

---

## 1. Цели на внедряването

- Платформа: Fly.io
- Метод за внедряване: Директно локално публикуване чрез `flyctl`
- Среда за изпълнение: Използване на съществуващите `Dockerfile` и `fly.toml` в хранилището
- Постоянно съхранение на данни: Fly Volume, монтиран в `/data`
- URL за достъп: `https://omniroute.fly.dev/`

---

## 2. Ключова конфигурация на текущия проект

Потвърдено е, че файлът `fly.toml` в текущото хранилище съдържа следните ключови настройки:

```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"
```

Бележки:

- `app = 'omniroute'` определя към кое приложение във Fly е насочено внедряването
- `destination = '/data'` определя директорията за монтиране на постоянния том
- За този проект трябва да бъде зададено `DATA_DIR=/data`, в противен случай базата от данни и ключовете ще бъдат записани във временната директория на контейнера

---

## 3. Предварителни изисквания

### 3.1 Инсталиране на Fly CLI

Windows PowerShell:

```powershell
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
```

Ако скриптът за инсталиране не се изпълни успешно във вашата среда, можете също ръчно да изтеглите изпълнимия файл `flyctl` и да го добавите към вашата променлива `PATH`.

### 3.2 Влизане във вашия Fly акаунт

```powershell
flyctl auth login
```

### 3.3 Проверка на състоянието на влизане

```powershell
flyctl auth whoami
flyctl version
```

---

## 4. Първоначално внедряване на текущия проект

### 4.1 Клониране на кода и влизане в директорията

```powershell
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
```

### 4.2 Потвърждаване на името на приложението

Отворете `fly.toml` и проверете следния ред:

```toml
app = 'omniroute'
```

Ако внедрявате в свое ново приложение, можете да го промените на глобално уникално име, например:

```toml
app = 'omniroute-yourname'
```

Забележка:

- Уверете се, че приложението, което виждате в конзолата, съответства на стойността на `app` във `fly.toml`
- Ако преди сте използвали друго име, например `oroute`, не го бъркайте с `omniroute`

### 4.3 Създаване на приложението

Ако приложението все още не съществува:

```powershell
flyctl apps create omniroute
```

Ако сте променили името на приложението, заменете `omniroute` с избраното от вас име.

### 4.4 Първоначално внедряване

```powershell
flyctl deploy
```

---

## 5. Задължителни параметри

За този проект се препоръчва във Fly.io да бъдат конфигурирани поне следните параметри.

### 5.1 Проверени параметри

Тези параметри са използвани при реални внедрявания на текущото приложение `omniroute`:

- `API_KEY_SECRET`
- `DATA_DIR`
- `JWT_SECRET`
- `MACHINE_ID_SALT`
- `NEXT_PUBLIC_BASE_URL`
- `OMNIROUTE_WS_BRIDGE_SECRET` (задължителен в производствена среда — използва се за удостоверяване на WebSocket моста)
- `STORAGE_ENCRYPTION_KEY`

### 5.2 Относно `INITIAL_PASSWORD`

В текущия проект `INITIAL_PASSWORD` не е зададен, тъй като не е необходим за това внедряване.

Ако не е зададен:

- Дневникът при стартиране ще покаже, че паролата по подразбиране е `CHANGEME`
- Трябва да промените паролата за вход в системните настройки възможно най-скоро след внедряването

Ако искате да инициализирате паролата на бекенда без ръчна намеса, можете да я добавите по-късно:

- `INITIAL_PASSWORD`

---

## 6. Препоръчителни параметри

### 6.1 Конфигурация на тайните

Следните променливи се препоръчват за Fly Secrets:

| Променлива                                 | Препоръка                | Описание                                                       |
| ------------------------------------------ | ------------------------ | -------------------------------------------------------------- |
| `API_KEY_SECRET`                           | Задължителна             | Използва се за генериране и валидиране на API ключове          |
| `JWT_SECRET`                               | Задължителна             | Използва се за сесии за вход и подписване на JWT               |
| `OMNIROUTE_WS_BRIDGE_SECRET`               | Задължителна в продукция | Тайна за удостоверяване на WebSocket моста                     |
| `STORAGE_ENCRYPTION_KEY`                   | Силно препоръчителна     | Шифрова чувствителната информация за връзките при съхранение   |
| `MACHINE_ID_SALT`                          | Препоръчителна           | Генерира стабилен идентификатор на машината                    |
| `INITIAL_PASSWORD`                         | Незадължителна           | Задава първоначалната парола за бекенда при първото внедряване |
| Частни идентификационни данни за OAuth/API | Според необходимостта    | Конфигурация за удостоверяване във външна платформа            |

### 6.2 Препоръчителни стойности за текущия проект

| Променлива             | Препоръчителна стойност     |
| ---------------------- | --------------------------- |
| `DATA_DIR`             | `/data`                     |
| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |

Бележки:

- `DATA_DIR=/data` е от критично значение и трябва да съответства на точката за монтиране на Fly Volume
- `NEXT_PUBLIC_BASE_URL` се използва от планировчика, обратните извиквания на фронтенда и при подобни сценарии

### 6.3 Конфигурация на URL адреса за обратно извикване на OAuth

Ако трябва да активирате доставчици, базирани на OAuth (например Antigravity, Gemini, Cursor), при внедряването във Fly.io, уверете се в следните две неща:

1. **Задайте `NEXT_PUBLIC_BASE_URL` на своя публичен HTTPS домейн**

   ```powershell
   flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute
   ```

   Ако използвате персонализиран домейн, заменете го със съответния домейн (например `https://omniroute.yourdomain.com`).

2. **Конфигурирайте URL адреса за обратно извикване в конзолата на доставчика**

   Всички OAuth доставчици използват един и същ път за обратно извикване `/callback` — НЯМА отделен маршрут за обратно извикване за всеки доставчик:

   ```text
   <NEXT_PUBLIC_BASE_URL>/callback
   ```

   Например, независимо дали става въпрос за Gemini, Antigravity, Cursor или GitLab Duo:
   - `https://omniroute.fly.dev/callback`

   Ако `NEXT_PUBLIC_BASE_URL` не съвпада с URL адреса за обратно извикване, регистриран при доставчика, OAuth процесът ще се провали на стъпката за пренасочване в браузъра.

---

## 7. Настройване на тайните с една команда

Следните команди генерират сигурни произволни стойности и записват всички необходими параметри за текущия проект във Fly Secrets с една стъпка.

Бележки:

- Не включва `INITIAL_PASSWORD`
- Предназначено е за текущия проект `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
```

В Linux / macOS можете също да използвате `openssl rand -hex 32`:

```bash
flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute
```

Бележки:

- `OMNIROUTE_WS_BRIDGE_SECRET` е задължителна в продукция; липсата ѝ ще наруши установяването на връзка с WebSocket моста

Ако искате да зададете и първоначална парола:

```powershell
flyctl secrets set INITIAL_PASSWORD=your-strong-password -a omniroute
```

---

## 8. Преглед на текущите параметри

```powershell
flyctl secrets list -a omniroute
```

Ако страницата `Secrets` в конзолата не показва очакваните променливи, проверете:

- Дали разглеждате приложението `omniroute`
- Дали стойността `app` във `fly.toml` съответства на приложението в конзолата

---

## 9. Последващи актуализации и издания

След актуализации на кода процесът по издаване е лесен:

```powershell
git pull
flyctl deploy
```

Ако трябва само да актуализирате параметрите, без да променяте кода:

```powershell
flyctl secrets set KEY=value -a omniroute
```

Fly автоматично ще извърши поетапна актуализация на машините.

### 9.1 Проследяване на актуализациите в основното хранилище при запазване на `fly.toml` от вашия форк

Ако текущото хранилище е форк и искате да синхронизирате актуализации от основното хранилище `https://github.com/diegosouzapw/OmniRoute`, следвайте работния процес по-долу.

Първо проверете отдалечените хранилища:

```powershell
git remote -v
```

Трябва да видите поне:

- `origin`, сочещо към собствения ви форк
- `upstream`, сочещо към оригиналното хранилище

Ако `upstream` не е конфигурирано, добавете го:

```powershell
git remote add upstream https://github.com/diegosouzapw/OmniRoute.git
```

Преди синхронизирането с основното хранилище извлечете най-новите къмити и тагове:

```powershell
git fetch upstream --tags
```

Проверете текущата версия и таговете в основното хранилище:

```powershell
git describe --tags --always
git show --no-patch --oneline v3.4.7
```

> Забележка: Текущата версия на проекта е `v3.8.0`. Препратките към `v3.4.7` по-долу са запазени само като исторически примери. За реални издания използвайте `:latest` или тага на текущата версия (напр. `:v3.8.0`).

Ако искате да слеете най-новата версия на `main` от основното хранилище, като принудително запазите `fly.toml` от вашия форк, следвайте този работен процес:

```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
```

Забележки:

- `git merge upstream/main` синхронизира най-новия код от оригиналното хранилище
- `git checkout HEAD~1 -- fly.toml` възстановява собствения `fly.toml` на вашия форк отпреди сливането
- Ако `fly.toml` не е бил променен в основното хранилище, тази стъпка няма да въведе разлики
- Ако `fly.toml` е бил променен в основното хранилище, тази стъпка гарантира, че името на вашето Fly приложение, монтираният том, регионът и другите специфични за форка настройки за разполагане няма да бъдат презаписани

Ако искате да се приведете в съответствие с конкретен таг на издание (напр. `v3.4.7`), първо проверете дали тагът вече е включен в `upstream/main`:

```powershell
git merge-base --is-ancestor v3.4.7 upstream/main
```

Успешното изпълнение означава, че `upstream/main` вече съдържа тази версия; можете просто да слеете `upstream/main`.

### 9.2 Стандартна последователност за издаване след синхронизиране с основното хранилище

След синхронизирането с оригиналното хранилище следвайте този препоръчителен ред за издаване:

1. `git fetch upstream --tags`
2. `git merge upstream/main`
3. Възстановете `fly.toml` на форка
4. `git push origin main`
5. `flyctl deploy`
6. `flyctl status -a omniroute`
7. `flyctl logs --no-tail -a omniroute`

Това е действителният работен процес, използван при надграждането на текущия проект до `v3.4.7` (примерът се отнася до историческа версия; текущата действителна версия е `v3.8.0`).

---

## 10. Проверки след внедряване

### 10.1 Проверка на състоянието на приложението

```powershell
flyctl status -a omniroute
```

### 10.2 Преглед на журналите при стартиране

```powershell
flyctl logs --no-tail -a omniroute
```

### 10.3 Проверка на достъпността на сайта

```powershell
try {
  (Invoke-WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).StatusCode
} catch {
  if ($_.Exception.Response) {
    $_.Exception.Response.StatusCode.value__
  } else {
    throw
  }
}
```

Върната стойност `200` показва, че сайтът отговаря нормално.

---

## 11. Индикатори за успех

След успешно внедряване журналите трябва да показват съдържание, подобно на следното:

```text
[bootstrap] Secrets persisted to: /data/server.env
[DB] SQLite database ready: /data/storage.sqlite
```

Тези две точки са от решаващо значение:

- `/data/server.env` потвърждава, че тайните за средата на изпълнение са записани в постоянния том
- `/data/storage.sqlite` потвърждава, че базата данни е записана в постоянния том

Ако вместо това виждате `/app/data/...`, `DATA_DIR` е конфигурирана неправилно и трябва незабавно да бъде коригирана.

---

## 12. Често срещани проблеми

### 12.1 Страницата `Secrets` е празна

Обикновено има две причини:

- Все още не сте изпълнили `flyctl secrets set`
- Преглеждате друго приложение (например `oroute` вместо `omniroute`)

### 12.2 `flyctl deploy` съобщава `app not found`

Първо създайте приложението:

```powershell
flyctl apps create omniroute
```

### 12.3 Анализирането на `fly.toml` е неуспешно

Проверете следното:

- Дали в коментарите има повредени символи
- Дали кавичките и отстъпите в TOML са правилни

### 12.4 Данните не се запазват постоянно

Проверете и двете от следните условия:

- `fly.toml` съдържа `destination = '/data'`
- `DATA_DIR` е зададена на `/data`

### 12.5 Може ли да работи без `INITIAL_PASSWORD`?

Да, може да работи. Ще се използва паролата по подразбиране `CHANGEME`. Препоръчително е паролата за бекенда да бъде променена възможно най-скоро в продукционна среда.

---

## 13. Повторно използване за нови проекти

Ако внедрявате нов проект, следвайки този документ, трябва да промените само следните елементи:

1. Променете стойността на `app` във `fly.toml`
2. Променете `NEXT_PUBLIC_BASE_URL`
3. Запазете `DATA_DIR=/data`
4. Генерирайте отново `API_KEY_SECRET`, `JWT_SECRET`, `MACHINE_ID_SALT` и `STORAGE_ENCRYPTION_KEY`
5. След първото внедряване проверете дали журналите се записват в `/data`

Не използвайте повторно ключове от предишен проект.

---

## 14. Минимален контролен списък за издаване на текущия проект

Най-често използваните команди за последващи издания са:

```powershell
flyctl auth whoami
flyctl status -a omniroute
flyctl secrets list -a omniroute
flyctl deploy
flyctl logs --no-tail -a omniroute
```

За обикновено издание основната команда е просто:

```powershell
flyctl deploy
```

При първоначално внедряване в нова среда основните стъпки са:

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`