Работа с Entrosity Matrix

Entrosity Matrix работи до Entrosity Hub, Axis, Edge и Sphere на същия хост. Той е по избор за всеки хост: профилът matrix на compose съдържа услугите му, а скриптовете за разгръщане ги стартират само когато deploy/.env съдържа MATRIX_ENABLED=true (Включване на Matrix на хост). Matrix няма нужда от друг порт освен 443: конекторите се свързват навън към него през HTTPS и WebSocket.

Част	Къде
Уеб приложение (entrosity-matrix.frontend)	https://hub.entrosity.com/matrix/, обслужвано от Caddy от уеб образа
API (entrosity-matrix.backend, образ ghcr.io/entrosity/matrix-backend)	https://hub.entrosity.com/matrix/api/…; Caddy премахва /matrix, така че бекендът обслужва /api/v1 (браузъри), /api/connector/v1 (конектори) и /api/releases/v1 (инсталатори на конектора: качване от CI, връзки за изтегляне с изтичащ срок)
База данни	Собствена база данни в PostgreSQL (matrix), мигрирана от бекенда
Влизане	Entrosity Hub, продукт matrix

Услуги

deploy/docker-compose.prod.yml на entrosity-infra, профил matrix:

Услуга	Образ	Какво прави
matrix-db-init	postgres:18-alpine	Създава базата данни matrix (собственик rmm) веднъж.
matrix-migrate	matrix-backend	Изпълнява migrate up като собственик и разрешава входа matrix_app с MATRIX_APP_DATABASE_PASSWORD.
matrix	matrix-backend	matrix-server serve, една инстанция: конекторите държат WebSocket към нея, уеб приложението – поток от събития, а графиците за включване се изпълняват в нейната опашка със задачи. API на :8080 зад Caddy; метрики на :9095 (вътрешно). Проверка на здравето: matrix-server healthcheck. Ограничение на паметта MATRIX_MEMORY (384m), GOMEMLIMIT от MATRIX_GOMEMLIMIT (300MiB).

Услугата web (Caddy) обслужва и Matrix:

