main

2026-05-20 19:33:02 +03:00
commit f4bca8449e
30 changed files with 4152 additions and 0 deletions
@@ -0,0 +1,173 @@
+# ZBrain
+
+Централизованная база знаний для AI-агентов ZETIT. Веб-админка + MCP-прокси поверх [gbrain](https://github.com/garrytan/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](docs/DEPLOYMENT.md). Кратко:
+
+```bash
+# 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
+```
+
+### Локальная разработка
+
+```bash
+# Зависимости
+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](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](docs/SECURITY.md).
+
+## Лицензия
+
+Proprietary. © ZETIT, Зуев А.В.
+
+gbrain используется по лицензии MIT, см. [гigit.zetit.ru/zuevav/gbrain-mirror](https://git.zetit.ru/zuevav/gbrain-mirror).