Конектор на Sphere

sphere-connector.exe работи като Windows услугата SphereConnector на компютър в мрежата на обекта. Изходен код: entrosity-sphere-connector (cmd/sphere-connector, пакети app, nvrs, media, driver (dahua, sim), spool, state), който споделя entrosity-shared-go/agentkit (транспорт, изпълнител на задачи, хранилище за тайни с DPAPI, журнали, обвивка за услуга) с другите конектори на Entrosity. Как се инсталира: Конектори.

Инсталиране

msiexec /i sphere-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=https://hub.entrosity.com/sphere

Свойство	Значение
`ENROLLMENT_TOKEN`	Токен за регистриране на конектор на Sphere (Connectors в Sphere).
`SERVER_URL`	Адресът на Sphere, включително `/sphere`.

Инсталира се в %ProgramFiles%\Entrosity Sphere Connector\ (64-битово, за машината) и регистрира услугата SphereConnector (показвано име Entrosity Sphere Connector, LocalSystem, автоматично стартиране, run) и източник на събития със същото име в журнала Application.
С двете свойства sphere-connector enroll се изпълнява като SYSTEM, преди услугата да стартира; неуспешно регистриране връща инсталацията назад. На вече регистриран компютър не прави нищо и е успешно. Без свойствата услугата стартира и чака регистриране.
След стартиране услугата се настройва да се рестартира 30 секунди след всеки от първите си три неуспеха, като броячът се нулира след един ден (sc.exe failure, доколкото е възможно).
Обновяванията запазват папката с данни, така че конекторът остава регистриран. MSI се инсталира върху всяка инсталирана версия, включително по-нова (AllowDowngrades: наблюдението при самообновяване инсталира отново предишната версия). Конекторите, компилирани с ключа за изданията, се обновяват сами (Самообновяване); всеки конектор може да се обнови, като се изпълни новият MSI.
Деинсталирането премахва услугата, connector.dat, state.json, nvrs.json и опашката с аларми (spool\: още некачените аларми се губят); журналите се запазват.
Подробен журнал на инсталацията (/l*v) съдържа токена: изтрийте го след това.
Изданията (тагове vX.Y.Z) публикуват sphere-connector.msi, неговия sphere-connector.msi.sha256 и EXE файла в изданието на хранилището в GitHub; всяко качване в main ги заменя в плъзгащото се pre-release издание dev (версия 0.0.<build>-dev.<commit>). И двете се качват и в Sphere за самообновяване (Издания на конектора), а администраторите на тенанта изтеглят най-новото от Изтегляне на конектора (sphere-connector-<версия>.msi).

Команден ред

