Функциональная архитектура

Архитектура Deckhouse Development Portal (DDP, портал) на уровне 2 модели C4 и его взаимодействие с другими компонентами изображены на следующей диаграмме:

Описание компонентов

В состав DDP входят следующие компоненты:

1. Frontend — это веб-интерфейс портала, построенный на Vue.js 3 с TypeScript. Компонент состоит из одного контейнера frontend и предоставляет пользователям графический интерфейс для работы с порталом через веб-браузер.

   Основные функции:

   • отображение пользовательского интерфейса для управления сервисами, окружениями и ресурсами;
   • обработка пользовательских действий в браузере и отправка запросов в backend через REST API.

   Технические характеристики:

   • отдаёт браузеру файлы веб-интерфейса через Ingress-контроллер или Gateway;
   • не обращается к backend сам: запросы к REST API отправляет браузер пользователя через тот же Ingress-контроллер или Gateway.

2. Backend — это серверная часть портала, реализованная на языке Go. Компонент предоставляет REST API для управления всеми механизмами портала.

   Основные функции:

   • предоставление REST API для программного взаимодействия с порталом;
   • обработка бизнес-логики портала;
   • реализация системы контроля доступа (RBAC) и управления правами пользователей;
   • интеграция с внешними инфраструктурными сервисами для выполнения различных операций;
   • управление данными через взаимодействие с PostgreSQL и Redis.

   Технические характеристики:

   • принимает API-запросы от веб-интерфейса в браузере пользователя и от внешних клиентов REST API;
   • выполняет вход пользователей через Dex и валидацию токенов доступа локально, используя кешированные ключи подписи;
   • ставит задачи агенту и передаёт его запросы к внешним языковым моделям;
   • подключается к Redis для координации очереди задач;
   • подключается к PostgreSQL для хранения и управления данными;
   • подключается к ClickHouse, если он настроен, для чтения хранящихся в нём данных.

   Состоит из следующих контейнеров:

   • wait-for-storage — init-контейнер, ожидающий, пока PostgreSQL, Redis и ClickHouse (если он настроен) начнут принимать подключения; для managed-экземпляров PostgreSQL и ClickHouse он также выполняет начальные SQL-скрипты, например создаёт нужные расширения PostgreSQL;
   • migrations — init-контейнер, выполняющий обновление структуры базы данных при старте компонента;
   • backend — основной контейнер.

3. Worker — это компонент для выполнения фоновых задач и асинхронных операций, реализованный на языке Go. Worker обрабатывает задачи из очередей Redis Streams: запускает действия и процессы, синхронизирует источники данных. Подробнее — в разделе «Воркеры».

   Основные функции:

   • синхронизация данных из внешних источников;
   • выполнение действий и процессов в асинхронном режиме;
   • выполнение проверок статуса сущностей;
   • запуск AI-агентов из элементов процессов «AI-агент».

   Технические характеристики:

   • может быть развёрнут в нескольких экземплярах для обеспечения масштабируемости;
   • использует Redis Streams для получения задач из очередей;
   • подключается к PostgreSQL для чтения и обновления данных;
   • интегрируется с внешними инфраструктурными сервисами для выполнения операций;
   • ставит задачи агенту при выполнении элементов процессов «AI-агент»;
   • переносит данные из PostgreSQL в ClickHouse, если он настроен.

   Состоит из следующих контейнеров:

   • wait-for-storage — init-контейнер, ожидающий, пока PostgreSQL, Redis и ClickHouse (если он настроен) начнут принимать подключения;
   • worker — основной контейнер.

4. Agent — это компонент, реализующий платформенный агент. Компонент состоит из одного контейнера agent. По умолчанию агент обрабатывает запросы в AI-ассистенте и в виджете «AI-чат»; его также можно выбрать в элементе процесса «AI-агент».

   Технические характеристики:

   • принимает задачи от backend и worker по протоколу A2A;
   • обращается к внешним языковым моделям и к инструментам портала через backend;
   • доступен только внутри кластера, без Ingress-контроллера или Gateway.

   DDP также поддерживает подключение внешнего AI-агента.

Следующие компоненты реализуют оперативное и долгосрочное хранение данных:

1. Redis — это хранилище данных в памяти, используемое порталом для работы с очередями задач. В режиме managed вместо Redis используется совместимый с ним Valkey.

   Основные функции:

   • реализация очередей задач через Redis Streams для асинхронной обработки;
   • поддержка распределённых блокировок для координации работы нескольких экземпляров worker;
   • передача событий, генерируемых при изменениях сущностей, в обработчики автоматизаций. Сами события хранятся в PostgreSQL.

   Технические характеристики:

   • используется для хранения очередей задач, которые обрабатываются worker.

2. PostgreSQL — это основная реляционная база данных портала, используемая для хранения всей постоянной информации.

