truf-server/RUNTIME_CHEATSHEET.md

Truf Runtime Cheatsheet

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

Команды выполняются из D:\truf в 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.exe -NoProfile -ExecutionPolicy Bypass -File .\start_runtime.ps1

Для полного рестарта используй именно:

.\stop_runtime.ps1
.\start_runtime.ps1

Для полного рестарта в core-only режиме:

.\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:

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 или найденные секреты.

Примеры диагностики:

# Один диагностический замер
.\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>`
logs <source> [N]	Последние N строк bounded-лога
`command <source	all>`
`start <source	all>`
`stop <source	all>`
`restart <source	all>`
`pause <source	all>`
`resume <source	all>`
`once <source	all>`
`mode <source	all> loop
`set <source	all> interval `
`set <source	all> restart on
`set <source	all> restart_delay `
`dashboard status	start
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

Формат:

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 не используется.

Примеры

# Повторить только 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 вручную.