sphere-connector <command> [flags]

  run         run the connector (foreground, or as a service under the SCM)
              --server URL --token T   enroll first if not enrolled yet
              --dev                    also drive simulated NVRs (driver "simulator")
  enroll      enroll this machine: --server URL --token T [--force]
              (URL is the Sphere address, e.g. https://hub.example.com/sphere)
  status      show enrollment state, NVRs and alarms waiting for the server
  install     install the Windows service
  uninstall   remove the Windows service
  version     print the version

enroll на регистриран компютър извежда already enrolled (use --force to enroll again), освен ако не е зададен --force. Грешките назовават причината: токенът е невалиден (не е токен за конектор на Sphere), няма оставащи използвания, изтекъл е или е отменен.
run без идентификационни данни и без --server/--token чака, като проверява на всеки 10 секунди, докато enroll не ги запише.
status извежда enrolled: connector <id>, server <url>, NVRs: <n> и alarms waiting for the server: <n> (или not enrolled).
Без команда извежда начина на употреба, флаговете и променливите на средата.
Когато сървърът отмени конектора (премахнат в Sphere, спрян тенант), run спира.

Променливи на средата

Променлива	По подразбиране	Значение
`SPHERE_CONNECTOR_DATA_DIR`	`%ProgramData%\Entrosity Sphere Connector` (Windows), `~/.sphere-connector` на други системи	Папка с данни.
`SPHERE_LOG_LEVEL`	`info`	`debug`, `info`, `warn` или `error`.
`SPHERE_SIM_ADDR`	`127.0.0.1:9554`	RTSP адресът на симулатора с `--dev`.
`SPHERE_CONNECTOR_MAX_STREAMS`	`64`	Едновременно публикувани потоци (64 запълват мрежа 8×8); повече се отказват със `stream_limit`.

За услугата задайте променливите като среда на услугата (HKLM\SYSTEM\CurrentControlSet\Services\SphereConnector, стойност Environment, REG_MULTI_SZ) и я рестартирайте.

Файлове

%ProgramData%\Entrosity Sphere Connector\
  connector.dat       credentials {connector_id, connector_key, server_url, ws_url},
                      encrypted with machine-scope DPAPI
  nvrs.json           the NVRs it drives: each one's NVRRef, desired state and
                      latest credentials, sealed with machine-scope DPAPI
  state.json          jobs in progress (reported as failed after a restart)
  spool\              the alarm queue: segments <first seq>.jsonl (4 MiB each)
                      and "acked" (the highest acknowledged sequence number)
  logs\connector.log  rotating JSON log (10 MB, 5 files, 30 days; the service also
                      writes warnings and errors to the Application event log)
  update\             self-update: the new MSI (rmm-sphere-connector-<version>.msi),
                      previous.msi (rollback), update.ps1, install.log and
                      result.json (the outcome, read and removed at the next start)

Папката с данни се създава с права само за собственика. Извън Windows идентификационните данни се пазят некриптирани (само за разработка). Рестартирането продължава оттам, където конекторът е спрял: той влиза отново във всеки свързан видеорекордер от nvrs.json, а сървърът изпраща отново състоянията, които той е изгубил.

Мрежа

Само изходящи връзки:

Към	Порт	За
`hub.entrosity.com`	TCP 443	API и WebSocket на Sphere (HTTPS), идентификационни данни
`media.entrosity.com`	TCP 8322	Медийният сървър (RTSP през TLS): публикувано видео
Видеорекордерите в LAN	80 или HTTPS портът и 554	HTTP CGI API и RTSP на видеорекордера, както са зададени за всеки видеорекордер в Sphere

Сертификатът на медийния сървър се проверява спрямо системните коренни сертификати. Самоподписаните сертификати на видеорекордерите не се проверяват (digest удостоверяването никога не изпраща самата парола). RTSP към видеорекордера и към медийния сървър минава по TCP.

Драйвери

Драйвер Какво

dahua Видеорекордери Dahua и OEM видеорекордери със същия фърмуер: HTTP CGI API с digest удостоверяване и RTSP.

simulator Софтуерни видеорекордери, само с run --dev: 4 канала, канал 1 с PTZ, аларма за движение приблизително веднъж в минута, непрекъснат запис на всеки час за последните 24 часа, вграден RTSP сървър, подреден като този на видеорекордер Dahua. Вижте Изпробване на Sphere със симулатора.

Драйвер	Какво
`dahua`	Видеорекордери Dahua и OEM видеорекордери със същия фърмуер: HTTP CGI API с digest удостоверяване и RTSP.
`simulator`	Софтуерни видеорекордери, само с `run --dev`: 4 канала, канал 1 с PTZ, аларма за движение приблизително веднъж в минута, непрекъснат запис на всеки час за последните 24 часа, вграден RTSP сървър, подреден като този на видеорекордер Dahua. Вижте Изпробване на Sphere със симулатора.

Драйверите реализират един интерфейс (internal/driver): влизане, описание на видеорекордера, проверка, следене на събитията му, PTZ, търсене на записи, снимка, скъсяване на интервала между ключовите кадри на подпотоците и изграждане на RTSP адресите на потоците на живо и записите. Извън драйвера каналите навсякъде се броят от 1.

Крайни точки на Dahua

Крайна точка	Използва се за
`/cgi-bin/magicBox.cgi?action=getDeviceType`	Проверка на входа и модела (също и проверката на всеки 30 секунди)
`/cgi-bin/magicBox.cgi?action=getSerialNo`, `getSoftwareVersion`, `getProductDefinition&name=MaxRemoteInputChannels`	Сериен номер, фърмуер, брой канали
`/cgi-bin/devVideoInput.cgi?action=getCollect`	Брой канали (резервен вариант)
`/cgi-bin/configManager.cgi?action=getConfig&name=ChannelTitle`, `Encode`, `NTP`	Заглавия на камерите, кодеци на основния поток и подпотока, часовата зона на видеорекордера; `Encode` – също кадровата честота и интервалът между ключовите кадри на подпотоците за `sphere.nvr.tune_live`
`/cgi-bin/configManager.cgi?action=setConfig&Encode[i].ExtraFormat[0].Video.GOP=…`	`sphere.nvr.tune_live`: интервалът между ключовите кадри на подпотока на камера, в кадри (основните потоци никога не се променят)
`/cgi-bin/LogicDeviceManager.cgi?action=getCameraState`	Кои канали имат сигнал от камера
`/cgi-bin/ptz.cgi?action=getCurrentProtocolCaps`	Дали камерата е PTZ
`/cgi-bin/ptz.cgi?action=start\|stop&channel=N&code=…&arg1=…&arg2=…&arg3=0`	PTZ команди (скорост 1–8, по подразбиране 4; номер на предварителна позиция)
`/cgi-bin/eventManager.cgi?action=attach&codes=[All]&heartbeat=5`	Потокът от събития (аларми)
`/cgi-bin/mediaFileFind.cgi` (`factory.create`, `findFile`, `findNextFile`, `close`, `destroy`)	Търсене на записи (файлове `.dav`, в местното време на видеорекордера)
`/cgi-bin/snapshot.cgi?channel=N`	Снимки
RTSP `/cam/realmonitor?channel=N&subtype=0\|1`	Основен поток (0) и подпоток (1) на живо
RTSP `/cam/playback?channel=N&starttime=YYYY_MM_DD_HH_MM_SS&endtime=…`	Записи

CGI заявките изтичат след 10 секунди (потокът от събития няма таймаут). Потребителят в видеорекордера има нужда от правата за това, което Sphere прави с него: гледане на живо, възпроизвеждане, PTZ и събития.

Задачи и ленти

Лента	Задачи	Паралелност
`config`	`sphere.nvr.apply`, `sphere.nvr.remove`	1
`probe`	`sphere.nvr.test`, `sphere.recordings.find`, `sphere.nvr.tune_live`	2
`stream`	`sphere.stream.start`, `sphere.stream.stop`, `sphere.playback.start`, `sphere.playback.stop`	8
`ptz`	`sphere.ptz`	4 (никога зад стартиране на поток)
`snapshot`	`sphere.snapshot`	2
`update`	`update_agent`	1

Данни и резултати: Протокол на конектора на Sphere.

Интервали

Какво	Интервал
Сигнал за активност	1 минута
Проверка на всеки свързан видеорекордер	30 секунди
Повторно прочитане на описанието на видеорекордера	5 минути
Изчакване при повторно свързване с видеорекордер	от 1 до 30 секунди
Отчет за състоянието	30 секунди и 200 ms след всяка промяна
Качване на опашката с аларми	Веднага щом пристигнат аларми, иначе на всеки 5 секунди; изчакване до 1 минута при грешки
Повторно изпращане по HTTP на непотвърдена порция аларми	15 секунди
Стартиране на поток	8 секунди, за да започне видеорекордерът да предава и медийният сървър да приеме
Заседнал поток	10 секунди без видео от видеорекордера свързват потока отново; изчакване от 1 до 30 секунди
Качване на снимка	30 секунди
Повторно свързване със Sphere	Експоненциално изчакване със случайно отклонение, както при агентите на Axis (Протокол)

Конекторът обявява възможността video в hello, а update – когато е компилиран с публичния ключ за изданията.

Самообновяване

Sphere предлага по-нова версия на конектора като задача update_agent (component: sphere-connector, Протокол на конектора на Sphere); как изданията стигат дотам: Работа с Entrosity Sphere.

Задачата носи изданието (target) и, когато Sphere го има, MSI на текущата версия (rollback), всяко с подпис Ed25519 върху компонента, версията, SHA-256 и размера му. Конекторът проверява подписите с публичния ключ, вграден в него (RELEASE_PUBLIC_KEY при компилиране, -X github.com/entrosity/entrosity-shared-go/agentkit/update.PublicKey=), преди да изтегли каквото и да е: компилация без ключа отговаря с update_unsigned, грешен подпис – със signature_invalid.
Изтегля двата MSI от връзките в задачата (валидни 2 часа) в <data dir>\update\, проверява SHA-256 и размера им (download_failed, hash_mismatch) и регистрира еднократна планирана задача като SYSTEM, SphereConnectorUpdate, която стартира минута по-късно (със собствено име, така че конектор на Axis или Edge на същия компютър запазва своята). Задачата завършва успешно с UpdateResult {scheduled, from_version, to_version, rollback}.
Планираната задача изпълнява msiexec /i <нов MSI> /qn /norestart. След това наблюдението ѝ чака (до пет минути) услугата SphereConnector да работи и да продължава да работи минута по-късно; ако не е така, инсталира отново предишния MSI (MSI позволява връщане към по-стара версия) и стартира услугата. Накрая планираната задача се премахва.
Резултатът (installed, rolled_back или failed, двете версии и подробностите) се записва в update\result.json и в журнала при следващото стартиране (connector update finished); новата версия се отчита в hello и се вижда в Конектори.

Грешки на задачата: update_unsigned, signature_invalid, download_failed, hash_mismatch, exec_failed (папката за обновяване или планираната задача не можа да бъде създадена), invalid_payload. Задача за вече работещата версия завършва успешно веднага.

Конекторите, компилирани без RELEASE_PUBLIC_KEY, не обявяват update и никога не получават обновявания: инсталирайте новата версия ръчно веднъж (Конектори → Обновявания).

Разработка

Хранилището има нужда от entrosity-shared-go, изтеглено до него, с go.work (игнориран от git), който използва и двете, докато споделеният модул не получи таг с proto/sphere.

make build-local
dist/sphere-connector enroll --server http://localhost:5175/sphere --token <token>
make dev        # sphere-connector run --dev, data in ~/.sphere-connector
make lint vet test

make vet проверява и за GOOS=windows; make build компилира dist/sphere-connector.exe (make build RELEASE_PUBLIC_KEY=<base64> вгражда ключа за изданията; без него компилацията не се обновява сама); make msi (Windows, PowerShell 7 и .NET SDK) изгражда MSI с WiX v4. Тестовете пускат целия конектор срещу фалшив бекенд, симулатора и фалшив медиен сървър, а препредаването – срещу чист RTSP и RTSP през прокси, което терминира TLS, както в продукция.

Инсталиране​

Команден ред​

Променливи на средата​

Файлове​

Мрежа​

Драйвери​

Крайни точки на Dahua​

Задачи и ленти​

Интервали​

Самообновяване​

Разработка​