Архитектура
Объяснение устройства продукта: какие компоненты есть, как они связаны и почему именно так. Опора для архитектора при оценке масштабирования, отказоустойчивости и периметра данных.
На какие вопросы отвечает раздел: Из чего собран продукт? Как компоненты общаются между собой? Что крутится в demo-образе и что входит в полноценный on-prem? Какие порты задействованы?
Компоненты системы
Платформа состоит из редактора, ядра оркестрации и подключаемых плагинов. В production каждый блок может работать отдельно и масштабироваться независимо.
| Компонент | Роль |
|---|---|
| Редактор | Процессы, библиотека узлов, секреты, Запуски и Трассировка Запуска |
| Ядро | REST API, оркестрация, очереди, хранение данных и секретов |
| Плагины | Внешние интеграции и пользовательские узлы (TCP SDK) |
Сервисы ядра
| Сервис | Роль | Транспорт внутри сети |
|---|---|---|
| api | REST API диаграмм, процессов, библиотеки, секретов; SSE по Запускам; прокси /auth | HTTP :3000 |
| auth-service | Логин, JWT, WebAuthn (passkeys), письма подтверждения | HTTP :3000 |
| runtime-engine | Оркестратор выполнения процессов (только TCP RPC, без HTTP) | TCP :3000 |
| runtime-control-plane | Ingress исполнителей (ack/result), policy dispatch, прокси /metrics движка | HTTP :3000 + TCP :3001 |
| executor | Встроенный исполнитель узлов ядра (HTTP, email, LLM, системные операции, пользовательский ввод) | очереди BullMQ (транспорт встроенных узлов) |
| scheduler | Cron- и webhook-триггеры | TCP :3000 |
| secret-manager | Хранение секретов (Postgres + Vault Transit) | TCP :3000 |
| preset-service | Раздача каталога пресетов | TCP :3000 |
| file-service | Загрузка и отдача файлов | HTTP :3000 |
| plugin-manager | Приём манифестов плагинов по SDK, запись каталога в БД | TCP :3000 + health :3001 |
| flow-agent | Генерация процессов по описанию и чат-агент (Ollama) | TCP :3000 + метрики :3001 |
| search-service | Семантический поиск, индексы, граф совместимости | TCP :3000 + health :3001 |
Конвенция портов: внутри Docker-сети каждый сервис слушает
:3000(HTTP или TCP), а где нужен второй слушатель (метрики, health, отдельный TCP) —:3001. Наружу проброшенные номера (4001,4013, …) во внутренних peer-URL не используются — между собой сервисы ходят по DNS-имени и внутреннему порту.
On-prem / prod-топология
В полноценном развёртывании каждый сервис — отдельный процесс (контейнер), редактор и плагины масштабируются независимо, инфраструктура (PostgreSQL, Redis, Vault и опционально Qdrant/Neo4j/Jaeger) разворачивается в вашем контуре.
Как связаны сервисы
- Редактор → api — REST + SSE (
NUXT_PUBLIC_API_BASE). Auth-вызовы api проксирует наauth-service. - api → engine: создание Запуска через очередь BullMQ.
runtime-engineстроит снимок графа и оркестрирует его, выбирая готовые узлы из БД. - engine ↔ runtime-control-plane — TCP RPC в обе стороны (
CONTROL_PLANE_TCP_CONNECT→ CP:3001; CP → engine RPC:3000). - executor → control-plane — ack/result шага по внутреннему HTTP (
RUNTIME_INTERNAL_BASE_URL); BullMQ — только транспорт встроенного executor. - Процессы плагинов → plugin-manager — TCP: манифест и batch-pull пакетов; →
control-plane — TCP step-ack/result (
:3001). - secret-manager → Vault Transit — секреты шифруются перед записью в Postgres.
- flow-agent / search-service — опциональны. При включении используют Ollama, Qdrant и Neo4j. search-service дополнительно требует Redis (очередь индексации BullMQ).
Demo: один Docker-образ
Demo-сценарий упаковывает весь стек в один контейнер (kosolapus/conveyor-demo на
Hub): PostgreSQL, Redis, Vault (file-storage на томе), нужные Nest-процессы,
workflow-manager (production Nitro) и Nginx как единая HTTP-точка для UI и API.
Состав demo-образа
Demo включает ядро оркестрации, редактор, PostgreSQL, Redis и Vault на томах. Опциональные компоненты полного стека (flow-agent, search-service, Qdrant, Neo4j) в образ не входят. Инструменты разработки и наблюдаемости (Mailcatcher, Jaeger, Adminer) подключают отдельно при локальной разработке.
Границы demo
- наружу проброшены только 5 портов (см. ниже): сайт, каналы для внешних плагинов, проверка готовности ядра, ответы о шагах процесса и служебный HTTP движка;
- внешние плагины подключаются отдельно ( см. Плагины → Demo Compose);
- секреты переживают рестарт только при подключённом томе
demo_vault; - образ рассчитан на локальное демо, не на production (об этом предупреждает статус-бар редактора).
Порты приложения по режимам
Demo (проброшено на хост, по умолчанию)
| Порт | Зачем нужен | Переменная |
|---|---|---|
| 8080 | Сайт: редактор, вход, API | DEMO_WEB_PORT |
| 4016 | Подключение плагинов к ядру | DEMO_PM_TCP_PORT |
| 4017 | Проверка, что ядро поднялось | DEMO_PM_HEALTH_PORT |
| 4021 | Ответы плагинов о выполнении шагов | DEMO_CP_TCP_PORT |
| 4020 | Служебный HTTP движка (метрики, отладка) | DEMO_CP_HTTP_PORT |
Dev-стек (локальная разработка, проброшено на хост)
| Сервис | Хост | Контейнер |
|---|---|---|
| api | 4001 (API_PUBLISH_PORT) | :3000 |
| runtime-engine RPC | 4013 | :3000 |
| search-service TCP / health | 4014 / 4015 | :3000 / :3001 |
| plugin-manager TCP / health | 4016 / 4017 | :3000 / :3001 |
| runtime-control-plane HTTP / TCP | 4020 / 4021 | :3000 / :3001 |
| Postgres | 5432 | :5432 |
| Redis | 6379 | :6379 |
| Qdrant | 6333 | :6333 |
| Neo4j HTTP / Bolt | 7474 / 7687 | :7474 / :7687 |
| Vault | 8200 | :8200 |
| Adminer | 8080 | :8080 |
Mailcatcher web (SMTP 1025 внутри) | 1080 | :1080 |
Ключевые механизмы
Редактирование процесса в рантайме
Граф меняется в редакторе без перезапуска платформы. Контракты узлов проверяются до запуска. Уже запущенное исполнение работает с тем графом, от которого оно строилось.
Stateless-исполнители и состояние в БД
Статусы и результаты выполнения шагов всех узлов Запуска хранятся в БД. Оркестратор выбирает готовые узлы из записей БД и передаёт payload исполнителю. Встроенные исполнители работают через очередь BullMQ. Plugin executors отправляют ack/result в runtime-control-plane по TCP. Долгоживущие сценарии не создают дополнительной нагрузки на оркестратор: состояние остаётся в БД.
Контур данных
- оркестрация и данные Запусков — в вашей инфраструктуре;
- секреты и пароли шифруются Vault Transit, в БД лежит только ciphertext;
- плагины можно изолировать сетью по политике безопасности;
- Трассировка Запуска: результаты выполнения шагов от исполнителей и события узлов;
- журнал аудита: критические действия пользователей (только в БД/внешней системе);
- метрики и распределённые трейсы выгружаются через явно настроенные порты и экспорт OpenTelemetry
Дальше
- Развёртывание и эксплуатация: demo, on-prem, переменные окружения и порты по шагам;
- Конфигурация и справочник: полный перечень переменных окружения;
- API: контракты и интеграции;
- Безопасность: контур данных и изоляция.