3. ClickHouse — это хранилище для больших объёмов данных, например истории изменений параметров сущностей.

   ClickHouse можно установить в составе DDP, создать с помощью модуля managed-clickhouse или подключить внешний экземпляр. Без ClickHouse портал работает, но зависящие от него возможности недоступны: например, не сохраняется история изменений параметров сущностей. Подробнее — в разделе «ClickHouse».

   Основные функции:

   • хранение больших объёмов записей;
   • обслуживание запросов на выборку из этих данных.

   Технические характеристики:

   • наполняется worker, который переносит в него данные из PostgreSQL;
   • принимает подключения backend и worker по нативному протоколу ClickHouse.

Следующий компонент не входит в состав DDP:

1. Dex — это компонент системы аутентификации и авторизации, выполняющий роль identity provider. Dex обеспечивает единую точку входа для пользователей и интегрируется с различными внешними провайдерами аутентификации.

   Компонент Dex является частью модуля user-authn в Deckhouse Platform (DP).

   Основные функции:

   • управление процессом аутентификации пользователей;
   • выдача токенов доступа;
   • интеграция с внешними провайдерами аутентификации (Keycloak, LDAP и другими);
   • предоставление ключей подписи для проверки токенов.

   Технические характеристики:

   • показывает пользователю страницу входа;
   • выписывает и обновляет токены по запросам backend;
   • периодически предоставляет ключи подписи токенов для проверки;
   • интегрируется с внешними провайдерами аутентификации через стандартные протоколы (OIDC, LDAP и др.).

Рабочие пространства

Рабочие пространства создаются в кластере и неймспейсе шаблона. При установке модулем Jobs операций OpenTofu запускаются в неймспейсе модуля. Постоянные данные рабочих пространств хранятся на отдельных томах; состояние OpenTofu передаётся в HTTP backend портала.

Стартовый шаблон создаёт под с контейнерами:

Браузер открывает IDE по отдельному HTTPS-домену через Ingress целевого кластера. Контейнер gate проверяет доступ в DDP. Агент обращается к модели и MCP через портал, поэтому подам нужен доступ к HTTPS-адресу DDP. Настройка описана в примерах сети и хранения.

Описание сетевых взаимодействий

Входящие соединения

Входящие соединения принимает Ingress-контроллер или Gateway кластера по протоколу HTTPS (TCP/443) и пересылает их в компоненты портала на порт TCP/8080:

• Пользователи → DDP Frontend: браузер загружает файлы веб-интерфейса.
• Пользователи → DDP Backend: браузер отправляет запросы к REST API с веб-интерфейса; внешние клиенты обращаются к REST API напрямую. На backend также поступают запросы к вебхукам портала.
• Пользователи → Dex (TCP/443): браузер открывает страницу входа Dex.

Взаимодействие между компонентами портала

• DDP Backend → Dex (TCP/443): Backend получает токены пользователей при входе и при их обновлении, а также ключи подписи для проверки токенов.
• DDP Backend ↔ Redis (TCP/6379): Backend использует Redis для координации очередей задач и хранения событий.
• DDP Backend ↔ PostgreSQL (TCP/5432): Backend выполняет операции чтения и записи постоянных данных.
• DDP Worker ↔ Redis (TCP/6379): Worker получает задачи из очередей Redis Streams и использует распределённые блокировки.
• DDP Worker ↔ PostgreSQL (TCP/5432): Worker обновляет данные в базе после выполнения задач.
• DDP Backend ↔ ClickHouse (TCP/9000, опционально): Backend читает данные, которые хранятся в ClickHouse.
• DDP Worker ↔ ClickHouse (TCP/9000, опционально): Worker переносит в ClickHouse данные из PostgreSQL и удаляет из него данные объектов, которые в портале уже удалены.
• DDP Backend → DDP Agent (TCP/8080): Backend ставит агенту задачи из AI-ассистента и виджета «AI-чат».
• DDP Worker → DDP Agent (TCP/8080): Worker ставит агенту задачи из элементов процессов «AI-агент».
• DDP Agent → DDP Backend (TCP/8080): Agent отправляет запросы к языковой модели и вызывает инструменты портала.

Интеграция с внешними сервисами

• Dex ↔ Провайдеры аутентификации (Keycloak, LDAP и др.): Dex интегрируется с внешними системами управления пользователями.
• DDP Backend ↔ Инфраструктурные сервисы (TCP/443): Backend взаимодействует с внешними сервисами для получения информации.
• DDP Worker ↔ Инфраструктурные сервисы (TCP/443): Worker выполняет операции с внешними сервисами при синхронизации данных и выполнении действий.
• DDP Backend → Внешние языковые модели (TCP/443): Backend передаёт провайдеру языковой модели запросы агента.
• DDP Backend и DDP Worker → Внешние AI-агенты (TCP/443): портал ставит задачи подключённым внешним агентам по протоколу A2A.