---
name: omniroute-update
description: Обновить/починить/проверить self-hosted LLM-шину OmniRoute на mac mini (боевая, LaunchDaemon под omniroute_svc) и на MacBook (LaunchAgent). Брать когда - «обнови omniroute», «шина omniroute упала/тормозит», «дашборд omniroute в ошибке / логин не появляется», «проверь шину после обновления», «OOM heap out of memory у omniroute», «codex-запросы сериализуются», нужно узнать актуальную версию пакета omniroute или откатиться. НЕ для - настройки провайдеров/моделей в Dashboard UI (это руками юзера), не для клиентских LLM-цепочек ботов (это их репо).
---

# Обновление и обслуживание OmniRoute

Полные знания об инстансах: Obsidian `Projects/omniroute/` (Architecture —
порты/механики, Scenarios — готовые команды, Decisions D1–D8 — почему так).
Прочитай Decisions перед нестандартными действиями.

## Карта (кратко)

| | mini (боевой) | MacBook |
|---|---|---|
| Код | ГЛОБАЛЬНЫЙ `/opt/homebrew/lib/node_modules/omniroute` | app-локальный `~/.local/share/omniroute-app/node_modules/omniroute` (+глобальный для CLI) |
| launchd | `system/com.cebers.omniroute` (нужен sudo) | `gui/$(id -u)/com.cebers.omniroute` |
| workdir (.env, data/) | `/Users/omniroute_svc/.local/share/omniroute-app` (читать через sudo) | `~/.local/share/omniroute-app` |
| доступ | `ssh -p 2222 cebers_mini@100.84.177.25` | локально |

Порты одинаковы: клиенты :20127 (Anthropic `/v1/messages`; chat/completions там 404!),
OpenAI-shape :20128, Dashboard :20129. Ключ: `set -a; . ~/.codex/omniroute.env; set +a`.

## Протокол обновления

⚠️ **Урок 2026-07-05: апгрейд 3.8.33→3.8.44 МОЛЧА УДАЛИЛ все codex-подключения
из provider_connections.** После КАЖДОГО обновления обязательно сверить
счётчики подключений по провайдерам с pre-upgrade бэкапом:
```sql
-- на бэкапе (открывать immutable-URI: file:...?immutable=1) и на текущей БД:
SELECT provider, count(*) FROM provider_connections GROUP BY provider;
```
Пропали строки → восстановить: `ATTACH 'file:<бэкап>?immutable=1' AS b;
INSERT OR IGNORE INTO provider_connections SELECT * FROM b.provider_connections
WHERE provider='<пропавший>';` → рестарт → проверить провайдера живым вызовом.
Копию бэкапа из /tmp после этого УДАЛИТЬ (в ней токены).

1. **Пароль** (sudo mini + при желании проверка логина) — спросить у юзера в момент
   операции. ЗАПРЕЩЕНО сохранять в файлы/скилл/историю понятным текстом (D1).
2. **Узнать целевую версию**: `npm view omniroute version` (или юзер назвал).
3. **Прогнать `tools/update.sh`** — он делает: бэкап БД (sqlite3 .backup в
   db_backups/) → npm install нужной копии → рестарт launchd → верификация
   (models 200, login-страница 200, живой chat-вызов 200). Флаги см. `-h`.
4. **Верификация сверх скрипта** (если меняли что-то про codex): параллельный
   тест двух codex-моделей (Scenarios §7 — паттерн /tmp/codex_diag2.py на mini,
   создать по образцу из Obsidian cryptopilot v0.2.22): здоровье = оба ~15-20с.
5. **Задокументировать**: строка в Obsidian `Projects/omniroute/Changelog.md`
   (версия, что менялось, чем проверено).

## Быстрые починки (без обновления)

- **Дашборд в ошибке / логин не появляется** → почти всегда OOM: в stderr-логе
  workdir/logs/launchd.stderr.log ищи `heap out of memory`; проверь
  `OMNIROUTE_MEMORY_MB` в .env (должно быть 2048) → рестарт → `tools/update.sh
  --verify-only <target>`.
- **Рестарт**: mini `sudo launchctl kickstart -k system/com.cebers.omniroute`;
  MacBook `launchctl kickstart -k gui/$(id -u)/com.cebers.omniroute`. Потребители
  ловят ~30с ошибок — не делать в дайджест-слоты CryptoPilot (03/11/19 МСК).
- **npm ENOTEMPTY** про `.omniroute-<hash>` → `rm -rf` этой мусорной папки в
  node_modules и повторить install.
- **Откат**: `tools/update.sh --version <старая>` (npm ставит любую); БД-бэкап
  восстанавливать только при реальной порче (redeploy кода БД не трогает).

## Грабли

- **Битый опубликованный релиз (3.8.45 И 3.8.46 битые, 2026-07-06/07)**: после апгрейда
  сервис стартует, но ВСЕ маршруты 404, в stderr `Cannot find module './chunks/89442.js'`
  (+ `Failed to load external module zod-...`) — чанка нет в собранной установке
  (packaging-баг разработчика, не чинится два релиза). **Проверка тарбола `npm pack`
  НЕНАДЁЖНА** — webpack-runtime генерится при установке, layout архива ≠ установленному
  (webpack-runtime.js в архиве не найти). Единственный надёжный тест — поставить на
  **MacBook-полигон** (не прод!) через `update.sh --version <ver> local`, затем
  `grep -iE "Cannot find module|chunks/" ~/.local/share/omniroute-app/logs/launchd.stderr.log`
  + повторный `--verify-only local`. Битый → откат `update.sh --version 3.8.44 local`,
  **боевой mini НЕ трогать**. **3.8.44 — последняя рабочая версия** (на 2026-07-07);
  следующий апгрейд пробовать только когда выйдет релиз НОВЕЕ 3.8.46.
- На MacBook работает APP-ЛОКАЛЬНАЯ копия — обновление только глобальной НЕ
  меняет работающий сервис.
- `.env` боевого инстанса читается из workdir (плист env почти пуст) — править
  через sudo, бэкапить перед правкой (`cp .env .env.bak-...`).
- Настройки живут в `data/storage.sqlite` `key_value(namespace,key,value)`,
  значения — JSON (строки в кавычках); сервис кэширует их — после прямой правки
  нужен рестарт. Лучше менять через Dashboard.
- Ошибка «Worker local total request limit (16/16)» — upstream OpenAI, шиной не
  лечится (только >1 аккаунта в пуле).
- **OAuth «добавить аккаунт» падает «соединение не удалось»** → OAuth-обмен кода
  в коде шины — голый fetch без прокси, а auth.openai.com с мини = 403 (гео).
  Фикс уже стоит в плисте демона mini: `NODE_USE_ENV_PROXY=1` +
  `HTTPS_PROXY=http://127.0.0.1:2081` + `NO_PROXY=localhost,127.0.0.1` —
  НЕ удалять при правках плиста. Плист перечитывается ТОЛЬКО через
  `sudo launchctl bootout system/com.cebers.omniroute && sudo launchctl
  bootstrap system /Library/LaunchDaemons/com.cebers.omniroute.plist`
  (kickstart -k НЕ перечитывает EnvironmentVariables).
