Справочник

Конфигурация, CLI и коды ошибок

CLI, конфигурация, переменные окружения, коды ошибок и лимиты.

Справочник для быстрого поиска значений. На него ссылаются другие страницы документации. Только факты и значения по умолчанию, без обучающего текста.

На какие вопросы отвечает раздел: Как называется эта команда/переменная? Что значит этот код ошибки? Какое значение по умолчанию?

Контракты HTTP API: автогенерируемый Swagger на /api (Basic-auth).

CLI и команды

Основные команды репозитория ядра (on-prem разработка и эксплуатация):

Команда	Назначение
`npm run docker:dev` / `docker:dev:build`	Локальный dev-стек в Docker
`npm run start:api` / `start:engine` / `start:control-plane` / `start:executor` / `start:scheduler`	Запуск отдельных сервисов
`npm run sc:m` / `sc:g`	Миграции Drizzle (apply / generate)
`npm run studio`	Drizzle Studio для просмотра БД
`npm run lint` / `format`	ESLint и Prettier
`npm run test` / `test:e2e` / `release-readiness`	Тесты и проверка перед релизом
`npx ts-node scripts/audit-retention.ts`	Purge журнала аудита старше `AUDIT_RETENTION_DAYS`

Demo на Hub: docker run. Подробнее в Быстром старте и Cookbook → Deploy.

Конфигурация и переменные окружения

Полный шаблон on-prem лежит в репозитории ядра (файл .env.example). Для demo Compose с плагинами используйте compose.env.example. Ниже сгруппированный справочник наиболее значимых переменных.

Общая инфраструктура

Переменная	Назначение	По умолчанию
`DATABASE_URL`	Подключение Drizzle к Postgres	`postgresql://postgres:postgres@postgres:5432/postgres`
`POSTGRES_HOST` / `POSTGRES_PORT` / `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	Параметры Postgres	`postgres` / `5432` / `postgres` / `postgres` / `postgres`
`REDIS_HOST` / `REDIS_PORT`	Redis (BullMQ)	`redis` / `6379`
`VAULT_ADDR` / `VAULT_TOKEN`	Адрес и токен Vault	`http://vault:8200` / —
`VAULT_MOUNT` / `VAULT_TRANSIT_MOUNT` / `VAULT_TRANSIT_KEY_NAME`	KV-mount, Transit-mount, имя ключа	`secret` / `transit` / `autokey`
`QDRANT_URL` / `QDRANT_HOST` / `QDRANT_PORT`	Qdrant (опц., для search)	`http://qdrant:6333`
`NEO4J_HOST` / `NEO4J_USER` / `NEO4J_PASSWORD` / `NEO4J_BOLT_PORT`	Neo4j (опц.)	`neo4j` / `neo4j` / `neo4j-local` / `7687`
`OLLAMA_BASE_URL` / `OLLAMA_HOST` / `OLLAMA_PORT`	Ollama для LLM/embeddings	`http://host.docker.internal:11434`
`LOG_LEVEL` / `LOG_FORMAT`	Логи Pino/Nest	`info` / `json`
`AUDIT_RETENTION_DAYS`	Хранение записей аудита, дней	`365`

api

Переменная	Назначение	По умолчанию
`API_HTTP_LISTEN` / `API_PATH`	Адрес прослушивания и префикс REST	`0.0.0.0:3000` / `api`
`JWT_SECRET`	Подпись JWT access/refresh	—
`ORIGIN_REGEXP`	Allowlist Origin (CORS)
`SWAGGER_USER` / `SWAGGER_PASSWORD`	Basic-auth Swagger UI	—
`PAYLOAD_LIMIT`	Лимит тела запроса	`50mb`
`AUTH_SERVICE_BASE_URL`, `SECRETS_TCP_CONNECT`, `PRESET_TCP_CONNECT`, `SCHEDULER_TCP_CONNECT`, `FILE_SERVICE_BASE_URL`, `FLOW_AGENT_TCP_CONNECT`, `SEARCH_SERVICE_TCP_CONNECT`	Адреса микросервисов	`<service>:3000`
`FLOW_AGENT_ENABLED` / `AGENT_CHAT_ENABLED`	Клиент flow-agent и чат-API	`false` / `false`
`API_SENSITIVE_ROUTE_CIDRS` / `API_TRUST_PROXY_HOPS`	Защита маршрутов за прокси	— / `0`

auth-service

