API: Администрирование

Только portal_admin. Базовый путь: /api/v1/admin.

GET /admin/dashboard

Статистика заданий, служб, журнал аудита, инфраструктура и текущая нагрузка.

В блоке maintenance (вкладка Обзор → Обслуживание, только статус; действия — Службы):

Поле	Содержание
`searchIndex`	Число записей, время обновления, расписание `search-crawler`, `health`
`recycleBin`	Число записей корзины, расписание `recycle-bin`
`backup`	Вкл/выкл, runner online, число успешных копий, дата/размер последней, расписание `portal-backup`
`adSync`	Вкл/выкл, LDAP настроен (`available`), расписание и последний job `ad-sync`

POST /admin/search/clear

Полностью очищает portal_search_index без переобхода. Только portal_admin. В UI: Службы → Поисковый индекс (иконка очистки).

curl -X POST "http://localhost/api/v1/admin/search/clear" \
  -H "Authorization: Bearer $TOKEN"

Ответ: { "success": true, "data": { "total": 0 } }.

Полный обход после очистки (или для сверки): POST /api/v1/services/search-crawler/run или ▶ у службы в админке. Повседневные изменения контента индексируются сразу при сохранении — см. Поиск.

Блок load (окно HTTP ≈ 60 с, обновляется на вкладке «Обзор» каждые 5 с):

Поле	Описание
`level`	`ok` / `warn` / `high`
`http.rps` / `http.rpm`	Запросов в секунду / минуту
`http.error_rate`	Доля ответов 5xx
`http.avg_latency_ms` / `http.max_latency_ms`	Средняя и пиковая latency
`worker.pending` / `worker.running`	Очередь и in-flight worker
`worker.completed_1m`	Завершённых заданий за последнюю минуту
`process.memory_mb`	Working set API-процесса
`postgres.active_connections`	Активные подключения к БД

LDAP / Active Directory

Подключение к каталогу и синхронизация настраиваются в админке. По умолчанию LDAP не настроен.

Порядок настройки (UI)

Службы → Синхронизация AD → ⚙ Настройки (/services/ad-sync) — два аккордеона:
- Подключение — URL, Base DN, Bind DN, пароль, фильтры входа/поиска, атрибут логина;
- Настройка синхронизации — фильтры sync, поля профиля (каталог + доп. атрибуты), флаги групп и деактивации пользователей.
Проверить статус подключения (badge «Подключён»)
На вкладке Службы — включить ad-sync, ⋮ → Расписание и/или Запустить (без confirm; флаги берутся из сохранённых настроек)
Результат — вкладка Задания; карточка пользователя — /users/{id}

GET /admin/settings/ldap-status

Статус подключения: configured, connected, url, baseDn, error.

GET /admin/settings/ldap

Параметры подключения (хранятся в portal_services.config службы ad-sync):

Поле	Описание
`url`	URL сервера (`ldap://` или `ldaps://`)
`baseDn`	Базовый DN поиска
`bindDn`	DN сервисной учётной записи
`hasPassword`	Задан ли пароль (сам пароль не возвращается)
`userFilter`	Фильтр входа, плейсхолдер `{{username}}`
`searchFilter`	Фильтр поиска в каталоге, плейсхолдер `{{query}}`
`loginAttr`	Атрибут логина (`sAMAccountName`, `uid`, …)
`searchLimit`	Лимит результатов поиска
`connectTimeoutMs`	Таймаут подключения (мс)
`configured`	Все обязательные поля заданы
`defaults`	Значения по умолчанию для пустых полей

PUT /admin/settings/ldap

{
  "url": "ldap://dc.company.local:389",
  "baseDn": "dc=company,dc=local",
  "bindDn": "cn=portal-svc,dc=company,dc=local",
  "bindPassword": "secret",
  "userFilter": "(sAMAccountName={{username}})",
  "searchFilter": "(|(sAMAccountName=*{{query}}*)(displayName=*{{query}}*)(mail=*{{query}}*))",
  "loginAttr": "sAMAccountName",
  "searchLimit": 20
}

Пароль: новое значение, или опустите поле / отправьте ********, чтобы оставить текущий.

Переменные LDAP_* в portal.env больше не используются. При первом запуске после обновления значения из env автоматически переносятся в БД; затем удалите блок LDAP_* из env и перезапустите backend.

GET /admin/settings/ldap-sync

Настройки службы ad-sync (синхронизация пользователей и групп):

Пользователи:

Поле	Описание
`syncFilter`	LDAP-фильтр пользователей (пусто → значение по умолчанию)
`syncLimit`	Лимит за один проход
`effectiveSyncFilter`, `effectiveSyncLimit`	Фактически применяемые значения

Группы AD:

