Работа с Entrosity Edge

Entrosity Edge работи до Entrosity Hub и Axis на същия хост:

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

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

edge-server serve                     run the HTTP API and the background jobs (default)
edge-server migrate up|down [N]|version|force N
                                      database migrations (up also enables the edge_app
                                      login when EDGE_APP_DATABASE_PASSWORD is set)
edge-server healthcheck               exit 0 when /readyz answers (container health check)
edge-server release-keygen            print a new connector release signing key pair:
                                      EDGE_RELEASE_SIGNING_KEY (server) and
                                      RELEASE_PUBLIC_KEY (connector builds)
edge-server version                   print the version

serve отказва да стартира със схема на базата данни, за която не е изграден: първо изпълнете migrate up.

В Hub продуктът edge (роли tenant_admin, operator, viewer) се регистрира от миграция 0003 на Hub като изключен: изключените продукти са скрити от списъка с продукти и не могат да бъдат дадени на организации. Той се включва, след като Edge бъде разгърнат; тогава администраторите на платформата го включват за всяка организация (Администриране на платформата). Hub трябва да знае токена на Edge: PLATFORM_PRODUCT_TOKENS съдържа edge:<token> със същата стойност като EDGE_PLATFORM_TOKEN.

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

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

Сървър

Променлива	По подразбиране	Значение
EDGE_ENV	dev	dev, test или prod. prod отказва примерните тайни за разработка.
EDGE_PUBLIC_URL	http://localhost:8082	Публичният адрес на Edge, включително представката /edge, която проксито премахва (https://hub.entrosity.com/edge). Конекторите получават <EDGE_PUBLIC_URL>/api/connector/v1/ws, а командите за инсталиране, показвани с нови токени за регистриране, го използват като SERVER_URL.
EDGE_HTTP_ADDR	:8082	Слушател на API.
EDGE_METRICS_ADDR	:9092	Вътрешен слушател за Prometheus /metrics. Никога не го излагайте публично; празно го изключва.
EDGE_LOG_LEVEL	info	debug, info, warn или error.
EDGE_CORS_ORIGINS	http://localhost:5176	Разрешени произходи (origins) на браузъри, разделени със запетая, без заместващи символи и пътища (продукция: https://hub.entrosity.com).
EDGE_TRUSTED_PROXIES	няма	CIDR или IP адреси, на които е разрешено да задават X-Forwarded-For (мрежата на проксито).
EDGE_API_RATE_PER_SECOND, EDGE_API_RATE_BURST	20, 60	Ограничение на заявките към уеб API за IP адрес на клиент (офис зад един NAT адрес го споделя).
EDGE_ENROLL_RATE_PER_MINUTE	60	Регистрирания на конектори за IP адрес на клиент.
EDGE_CONNECTOR_DOWNLOAD_URL	няма	Откъде може да се изтегли MSI на конектора; показва се като Изтегляне на инсталатора на конектора с новите токени за регистриране.

База данни

Променлива	По подразбиране	Значение
EDGE_DATABASE_URL	няма (задължителна)	URL за връзка. Продукцията се свързва като edge_app.
EDGE_DATABASE_ROLE	edge_app	Ролята, към която пулът превключва след свързване (SET ROLE), така че защитата на ниво ред важи дори при връзка като собственик. Празно, когато входът вече е ролята на приложението и не може да превключва.
EDGE_DATABASE_MAX_CONNS	20	Размер на пула.
EDGE_DATABASE_STATEMENT_TIMEOUT	30s	Горна граница за всяка заявка.
EDGE_APP_DATABASE_PASSWORD	няма	Чете се от migrate up: разрешава входа edge_app с тази парола.

Тайни

Променлива	Значение
EDGE_JWT_SECRET	Задължителна. Подписва едноминутните токени за потока с обновления на живо (POST /auth/sse-token). Поне 32 байта, сурови или base64 (openssl rand -base64 32). Токените за достъп на потребителите идват от Hub.
EDGE_JWT_SECRET_OLD	Предишната тайна по време на смяна (все още се приема).
EDGE_MASTER_KEY	По избор. Base64 на точно 32 байта (openssl rand -base64 32). Шифрова ПИН кодовете на контролерите и е ключът на връзките за изтегляне на конектора. Пазете го: без него запазените ПИН кодове не могат да бъдат прочетени. Без него сървърът стартира, но ПИН кодове не могат да се задават (master_key_missing), а самообновяването на конекторите е изключено. Невалидна стойност спира сървъра.
EDGE_MASTER_KEY_OLD	Предишни главни ключове по време на смяна, разделени със запетая; те само дешифрират (и все още проверяват връзките за изтегляне). Само заедно с EDGE_MASTER_KEY.
EDGE_RELEASE_SIGNING_KEY	По избор. Частен ключ Ed25519 в base64 (64 байта) или 32-байтово семе, което подписва изданията на конектора, от edge-server release-keygen. Нужен е, заедно с главния ключ, за публикуване и разпространение на издания на конектора.
EDGE_RELEASE_TOKEN	По избор. Bearer токенът на CI за публикуване на издания на конектора, поне 32 знака. Без него крайната точка за публикуване отговаря с 404.

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

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

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

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

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

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