Път	Отива към
/matrix/	Уеб приложението (от образа matrix-frontend, вграден в уеб образа); /matrix пренасочва към /matrix/
/matrix/api/*	matrix:8080, с премахнат /matrix; отговорите не се буферират (WebSocket, поток от събития)

Докато Matrix не е включен на хост, услуга matrix няма и /matrix/api/* връща 502; Hub не показва връзка към Matrix, докато продуктът не бъде включен.

Изпълнимият файл на бекенда е matrix-server:

matrix-server serve                 run the HTTP API and job workers (default)
matrix-server migrate [cmd]         database migrations: up | down [N] | version | force N
                                    (up also sets the matrix_app login password when
                                    MATRIX_APP_DATABASE_PASSWORD is set)
matrix-server healthcheck           exit 0 when this server is ready (/readyz), for
                                    container health checks
matrix-server release-keygen        print a new connector release signing key pair
matrix-server import-stop-internet  import the stop-internet panel's room rights and history
matrix-server version               print the version

В Hub продуктът matrix (роли tenant_admin, teacher, viewer) се регистрира от миграция 0008 на Hub като изключен и в бета версия и се включва от миграция 0009 (Въвеждане). Hub трябва да знае токена на Matrix: PLATFORM_PRODUCT_TOKENS съдържа matrix:<token> със същата стойност като MATRIX_PLATFORM_TOKEN. В продукция и двете идват от PLATFORM_PRODUCT_TOKEN_MATRIX в deploy/.env.

Справочник на конфигурацията

Бекендът се конфигурира само чрез променливи на средата MATRIX_* (entrosity-matrix.backend/internal/config). Невалидни стойности спират стартирането със списък на всички проблеми. Разделът RETENTION приема едно или две долни тирета: MATRIX_RETENTION_JOB_DAYS = MATRIX_RETENTION__JOB_DAYS.

Сървър

Променлива	По подразбиране	Значение
MATRIX_ENV	dev	dev, test или prod. prod отказва примерните тайни за разработка и пише журнала в JSON.
MATRIX_PUBLIC_URL	http://localhost:8085	Публичният адрес на Matrix, включително представката /matrix, която проксито премахва (https://hub.entrosity.com/matrix). Конекторите получават <MATRIX_PUBLIC_URL>/api/connector/v1/ws, а командите за инсталиране, показвани с нови токени за регистриране, го използват като SERVER_URL.
MATRIX_HTTP_ADDR	:8085	Слушател на API (продукция: :8080).
MATRIX_METRICS_ADDR	:9095	Вътрешен слушател за Prometheus /metrics. Никога не го излагайте публично; празно го изключва.
MATRIX_INTERNAL_ADDR	:8086	Вътрешен API за стената с екрани на Entrosity Axis: GET /internal/v1/screen-rooms (залите на тенант с компютрите им или залите, дадени на учител). Работи само когато е зададен MATRIX_AXIS_TOKEN. Никога не го излагайте публично (compose: само мрежата, не и Caddy).
MATRIX_AXIS_TOKEN	празно (изключено)	Токенът (bearer), с който Axis се обръща там (поне 32 знака; RMM_MATRIX_AXIS_TOKEN на Axis). В compose един MATRIX_AXIS_TOKEN в .env (openssl rand -hex 32) включва стената с екрани и за двете услуги.
MATRIX_LOG_LEVEL	info	debug, info, warn или error.
MATRIX_CORS_ORIGINS	http://localhost:5178	Разрешени произходи (origins) на браузъри, разделени със запетая, без заместващи символи и пътища (продукция: https://hub.entrosity.com).
MATRIX_TRUSTED_PROXIES	няма	CIDR или IP адреси, на които е разрешено да задават X-Forwarded-For (продукция: мрежата на compose 172.30.0.0/24). От него идва IP адресът на клиента, записван с всяка промяна.
MATRIX_API_RATE_PER_SECOND, MATRIX_API_RATE_BURST	20, 60	Ограничение на заявките към уеб API за IP адрес на клиент (училище зад един NAT адрес го споделя).
MATRIX_ENROLL_RATE_PER_MINUTE	60	Регистрирания на конектори за IP адрес на клиент.
MATRIX_CONNECTOR_DOWNLOAD_URL	няма	Откъде може да се изтегли MSI на конектора; показва се с новите токени за регистриране, докато няма съхранено издание на конектора (Издания на конектора).

База данни

Променлива	По подразбиране	Значение
MATRIX_DATABASE_URL	няма (задължителна)	URL за връзка. Продукцията се свързва като matrix_app.
MATRIX_DATABASE_ROLE	matrix_app	Ролята, към която пулът превключва след свързване (SET ROLE), така че защитата на ниво ред важи дори при връзка като собственик. Празно, когато входът вече е ролята на приложението и не може да превключва.
MATRIX_DATABASE_MAX_CONNS	20	Размер на пула.
MATRIX_DATABASE_STATEMENT_TIMEOUT	30s	Горна граница за всяка заявка.
MATRIX_APP_DATABASE_PASSWORD	няма	Чете се от migrate up: разрешава входа matrix_app с тази парола.

Тайни

Променлива	Значение
MATRIX_JWT_SECRET	Задължителна. Поне 32 байта, сурови или base64. Подписва едноминутните токени за потока с обновления на живо (POST /auth/sse-token). Токените за достъп на потребителите идват от Hub.
MATRIX_JWT_SECRET_OLD	Предишната тайна по време на смяна (все още се проверява).
MATRIX_CREDENTIALS_KEY	Задължителна. Точно 32 байта, base64: криптира API ключовете на FortiGate в базата данни (AES-256-GCM; ID на защитната стена е свързан с шифрования текст, така че шифрован текст, копиран към друга защитна стена, не се декриптира).
MATRIX_CREDENTIALS_KEY_OLD	Предишният ключ по време на смяна: той още декриптира; ключовете, съхранени след смяната, използват текущия ключ.

При MATRIX_ENV=prod стойностите, съдържащи dev-only (примерите за разработка), се отказват.

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

Без MATRIX_CREDENTIALS_KEY (или с друг ключ) нито един API ключ на FortiGate не може да бъде декриптиран: конекторите, които се рестартират или получат нова конфигурация, не могат да влязат в защитните си стени, докато всички ключове не бъдат въведени отново. Пазете копие на deploy/.env заедно с резервните копия, но отделно от тях.

Влизане чрез Entrosity Hub

Променлива	По подразбиране	Значение
MATRIX_PLATFORM_URL	няма (задължителна)	Публичният произход на Hub (https://hub.entrosity.com): издателят на токените за продукт и мястото, където браузърите влизат.
MATRIX_PLATFORM_INTERNAL_URL	няма (задължителна)	Вътрешният API на Hub, достъпван директно, а не през проксито (compose: http://platform:8081): ключове за подписване и моментната снимка на достъпа.
MATRIX_PLATFORM_TOKEN	няма (задължителна)	Bearer токенът на Matrix за вътрешния API на Hub, поне 32 знака; matrix:<token> в PLATFORM_PRODUCT_TOKENS на Hub.
MATRIX_PLATFORM_SYNC_INTERVAL	30s	Колко често Matrix изтегля потребителите, организациите и ролите от Hub (поне 1s).

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

Променлива	По подразбиране	Значение
MATRIX_REPORT_STALE_AFTER	90s	Залите на една защитна стена са неактуални (показват се като неактуални, промените се отказват със snapshot_stale), когато последният ѝ отчет е по-стар от тази стойност или от 2,5 × интервала на отчитане на защитната стена (по-дългото от двете), когато конекторът ѝ е офлайн или когато тя не отчита online. Поне 15s.
MATRIX_CHANGE_LIMIT_USER	10	Заявки за промяна на потребител за минута (всяка зала от групова промяна се брои). Над това: 429 rate_limited, записва се като отказана.
MATRIX_CHANGE_LIMIT_TENANT	30	Заявки за промяна на тенант за минута.

Обновявания на конектора

Променлива	По подразбиране	Значение
MATRIX_RELEASE_SIGNING_KEY	няма	Подписва изданията на конектора: ключ Ed25519, base64 на 32-байтовото начално число (seed) или на 64-байтовия частен ключ. Публичната му половина е RELEASE_PUBLIC_KEY, с който се компилират конекторите. Празна стойност изключва качването и самообновяването (качванията връщат 503 releases_disabled). Невалидна стойност спира сървъра.
MATRIX_RELEASE_TOKEN	няма	Bearer токенът на CI за качване на версии на конектора (POST /api/releases/v1/connector), поне 32 знака. Празна стойност: всяко качване връща 401.
MATRIX_CONNECTOR_UPDATE_CHANNEL	stable	До какво се обновяват конекторите (и какво предлага Изтегляне на конектора): stable (само издания с етикет) или dev (версии за разработка и издания с етикет).

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

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

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

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

В продукция файлът на compose фиксира повечето от горните (MATRIX_PUBLIC_URL=https://${PLATFORM_DOMAIN}/matrix, MATRIX_CORS_ORIGINS, слушателите, доверените проксита, MATRIX_PLATFORM_INTERNAL_URL=http://platform:8081). deploy/.env (deploy/.env.prod.example ги изброява) задава останалото:

Променлива	Значение
MATRIX_ENABLED	true пуска профила matrix. По подразбиране false.
MATRIX_APP_DATABASE_PASSWORD	Паролата на входа matrix_app. Задължителна, когато е включен.
MATRIX_JWT_SECRET, MATRIX_JWT_SECRET_OLD	Както по-горе. Първата е задължителна, когато е включен.
MATRIX_CREDENTIALS_KEY, MATRIX_CREDENTIALS_KEY_OLD	Както по-горе. Първият е задължителен, когато е включен.
PLATFORM_PRODUCT_TOKEN_MATRIX	Токенът на Matrix в Hub: става MATRIX_PLATFORM_TOKEN и записът matrix: в PLATFORM_PRODUCT_TOKENS на Hub. Задължителен, когато е включен.
MATRIX_RELEASE_SIGNING_KEY, MATRIX_RELEASE_TOKEN	Самообновяване на конекторите, както по-горе. По избор: празни стойности го изключват (Включване на самообновяването на конекторите).
MATRIX_CONNECTOR_DOWNLOAD_URL, MATRIX_LOG_LEVEL	Както по-горе.
MATRIX_BACKEND_IMAGE	По подразбиране ghcr.io/entrosity/matrix-backend.
MATRIX_MEMORY, MATRIX_GOMEMLIMIT	Ограничения на паметта: 384m, 300MiB.

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

openssl rand -base64 32   # MATRIX_JWT_SECRET, MATRIX_CREDENTIALS_KEY (exactly 32 bytes)
openssl rand -hex 32      # MATRIX_APP_DATABASE_PASSWORD, PLATFORM_PRODUCT_TOKEN_MATRIX, MATRIX_RELEASE_TOKEN

Паролата за базата данни попада в URL за връзка, затова използвайте стойност без /, + и = (hex). Токенът за продукта трябва да е поне 32 знака. Никога не публикувайте тези стойности в хранилище и не ги поставяйте в тикети.

Включване на Matrix на хост

1. Генерирайте тайните и задайте MATRIX_APP_DATABASE_PASSWORD, MATRIX_JWT_SECRET, MATRIX_CREDENTIALS_KEY и PLATFORM_PRODUCT_TOKEN_MATRIX в deploy/.env.
2. Задайте MATRIX_ENABLED=true.
3. Разгърнете (следващото изпълнение на deploy или deploy/scripts/upgrade.sh).

При MATRIX_ENABLED=true deploy/scripts/lib.sh добавя --profile matrix към всяка команда на compose и отказва да работи, докато MATRIX_APP_DATABASE_PASSWORD, MATRIX_JWT_SECRET, MATRIX_CREDENTIALS_KEY или PLATFORM_PRODUCT_TOKEN_MATRIX е празна. След това upgrade.sh изтегля образите на Matrix и след Hub изпълнява matrix-migrate и рестартира matrix (и изчаква да стане здрав). Hub се създава наново с matrix:<token> в токените си за продукти. Финалната проверка на работния поток deploy чака и /matrix/api/v1/healthz на хостовете с MATRIX_ENABLED=true.

Въвеждане

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

1. Споделеният протокол е с етикет. proto/matrix (и JobProgress.Detail) са в entrosity-shared-go: създайте издание с етикет, което ги съдържа, и обновете entrosity-matrix.backend и entrosity-matrix-connector до този етикет (дотогава те се компилират само с локален go.work, а CI се проваля).
2. Образите са публикувани. ghcr.io/entrosity/matrix-backend:main и ghcr.io/entrosity/matrix-frontend:main съществуват (от техния CI на main); MSI на конектора се компилира от работния му поток за издания.
3. Инфраструктура. Публикувайте промяната в entrosity-infra, която добавя Matrix (профил на compose, маршрути на Caddy, уеб образ, скриптове, работен поток за разгръщане), след това настройте хоста както по-горе с MATRIX_ENABLED=true и разгърнете. Миграция 0008 на Hub е регистрирала продукта изключен: още никой не го вижда.
4. Включен, в бета версия. Разгърнете изданието на Hub с миграция 0009, която включва продукта. Той остава в бета версия: само администраторите на платформата го виждат и отварят и могат да го включват за организации.
5. Пуснат. Администратор на платформата избира Release to organizations (Продукти в бета версия).

Ред на разгръщането

Работният поток deploy изтегля matrix-backend:main и изгражда уеб образа с matrix-frontend:main при всяко изпълнение, независимо дали хостът включва Matrix. Публикувайте промяната в entrosity-infra само след като и двата образа са публикувани, иначе всяко разгръщане се проваля (Непрекъснато разгръщане). Миграция 0009 трябва да влезе в издание на Hub, разгърнато след стъпка 3: преди това списъкът с продукти би водил към Matrix, който не отговаря.

Въвеждане на разрешените сайтове

Разрешените сайтове изискват миграция 0003_allowed_sites (прилага се от matrix-migrate с новия бекенд) и конектори, които обявяват възможността sites. Бекендът и конекторите могат да се обновяват в произволен ред:

• Старите конектори с новия бекенд продължават да работят както досега. Те не получават задачи matrix.sites.set; приложението казва Конекторът на тази защитна стена все още не поддържа разрешени сайтове, запазването отговаря с 409 connector_outdated, а отчетите им без сайтове продължават да работят.
• Новите конектори с предишния бекенд също продължават да работят: изпращат списъците, които този бекенд пренебрегва, а проверката им показва новите предупреждения (sites_not_set_up:), докато групите не бъдат настроени.
• Файловете на защитата не се променят. Записите на сайтове са изключени до matrix-connector guard set <id> --site-writes on. Обхватът не се променя, така че никоя защитна стена не трябва да се приема отново.
• Във FortiGate не се случва нищо, докато администраторът му не изпълни командите за настройка: без групите Matrix не записва нищо, а новият превключвател site_writes_enabled (изключен) има ефект едва когато групите съществуват.

Премахване на услугите на Entrosity

Услугите на Entrosity (заключената група Matrix Entrosity services, MATRIX_SERVICE_DOMAINS, services_enabled на защитните стени и задачите matrix.services.sync) са премахнати: докато интернетът на залата е спрян, достъпни са само сайтовете, които учителите и администраторите са изброили. Миграцията 0004_remove_entrosity_services премахва firewalls.services_enabled, firewall_snapshots.services и индекса за една отворена синхронизация, изтрива отворените задачи matrix.services.sync и отменя чакащите им промени; историята запазва записите си services.

• Разгърнете първо фронтенда (или заедно с бекенда): новият API отказва services_enabled при промяна на защитна стена (422), а предишният фронтенд го изпраща при запазване на защитна стена. Новият фронтенд работи с предишния бекенд.
• Старите конектори с новия бекенд продължават да работят: прилагането вече не съдържа services_enabled / service_domains, затова те държат групата празна и никога не получават синхронизация; останала синхронизация би била отказана при разрешаването (services_removed). services в отчетите им се пренебрегва; проверката им може още да показва предупреждения services_not_set_up: или services_out_of_sync:, които вече нямат значение (обновете конектора).
• Новите конектори с предишния бекенд също продължават да работят: пренебрегват полетата за услуги при прилагането, никога не записват в групата, не изпращат services (затова този бекенд никога не изпраща синхронизация) и отказват matrix.services.sync като неподдържан тип задача. allow_service_writes в съществуващ guard.json се пренебрегва; никоя защитна стена не трябва да се приема отново.
• Премахнете MATRIX_SERVICE_DOMAINS от средата на разгръщането (сървърът вече не го чете).
• Във FortiGate, настроени по-рано, администратор може да премахне празната група (Отстраняване на проблеми → Премахване на старата група с услугите на Entrosity).

Издания на конектора

Matrix пази инсталаторите на конектора и ги разпространява: CI качва всяка версия, Matrix я подписва, на конекторите, които могат да се обновяват сами, се предлага най-новата, а администраторите на тенанта я изтеглят от Изтегляне на конектора (Конектори → Обновявания).

Включване на самообновяването на конекторите

1. Генерирайте веднъж двойката ключове Ed25519:

   docker compose -f docker-compose.prod.yml --env-file .env --profile matrix run --rm --no-deps matrix release-keygen
   openssl rand -hex 32                                                            # MATRIX_RELEASE_TOKEN

   release-keygen отпечатва MATRIX_RELEASE_SIGNING_KEY (тайната на сървъра) и RELEASE_PUBLIC_KEY (за компилирането на конектора). Пазете ключа за подписване толкова тайно, колкото и другите ключове.

2. В deploy/.env на хоста задайте MATRIX_RELEASE_SIGNING_KEY и MATRIX_RELEASE_TOKEN и по желание MATRIX_CONNECTOR_UPDATE_CHANNEL.

3. В хранилището entrosity-matrix-connector задайте тайните RELEASE_PUBLIC_KEY (компилиран в конектора) и MATRIX_RELEASE_TOKEN (същият токен), както и променливата RELEASE_PUBLISH_ENABLED=true. MATRIX_RELEASE_API (променлива) сменя адреса, по подразбиране https://hub.entrosity.com/matrix/api/releases/v1.

4. Разгърнете отново. Следващата версия на конектора се качва и предлага.

5. Конекторите, инсталирани преди това, са компилирани без публичния ключ и не могат да се обновяват сами: инсталирайте новата версия на всеки от тях веднъж.

Пазете ключа за подписване

Конекторите приемат само издания, подписани с ключа, който съдържа тяхната версия. С друг ключ (изгубено или сменено начално число) всяко обновяване завършва с signature_invalid, докато всеки конектор не бъде преинсталиран ръчно с версия, съдържаща новия публичен ключ.

Публикуване

CI качва всеки MSI със scripts/publish-release.sh от хранилището на конектора:

Версия	Номер	Канал
Етикет vX.Y.Z (release.yml)	X.Y.Z	stable
Етикет vX.Y.Z-suffix	X.Y.Z-suffix	dev
Всяко качване в main (dev-release.yml)	предварителна версия -dev	dev

Качването е POST /api/releases/v1/connector?version=…&channel=…&notes=… с Authorization: Bearer $MATRIX_RELEASE_TOKEN и самия MSI като тяло (до 64 MiB). Matrix подписва манифеста му (компонент matrix-connector: версия, SHA-256 и размер) и пази най-новите десет издания.

Отговор	Значение
201	Съхранено.
401 unauthorized	Грешен или липсващ токен, или MATRIX_RELEASE_TOKEN не е зададен.
409 release_exists	Тази версия вече е публикувана (скриптът го приема за успех).
422 validation	Не е семантична версия, канал, различен от stable или dev, или празно или твърде голямо тяло.
503 releases_disabled	MATRIX_RELEASE_SIGNING_KEY не е зададен.

Предлагане на обновявания

На всеки 5 минути (releases.rollout) и когато конектор изпрати hello, Matrix предлага най-новото издание от MATRIX_CONNECTOR_UPDATE_CHANNEL на онлайн конекторите, които обявяват възможността update, работят с по-стара версия, нямат отворена задача за обновяване и не им е предлагана същата версия през последния час. Предложението е задача update_agent с връзки за изтегляне, валидни 2 часа (GET /api/connector/v1/releases/{releaseID}/msi?t=…, упълномощени от самата връзка). Какво прави конекторът: Конектор на Matrix → Самообновяване.

Фонови задачи

Бекендът изпълнява задачите си в PostgreSQL (River):

Задача	Кога	Какво
realtime.sweep	На всеки 30 секунди	Маркира като офлайн конекторите, мълчали 3 минути; прекратява просрочените задачи на конекторите и изпраща повторно непотвърдените. Просрочена задача за запис става Непотвърдено, ако конекторът я е бил поел, и Грешка, ако никога не я е поемал.
matrix.stale	На всеки 30 секунди	Намира защитните стени, чиито зали са станали неактуални (или отново актуални), и уведомява отворените уеб приложения (matrix.rooms).
schedule.fire	В часа на всяко включване	Маркира графика като firing и изпраща включването на залата като системна промяна. Докато конекторът е офлайн или защитната стена е неактуална, опитва отново (след 30 секунди, с удвояване до 15 минути); 24 часа след зададения час графикът става failed.
schedule.sweep	На всяка минута	Поставя отново в опашката просрочените графици в състояние pending (например след като сървърът е бил спрян).
releases.rollout	На всеки 5 минути	Предлага най-новото издание на конектора (Предлагане на обновявания). Не прави нищо без MATRIX_RELEASE_SIGNING_KEY.
retention.cleanup	Ежедневно	Вижте Съхранение.

Освен това всеки отчет на конектор (matrix.report) обновява залите (зала, липсваща в успешен отчет, става вече не е в защитната стена), адресните групи и разрешените сайтове, когато са се променили, и състоянието, версията на FortiOS и състоянието на локалната защита на защитната стена и уведомява уеб приложенията. Matrix никога не създава отново задача за запис сам: неуспешна или непотвърдена промяна остава такава, докато човек не предприеме действие. Единствените системни записи са автоматичните включвания.

Съхранение

Ежедневна задача retention.cleanup изтрива старите данни на порции от 10 000 реда:

Данни	Пазят се
Приключили задачи на конекторите	Замяната на тенанта (settings.retention.job_days, 7–730), иначе MATRIX_RETENTION_JOB_DAYS.
Одитен журнал	Замяната на тенанта (settings.retention.audit_days, 30–3650), иначе MATRIX_RETENTION_AUDIT_DAYS.
Токени за регистриране	30 дни след изтичането или отмяната им.
Приключили сесии в Hub, използвани step-up токени	Докато вече не са нужни.
История на промените (change_events)	Пази се (не се изчиства).

matrix_retention_rows_deleted_total{category} брои какво е премахнато.

База данни и миграции

Matrix има собствена база данни. Миграциите са вградени в изпълнимия файл (entrosity-matrix.backend/db/migrations) и се прилагат от migrate up:

Миграция	Добавя
0001_init	Копието на Matrix на тенантите, потребителите и ролите от Hub (tenants, users, tenant_memberships, състояние на синхронизацията с Hub, приключили сесии, използвани step-up токени), sites, audit_log само за добавяне, enrollment_tokens, connectors, jobs, connector_releases и защита на ниво ред с ролята matrix_app.
0002_matrix	firewalls (конфигурацията, запечатаният ключ token_enc с credentials_version, превключвателите за запис и последно отчетеното от конектора), rooms, firewall_snapshots (адресни групи), room_grants, change_events само за добавяне (историята), address_operations, bulk_actions, room_schedules, rate_buckets (ограничения на промените), а в jobs – колоните, свързващи задача със защитната ѝ стена, правило, зала, групова промяна, график и адресна операция, като за всяко правило може да има най-много едно отворено превключване на зала и за всяка защитна стена – най-много една отворена адресна задача.
0003_allowed_sites	Разрешени сайтове: във firewalls превключвателите site_writes_enabled (изключен по подразбиране) и services_enabled (включен по подразбиране); във firewall_snapshots изпратените списъци и група с услуги (sites, sites_hash, sites_fetched_at, services); видовете промени sites и services; най-много една отворена matrix.sites.set за защитна стена и списък (списъкът се пази в jobs.room_code: shared или кодът на залата) и една отворена matrix.services.sync за защитна стена. Обратната миграция ги премахва.
0004_remove_entrosity_services	Премахва услугите на Entrosity: изтрива firewalls.services_enabled, firewall_snapshots.services и индекса на отворените matrix.services.sync, изтрива отворените задачи и отменя чакащите им промени. Историята запазва записите си services (видът остава разрешен). Обратната миграция връща колоните (services_enabled изключено за съществуващите защитни стени) и индекса.

• Изолация на тенантите: всяка таблица на тенант има политика за защита на ниво ред (FORCE); сървърът работи като matrix_app (NOBYPASSRLS).
• История само за добавяне: тригер отказва промяна или изтриване на приключил ред в change_events; само ред в изчакване получава резултата и стъпките си.
• API ключовете на FortiGate се съхраняват само криптирани (token_enc) и никога не са част от задача, събитие или одитния журнал.

Резервни копия и възстановяване

deploy/scripts/backup.sh прави дъмп на базата данни matrix, когато тя съществува, до останалите: backups/db/matrix-<timestamp>.dump (pg_dump -Fc, проверен чрез обратно прочитане), изтриван заедно с другите дъмпове след дните за съхранение.

deploy/scripts/restore.sh при MATRIX_ENABLED=true спира matrix, възстановява дъмпа matrix-… от същото изпълнение на резервното копие, ако има такъв (създава наново базата данни и ролята matrix_app), изпълнява matrix-migrate и стартира отново matrix.

Дъмпът съдържа API ключовете на FortiGate, криптирани с MATRIX_CREDENTIALS_KEY: възстановяването изисква същия ключ. Дъмпът съдържа и историята (имейл адреси на потребители и IP адреси на клиенти): защитавайте резервните копия като самата база данни. След възстановяване залите се актуализират от следващите отчети на конекторите; промените, направени след резервното копие, не са във възстановената история.

Прехвърляне от панела stop-internet

matrix-server import-stop-internet --tenant <id> --firewall <id> --users users.csv --export export.json прехвърля панела за едно училище, който Matrix заменя, в един тенант и една защитна стена: разрешените зали на учителите стават права по зали, а историята му (превключвания на зали, смени на IP адреси, нови компютри) става история на промените с източник stop-internet. Потребителите се съпоставят по имейл чрез users.csv (username,email) и трябва вече да съществуват в Matrix. Командата може да се изпълнява многократно без дублиране. Процедурата стъпка по стъпка, включително експорт само за четене от базата данни SQLite на панела: Преминаване от стария панел.

Наблюдение

• GET /healthz (жизненост) и GET /readyz (готовност: базата данни отговаря; показва също дали копието на данните от Hub е актуално, stale след 5 минути, без да се проваля) на слушателя на API. Публично: https://hub.entrosity.com/matrix/api/v1/healthz.
• Метрики за Prometheus на MATRIX_METRICS_ADDR (:9095; задачата на Prometheus matrix в deploy/monitoring/prometheus.yml), сред тях matrix_ws_connections, matrix_connectors_online, matrix_firewalls_online (включени защитни стени, отчетени като онлайн), matrix_jobs_total{type,status}, matrix_job_dispatch_seconds, matrix_http_request_duration_seconds, matrix_platform_syncs_total, matrix_platform_sync_age_seconds, matrix_sse_subscribers, matrix_retention_rows_deleted_total, matrix_river_queue_depth и matrix_db_pool_connections.
• Журналите са в JSON при prod. Отказано упълномощаване в момента на запис се записва на ниво info (connector write refused, със задачата и причината); то е и стъпка на промяната в историята.
• Следете График → Неуспешни включвания в тенантите: неуспешно включване оставя зала изключена.

Локална разработка

Средата за разработка на entrosity-infra пуска Matrix до Hub (Среда за разработка):

1. deploy/.env.example има блок за Matrix (MATRIX_* на :8085, метрики на :9095, тайни за разработка, MATRIX_PUBLIC_URL=http://localhost:5175/matrix), а PLATFORM_PRODUCT_TOKENS на Hub съдържа токена на matrix.
2. Създайте базата данни веднъж: docker compose -f deploy/docker-compose.yml exec postgres createdb -U rmm matrix.
3. В entrosity-matrix.backend (с локален go.work, който използва ../entrosity-shared-go, докато споделеният етикет не съществува): make migrate, след това make dev (API на :8085).
4. В entrosity-matrix.frontend: неговият сървър за разработка на :5178.
5. Отворете http://localhost:5175/matrix/. Сървърът за разработка на Hub препраща /matrix/api към :8085 (с премахната представка) и /matrix към :5178.
6. За зали пуснете конектор със симулатора: matrix-connector enroll --server http://localhost:5175/matrix --token <token>, след това make dev в entrosity-matrix-connector (Изпробване на Matrix със симулатора).