Поле	Описание
`syncGroups`	Импортировать группы AD как `domain_linked`
`groupSyncFilter`, `groupSyncLimit`	Фильтр и лимит групп
`removeMissingGroupMembers`	Убирать участников, отсутствующих в AD (по умолчанию `true`)
`removeMissingGroups`	Удалять группы Portal, пропавшие из AD (по умолчанию `false`)

Прочее:

Поле	Описание
`cronDeactivateMissing`	Деактивировать доменных пользователей вне выборки sync (и по cron, и при ручном запуске, если в теле run не передан override). UI: «Деактивировать пользователей, отсутствующих в AD». Не связано с флагами состава групп

Поля профиля пользователя:

Поле	Описание
`catalog`	Встроенный каталог атрибутов (`key`, `ldapAttr`, `label`, `isCoreColumn`, `isBinary`)
`syncUserAttributes`	Включённые ключи встроенного каталога. Если ключ не задан в конфиге — все из каталога (включая `thumbnailPhoto`)
`personCardVisibleFields`	Ключи полей meta-блока карточки сотрудника (порядок сохраняется). Если ключ не задан — `department`, `title`, `telephoneNumber`, `mobile`, `email`
`defaultPersonCardVisibleFields`	Справочно: набор по умолчанию
`customUserAttributes`	Доп. маппинги: `{ "key", "ldapAttr", "label" }[]`

Логин и objectSid / external_id синхронизируются всегда. email и displayName пишутся в колонки users; строковые атрибуты — в users.directory_attrs. Бинарный thumbnailPhoto (по умолчанию включён) пишется в объектное хранилище (S3/MinIO, ключ avatars/{userId}), в БД — avatar_storage_key / hash / content-type. DN руководителя (manager) резолвится в users.manager_user_id после sync. В карточке сотрудника (GET /users/{id}/profile) meta-поля приходят в card_fields согласно personCardVisibleFields (без displayName / manager / thumbnailPhoto — они в шапке, оргструктуре и аватаре).

PUT /admin/settings/ldap-sync

{
  "syncFilter": "(&(objectCategory=person)(objectClass=user))",
  "syncLimit": 500,
  "syncGroups": true,
  "groupSyncFilter": "(&(objectCategory=group)(objectClass=group))",
  "groupSyncLimit": 200,
  "removeMissingGroupMembers": true,
  "removeMissingGroups": false,
  "cronDeactivateMissing": true,
  "syncUserAttributes": ["email", "displayName", "department", "title"],
  "personCardVisibleFields": ["department", "title", "telephoneNumber", "mobile", "email"],
  "customUserAttributes": [
    { "key": "employeeId", "ldapAttr": "employeeID", "label": "Табельный номер" }
  ]
}

Пустой syncFilter сбрасывает переопределение и возвращает значение по умолчанию.

Служба ad-sync

Метод	Путь	Описание
GET	`/services`	Список служб (`available: false` для ad-sync без LDAP)
PATCH	`/services/ad-sync`	`{ "isEnabled": true, "cronEnabled": true, "cronExpression": "0 3 * * *" }`
POST	`/services/ad-sync/run`	Ручной запуск. Тело можно не передавать (`{}`): деактивация берётся из `cronDeactivateMissing`. Опциональный override: `{ "deactivateMissing": true\|false }`

В админке расписание — модальное окно (⋮ → Расписание): как часто (каждый час / каждые N часов / ежедневно / еженедельно / каждые N минут) и время или день → сохраняется как cronExpression.

Тип задания: adSync.run. Результат во вкладке Задания (users, groups). UI не показывает confirm при запуске.

См. также: Службы → ad-sync, Job-модули, Каталог AD.

Резервное копирование (API)

UI: Службы → Резервное копирование → Настройки (/services/portal-backup). Руководство: Бэкап.

Метод	Путь	Описание
GET	`/admin/settings/backup`	Путь, retention, `lastValidatedOk`, статус runner
PUT	`/admin/settings/backup`	Сохранить каталог и retention
POST	`/admin/settings/backup/validate`	Поставить `validate` в очередь runner
GET	`/admin/backups`	Журнал (`page`, `limit`) — `validate` / `backup` / `restore`
POST	`/admin/backups`	Поставить создание копии (`backup`)
GET	`/admin/backups/restorable`	Успешные копии с файлом на диске (для UI восстановления)
POST	`/admin/backups/{id}/restore`	Восстановление из выбранной копии
GET	`/admin/backups/{id}`	Статус одной записи
DELETE	`/admin/backups/{id}`	Удалить запись журнала (и файл, если есть)

Расписание службы — PATCH /services/portal-backup (cronEnabled, cronExpression). Ручной POST /services/portal-backup/run не используется.

SMTP / почта

Настройки хранятся в конфиге службы notifications. Чтобы портал реально отправлял письма (API, Event Receivers, «Запустить» в Службах), службу нужно включить. Тест SMTP ниже работает и при выключенной службе. См. notifications, API: Почта.