Конекторите на Edge се обновяват сами от издания, съхранени в Edge (Конектори → Обновления).

Настройване

1. Създайте веднъж двойката ключове за подписване:

   edge-server release-keygen
   # production:
   docker compose run --rm --no-deps edge release-keygen

   Командата отпечатва EDGE_RELEASE_SIGNING_KEY (пазете го в тайна) и съответния RELEASE_PUBLIC_KEY.

2. На сървъра задайте EDGE_MASTER_KEY, EDGE_RELEASE_SIGNING_KEY и EDGE_RELEASE_TOKEN (32+ знака) (в продукция в deploy/.env) и рестартирайте Edge.

3. В хранилището entrosity-edge-connector задайте тайната RELEASE_PUBLIC_KEY (компилира се в конектора: компилации без нея отказват обновявания), тайната EDGE_RELEASE_TOKEN (същата стойност като на сървъра) и променливата EDGE_RELEASE_API – адресът на Edge (https://hub.entrosity.com/edge). Без EDGE_RELEASE_API компилациите не се публикуват в Edge (CI workflows).

4. Обновете ръчно веднъж конекторите, инсталирани преди самообновяването (Конектори → Обновления).

Публикуване

CI публикува всяка компилация на конектора:

Компилация	Версия	Канал
Издание с етикет vX.Y.Z	X.Y.Z	stable
Предварително издание vX.Y.Z-suffix	X.Y.Z-suffix	beta
Версия в разработка (всяко качване в main)	0.0.<build>-dev.<commit>	beta

curl -X POST -H "Authorization: Bearer $EDGE_RELEASE_TOKEN" \
  -H "Content-Type: application/octet-stream" --data-binary @edge-connector.msi \
  "https://hub.entrosity.com/edge/api/v1/admin/connector-releases?version=1.4.0&channel=stable&notes=release%20v1.4.0"

Тялото е суровият MSI (до 64 MiB). Edge го съхранява в базата си данни и го подписва с EDGE_RELEASE_SIGNING_KEY.

Отговор	Значение
201	Ново издание.
200	Тази версия вече е издадена със същия MSI (повторен опит).
409 release_exists	Тази версия вече е издадена с различен MSI.
409 signing_key_missing, master_key_missing	EDGE_RELEASE_SIGNING_KEY или EDGE_MASTER_KEY не е зададен.
401	Грешен токен.
404	EDGE_RELEASE_TOKEN не е зададен на сървъра.

Edge пази най-новите 10 издания от всеки канал, както и всяка версия, с която още работи някой конектор (за връщането от защитния механизъм). Глобалните администратори ги виждат с GET /api/v1/admin/connector-releases, който връща и public_key, който компилациите на конектора трябва да вграждат.

Разпространение

Всеки конектор следва канал за обновления, по подразбиране Стабилни; администраторите на тенанта превключват конектор на Бета (версии в разработка) на страницата Конектори. Стабилните конектори получават най-новото стабилно издание, бета конекторите – най-новото от бета и стабилните издания.

Edge предлага по-нова версия, когато конекторът се свърже, и на всеки 5 минути (releases.rollout): задача update_agent с подписани връзки за изтегляне, валидни 24 часа (GET /api/connector/v1/releases/{id}/msi?exp=&sig=, без влизане: подписаната връзка е разрешението). Версия се предлага само на конектори, които обявяват edge_update (компилации със самообновяване), когато няма отворена задача за обновяване на конектора, и не отново в рамките на час. Задачата и инсталирането: Протокол на конектора на Edge, Конектор на Edge → Самообновяване.

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

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

Данни	Пазят се
Журнал на достъпа	EDGE_RETENTION_EVENT_DAYS, за всеки тенант. Събитията се съхраняват в месечни дялове (partitions); един месец се изтрива изцяло, след като е по-стар от срока, така че събитията се пазят между срока и срока плюс един месец.
Приключили задачи на конекторите	Пазене на историята на задачите на конекторите (дни) на тенанта, иначе EDGE_RETENTION_JOB_DAYS (никога по-малко от 7 дни).
Одитен журнал	Пазене на одитния журнал (дни) на тенанта, иначе EDGE_RETENTION_AUDIT_DAYS (никога по-малко от 30 дни).
Токени за регистриране	30 дни след като са изтекли или отменени.
Приключили сесии в Hub, използвани step-up токени	Час след приключването; след изтичането.

Сроковете на тенанта се задават в Настройки на тенанта (Настройки на тенанта, обекти и одитен журнал). edge_retention_rows_deleted_total{category} брои премахнатото.

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

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

Задача	Кога	Какво
controller.sync	След всяка промяна, за всеки контролер	Съставя конфигурацията на контролера и я изпраща като задача edge.config.apply, освен ако той вече я пази. Поредица от промени за един контролер се обединява.
controller.reconcile	На всеки 5 минути	Поставя отново в опашката контролерите, чиято желана версия не е приложена (конекторът е бил офлайн, изгубена задача, синхронизация в състояние Синхронизира се за повече от 20 минути).
cardholder.validity	Всяка минута	Синхронизира отново контролерите на картодържатели, чийто период на валидност е започнал или свършил.
holidays.horizon	Всеки час	Синхронизира отново контролерите, за които празник току-що е влязъл в 90-те дни, които носи конфигурацията (по часовата зона на всеки контролер).
releases.rollout	На всеки 5 минути	Предлага по-ново издание на конектора на онлайн конекторите, които се обновяват сами (Разпространение). Не прави нищо без EDGE_MASTER_KEY и EDGE_RELEASE_SIGNING_KEY.
realtime.sweep	На всеки 30 секунди	Отбелязва като офлайн конекторите, мълчали 3 минути; прекратява просрочените задачи на конекторите и изпраща отново непотвърдените (след 60 секунди).
events.partitions	Ежедневно	Създава месечните дялове за събития два месеца напред.
retention.cleanup	Ежедневно	Вижте Срок на съхранение.

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

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

Миграция	Добавя
0001_init	Копието на Edge на тенантите, потребителите и ролите от Hub (tenants, users, tenant_memberships, състояние на синхронизацията с Hub, приключили сесии, използвани step-up токени), sites, audit_log само за добавяне, enrollment_tokens, connectors, jobs и защита на ниво ред с ролята edge_app.
0002_access_control	controllers (с желана и приложена версия и състояние на синхронизацията), doors, readers, cardholders, cards, schedules, holidays, access_groups с вратите и членовете им, журнала events, разделен по месеци, с функциите за дяловете, и worker_watermarks.
0003_controller_pin	controllers.pin_enc: ПИН кодът на контролера, шифрован с EDGE_MASTER_KEY (NULL: няма ПИН).
0004_connector_releases	connector_releases (MSI файловете на конектора с канала, SHA-256, размера и подписа им; глобална, без защита на ниво ред) и update_channel, update_version и update_offered_at на конекторите.
0005_controller_enabled	controllers.enabled (по подразбиране true) и състоянието на синхронизация disabled, което контролерът има точно докато е деактивиран.

• Изолация на тенантите: всяка таблица на тенант има политика за защита на ниво ред; сървърът работи като edge_app (NOBYPASSRLS). Връзките между таблиците на тенантите са съставни ключове (tenant_id, id), така че препратка между тенанти е невъзможна.
• Само добавяне: edge_app не може да променя или изтрива events (сроковете за съхранение изтриват дялове) и audit_log (сроковете за съхранение изчистват чрез специална функция).
• Събития, чийто час е извън месечните дялове, попадат в events_default и се преместват, когато бъде създаден дялът за техния месец.

Наблюдение

• GET /healthz (жизненост) и GET /readyz (готовност: базата данни отговаря; показва и възрастта на копието на данните от Hub).
• Метрики за Prometheus на EDGE_METRICS_ADDR: edge_ws_connections (свързани конектори), edge_jobs_total{type,status}, edge_job_dispatch_seconds, edge_http_request_duration_seconds, edge_platform_syncs_total, edge_platform_sync_age_seconds, edge_sse_subscribers, edge_retention_rows_deleted_total.
• В prod журналите са в JSON.