---
owner: gmikcon
status: active
last_reviewed: "2026-10-07"
review_interval: "90d"
confidence: "high"
source_of_truth: "ssh-host-and-live-verified"
---

# Gnexus Synapse

Централизованный хаб уведомлений экосистемы Gnexus: сервисы присылают событие «что случилось», Synapse решает, кому, куда и каким каналом доставить (Telegram, Email, Push, internal log, system-to-system в Navi). Проект gntodo id 9; репозиторий `root/gn-synapse` на GitBucket.

## Identity

- Host: `gnsynapse` (192.168.1.172), VM на `hp-proliant-dl380-g6`
- Deploy path: `/home/ubuntu/gnsynapse` (git clone, HEAD `2f6d8d4`)
- Stack: docker compose (api + worker + postgres:17 + redis:7), порт хоста 8013
- Public URL: `https://synapse.gnexus.space`
- Credentials: gnexus-creds secret `gn-synapse-prod-secrets` (id 616b707b-8194-4c98-a031-374b39012e9c) — POSTGRES_PASSWORD, MCP_TOKEN, GAUTH_CLIENT_ID/SECRET, GAUTH_WEBHOOK_SECRET; SSH хоста — secret `gnsynapse-ssh`

## Deployment (2026-10-04, navi rei)

- `docker compose up -d --build` через sudo (user ubuntu не в docker-группе — ловушка как на bugtrail).
- Alembic-миграции применяются entrypoint'ом api автоматически; голова `a4f8d2c17b90` (после Update 18:40).
- `.env` создан из `.env.example`: POSTGRES_PASSWORD и MCP_TOKEN = `openssl rand -hex`, `GAUTH_BASE_URL=https://auth.gnexus.space`, `GAUTH_VERIFY_TLS=true`, `GAUTH_REDIRECT_URI=https://synapse.gnexus.space/auth/callback`, `SYNAPSE_PORT=8013`.
- `docker-compose.override.yml` (локальная модификация, переживает git pull): extra_hosts `auth.gnexus.space:192.168.1.226` для api и worker — серверный call-home (валидация opaque-токенов через userinfo) идёт в LAN через internal-proxy, где валидный LE-сертификат. Браузерный редирект остаётся на публичный auth.gnexus.space (GAUTH_BASE_URL).

## Update 2026-10-04 13:37 (navi rei)

- Минорное обновление `82d9181..e00539e` (fix: знак Synapse на экране входа, правка frontend-ассетов).
- Апстрим-баг: коммит `e00539e` удалил `frontend/public/assets/imgs/gnexus-mark.svg`, но ссылка в `LoginView.vue:19` осталась — Vite-сборка пала (`npm run build` exit 1, unresolved import). Описание коммита утверждало замену на `synapse-mark.svg`, фактически строка не была изменена.
- Локальный фикс: `LoginView.vue:19` → `/assets/imgs/synapse-mark.svg` (sed), пересборка, стек поднят.
- Бэкап перед обновлением: `/home/ubuntu/backup-synapse-2026-10-04-1337.sql` (24 KB).
- Проверено после обновления: postgres/redis healthy, api healthy, worker celery ready, healthz/readyz ok, SPA отдаётся, `/assets/imgs/synapse-mark.svg` → 200 image/svg+xml, старый ассет → SPA-fallback (200 text/html, файл из dist удалён), публичный healthz ok, `/login` 200.

## Update 2026-10-04 15:00 (navi rei) — персональные MCP-ключи

- Обновление `e00539e..f13a251` (2 коммита): `f13a251` feat: персональные MCP-ключи — выпуск в SPA, роль владельца у тула; `2b86b4b` fix: ссылки на gnexus-mark в LoginView и docs/06 (дополнение к e00539e).
- Локальный фикс LoginView из Update 13:37 сброшен перед pull — апстримный `2b86b4b` содержит идентичное исправление (тот же diff f7c45c0..f8ff947); пункт «запушить фикс» из Pending закрыт апстримом.
- Миграция `20261004_0008_mcp_tokens.py` (c9a2d6e71f43): таблица `mcp_tokens` (user_id, name, system_role, token_hash, token_hint, last_used_at, revoked_at) — применена, `alembic current` = head.
- `.env` не менялся: по новому `.env.example` семантика `MCP_TOKEN` сместилась — теперь это опциональный статический Bearer суперадмин-бэкдора; `/mcp` монтируется всегда, персональные ключи `mcp_...` пользователи выпускают себе в SPA на `/mcp-keys`. Наш MCP_TOKEN оставлен как есть (работает как бэкдор).
- Бэкап после обновления: `/home/ubuntu/backup-synapse-2026-10-04-postupdate.sql` (26 KB).
- Проверено после обновления: api healthy, postgres/redis healthy, worker обрабатывает задачи (`synapse.retry_due succeeded` в логах, PID1 `celery -A app.worker.celery_app worker -B`), healthz/readyz ok, SPA 200, `/mcp` без токена 401, `/mcp-keys` 200, публичный healthz ok, публичная SPA 200.

