# Operations Guide

Документ для оператора ZBrain (admin) — повседневные задачи, типовые проблемы, runbook.

## Чек-лист после деплоя

После завершения [DEPLOYMENT.md](DEPLOYMENT.md):

- [ ] Все systemd unit'ы для брейнов активны: `systemctl status 'zbrain-gbrain-*'`
- [ ] Docker контейнеры brainhub запущены: `docker compose -f /opt/zbrain/deploy/docker/docker-compose.yml ps`
- [ ] Nginx обслуживает оба домена: `curl -H "Host: brain.zetit.local" http://localhost/health`
- [ ] Cron для backup'ов настроен: `sudo crontab -l | grep backup`
- [ ] Логи пишутся: `ls -lh /var/log/zbrain/`
- [ ] Disk usage в норме: `df -h /var/lib/postgresql /var/lib/zbrain /var/log`

## Ежедневные задачи (автоматические)

### Backup (cron, 03:00)

```cron
0 3 * * *  root  /opt/zbrain/scripts/backup.sh
```

Что проверять раз в неделю:
- `ls -lh /var/backups/zbrain/` — есть свежий бэкап
- `cat /var/log/zbrain/backup.log | tail -20` — нет ошибок
- Раз в месяц — тестовое восстановление на отдельной VM

### Sync (опционально, cron, 06:00 / 18:00)

Если источники не настроены через UI с расписанием, можно запускать вручную через scripts/sync-all.sh (будет добавлено в Sprint 4).

## Типовые задачи

### Создать нового пользователя

Через UI:
1. Залогинься как owner
2. /users → New user
3. Email + role (admin / editor / viewer)
4. Скопировать temp password из ответа

Через CLI (только owner):
```bash
sudo docker exec zbrain-api node -e '
  // TODO: команда будет добавлена в Sprint 7
'
```

### Создать новый брейн

```bash
sudo bash /opt/zbrain/scripts/create-brain.sh <name> "<display name>" <port>

# Пример
sudo bash /opt/zbrain/scripts/create-brain.sh fontvielle "Fontvielle Infrastructure" 3005
```

### Импорт большого корпуса в брейн

```bash
sudo -u zbrain bash -c '
  export PATH=$HOME/.bun/bin:$PATH
  source /etc/zbrain/.env
  export DATABASE_URL=$(cat /var/lib/zbrain/brains/zetit/config.json | jq -r .database_url)
  cd /var/lib/zbrain/gbrain
  bun run gbrain import /path/to/markdown/
'
```

Для очень больших корпусов (>10000 страниц) — лучше через UI после Sprint 4, там SSE прогресс.

### Обновить gbrain до новой версии

1. **На рабочей машине** (с GitHub доступом):
   ```bash
   git clone --bare https://github.com/garrytan/gbrain.git
   cd gbrain.git
   git push --mirror git@git.zetit.ru:zuevav/gbrain-mirror.git
   ```

2. **На VM ZBrain** — проверить changelog upstream'а на breaking changes, особенно в БД схеме.

3. Создать ADR в `docs/DECISIONS/` если есть значимые изменения.

4. Останавливаем все брейны:
   ```bash
   sudo systemctl stop 'zbrain-gbrain-*'
   ```

5. Обновляем gbrain:
   ```bash
   sudo -u zbrain bash -c '
     cd /var/lib/zbrain/gbrain
     git fetch
     git checkout v0.27.0   # новая версия
     export PATH=$HOME/.bun/bin:$PATH
     export HTTPS_PROXY=$(grep HTTPS_PROXY /etc/zbrain/.env | cut -d= -f2-)
     bun install
   '
   ```

6. Применяем миграции каждого брейна:
   ```bash
   for brain in zetit telerapharma personal community; do
     sudo -u zbrain bash -c "
       export PATH=\$HOME/.bun/bin:\$PATH
       export DATABASE_URL=\$(cat /var/lib/zbrain/brains/$brain/config.json | jq -r .database_url)
       cd /var/lib/zbrain/gbrain
       bun run gbrain migrate
     "
   done
   ```

7. Запускаем брейны:
   ```bash
   sudo systemctl start 'zbrain-gbrain-*'
   ```

8. Проверяем health.

### Восстановление из бэкапа

См. `scripts/restore.sh`. Краткая инструкция:

```bash
sudo bash /opt/zbrain/scripts/restore.sh 20260520-031500
# спросит путь к age приватному ключу
```

**ВАЖНО:** после restore удалить age ключ с VM:
```bash
shred -u /tmp/backup.age
```

### Реактивация заблокированного пользователя

Если пользователь забыл пароль или нужно сбросить:

```sql
-- Через UI пока нет, делаем напрямую
sudo -u postgres psql -d brainhub

-- Сгенерировать новый bcrypt hash (cost=12)
-- Можно через: echo 'newpassword' | htpasswd -bnBC 12 "" -
UPDATE users
SET password_hash = '<new-bcrypt-hash>',
    must_change_password = true
WHERE email = 'user@example.com';
```

### Срочный отзыв токена

Если подозрение на утечку токена и нельзя ждать 30 секунд кэша:

