Newer
Older
gnexus-book / 10-systems / services / gnexus-synapse.md

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, statsget, sources, keys_, types*, targets, rules_, events_, deliverieslist, 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_APIKEY=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 после реальной настройки.