Админ-панель: каталог, качество, использование, настройки
Как устроена локальная панель 127.0.0.1:8777: четыре блока, REST API, токен-гейт мутаций, безопасность и интерактивный эмулятор.
Что это и зачем #
ragraf admin поднимает локальную панель (127.0.0.1:8777, только loopback, ноль внешних зависимостей — чистый Python stdlib + один HTML/CSS/JS-бандл). Это операционный пульт корпуса: что в индексе, какого он качества, как агент его использует и какие пороги governят переиндексацию. Панель read-only по данным индекса; мутации (настройки, очистка кэша) требуют токен.
Интерактивная копия панели с реальными измеренными данными — эмулятор на сайте. Всё, что описано ниже, можно «пощупать» там без установки продукта.
Четыре блока #
Каталог (corpus) #
Ревизии корпуса: rev-NNNN, состояние (ready/degraded), corpus_hash, число файлов по статусам разбора, размеры трёх хранилищ, hash_matches (сколько файлов совпало с прошлой ревизией — метрика переиспользования). Отсюда видно экономию пересборок: на пилоте 123 файла → 487 узлов → 7 292 рёбра → 27,5 МБ хранилищ.
Качество (quality) #
- Векторные нормы: распределение норм эмбеддингов (пилот: min 0.0576, max 0.6627) — выбросы-нули означают битые чанки.
- Чанки против бюджета: размер самого большого чанка в токенах против
chunk_budget: 8000(пилот: max 5 543, over-budget 0). - Усечённые сигнатуры: сколько подписей символов обрезано (дефект U3: 33 → 0 после исправления) — индикатор здоровья экстрактора.
Использование (usage) #
Телеметрия usage_call: вызовы по операциям, факты, спаны, символы и оценка токенов, ошибки выполнения. Реальный профиль пилотной сессии: 46 вызовов, write_check — 14, ошибок 0, оценка экономии ~5 200 токенов. Средние латентности: schema 0,5 мс · symbol 0,7 мс · table_usage 0,9 мс · write_check 3,3 мс · search до ~1 с (доминирует эмбеддинг запроса).
Настройки (settings) #
Глобальные пороги и проектные значения: full_reindex_threshold / fast_reindex_threshold (валидация full > fast на сервере, а не только в форме), joern_enabled, retain_revs. Запись проектного конфига — с валидацией и .bak-копией файла. Кнопка очистки кэша состояния — под токеном.
REST API #
| Метод и путь | Назначение | Токен |
|---|---|---|
GET /api/state | сводка каталога и качества | — |
GET /api/usage | телеметрия | — |
GET /api/settings | текущие пороги (глобальные + проектные) | — |
GET /api/health | живость и capability | — |
POST /api/settings/global | изменить глобальные пороги | ✓ |
POST /api/settings/project | изменить проектный конфиг (с .bak) | ✓ |
POST /api/cache/clear | сбросить кэш состояния | ✓ |
GET /api/token | выдать токен локальному клиенту | — (см. безопасность) |
Токен проверяется secrets.compare_digest (тайминг-безопасное сравнение). Токен печатается в консоль при старте или берётся из RAGRAF_ADMIN_TOKEN.
Модель безопасности — честно #
Панель спроектирована для одной машины одного пользователя:
- Привязка к loopback: снаружи недоступна (файрвол не требуется, но и не заменяется).
- Мутации — только с токеном; чтение — свободное (данные индекса не секретнее самого кода на диске).
- Известный зазор (задокументирован в SECURITY.md и реестре дефектов, C-01):
GET /api/tokenвыдаёт токен любому локальному процессу. Модель угрозы принимает это осознанно: локальный процесс с доступом к loopback уже может читать файлы корпуса напрямую. Усиление (токен только из консоли/окружения) — в roadmap R-SEC. - CSP/заголовки панель не отдаёт (локальный инструмент одного пользователя); сайт, который вы читаете, — отдельное приложение со строгими заголовками.
Когда панель полезна, а когда нет #
Полезна: отладка порогов переиндексации на живом корпусе; аудит «что знает индекс» после большой правки; обзор телеметрии агента (здоров ли профиль вызовов); демонстрация продукта. Не нужна: CI-пайплайнам (там --json + jq), headless-серверам (панель интерактивная), нескольким корпусам сразу (панель — про один корпус; мультикорпусность — в перспективах).
Смежное: эмулятор панели → · GPU-вычисления → · замеры →