Работа с Entrosity Vertex

Entrosity Vertex (entrosity-vertex.backend, изпълним файл vertex-server) е API сървър със собствена база данни PostgreSQL. Той работи до Entrosity Hub и Axis и се нуждае и от двата: потребителите влизат в Hub, а всяка заявка към директорията се изпълнява като задача на конектор на Axis, до който Vertex достига през вътрешното API на Axis. Vertex няма конектор, няма издания на конектор и няма публичен порт освен API-то зад проксито.

Все още не е внедрен

Бекендът и API-то му са готови; уеб интерфейсът е в разработка, а Vertex все още не е част от compose стека на entrosity-infra (няма compose услуга, няма маршрут на Caddy за /vertex). Hub регистрира продукта като изключен, така че нищо не води към него, докато не бъде внедрен и включен (Включване на Vertex по-късно).

Част	Къде
API	`https://hub.entrosity.com/vertex/api/v1`, след като бъде внедрен; проксито премахва `/vertex`, така че бекендът обслужва `/api/v1`
Вътрешно API за Axis	`VERTEX_INTERNAL_ADDR` (`:8088`), само в мрежата на контейнерите
Метрики	`VERTEX_METRICS_ADDR` (`:9096`), само в мрежата на контейнерите
База данни	Собствена база данни PostgreSQL, мигрирана с `vertex-server migrate up`; сървърът се свързва като `vertex_app` (защита на ниво ред)
Влизане	Entrosity Hub, продукт `vertex`

Слушатели и портове

Слушател	По подразбиране	Предназначение
`VERTEX_HTTP_ADDR`	`:8087`	API-то (`/api/v1`, `/healthz`, `/readyz`). Продукционният контейнер задава `:8080`, зад проксито.
`VERTEX_INTERNAL_ADDR`	`:8088`	Вътрешно API за Axis: заявките за тайни на конекторите, частите с резултати и подсказките за приключили задачи (Протокол на Vertex). Bearer `VERTEX_AXIS_TOKEN`. Никога не го публикувайте. Трябва да е различен от другите два.
`VERTEX_METRICS_ADDR`	`:9096`	Prometheus `/metrics`. Никога не го публикувайте; празно го изключва.

Vertex на свой ред извиква вътрешния слушател на Axis (RMM_INTERNAL_ADDR, :8089) и вътрешното API на Hub. Нито един от тях не изисква отваряне на защитната стена към интернет.

vertex-server serve        run the HTTP API and the background work (default)
vertex-server migrate [cmd] database migrations: up | down [N] | version | force N
                           (up also sets the vertex_app login password when
                           VERTEX_APP_DATABASE_PASSWORD is set)
vertex-server healthcheck  exit 0 when this server is ready (/readyz)
vertex-server version      print the version

Справочник на настройките

Сървърът се настройва само чрез променливи на средата VERTEX_* (entrosity-vertex.backend/internal/config). Невалидни стойности го спират при старт със списък на всички проблеми. Разделът RETENTION приема едно или две подчертавания: VERTEX_RETENTION_JOB_DAYS = VERTEX_RETENTION__JOB_DAYS.

Сървър

Променлива	По подразбиране	Значение
`VERTEX_ENV`	`dev`	`dev`, `test` или `prod`. `prod` отказва примерните тайни за разработка (стойности, съдържащи `dev-only`).
`VERTEX_PUBLIC_URL`	`http://localhost:8087`	Публичният адрес на Vertex включително префикса `/vertex`, който проксито премахва (`https://hub.entrosity.com/vertex`).
`VERTEX_HTTP_ADDR`	`:8087`	Слушател на API-то.
`VERTEX_INTERNAL_ADDR`	`:8088`	Вътрешно API за Axis. Задължителна.
`VERTEX_METRICS_ADDR`	`:9096`	Слушател за метрики; празно го изключва.
`VERTEX_LOG_LEVEL`	`info`	`debug`, `info`, `warn` или `error`.
`VERTEX_CORS_ORIGINS`	`http://localhost:5179`	Разрешени източници на браузъри, разделени със запетая, без заместващи символи и пътища (в продукция: `https://hub.entrosity.com`).
`VERTEX_TRUSTED_PROXIES`	няма	CIDR или IP адреси, на които е позволено да задават `X-Forwarded-For`; клиентският IP в одитния журнал идва от тях.
`VERTEX_API_RATE_PER_SECOND`, `VERTEX_API_RATE_BURST`	`20`, `60`	Ограничение на честотата на API-то на клиентски IP.