GET /admin/settings/smtp

Текущие настройки (пароль не возвращается, только hasPassword).

PUT /admin/settings/smtp

{
  "host": "smtp.company.local",
  "port": 587,
  "secure": false,
  "user": "portal@company.local",
  "password": "secret",
  "fromEmail": "portal@company.local",
  "fromName": "Portal",
  "replyTo": "",
  "allowAuthenticatedSend": false
}

GET /admin/settings/smtp-status

Проверка подключения к SMTP.

POST /admin/settings/smtp/test

{ "to": "admin@company.local" }

Подробнее: mail.md.

Версия релиза и проверка обновлений

Версия установленного релиза берётся из файла RELEASE в дистрибутиве (см. Обновление Portal). В админке: Настройки → Продукт и лицензия.

GET /admin/settings/release

Текущие настройки версии релиза:

Поле	Описание
`installedReleaseVersion`	Версия из `RELEASE` или БД
`installedReleaseSource`	`file` или `database`
`releaseFilePath`	Путь к найденному файлу `RELEASE`
`canEditInstalledVersion`	`false`, если версия задана файлом
`lastKnownLatestVersion`	Последняя версия с korport.ru
`lastUpdateCheckAt`	Время последней проверки
`updateCheckUrl`	URL API вендора (по умолчанию korport.ru)
`updatesPageUrl`	Страница changelog

PUT /admin/settings/release

Ручное изменение версии — только если файл RELEASE не найден (режим разработки):

{ "installedReleaseVersion": "1.0.0" }

GET /admin/settings/office

Статус Portal Office: включён ли редактор, доступность по PORTAL_OFFICE_INTERNAL_URL, установленная версия (probe portal-office-version.json или env PORTAL_OFFICE_VERSION).

POST /admin/settings/office/check

Сверка установленной версии Office с GET {OfficeUpdateCheckUrl} на korport (/api/portal/office/version). Обновление пакета — вручную через portal-office (не update-runner).

POST /admin/settings/release/check

Проверка обновлений на korport.ru. Ответ:

Поле	Описание
`installedReleaseVersion`	Установленная версия
`latestVersion`	Актуальный релиз на korport.ru
`updateAvailable`	`true`, если есть более новая версия
`upToDate`	`true`, если версии совпадают
`whatsNew`, `fixes`	Списки изменений
`updatesUrl`	Ссылка на страницу обновлений
`licenseOk`	Действует ли локальная лицензия
`canUpgradeOnline`	Можно ли запускать онлайн-обновление
`upgradeBlockedReason`	Причина, если онлайн-обновление недоступно
`channel`, `platform`	Канал/платформа установки

Публичный API вендора (без авторизации): GET https://korport.ru/api/portal/version.

GET /admin/settings/release/upgrade

Статус update-runner и последнего задания обновления:

Поле	Описание
`runnerOnline`	Есть ли heartbeat от `portal-cli update-runner`
`licenseOk`	Действует ли лицензия
`channel`, `platform`	Канал/платформа установки
`entitleUrl`	URL entitle API на korport.ru
`latestJob`	Последнее задание или `null`

POST /admin/settings/release/upgrade

Ставит задание в очередь. Требует: новая версия на korport.ru, действующая лицензия, Online update-runner. Ответ — объект задания.

GET /admin/settings/release/upgrade/{id}

Статус конкретного задания.

Поле	Описание
`id`	UUID задания
`status`	`queued` \| `running` \| `succeeded` \| `failed`
`phase`	`queued` → `entitle` → `download` → `apply` → `restart` → `done` (или `failed`)
`fromVersion`, `toVersion`	Исходная и целевая версии релиза
`channel`, `platform`	Канал/платформа установки
`message`	Текущий статус или текст ошибки
`createdAt`, `startedAt`, `completedAt`	Метки времени

Сценарий для администратора: Обновление из админки.

Публичный entitle API вендора: POST https://korport.ru/api/portal/updates/entitle (тело: licenseKey, installBinding, channel, platform, currentVersion) → одноразовый downloadUrl.

Продукт и лицензия

В админке: Настройки → Продукт и лицензия — версия сборки, статус лицензии, привязка инсталляции, entitlement платных модулей (modules в ключе), активация LICENSE.key без терминала.

GET /admin/version

Версия продукта и полный статус лицензии (product, license).

GET /admin/license

Только статус лицензии (LicenseStatusDto).

Поле	Описание
`mode`	`trial`, `licensed`, `expired`, `invalid`
`valid`	Разрешена ли запись в API
`expiresAt`, `daysRemaining`	Срок действия ключа
`installId`, `installBinding`	Идентификатор инсталляции и SHA256-привязка для вендора
`channel`, `platform`	Канал и платформа в ключе
`installedChannel`, `installedPlatform`	Фактическая установка (`install.mode`, `install.platform`)
`modules`	Entitlement платных модулей (`korport.helpdesk.`, `` и т.д.); при `licensed` без поля в ключе — пустой массив