```bash
# Через UI: /tokens → Revoke. Это уже делает invalidate cache.

# Срочное через API:
curl -X POST http://brain.zetit.local/api/admin/cache/invalidate-token \
  -H "Authorization: Bearer <admin-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"tokenPrefix":"brain_pat_a8f3"}'

# Полный сброс кэша токенов (drastic):
sudo systemctl restart docker
sudo docker compose restart brainhub-api
```

## Мониторинг

### Что смотреть в /var/log/zbrain/

```bash
# Live tail всех логов
sudo tail -F /var/log/zbrain/*.log

# Ошибки за последний час
sudo journalctl --since "1 hour ago" -u 'zbrain-gbrain-*' | grep -i error

# Brainhub access pattern
sudo tail -1000 /var/log/zbrain/brainhub.log | jq -r 'select(.req.url) | "\(.time) \(.req.method) \(.req.url) → \(.res.statusCode)"'
```

### Метрики Postgres

```bash
# Connection count
sudo -u postgres psql -c 'SELECT count(*), state FROM pg_stat_activity GROUP BY state;'

# Размер БД
sudo -u postgres psql -c "
SELECT datname, pg_size_pretty(pg_database_size(datname))
FROM pg_database WHERE datname IN ('brainhub','gbrain_zetit','gbrain_telerapharma','gbrain_personal','gbrain_community')
ORDER BY pg_database_size(datname) DESC;
"

# Топ медленных запросов
sudo -u postgres psql -c '
SELECT calls, mean_exec_time, query
FROM pg_stat_statements
ORDER BY mean_exec_time DESC LIMIT 10;
'  # если pg_stat_statements включён
```

### Disk usage

```bash
# По брейнам
du -sh /var/lib/zbrain/brains/*/

# Postgres data
sudo du -sh /var/lib/postgresql/16/main/

# Логи
sudo du -sh /var/log/zbrain/ /var/log/postgresql/ /var/log/nginx/
```

Если /var/log пухнет — настроить logrotate.

## Runbook'и инцидентов

### Сценарий: брейн не отвечает на MCP запросы

**Симптомы:** Claude Code получает 502 от /mcp/<brain>, в UI брейн помечен красным.

```bash
# 1. Проверить systemd unit
sudo systemctl status zbrain-gbrain-<brain>

# 2. Если down - последние логи
sudo journalctl -u zbrain-gbrain-<brain> -n 100 --no-pager

# 3. Если crash loop - проверить Postgres connection
sudo -u postgres psql -d gbrain_<brain> -c 'SELECT version()'

# 4. Если ОК - перезапустить
sudo systemctl restart zbrain-gbrain-<brain>

# 5. Если не помогло - временно отключить и эскалировать
sudo systemctl stop zbrain-gbrain-<brain>
```

### Сценарий: Postgres недоступен

**Симптомы:** brainhub возвращает 503, все брейны лежат.

```bash
# 1. Статус
sudo systemctl status postgresql

# 2. Если crashed - проверить логи
sudo tail -200 /var/log/postgresql/postgresql-16-main.log

# 3. Частые причины:
#    a) Disk full → освободить место (старые WAL, логи)
df -h /var/lib/postgresql
sudo du -sh /var/lib/postgresql/16/main/pg_wal/

#    b) OOM → проверить dmesg
sudo dmesg | tail -50 | grep -i 'killed process'

#    c) Corrupt → restore из бэкапа
```

### Сценарий: исчерпался лимит OpenAI/Anthropic API

**Симптомы:** sync падает с 429, новые pages не получают embeddings.

```bash
# Проверка через FNA прокси
sudo -u zbrain bash -c '
  source /etc/zbrain/.env
  curl --proxy "$HTTPS_PROXY" \
       https://api.openai.com/v1/dashboard/billing/usage \
       -H "Authorization: Bearer $OPENAI_API_KEY"
'

# Действия:
# 1. Пополнить баланс на платформе OpenAI/Anthropic
# 2. Или временно поставить на паузу автоматический sync
# 3. Прикинуть стоимость re-embed: ~$0.65 на 7500 страниц для text-embedding-3-large
```

### Сценарий: подозрение на утечку токена

```bash
# 1. Найти токен в UI: /tokens → найти по prefix
# 2. Посмотреть активность: /audit?actor_type=token&actor_id=<id>
# 3. Revoke + invalidate cache
# 4. Создать новый токен с теми же scope, передать пользователю
# 5. Анализ через audit log:
sudo -u postgres psql -d brainhub -c "
SELECT created_at, ip, action, payload
FROM audit_log
WHERE actor_type='token' AND actor_id='<token-id>'
ORDER BY created_at DESC LIMIT 100;
"
# 6. Если был доступ из неожиданного IP - эскалация (анализ что было прочитано/изменено)
```

## Регулярные процедуры

### Раз в неделю
- Проверить freshness бэкапов и логи backup.log
- Проверить disk usage
- Глянуть audit log на необычную активность

### Раз в месяц
- Тестовый restore на отдельной VM
- Review обновлений gbrain upstream
- Обновить ОС (`apt update && apt upgrade`)
- Rotate session secrets (опционально, но повышает security posture)

### Раз в квартал
- Penetration test публичного контура (хотя бы на nikto/zap-baseline)
- Review активных токенов, удаление неиспользуемых
- Review активных пользователей, удаление неактивных
- Capacity planning: смотреть рост БД и проектировать апгрейд VM при необходимости