Переменная	Назначение	По умолчанию
`AUTH_SERVICE_HTTP_LISTEN`	Адрес прослушивания	`0.0.0.0:3000`
`JWT_ACCESS_TTL` / `JWT_REFRESH_TTL`	TTL токенов	`15m` / `7d`
`WEBAUTHN_RP_ID` / `WEBAUTHN_RP_NAME` / `WEBAUTHN_ORIGIN`	Параметры WebAuthn (passkeys)	`localhost` / `Conveyor` / `https://localhost:3000`
`SMTP_HOST` / `SMTP_PORT` / `SMTP_FROM` / `SMTP_SECURE`	Исходящая почта	`mailcatcher` / `1025` / `noreply@flowforge.local` / `false`

runtime-engine и runtime-control-plane

Переменная	Назначение	По умолчанию
`RUNTIME_ENGINE_RPC_TCP_PORT`	TCP RPC движка в контейнере	`3000`
`CONTROL_PLANE_TCP_CONNECT`	engine → control-plane TCP	`runtime-control-plane:3001`
`RUNTIME_CONTROL_PLANE_HTTP_PORT` / `RUNTIME_CONTROL_PLANE_TCP_PORT`	HTTP и TCP control-plane	`3000` / `3001`
`RUNTIME_ENGINE_TCP_HOST`	control-plane → engine RPC hostname	`runtime-engine`
`RUNTIME_INTERNAL_BASE_URL`	base-URL control-plane для SDK исполнителя	`http://runtime-control-plane:3000`
`PLUGIN_CONTROL_PLANE_KEY`	Ключ внутренних маршрутов	—
`PLUGIN_CONTROL_PLANE_ALLOW_CIDRS`	Allowlist исполнителей/плагинов	`0.0.0.0/0`
`DISPATCH_MAX_ATTEMPTS` / `DISPATCH_RETRY_BASE_MS`	Ретраи диспетчеризации	`5` / `300`

plugin-manager

Переменная	Назначение	По умолчанию
`PLUGIN_MANAGER_TCP_PORT` / `PLUGIN_MANAGER_HEALTH_PORT`	TCP приёма SDK и HTTP health	`3000` / `3001`
`PLUGIN_MANAGER_INGRESS_TOKEN`	Токен в TCP-payload плагинов	`dev-plugin-ingress`
`PLUGIN_MANAGER_ALLOW_CIDRS`	Allowlist TCP-подключений плагинов	`0.0.0.0/0`
`PLUGIN_MANAGER_FILE_SERVICE_URL`	file-service для блобов	`http://file-service:3000`
`PLUGIN_MANAGER_STARTUP_RECONCILE`	Reconcile при старте	`true`
`PLUGIN_MANAGER_PLUGIN_HEALTH_INTERVAL_MS`	Периодический TCP-опрос pull-endpoint плагинов (мс); `0` или `<15000` — выключено	`0` (on-prem); demo Compose — Плагины
`PLUGIN_MANAGER_PLUGIN_HEALTH_JITTER_RATIO`	Джиттер перед sweep (0–0.5)	`0.2`

secret-manager, file-service, preset-service, scheduler, search-service

Переменная	Назначение	По умолчанию
`SECRETS_TCP_LISTEN`	Адрес secret-manager	`0.0.0.0:3000`
`FILE_SERVICE_HTTP_LISTEN` / `FILE_STORAGE_PATH`	Адрес и каталог хранения файлов	`0.0.0.0:3000` / —
`PRESET_TCP_LISTEN` / `PRESET_CATALOG_PATH`	Адрес и каталог пресетов	`0.0.0.0:3000` / —
`SCHEDULER_TCP_LISTEN` / `SCHEDULER_MIN_CRON_PERIOD_MINUTES`	Адрес и мин. период cron	`0.0.0.0:3000` / `60`
`SEARCH_SERVICE_TCP_LISTEN` / `SEARCH_SERVICE_HEALTH_HTTP_LISTEN`	TCP и health search	`0.0.0.0:3000` / `0.0.0.0:3001`
`REDIS_HOST` / `REDIS_PORT`	Redis для search-service	BullMQ outbox индексации; в prod задайте `redis`, не `localhost`
`EMBEDDING_MODEL` / `SEARCH_SERVICE_START_MODE`	Модель эмбеддингов и режим старта	`embeddinggemma` / `normal`

Наблюдаемость

Переменная	Назначение	По умолчанию
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP-endpoint Jaeger (пусто — трассировка выкл.)	`http://jaeger:4318`
`OTEL_SERVICE_NAME` / `OTEL_SERVICE_VERSION`	Имя и версия сервиса в телеметрии	`flow-forge` / `0.0.1`
`OTEL_SDK_DISABLED`	Полностью отключить OpenTelemetry	—