База данни

Променлива	По подразбиране	Значение
`VERTEX_DATABASE_URL`	няма (задължителна)	URL за връзка.
`VERTEX_DATABASE_ROLE`	`vertex_app`	Роля, към която пулът превключва след свързване (`SET ROLE`), за да важи защитата на ниво ред; празно, когато потребителят за вход вече е ролята на приложението.
`VERTEX_DATABASE_MAX_CONNS`	`20`	Размер на пула.
`VERTEX_DATABASE_STATEMENT_TIMEOUT`	`30s`	Горна граница за всяка заявка.
`VERTEX_APP_DATABASE_PASSWORD`	няма	Чете се от `migrate up`: включва потребителя за вход `vertex_app` с тази парола.

Тайни

Променлива	Значение
`VERTEX_JWT_SECRET`	Задължителна. Поне 32 байта, сурови или в base64. Подписва едноминутните токени за потока на живо. Токените за достъп на потребителите идват от Hub.
`VERTEX_JWT_SECRET_OLD`	Предишната тайна по време на ротация.
`VERTEX_CREDENTIALS_KEY`	Задължителна. Точно 32 байта, в base64. Криптира (AES-256-GCM) паролата на AD акаунта на всеки тенант и паролите на чакащите операции и импорти.
`VERTEX_CREDENTIALS_KEY_OLD`	Предишният ключ по време на ротация: той все още декриптира.

Пазете ключа за идентификационните данни

Без VERTEX_CREDENTIALS_KEY (или с друг) нито една запазена парола на AD не може да бъде декриптирана: всяка операция е неуспешна, докато паролата на AD на всеки тенант не бъде въведена отново в настройките на директорията. Чакащите операции и импорти с пароли не могат да се изпълнят. Пазете копие на ключа с тайните на внедряването, отделно от резервните копия на базата данни.

Променлива	По подразбиране	Значение
`VERTEX_PLATFORM_URL`	няма (задължителна)	Публичният източник на Hub (`https://hub.entrosity.com`): издателят на продуктовите токени.
`VERTEX_PLATFORM_INTERNAL_URL`	няма (задължителна)	Вътрешното API на Hub, достигано директно (compose: `http://platform:8081`): ключове за подписване и снимката на достъпа.
`VERTEX_PLATFORM_TOKEN`	няма (задължителна)	Bearer токенът на Vertex за вътрешното API на Hub, поне 32 знака; `vertex:<token>` в `PLATFORM_PRODUCT_TOKENS` на Hub.
`VERTEX_PLATFORM_SYNC_INTERVAL`	`30s`	Колко често Vertex изтегля потребителите, организациите и ролите от Hub (поне `1s`).

Entrosity Axis

Променлива	По подразбиране	Значение
`VERTEX_AXIS_INTERNAL_URL`	няма (задължителна)	Вътрешното API на Axis (`RMM_INTERNAL_ADDR`), например `http://rmm:8089`.
`VERTEX_AXIS_TOKEN`	няма (задължителна)	Bearer токенът и в двете посоки между Vertex и Axis, поне 32 знака; същата стойност като `RMM_VERTEX_AXIS_TOKEN` на Axis.

Промени в директорията

Променлива	По подразбиране	Значение
`VERTEX_CHANGE_LIMIT_USER`	`600`	Промени на потребител в минута (всеки член и всяка стойност в регистъра се броят; приложените импорти не). Над това: `429 rate_limited`.
`VERTEX_CHANGE_LIMIT_TENANT`	`2000`	Промени на тенант в минута.

Срокове на съхранение

Променлива	По подразбиране	Значение
`VERTEX_RETENTION_JOB_DAYS`	`90`	Приключили операции. Тенантите могат да го променят (7–730).
`VERTEX_RETENTION_AUDIT_DAYS`	`365`	Одитен журнал. Тенантите могат да го променят (30–3650).

0 или незададено запазва стойността по подразбиране.

Генериране на тайните

