sashatrask
274 lines
14 KiB
Markdown
274 lines
14 KiB
Markdown
# 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 вручную.
|