ZBrain

Централизованная база знаний для AI-агентов ZETIT. Веб-админка + MCP-прокси поверх gbrain.

Зачем это

У нас много разных контекстов, и каждый Claude Code инстанс сейчас читает документацию с диска целиком при каждом запросе:

ZetitConnect MSP — спецификации, спринты, архитектура
TeleraPharma — runbook'и по Exchange, MikroTik, FortiGate, 1C
ZETIT клиенты — конфигурации, инциденты, скрипты
Personal — личные проекты, недвижимость, авто
Community (Смоленская 10) — общедомовое, ЖКХ

ZBrain даёт единую точку доступа: гибридный семантический поиск по корпусу, MCP-интеграция с Claude Code/Cursor, разделение по доменам с изоляцией доступа.

Архитектура

                          ИНТЕРНЕТ
                              │
                              ↓
              brain.zetit.ru (nginx, TLS, OAuth)
                              │
              ┌───────────────┴────────────────┐
              │     brainhub-public            │
              │   - OAuth 2.1 (PKCE)           │
              │   - токены с scope             │
              │   - rate limit                 │
              │   - audit log                  │
              └───────────────┬────────────────┘
                              │
══════════════════════════════╪═══════════════════════════════
                  VPN / внутренний контур
                              │
              ┌───────────────┴────────────────┐
              │     brainhub-internal          │
              │   - Web UI (React)             │
              │   - Admin API                  │
              │   - MCP proxy router           │
              │   - SSE event aggregator       │
              └───────┬────────────┬───────────┘
                      │            │
              ┌───────┴────────────┴──────────┐
              │   gbrain instances (HTTP)     │
              │   :3001 → gbrain_zetit        │
              │   :3002 → gbrain_telerapharma │
              │   :3003 → gbrain_personal     │
              │   :3004 → gbrain_community    │
              └───────┬───────────────────────┘
                      │
              ┌───────┴───────────────────────┐
              │  PostgreSQL 16 + pgvector     │
              │  - brainhub (admin/auth/audit)│
              │  - gbrain_zetit               │
              │  - gbrain_telerapharma        │
              │  - gbrain_personal            │
              │  - gbrain_community           │
              └───────────────────────────────┘

Стек

Backend: Node.js 22 LTS + TypeScript + Express
Frontend: React 18 + TypeScript + Vite + Tailwind + shadcn/ui
DB: PostgreSQL 16 + pgvector + pg_trgm
Auth: Local email/password + Yandex OAuth + GitHub OAuth (passport.js)
Engine: gbrain (vendored через git.zetit.ru/zuevav/gbrain-mirror)
Runtime: Docker Compose в prod, native dev на разработке
Deploy: VM Ubuntu 22.04 в сети ZETIT

Структура репозитория

ZBrain/
├── apps/
│   ├── api/                # Express + TS backend
│   └── web/                # React + Vite frontend
├── packages/
│   ├── shared/             # общие типы и утилиты
│   └── mcp-proxy/          # MCP-прокси (валидация токенов, rate limit, audit)
├── deploy/
│   ├── docker/             # Dockerfile'ы и docker-compose
│   ├── systemd/            # unit-файлы для нативного деплоя
│   ├── nginx/              # конфиги reverse proxy
│   └── postgres/           # init scripts, tuning
├── docs/
│   ├── ARCHITECTURE.md     # детальная архитектура
│   ├── DEPLOYMENT.md       # инструкция по деплою
│   ├── SECURITY.md         # модель безопасности
│   ├── API.md              # API reference
│   ├── ROADMAP.md          # план по спринтам
│   └── DECISIONS/          # ADR (Architecture Decision Records)
├── scripts/
│   ├── bootstrap-vm.sh     # первичная установка на чистой Ubuntu 22.04
│   ├── create-brain.sh     # создание нового gbrain instance
│   ├── backup.sh           # бэкап всех БД
│   └── restore.sh          # восстановление
└── README.md               # этот файл

Быстрый старт

Развёртывание production VM

См. docs/DEPLOYMENT.md. Кратко:

# 1. Создать VM (4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04)
# 2. Склонировать репо
git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
cd /opt/zbrain

# 3. Запустить bootstrap (ставит Postgres, Node, Bun, gbrain, тюнит ОС)
sudo bash scripts/bootstrap-vm.sh

# 4. Создать первый брейн
sudo bash scripts/create-brain.sh zetit "ZETIT MSP" 3001

# 5. Сконфигурировать .env (см. .env.example)
sudo nano /etc/zbrain/.env

# 6. Запустить brainhub
cd /opt/zbrain
docker compose up -d

Локальная разработка

# Зависимости
bun install

# Postgres в docker
docker compose -f deploy/docker/docker-compose.dev.yml up -d

# Миграции
bun run db:migrate

# Запуск API + Web
bun run dev

API на http://localhost:3000, Web на http://localhost:5173.

Дорожная карта

Подробности — в docs/ROADMAP.md. Кратко по спринтам:

S0 — Инфраструктура VM, Postgres, базовая gbrain установка
S1 — Первый рабочий gbrain через gbrain serve --http
S2 — Каркас brainhub + локальный auth + RBAC
S3 — MCP-прокси + токены с scope
S4 — CRUD брейнов + источники + sync
S5 — Dashboard + Projects + Connect страница
S6 — OAuth (Yandex + GitHub) + публичный контур
S7 — Audit, 2FA, backup, метрики, hardening

Безопасность

Каждый gbrain instance имеет отдельного Postgres-пользователя и отдельную БД
MCP-токены имеют scope (mcp:read:<brain>, mcp:write:<brain>, mcp:admin:<brain>)
Все MCP-запросы проходят через brainhub-proxy, не напрямую к gbrain
Все действия пишутся в audit log
Публичный контур принимает только /mcp/* и /oauth/*

Подробности — docs/SECURITY.md.

Лицензия

gbrain используется по лицензии MIT, см. гigit.zetit.ru/zuevav/gbrain-mirror.

8.1 KiB Raw Permalink Blame History Unescape Escape