openssl rand -base64 32   # VERTEX_JWT_SECRET, VERTEX_CREDENTIALS_KEY (exactly 32 bytes)
openssl rand -hex 32      # VERTEX_APP_DATABASE_PASSWORD, VERTEX_PLATFORM_TOKEN, VERTEX_AXIS_TOKEN

Настройки на Axis

Axis говори с Vertex само когато са зададени тези настройки (Настройки):

Променлива	По подразбиране	Значение
`RMM_VERTEX_INTERNAL_URL`	празно (без Vertex)	Вътрешното API на Vertex, например `http://vertex:8088`.
`RMM_VERTEX_AXIS_TOKEN`	празно	Споделеният bearer токен: същата стойност като `VERTEX_AXIS_TOKEN`, поне 32 знака.
`RMM_INTERNAL_ADDR`	`:8089`	Вътрешният слушател на Axis за Vertex (конектори, задачи). Работи само докато Vertex е настроен. Никога не го публикувайте.

Когато са зададени и двете RMM_VERTEX_*, Axis стартира вътрешния слушател, добавя крайните точки за конектора POST /api/connector/v1/vertex/jobs/{jobID}/secrets и …/chunks и известява Vertex, когато задача на Vertex приключи. Ако е зададена само едната, Axis спира при старт.

В Entrosity Hub

Миграция 0013 на Hub регистрира продукта vertex (име Entrosity Vertex, базов път /vertex, роли tenant_admin и helpdesk) като изключен и в бета версия: той е скрит от списъка с продукти и не може да бъде даден на организации или потребители. Hub трябва да знае токена на Vertex: PLATFORM_PRODUCT_TOKENS включва vertex:<token>, със същата стойност като VERTEX_PLATFORM_TOKEN.

Включване на Vertex по-късно

Vertex достига до потребителите в този ред; всяка стъпка изисква предишната:

Споделеният протокол е маркиран. proto/vertex е в entrosity-shared-go: маркирайте издание, което го съдържа, и обновете entrosity-vertex.backend, entrosity-axis.backend и entrosity-axis-connector до този таг (дотогава те се изграждат само с локален go.work).
Axis и конекторът са издадени. Внедрете изданието на Axis с вътрешното API и препредаването и разпространете версията на конектора с възможността vertex до домейн контролерите, които ще изпълняват Vertex.
Инфраструктура. Добавете Vertex в entrosity-infra: базата данни и миграцията ѝ, услугата vertex с горните настройки, маршрута на Caddy /vertex/api/* (с премахване на /vertex, без буфериране за потока на събития), вътрешния мрежов път между Axis и Vertex и споделените токени (VERTEX_AXIS_TOKEN = RMM_VERTEX_AXIS_TOKEN, vertex:<token> в продуктовите токени на Hub). Уеб интерфейсът се добавя на /vertex/, когато бъде готов.
Включен, в бета версия. По-късна миграция на Hub включва продукта, както 0009 за Matrix. Той остава в бета версия: само администраторите на платформата го виждат и отварят.
Пуснат. Администратор на платформата избира Release to organizations (Продукти в бета версия).

Включете го само когато отговаря

Включването на продукта, преди Vertex да е внедрен на /vertex, кара списъка с продукти на Hub да води към продукт, който не отговаря.

Фонова работа

vertex-server serve също:

проверява задачите в Axis на отворените операции на всеки 2 секунди (подсказката от Axis за приключила задача ускорява това), прилага резултатите към огледалото веднъж, прави неуспешни операциите, които не са достигнали до Axis до една минута (not_dispatched) или които Axis вече не познава (job_lost);
стартира планираната синхронизация на всеки тенант, когато ѝ дойде времето (проверява се на всеки 30 секунди; интервалът на тенанта, по подразбиране 30 минути);
изтрива приключилите операции и записите в одита след сроковете им на съхранение, както и използваните токени за потвърждение с парола.

Слушатели и портове​

Справочник на настройките​

Сървър​

База данни​

Тайни​

Влизане в Entrosity Hub​

Entrosity Axis​

Промени в директорията​

Срокове на съхранение​

Генериране на тайните​

Настройки на Axis​

В Entrosity Hub​

Включване на Vertex по-късно​

Фонова работа​