## Update 2026-10-04 18:40 (navi rei) — i18n и блокировка пользователей

- Обновление `f13a251..0ba611c` (3 коммита): `0ba611c` docs/06: язык интерфейса в Настройках (override, /me, Accept-Language); `597fb30` синхронизация с gnexus-handbook: healthz, /mcp-protocol/, блокировка, i18n; `689ea95` docs: конвенции экосистемы — ссылка на gnexus-handbook.
- Diffstat: 40 файлов +2281/−452 — i18n ru/en/uk (~389–390 строк каждый), все views обновлены.
- Миграция `20261004_0009_user_prefs.py` (a4f8d2c17b90): таблица `user_prefs` (user_id = sub gnexus-auth PK, locale override, blocked NOT NULL default false, blocked_at, updated_at) — применена, `alembic current` = head.
- Флаг `blocked` приходит из вебхуков gnexus-auth (user.blocked/unblocked/deleted/archived/restored) и гейтит MCP-токены владельца.
- `.env` не менялся; локально только untracked `docker-compose.override.yml` (не мешает).
- Бэкап ДО обновления: `/home/ubuntu/backup-synapse-2026-10-04-1505-preupdate.sql` (26 KB, валидный дамп).
- Проверено после обновления: api healthy, postgres/redis healthy, worker обрабатывает задачи (`synapse.retry_due succeeded`), healthz/readyz ok, SPA 200, `/mcp` без токена 401, публичный healthz ok, публичная SPA 200.

## Update 2026-10-05 03:50 (navi rei) — MCP подключён к Navi (rei)

- Владелец выдал персональный MCP-ключ (роль владельца); Navi rei подключила Synapse как MCP-сервер: `/home/ubuntu/navi-1/mcp_servers.d/synapse.json` (локальная модификация, переживает git stash при обновлениях). Конфиг: url `http://192.168.1.172:8013/mcp`, headers `Authorization: Bearer mcp_…` + `Host: localhost:8013`.
- **Ловушка Host-заголовка**: FastMCP на бэкенде Synapse отклоняет запросы с Host `synapse.gnexus.space` → 421 «Invalid Host header» (DNS-rebinding защита). Прямой LAN-эндпоинт `http://192.168.1.172:8013/mcp` принимает только `Host: localhost:8013` или `127.0.0.1:8013`.
- **Следствие — публичный MCP-эндпоинт сломан для внешних клиентов**: nginx на .226 передаёт `proxy_set_header Host $host`, бэкенд отвечает 421 на `https://synapse.gnexus.space/mcp`. Варианты фикса (не применены, решение за владельцем): (а) на .226 выделить `location /mcp` с `proxy_set_header Host localhost:8013`; (б) серверно ослабить host-validation в Synapse (доверенный хост). Внутренние клиенты LAN работают через прямое подключение с подменой Host.
- Проверено: initialize на LAN-эндпоинте → 200, serverInfo `synapse v1.30.0`; после рестарта navi.service в реестре Navi 35 тулов `mcp__synapse__*` (system_status, stats_get, sources_*, keys_*, types_*, targets_*, rules_*, events_*, deliveries_list, push_*, settings_*, me, my_*, send_test_event) — в docs/07 было 31, список вырос.
- Нюанс рестарта navi.service: SIGTERM не завершал старый процесс, пока жива сессия агента (веб-клиент держит соединение); systemd добил по TimeoutStopSec (~90 c), новый процесс подхватил конфиг. Проверка подключения без journalctl: `GET http://127.0.0.1:8099/agents/mcp_servers` (без авторизации) → `connected: true`.