Редактор (workflow-manager)

Переменная	Назначение	По умолчанию
`NUXT_PUBLIC_API_BASE`	Базовый URL backend (единая точка входа)	`http://localhost:4001`
`NUXT_PUBLIC_EDITOR_CONFIG_AGENT_ENABLED`	AI-агент в шапке	выкл.
`NUXT_PUBLIC_EDITOR_CONFIG_USER_MANAGEMENT_ENABLED`	Логин/регистрация в UI	вкл.
`NUXT_PUBLIC_EDITOR_CONFIG_USER_MESSAGE` / `_TONE`	Сообщение в статус-баре	—
`NUXT_PUBLIC_LEGAL_TERMS_URL` / `NUXT_PUBLIC_LEGAL_PRIVACY_URL`	Внешние юридические ссылки	—

Docker demo (контейнер и Compose)

Переменная	Назначение	По умолчанию
`PUBLIC_SITE_URL`	Origin UI и WebAuthn в demo-контейнере	`http://localhost:8080`
`DEMO_SEED_PASSWORD`	Пароль встроенных демо-учёток	`Test123456!`
`DEMO_PLUGIN_HEALTH_INTERVAL_MS`	TCP-опрос pull-endpoint плагинов	`1200000`

Секреты (JWT_SECRET, PLUGIN_*, POSTGRES_PASSWORD) и полная таблица demo: Развёртывание → Docker demo. Переменные Compose с плагинами (DEMO_IMAGE_REF, DEMO_*_EXECUTOR_PORT, …): Плагины → Demo Compose.

Фрагмент шаблона on-prem. Полный построчный список в .env.example репозитория ядра.

# -----------------------------------------------------------------------------
# Общие — Postgres Redis Vault URLs, общая инфра и observability
# -----------------------------------------------------------------------------
# Строка подключения Drizzle ORM к Postgres (в docker-all: хост postgres, не localhost)
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres
# Хост экземпляра Postgres
POSTGRES_HOST=postgres
# Порт Postgres для строки подключения
POSTGRES_PORT=5432
# Имя пользователя базы Postgres
POSTGRES_USER=postgres
# Пароль пользователя Postgres
POSTGRES_PASSWORD=postgres
# Имя базы данных приложения
POSTGRES_DB=postgres
# Хост Redis для очередей BullMQ
REDIS_HOST=redis
# Порт процесса Redis
REDIS_PORT=6379
# Базовый URL Vault для клиентов SDK
VAULT_ADDR=http://vault:8200
# Токен аутентификации в Vault dev
VAULT_TOKEN=
# Путь KV secrets engine в Vault
VAULT_MOUNT=secret
# Путь Transit mount для шифрования
VAULT_TRANSIT_MOUNT=transit
# Имя ключа Transit для секретов
VAULT_TRANSIT_KEY_NAME=autokey
# OTLP хост для трейсов Jaeger (сервис jaeger из docker-compose.observability.yml)
OTEL_OTLP_HOST=jaeger
# OTLP порт HTTP ingest
OTEL_OTLP_PORT=4318
# Полный endpoint OTLP экспортёра
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
# Имя сервиса в телеметрии
OTEL_SERVICE_NAME=flow-forge
# Версия сервиса в телеметрии
OTEL_SERVICE_VERSION=0.0.1
# Полностью отключить OpenTelemetry SDK
# OTEL_SDK_DISABLED=true
# -----------------------------------------------------------------------------
# Сервис — plugin-manager, приём SDK и запись каталога в БД
# -----------------------------------------------------------------------------
# Порт TCP приёма SDK plugin-manager в контейнере (с хоста — PLUGIN_MANAGER_TCP_PUBLISH_PORT→3000)
PLUGIN_MANAGER_TCP_PORT=3000
# Порт HTTP только health проверок plugin-manager
PLUGIN_MANAGER_HEALTH_PORT=3001
# Тот же токен, что у плагинов в TCP payload
PLUGIN_MANAGER_INGRESS_TOKEN=dev-plugin-ingress
# Таймаут TCP batch pull plugin-manager → plugin (мс); наследие: PLUGIN_MANAGER_CONTROL_PLANE_HTTP_TIMEOUT_MS
PLUGIN_MANAGER_EXECUTOR_PULL_TIMEOUT_MS=30000
# Базовый URL HTTP file-service для блобов
PLUGIN_MANAGER_FILE_SERVICE_URL=http://file-service:3000
# Allowlist CIDR подключений TCP SDK
PLUGIN_MANAGER_ALLOW_CIDRS=0.0.0.0/0
# Размер батча публикации исполнителей плагина
PLUGIN_MANAGER_PUBLICATION_EXECUTOR_BATCH_SIZE=50
# Максимум статических assets одной публикации
PLUGIN_MANAGER_PUBLICATION_MAX_STATIC=200
# Максимум исполнителей одного запроса манифеста
PLUGIN_MANAGER_PUBLICATION_MAX_EXECUTORS=500
# Список pluginId разрешённых публикации пусто все
PLUGIN_MANAGER_PUBLICATION_ALLOWED_PLUGIN_IDS=
# Включить reconcile при старте plugin-manager
PLUGIN_MANAGER_STARTUP_RECONCILE=true
# Таймаут TCP probe startup reconcile миллисекунды
PLUGIN_MANAGER_STARTUP_PULL_TIMEOUT_MS=3000
# Интервал периодического health sweep миллисекунды ноль выкл
PLUGIN_MANAGER_PLUGIN_HEALTH_INTERVAL_MS=0
# Джиттер доля перед периодическим health sweep
PLUGIN_MANAGER_PLUGIN_HEALTH_JITTER_RATIO=0.2

