FAQ

Частые вопросы при первом знакомстве с Soul Stack. Ответы короткие; за деталями — ссылки на соответствующие разделы.

Почему Go и один исполняемый файл?

Чтобы на управляемом хосте не было рантайм-зависимостей. Агент soul — статический исполняемый файл на Go: на хосте не нужен Python, Ruby или иной интерпретатор. Модули — нативный Go-код, скомпилированный в этот же исполняемый файл; кастомные расширения подключаются как отдельные исполняемые файлы-плагины через gRPC, поэтому язык плагина не навязывает зависимость хосту.

Практический эффект — нет version-drift интерпретатора по душам: нечего устанавливать, согласовывать и обновлять на хостах. Это работает на минималистичных и жёстко заблокированных образах, где ставить интерпретатор нежелательно.

Подробнее — Компоненты → Soul.

Обязателен ли Vault?

Да. Обязательный инфра-контур Keeper — PostgreSQL + Redis + Vault (все три). Keeper проверяет каждый из них на старте и отказывается стартовать, если хотя бы один недоступен (fail-fast). Без Vault Keeper не поднимется: на нём держатся PKI mTLS-идентичности агентов и подпись операторских токенов, без которых аутентификация душ и операторов не работает в принципе.

• PostgreSQL — единственное холодное хранилище Keeper-кластера: реестры агентов и операторов, каталог сервисов, состояния инкарнаций, журналы.
• Redis — heartbeat-кэш, lease на идентификаторы агентов, координация между инстансами Keeper.
• Vault — PKI для выпуска mTLS-идентичности агентов, подпись операторских JWT и хранение секретов (DSN PostgreSQL, пароль Redis, прикладные секреты Destiny).

Все три — внешние компоненты, которые вы поднимаете и эксплуатируете сами; Soul Stack их не поставляет в комплекте. Подробнее — Установка → Обзор и Quick Start → Что понадобится.

Pull или push?

Оба режима поддерживает один и тот же исполняемый файл soul одним и тем же набором модулей — отдельных реализаций нет.

• Pull (демон). Агент запущен как systemd-сервис, сам инициирует долгоживущий gRPC-стрим к Keeper-у поверх mTLS и применяет приходящие по стриму задачи.
• Push (oneshot по SSH). Без постоянного демона: Keeper доставляет исполняемый файл и модули на хост по SSH и запускает разовое применение; модули кешируются на хосте по SHA-256.

Применение задачи не зависит от того, демон это или oneshot. Подробнее — Компоненты → Soul.

Можно ли отключить web-UI или MCP?

Да, оба — опциональны на стороне Keeper-а.

• Web-UI управляется top-level тогглом web_ui_enabled (tri-state, default-ON). Явный web_ui_enabled: false — opt-out: статика /ui не монтируется, /v1/* и /docs не затрагиваются. UI включён в исполняемый файл Keeper-а, отдельного backend-а не требует; новых портов включение не открывает (статика делит порт Operator API). См. Конфигурация → keeper.yml → web_ui_enabled.
• MCP поднимается, только если задан listen.mcp.addr. Уберите блок / оставьте addr пустым — listener не стартует, MCP выключен. См. Конфигурация → keeper.yml → listen.

Метрики выключить нельзя. listen.metrics.addr — обязательный listener: Prometheus-/metrics Keeper отдаёт всегда (опциональна только защита эндпоинта через блок metrics). У агента метрики, наоборот, опциональны (metrics.enabled) — не каждый хост открывает порт. См. Конфигурация → keeper.yml → metrics.

Нужно ли открывать входящие порты на управляемых хостах?

Нет. Стрим к Keeper-у инициирует сам агент — соединение всегда исходящее, на bootstrap- и EventStream-порты Keeper-а. Наружу на хосте слушает только локальный listener метрик (и тот опционален). Открывать входящие порты под управление не нужно. См. Компоненты → Soul → Требования к хосту и Безопасность → Транспорт.

Как обновить сервис и его состояние?

Состояние инкарнации (runtime-инстанса сервиса) версионируется полем state_schema_version. Переход на новую версию схемы — явный шаг оператора через Operator API, а не ленивое автообновление:

• оператор инициирует upgrade инкарнации до целевой версии;
• цепочка миграций применяется атомарно, одной транзакцией PostgreSQL — либо состояние полностью переходит на новую версию, либо остаётся прежним при ошибке;
• перед изменением сохраняется snapshot прежнего состояния в историю (миграции forward-only, обратной миграции нет — путь отката идёт через историю).

Грамматика DSL, раскладка migrations/ и тесты — DSL → Миграции состояния. Эксплуатационная сторона апгрейда — Операции → Обновление инкарнации.

Чем Soul Stack отличается от традиционных инструментов?

Коротко: нет рантайма на хосте (один статический исполняемый файл на Go вместо интерпретатора), типобезопасный шаблонизатор (CEL + Go text/template вместо текстового шаблонизатора общего назначения), stateless-кластер Keeper с горизонтальным масштабированием поверх общих PostgreSQL/Redis (вместо stateful-master), mTLS / RBAC / аудит / Vault встроены в ядро, единая модель pull + push одним набором модулей.

Безопасно ли хранить секреты?

Да, по двум правилам.

• Резолв на стороне Keeper-а. Секреты подтягиваются из Vault на Keeper-е в момент рендера Destiny — до того, как задачи уходят на хост. Агент не несёт Vault-клиента, на хосте нет Vault-токенов, секреты не материализуются на диск кластера.
• Маскинг на выходе. Секретные значения маскируются на каждой границе, где данные покидают систему — логи, OpenTelemetry-трейсы, UI и API-ответы, отчёты о прогоне. В открытом виде секрет наружу не попадает.

Подробнее — Безопасность → Секреты.