## Update 2026-10-05 04:35 (navi rei) — admin-сводка и мобильная адаптация

- Обновление `0ba611c..2f6d8d4` (2 коммита): `a188bf8` Обзор: admin-сводка вместо пустой витрины; `2f6d8d4` Мобильная адаптация: перенос строк и модалка правил на узких экранах.
- Diffstat: 14 файлов +277/−51 — admin_routes.py (+46), mcp/tools.py (−44), DashboardView.vue (+143), i18n ru/en/uk (+11 каждый), RuleForm.vue, api.js, мелкие правки views.
- Миграций нет: `alembic current` = `a4f8d2c17b90 (head)` — без изменений.
- `.env` не менялся; локально только untracked `docker-compose.override.yml` (пережил pull и пересборку).
- Бэкап ДО обновления: `/home/ubuntu/backup-synapse-preupdate-2026-10-05-0433.sql` (28 KB, валидный дамп, pg_dump rc=0).
- Проверено после обновления: api healthy, postgres/redis healthy, worker celery ready (beat запущен, connected to redis), healthz `{"status":"ok","service":"synapse"}`, readyz postgres ok + redis ok, логи api без traceback (миграции entrypoint'ом — «применяю миграции...» без ошибок), MCP-запросы обрабатываются (POST /mcp 200).

## Update 2026-10-07 (navi rei) — источник tgclient подключён

- Source `tgclient` (id 2, label tgclient-mcp) создан через MCP; зарегистрированы 10 типов (ids 2–11): `account/logged_in|logged_out|auth_lost|login_failed`, `api/flood_wait`, `token/issued|revoked`, `message/received|edited|deleted` — ровно по каталогу SINKS репортера tgclient-mcp (`backend/app/synapse_report.py`).
- API-ключ выдан (key id 2, hint `0b7b`), plaintext — в gnexus-creds secret «tgclient-mcp Synapse reporter API key (syn_…)» (id 98284541-d320-4bc4-b691-09295d22dba3).
- На стороне tgclient-mcp (.171): TGCLIENT_SYNAPSE_URL=http://192.168.1.172:8013, TGCLIENT_SYNAPSE_API_KEY=syn_…0b7b, **TGCLIENT_SYNAPSE_DEFAULT_SOURCE=tgclient** (не tgclient-mcp — иначе 403 «Поле source не совпадает с источником ключа»), TGCLIENT_SYNAPSE_TIMEOUT=10. Контейнер пересоздан, health ok.
- E2E проверено: POST `/api/v1/events` с syn_-ключом с .171 → 202, событие `token/issued` (c9837953) status done; контрольный `send_test_event` `account/logged_in` (75ede28e) тоже done.
- Пуш-события сообщений (message/received|edited|deleted) выключены: TGCLIENT_NOTIFY_MESSAGES не задан — решение за владельцем.

## Update 2026-10-07 19:04 (navi rei) — s2s-доставка в Navi rei (фаза 2)

- **Секрет s2s**: `S2S_SECRET_NAVI_REI=<hex 64>` добавлен в `/home/ubuntu/gnsynapse/.env` (бэкап `.env.bak-s2s-20261007`), api+worker пересозданы (`docker compose up -d`), секрет виден в обоих контейнерах, healthz/readyz ok. Plaintext — gnexus-creds secret «Synapse s2s secret navi-rei (S2S_SECRET_NAVI_REI)» (id 76fc39b4-6ebb-4d97-8505-67b2d1a37655). Схема имён: `S2S_SECRET_<TOKEN_REF>` (дефисы/точки → подчёркивания), резолвится в `app/worker/senders.py`.
- **Цель**: `navi-rei` (id 3, channel s2s) — endpoint `http://192.168.1.168:8099/webhooks/synapse`, token_ref `navi-rei`.
- **Правило**: «tgclient → navi-rei (s2s)» (id 2) — conditions `{source: tgclient}`, action s2s → target 3.
- **Сторона Navi** (192.168.1.168, navi-1): таргет зарегистрирован в postgres navidb `synapse_targets` (id 1, user_id 1, token_ref navi-rei, секрет Fernet-шифрован ключом NAVI_AUTH_ENCRYPTION_KEY — вставка через psql, шифрование тем же TokenEncryptor, что и у POST /synapse-targets); `synapse_settings` user_id 1: reactions_enabled=true, push_target=app, completion_notify=important.
- **E2E**: `send_test_event` tgclient/account/logged_in (be6a83a6) → delivery s2s navi-rei **delivered** (1 попытка); Navi: `synapse.delivery_accepted` (target_ref navi-rei, target_user_id 1), создана special-сессия «Synapse: tgclient.account.logged_in» (5427bef9), реакция-ран запущен (dispatcher → headless run).
- **Контракт доставки** (docs/05): POST конверт + event_id; заголовки `X-Gnexus-Signature` (HMAC по секрету token_ref), `X-Gnexus-Event-Type` = `{source}.{subject}.{action}`, `X-Gnexus-Event-Id`, `X-Synapse-Source`. Navi верифицирует подпись по всем активным таргетам (мисматч → 401 без указания таргета), дедуп по event_id, ack не ждёт реакцию (fire-and-forget).

## Update 2026-10-07 19:26 (navi rei) — e2e message/received после фикса _touch

- **Тест 2 пройден**: реальное входящее сообщение (id 788560, 19:26:27 UTC, от аккаунта Navi 8781031814 в диалог с владельцем, account-1) → событие tgclient/message/received `8093aa27-1c02-4a57-a7d9-c54fabb9d7ae` создано в Synapse через ~0.9 c, доставка s2s navi-rei **delivered** (1 попытка), reaction-сессия запущена. Полный конвейер tgclient → Synapse → Navi работает.
- **Тест 1** (сообщение 788559, 19:22:54 UTC, до фикса `_touch` на стороне tgclient-mcp) в Synapse отсутствует — событие не создано, что подтверждает баг до фикса.
- После фикса пошёл поток `message/edited` из каналов (например, -1001431180517 Times of Ukraine) — все доставки delivered.
- **Риск петли (не исправлено, решение за владельцем)**: правило id 2 матчит весь источник tgclient без фильтра по payload (entity/account/out) — ответ Navi в Telegram порождает новое событие message/received и новую reaction-сессию. Рекомендация: добавить в conditions фильтр payload (например, только входящие на account-1 от чужих отправителей) или гейтить реакцию на стороне Navi.

## Update 2026-10-07 20:41 (navi rei) — источник hard-panel подключён

- Source `hard-panel` (id 3) создан через MCP; зарегистрированы 11 типов (ids 12–22) по каталогу SINKS репортера панели: `server/offline|online`, `container/added|removed|started|exited`, `service/down|degraded|recovered`, `resource/over_threshold|back_normal`. Приоритеты: high — server_offline, service_down, *_high; normal — container_exited, service_degraded; low — остальные.
- API-ключ выдан (key id 3, hint `89c0`), plaintext — gnexus-creds secret «hard-panel Synapse reporter API key (syn_…89c0)» (id dea3809d-f079-42aa-b268-06b69a90b36a).
- **Правило**: «hard-panel → navi-rei (s2s)» (id 3) — conditions `{source: hard-panel}`, action s2s → target 3 (navi-rei), зеркально правилу tgclient (id 2).
- Сторона панели (.176): в `/opt/hard-panel/.env` добавлены `GHARD_SYNAPSE_URL=http://192.168.1.172:8013`, `GHARD_SYNAPSE_API_KEY=syn_…89c0`, `GHARD_SYNAPSE_DEFAULT_SOURCE=hard-panel`, `GHARD_SYNAPSE_TIMEOUT=10` (бэкап `.env.bak-synapse-20261007`); compose уже пробрасывал переменные (апстрим b6080d0), контейнер пересоздан `docker compose up -d --force-recreate panel`, данные volume `panel-data` целы.
- E2E: `send_test_event` resource/over_threshold (16d26bf2) → delivery s2s navi-rei **delivered** (1 попытка); живое событие от панели cpu_high 99.9% на сервере navi (c0f332a4, dedup `cpu_high-45-20261007`) доставлено так же — репортер работает в бою.
- **Шум (решение за владельцем)**: правило матчит весь источник — каждый пороговый переход и recovery (cpu_high/cpu_recovered бывают часто) порождает reaction-сессию в Navi. Варианты: фильтр conditions по payload.type (только server_offline/service_down) или throttle_seconds на правиле.

## SSO (gnexus-auth) — настроено 2026-10-04 (рантбук §5)

- Владелец зарегистрировал OAuth-клиент `synapse` в gnexus-auth и передал креды; они вписаны в `.env` на хосте (GAUTH_CLIENT_ID `gnx_N4NS…`, GAUTH_CLIENT_SECRET, GAUTH_WEBHOOK_SECRET — значения в gnexus-creds, не в доках).
- `docker compose up -d` пересоздал api и worker; api healthy.
- Проверка: `/auth/login` → 307 на `https://auth.gnexus.space/oauth/authorize` с реальным client_id, redirect_uri `https://synapse.gnexus.space/auth/callback`, PKCE S256, scope `openid email profile roles permissions` (локально и через публичный HTTPS).
- `authorize`-эндпоинт auth-сервера на этот запрос → 302 на `/login` — клиент зарегистрирован, PKCE принят (при неизвестном клиенте была бы ошибка 400).
- Вебхуки `auth.logout` / `auth.global_logout` / `session.revoked` → `https://synapse.gnexus.space/auth/webhooks` зарегистрированы владельцем в auth при создании клиента; подпись проверяется через GAUTH_WEBHOOK_SECRET.

## Public entry

- Route: internet → external-vps (catch-all → internal-proxy) → nginx на `internal-proxy-vps` (.226) → `http://192.168.1.172:8013`.
- nginx site: `/etc/nginx/sites-available/synapse.gnexus.space` на .226; TLS Let's Encrypt `synapse.gnexus.space` (certbot --nginx, до 2027-01-02, автопродление); HTTP→HTTPS 301 добавлен вручную (certbot не вписал).
- DNS: wildcard `*.gnexus.space` → 51.83.131.93 (external-vps), отдельной записи не потребовалось.
- `proxy_buffering off` + `proxy_read_timeout 300s` — для SSE/MCP.
- Внимание: для `/mcp` см. Update 2026-10-05 — бэкенд отклоняет Host `$host`, публичный MCP-эндпоинт требует фикса.

## Verified smoke (2026-10-04)

- `/api/healthz` → `{"status":"ok","service":"synapse"}`; `/api/readyz` → postgres ok, redis ok.
- Worker: `celery@... ready.` в логах.
- SPA отдаётся на `/` (Vue 3, lang=ru).
- `/mcp` без токена → 401 (MCP включён, MCP_TOKEN задан).
- Полный конвейер: source `monitoring` + type (container/down) + target `internal_log/smoke-log` + rule + API-ключ созданы через `python -m app.cli`; POST `/api/v1/events` через публичный HTTPS → 202; доставка в БД `delivered` с отрендеренным шаблоном.

## Pending (владелец)

1. Telegram-канал — отложен до задачи #29 (не создавать цель telegram).
2. Push-канал (VAPID) — опционально, рантбук §7.
3. Фикс публичного `/mcp` (421 Invalid Host header для внешних клиентов) — варианты в Update 2026-10-05 03:50.
4. Включение пуш-событий сообщений tgclient (TGCLIENT_NOTIFY_MESSAGES=1 на .171) — по умолчанию выключены, решение за владельцем.
5. Анти-петля для правила «tgclient → navi-rei (s2s)» — фильтр payload в conditions или гейт реакции на стороне Navi (см. Update 2026-10-07 19:26).
6. Анти-шум для правила «hard-panel → navi-rei (s2s)» — фильтр payload.type (только server_offline/service_down) или throttle_seconds (см. Update 2026-10-07 20:41).

## Operations

- Обновление: `cd /home/ubuntu/gnsynapse && git pull && sudo docker compose up -d --build` (перед этим `pg_dump` — откат миграций вниз не поддерживается всеми ревизиями).
- Бэкап БД: `sudo docker compose exec -T postgres pg_dump -U synapse synapse > backup-$(date +%F).sql`.
- MCP-управление: LAN `http://192.168.1.172:8013/mcp` с `Host: localhost:8013` (работает для внутренних клиентов) или персональным ключом `mcp_...`; публичный `https://synapse.gnexus.space/mcp` — см. Pending №3 (421 для внешних клиентов).
- Smoke-объекты приёмки (source monitoring, key smoke-key, target smoke-log, rule id=1) — можно архивировать через админку/MCP после реальной настройки.
