Initial server source import

2026-09-30 20:30:56 +03:00
commit 170dd941b9
498 changed files with 261563 additions and 0 deletions
@@ -0,0 +1,273 @@
+# Truf Runtime Cheatsheet
+
+## Быстрый старт
+
+Команды выполняются из `D:\truf` в PowerShell.
+
+```powershell
+# Запустить весь canonical runtime
+.\start_runtime.ps1
+
+# Запустить explicit core set с keychecks, без dashboard
+.\start_core_runtime.ps1
+
+# Подключиться к интерактивной консоли supervisor
+.\attach_runtime.ps1
+
+# Координированно остановить весь runtime и PostgreSQL
+.\stop_runtime.ps1
+```
+
+Если PowerShell блокирует запуск скриптов:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\start_runtime.ps1
+```
+
+Для полного рестарта используй именно:
+
+```powershell
+.\stop_runtime.ps1
+.\start_runtime.ps1
+```
+
+Для полного рестарта в core-only режиме:
+
+```powershell
+.\stop_runtime.ps1
+.\start_core_runtime.ps1
+```
+
+Не используй `restart all` как замену полному рестарту: pipeline workers защищены от ручного рестарта, пока scanner sources работают.
+
+## Что запускается
+
+| Компонент | Назначение |
+|---|---|
+| PostgreSQL | Единственный authoritative storage |
+| `result-ingester` | Переносит scan bundles в PostgreSQL |
+| `jsonl-projector` | Создаёт compatibility JSONL projections |
+| `janitor` | Обслуживает runtime queues и временные данные |
+| `github` | GitHub scanner loop |
+| `gitlab` | GitLab scanner loop |
+| `huggingface` | Hugging Face scanner loop |
+| `dockerhub` | Docker Hub scanner loop |
+| `package_git` | Package/repository scanner loop |
+| `keychecks` | Почасовой provider checker scheduler |
+
+Одновременно выполняется максимум `3` scan workers. Dashboard при обычном запуске выключен.
+
+## PowerShell-скрипты
+
+| Скрипт | Что делает |
+|---|---|
+| `start_runtime.ps1` | Запускает freeze diagnostics, проверяет identity PostgreSQL и поднимает background supervisor |
+| `start_core_runtime.ps1` | Поднимает PostgreSQL, pipeline, janitor и три discovery-only producer; dashboard выключен |
+| `stop_runtime.ps1` | Выполняет authenticated coordinated shutdown supervisor, children и PostgreSQL |
+| `attach_runtime.ps1` | Открывает интерактивную supervisor-консоль; `quit` только отключает консоль |
+| `start_freeze_counters.ps1` | Запускает Windows performance counters в `H:\truf-diagnostics` |
+| `monitor_runtime_lag.ps1` | Пишет CPU/RAM/disk/runtime lag в CSV |
+| `cleanup_stale_agentui_vite.ps1` | Отдельная уборка старых AgentUI/Vite процессов; без `-Apply` только dry run |
+| `runtime\check-openrouter-keys.ps1` | Retired; намеренно завершается ошибкой |
+
+В проекте нет собственных `.bat`/`.cmd`. Найденные BAT внутри `runtime\postgres\pgsql\pgAdmin 4` принадлежат pgAdmin и для Truf не используются.
+
+## Full и Core-only режимы
+
+`start_runtime.ps1` использует allowlist `supervisor.enabled_sources` из `config.linux.yaml`. Сейчас этот allowlist уже равен distributed core set, поэтому оба start-скрипта запускают одинаковые discovery producer.
+
+`start_core_runtime.ps1` фиксирует core set прямо в wrapper и не зависит от будущего расширения default allowlist:
+
+```text
+gitlab,dockerhub,huggingface
+```
+
+PostgreSQL, `result-ingester`, `jsonl-projector`, `janitor` и независимо включённый `keychecks` также запускаются. Dashboard не запускается.
+
+Чтобы сменить режим, сначала останови текущий supervisor через `.\stop_runtime.ps1`, затем запусти нужный start-скрипт. `stop_runtime.ps1` одинаков для обоих режимов.
+
+## Core Sources
+
+| Source | Что производит на сервере |
+|---|---|
+| `gitlab` | Ищет недавно активные GitLab projects и ставит их в очередь remote workers |
+| `dockerhub` | Ищет Docker Hub images и ставит в очередь только immutable `repo@sha256:...` targets |
+| `huggingface` | Ищет новейшие Hugging Face Spaces и ставит их в очередь remote workers |
+
+`result-ingester`, `jsonl-projector`, `janitor` и `keychecks` отображаются как отдельные system workers, но не являются discovery sources. GitHub и `package_git` остаются доступными legacy/manual source, однако в distributed core profile не входят.
+
+## Janitor
+
+Janitor обслуживает только scanner work area (`S:\scanner-work`), а не PostgreSQL и не provider status files.
+
+- Каждые `60` секунд ищет временные каталоги разрешённых типов.
+- Рассматривает только каталоги старше `7200` секунд.
+- Требует приватный `.scanner-owner.json` с точным process identity.
+- Удаляет каталог только если owner и parent гарантированно мертвы.
+- Не следует по symlink, junction или другим reparse points.
+- Один проход ограничен `50` каталогами, `10000` entries, `1 GiB`, `30` секундами и depth `64`.
+- Не имеет PostgreSQL credentials и не удаляет findings, keycheck history, current state или найденные секреты.
+
+Примеры диагностики:
+
+```powershell
+# Один диагностический замер
+.\monitor_runtime_lag.ps1 -Once
+
+# Свой файл и интервал
+.\monitor_runtime_lag.ps1 -OutputPath H:\truf-diagnostics\lag.csv -IntervalSeconds 10
+
+# Безопасный просмотр кандидатов на очистку Vite
+.\cleanup_stale_agentui_vite.ps1
+
+# Реальная очистка найденного точного набора
+.\cleanup_stale_agentui_vite.ps1 -Apply
+```
+
+## Supervisor-команды
+
+Сначала запусти `.\attach_runtime.ps1`, затем используй команды ниже.
+
+| Команда | Назначение |
+|---|---|
+| `help` | Полная встроенная справка |
+| `status` | Свежий status table |
+| `watch` | Live status; `q` возвращает в prompt |
+| `auth <source|all>` | Состояние auth pools |
+| `logs <source> [N]` | Последние `N` строк bounded-лога |
+| `command <source|all>` | Фактическая child-команда, log и state paths |
+| `start <source|all>` | Запустить остановленный source |
+| `stop <source|all>` | Остановить и оставить остановленным |
+| `restart <source|all>` | Перезапустить отдельный source |
+| `pause <source|all>` | Остановить и отметить paused |
+| `resume <source|all>` | Снять pause и запустить |
+| `once <source|all>` | Один проход source с `--once` |
+| `mode <source|all> loop|once|repeat` | Изменить режим source |
+| `set <source|all> interval <sec>` | Интервал repeat mode |
+| `set <source|all> restart on|off` | Автоматический restart после сбоя |
+| `set <source|all> restart_delay <sec>` | Начальная задержка restart |
+| `dashboard status|start|stop|restart` | Управление dashboard |
+| `shutdown` | Полный coordinated shutdown |
+| `quit` | В attach-режиме только отсоединиться |
+
+`reload` намеренно отключён. После изменения `config.yaml` или runtime-кода нужен полный `stop_runtime.ps1` + `start_runtime.ps1`.
+
+Source alias: `docker` означает `dockerhub`.
+
+## Статусы
+
+| Статус | Значение |
+|---|---|
+| `running` | Child сейчас работает |
+| `waiting` | Ожидает следующего запуска/retry |
+| `blocked` | Ждёт стабильной готовности PostgreSQL |
+| `paused` | Остановлен командой `pause` |
+| `done` | Успешный one-shot завершён |
+| `failed` | Child завершился с ошибкой, restart выключен |
+
+`desired=running` показывает желаемое состояние. `rs` означает текущую серию ошибок / общее число automatic restarts. Старый `exit=1` рядом с уже `running` source относится к предыдущей попытке запуска.
+
+## Keycheck Recheck
+
+Формат:
+
+```text
+recheck <service|all> [type ...] [options]
+```
+
+Если type не указан, выполняется полный `--recheck-all` выбранного service.
+
+### Типы
+
+| Type | Что ставится в очередь |
+|---|---|
+| `network` | Текущие transient network statuses |
+| `ratelimited` | Limited/rate-limited и связанные no-balance statuses |
+| `unknown` | Unknown и no-context |
+| `restricted` | Restricted |
+| `nobalance` | No-balance/no-quota |
+| `valid` или `alive` | Текущие alive credentials |
+| `all` | Все известные credentials |
+| `legacy-vertex` | Только GCP: импортировать и проверить отсутствующие legacy Vertex TXT credentials |
+
+### Опции
+
+| Опция | Значение |
+|---|---|
+| `--force` | Остановить уже работающий keycheck batch и начать этот |
+| `--max-keys N` | Ограничить число credentials |
+| `--proxy-file PATH` | Временно переопределить proxy file |
+| `--no-resource-probe` | Отключить resource probe; сейчас используется Replicate |
+| `--no-summary` | Не пересобирать summary/status projections после batch |
+
+`--input PATH` является legacy/offline compatibility option и в canonical PostgreSQL runtime не используется.
+
+### Примеры
+
+```text
+# Повторить только network failures у всех providers
+recheck all network
+
+# Перепроверить все текущие alive GCP credentials
+recheck gcp valid
+
+# Полностью перепроверить Qwen
+recheck qwen all
+
+# Проверить максимум 5 alive Replicate без resource probe
+recheck replicate valid --max-keys 5 --no-resource-probe
+
+# Импортировать/дедуплицировать старые GCP Vertex TXT записи и проверить только их
+recheck gcp legacy-vertex
+
+# Прервать текущий keycheck batch и запустить новый
+recheck gcp valid --force
+```
+
+Scheduled keychecks запускаются раз в `3600` секунд. По умолчанию проверяются новые candidates и повторяются только `NETWORK`; alive/limited/unknown/restricted/no-balance автоматически каждый час не перепроверяются.
+
+## Текущие GCP Vertex Probes
+
+| Provider | Модели | Locations | Проверка |
+|---|---|---|---|
+| Google | `gemini-3.6-flash`, `gemini-3.1-pro-preview` | `global`, `us`, `eu` | `countTokens`, без генерации |
+| Anthropic | `claude-opus-5`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-fable-5` | `global`, `us`, `eu`, `us-east5`, `europe-west1` | `rawPredict`, до 1 output token |
+
+Anthropic probe является реальным минимальным inference-вызовом и может иметь небольшой расход.
+
+## Куда идут данные
+
+1. Scanner sources создают result bundles.
+2. `result-ingester` пишет findings и keycheck candidates в PostgreSQL.
+3. Provider checker арендует candidate и выполняет API probe через `runtime\proxy.txt`.
+4. Новый результат добавляется в append-only `keycheck_results`.
+5. `keycheck_current_state` переключается на последний результат.
+6. `jsonl-projector` создаёт compatibility JSONL.
+7. Summary projection атомарно обновляет status TXT.
+
+PostgreSQL является source of truth. TXT/JSONL в `runtime\keychecks` являются compatibility projections, а не входом для обычного recheck.
+
+## Полезные пути
+
+| Путь | Назначение |
+|---|---|
+| `app\config.yaml` | Основная конфигурация runtime, sources и probes |
+| `runtime\proxy.txt` | Proxy для provider checks |
+| `runtime\logs\supervisor.status.txt` | Последний status snapshot |
+| `runtime\logs\supervisor.log` | Supervisor log |
+| `runtime\logs\keychecks.log` | Общий keycheck log |
+| `runtime\keychecks\summary.tsv` | Текущий provider summary |
+| `runtime\keychecks\alive_summary.tsv` | Краткий alive summary |
+| `runtime\keychecks\<service>` | Compatibility status/results files provider-а |
+| `runtime\control\supervisor.instance.json` | Private control metadata; вручную не редактировать |
+| `S:\postgres-data` | Canonical PostgreSQL cluster |
+| `S:\scanner-work` | Scanner scratch/work area |
+
+## Безопасность
+
+- Не запускай provider scripts напрямую.
+- Не передавай raw credentials через CLI.
+- Не редактируй `supervisor.instance.json`.
+- Для управления используй только authenticated supervisor.
+- Для полного рестарта используй canonical start/stop scripts.
+- Не удаляй PostgreSQL cluster или runtime queues вручную.