Порты по умолчанию

Режим	Назначение	Порт
Внутри сети	Любой сервис (HTTP/TCP), второй слушатель	`:3000`, `:3001`
Demo	Сайт / плагины / health / шаги / отладка движка	8080 / 4016 / 4017 / 4021 / 4020
Dev	api / engine RPC / search TCP+health	4001 / 4013 / 4014+4015
Dev (инфра)	Postgres / Qdrant / Neo4j / Vault / Adminer / Mailcatcher	5432 / 6333 / 7474+7687 / 8200 / 8080 / 1080

Порты внешних плагинов: Плагины → Порты плагинов.

Коды ошибок

REST API использует стандартные HTTP-коды NestJS:

Код	Типичная причина	Действие
`400`	Невалидный запрос, несовместимый контракт, неизвестный MCP-tool	Проверить тело запроса и схему входа
`401`	Нет или просрочен JWT/ключ	Обновить токен или ключ `afk_*`
`403`	Нет прав на ресурс (scope, capability, CIDR)	Проверить capabilities и `API_SENSITIVE_ROUTE_CIDRS`
`404`	Процесс, Запуск или файл не найден	Проверить ID и владельца
`413` / `FILE_TOO_LARGE`	Превышен лимит загрузки файла	Уменьшить размер или поднять `PAYLOAD_LIMIT`
`429`	Rate limit	Повторить с backoff
`500`	Внутренняя ошибка сервиса	Логи сервиса, трассировка OTEL

Контракты HTTP API генерируются автоматически (Swagger на /api с Basic-auth).

Лимиты и значения по умолчанию

Параметр	Переменная	По умолчанию
Лимит тела HTTP-запроса	`PAYLOAD_LIMIT`	`50mb`
Срок access-токена	`JWT_ACCESS_TTL`	`15m`
Срок refresh-токена	`JWT_REFRESH_TTL`	`7d`
Срок хранения журнала аудита	`AUDIT_RETENTION_DAYS`	`365`
Ретраи диспетчеризации	`DISPATCH_MAX_ATTEMPTS` / `DISPATCH_RETRY_BASE_MS`	`5` / `300`
Мин. период cron	`SCHEDULER_MIN_CRON_PERIOD_MINUTES`	`60`
Период TCP-опроса плагинов	`PLUGIN_MANAGER_PLUGIN_HEALTH_INTERVAL_MS`	`0` (выкл.)
Размер пакета публикации исполнителей	`PLUGIN_MANAGER_PUBLICATION_EXECUTOR_BATCH_SIZE`	`50`

Матрица совместимости версий

Соответствие версий: ядро ↔ плагины ↔ API/SDK.

Версия ядра	@kosolapus/plugin-ts-sdk	Совместимость
2026.06.11	0.0.9	да

Матрица поставляется с каждым релизом платформы и обновляется при каждом релизе ядра. Совместимость плагинов проверяйте по semver SDK и notes релиза.

Дальше

Сервисы: зона ответственности каждого микросервиса.
Развёртывание: demo, on-prem и полные таблицы env.
Наблюдаемость: OTEL, метрики и health.

search-service

Семантический поиск Conveyor — индексация и retrieval по узлам, плагинам и документации через Qdrant и embeddings.

Оценка и выбор

Критерии выбора, миграция и чек-лист оценки.