POST /admin/license/activate

Активация лицензии из админки (альтернатива portal-cli license activate).

{ "licenseKey": "base64url(payload).base64url(signature)" }

Можно передать содержимое файла LICENSE.key (первая непустая строка без #).

Ответ (LicenseActivationResultDto):

Поле	Описание
`license`	Обновлённый `LicenseStatusDto` (включая `modules`)
`storagePath`	Путь, куда сохранён ключ (по умолчанию `{PORTAL_DATA_DIR}/license.key`)
`message`	Подсказка: API и установка модулей доступны сразу; Worker — после перезапуска Portal

Проверки: подпись Ed25519, срок, привязка install, канал/платформа. Ошибки валидации — 400 VALIDATION_ERROR.

После активации entitlement из поля modules сразу учитываются в GET /modules/catalog/status, POST /modules/install-template и установке с korport.ru (см. modules.md).

Пользователи

GET /admin/users?q=&page=1&limit=50&isPortalAdmin=

Список пользователей (local + domain).

Параметр	Описание
`q`	Поиск по логину, имени, email
`page`, `limit`	Пагинация
`isPortalAdmin`	Опциональный фильтр: `true` — только администраторы портала, `false` — только без роли

В ответе у пользователя дополнительно: is_seed_admin — системная bootstrap-учётка (SEED_ADMIN_LOGIN, по умолчанию admin). Список не включает directory_attrs.

Карточка в UI: отдельная страница /users/{id} (не вкладка списка).

GET /admin/users/{id}

Полная карточка пользователя:

Поле	Описание
поля списка	`login`, `display_name`, `email`, флаги, даты
`external_id`	SID / внешний id (для domain)
`updated_at`	Последнее обновление записи
`directory_attrs`	Объект доп. атрибутов AD (`key` → строка)
`attribute_schema`	Эффективная схема полей sync (`key`, `ldapAttr`, `label`, `isCoreColumn`, `isBuiltin`) для подписей в UI

POST /admin/users

Создать локального пользователя:

{
  "login": "user1",
  "password": "secret123",
  "displayName": "Иван Иванов",
  "email": "ivan@company.local",
  "isPortalAdmin": false
}

PATCH /admin/users/{id}

{
  "displayName": "Новое имя",
  "email": "new@mail.local",
  "isActive": true,
  "isPortalAdmin": false
}

Снятие isPortalAdmin отклоняется (400 VALIDATION_ERROR), если:

роль снимают с себя;
учётка — bootstrap (SEED_ADMIN_LOGIN);
это последний администратор портала.

POST /admin/users/{id}/reset-password

Только для auth_source: local:

{ "password": "new_secret" }

UI

Узел Админка портала → вкладки Пользователи, Группы, Настройки, Службы, Задания. Руководства: Администрирование, Службы.

Группы доступа: вкладка Группы в админке (список); страницы /groups, /groups/new, /groups/{uuid}, /groups/{uuid}/edit. Подробнее: Группы доступа.

Узлы: вкладка Узлы в админке (список); создание и редактирование — /nodes/new (опционально ?parentId=), /nodes/{uuid}/edit.

LDAP / AD: Службы → Синхронизация AD → Настройки (/services/ad-sync) — подключение, статус, параметры синхронизации и поля профиля. См. ad-sync.

Резервное копирование: Службы → Резервное копирование → Настройки (/services/portal-backup) — аккордеоны «Резервное копирование» и «Восстановление». Восстановление: POST /api/v1/admin/backups/{id}/restore (очередь backup-runner); список копий: GET /api/v1/admin/backups/restorable. Подробнее: Бэкап.

Версия релиза: Настройки → Продукт и лицензия — версия из RELEASE, кнопки Проверить обновления и Обновить (при Online update-runner).

Portal Office: в том же разделе — установленная версия редактора, кнопка Проверить версию Office, ссылка на скачивание пакета (Native обновляет Office отдельно).

Лицензия: Настройки → Продукт и лицензия — статус, привязка, entitlement модулей, загрузка LICENSE.key или вставка ключа, кнопка Активировать лицензию.

Синхронизация AD: Службы → Синхронизация AD — включить, ⋮ → Расписание, Запустить (без confirm); настройки — /services/ad-sync. Результат во вкладке Задания.

Журнал заданий: вкладка Задания — срок хранения (по умолчанию 30 дней). Служба jobs-cleanup по расписанию удаляет завершённые записи старше срока (GET/PUT /api/v1/jobs/settings/retention).

Служба ad-sync недоступна для включения, пока LDAP не настроен и не проходит проверку подключения. Действия в таблице Служб — меню ⋮; у названия — справка ?.