---
owner: gmikcon
status: active
last_reviewed: 2026-10-04
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 `f13a251`)
- 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 автоматически; голова `c9a2d6e71f43` (после Update 15:00).
- `.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.

## 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.

## 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.

## 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-управление: `https://synapse.gnexus.space/mcp` с Bearer MCP_TOKEN (суперадмин-бэкдор) или персональным ключом `mcp_...` (31 тул, docs/07).
- Smoke-объекты приёмки (source monitoring, key smoke-key, target smoke-log, rule id=1) — можно архивировать через админку/MCP после реальной настройки.
