Службы

Каталог встроенных фоновых служб портала (Админка → Службы): назначение, расписание, ручной запуск, настройки и поведение при выключении.

Для разработчиков расширений см. также Service Framework и Hot deploy.

Обзор

Платформа управляет фоновыми службами портала. Каждая служба — строка в portal_services: тумблер включения, опциональное расписание и конфиг. Задания (кроме резервного копирования) идут в очередь portal_jobs и выполняются процессом Portal.Worker.

Событие (API) → EventDispatch → Event Receivers → portal_jobs → Worker
CronScheduler → portal_jobs (или portal_backups) → Worker / backup-runner

Админка → Службы — таблица встроенных служб.

UI таблицы «Службы»

Элемент	Поведение
Меню ⋮	Действия строки: Вкл/Выкл, Запустить / Полный обход, Очистить индекс, ⚙ Настройки, Расписание
Расписание	Открывает модальное окно (не раскрытие строки). Сохранение → cronExpression + cronEnabled
Колонка расписания	Текст расписания показывается и при выключенном cron: … (выкл)
Последний	last_run_at из заданий/журнала или cron_last_run_at
? у названия	Справка о службе (popover) со ссылкой на этот каталог (/docs/admin/services#…)
Runner online	Нет в таблице Служб — только на /services/portal-backup и в Обзор → Обслуживание

Если служба выключена, Worker не выполняет задания с её service_key (статус failed: «Служба отключена или не найдена»). Cron тоже не ставит новые задания для выключенной службы.

Компоненты

Компонент	Назначение
portal_services	Реестр служб (ключ, title, is_enabled, cron, config)
portal_jobs	Очередь заданий большинства служб
portal_backups	Очередь validate / backup / restore (служба portal-backup)
event_receivers	Подписчики на события списков и др.
Worker	Опрос portal_jobs, cron, hot-load пакетов
backup-runner	Отдельный процесс/контейнер для бэкапов

API (только portal_admin)

Метод	Путь	Описание
GET	/admin/dashboard	Обзор: статистика, аудит, блок обслуживания
POST	/admin/search/clear	Очистить поисковый индекс без обхода
GET	/services	Список служб
PATCH	/services/{key}	{ "isEnabled", "cronEnabled", "cronExpression", … }
POST	/services/{key}/run	Ручной запуск (где поддерживается)
GET	/jobs	Очередь / журнал заданий
POST	/jobs/{id}/retry	Повторить задание
GET/PUT	/jobs/settings/retention	Срок хранения журнала (jobs-cleanup)
GET/POST/PATCH/DELETE	/event-receivers	Подписчики событий

Расписание служб

Планировщик — CronSchedulerService в Portal.Worker. В админке расписание задаётся в понятном виде; в API/БД хранится как cron (5 полей: мин час день месяц день_недели).

Поле	Описание
cron_enabled	Включить автозапуск
cron_expression	Выражение cron
cron_job_type	Тип задания (платформа; в UI не редактируется)
cron_last_run_at	Время последнего запуска по расписанию

Пример: 0 3 * * * — каждый день в 03:00. В UI: Службы → ⋮ → Расписание (модальное окно).

Переменная CRON_RELOAD_INTERVAL_MS (по умолчанию 60000) — как часто Worker перечитывает расписание из БД.

Ночные задания по умолчанию

После seed / миграций обслуживания (если расписание ещё не меняли):

Служба	Cron	Вкл. по умолчанию
portal-backup	0 2 * * *	расписание выкл (нужны путь и runner)
search-crawler	0 3 * * *	да
list-export (purge файлов)	0 3 * * *	да (в БД; в UI расписания нет)
recycle-bin	0 4 * * *	да
jobs-cleanup	0 5 * * *	да

Состояние индекса и корзины — Админка → Обзор → Обслуживание. Срок хранения журнала заданий — Админка → Задания.

Сводка встроенных служб

Порядок как в реестре платформы (BuiltinServices) и в таблице Службы.

#	Ключ	Название	Вкл. по умолчанию*	Расписание в UI	Ручной запуск в UI	Страница настроек
1	audit	Аудит	да	нет	нет	—
2	notifications	Уведомления	нет	нет	да (тест e-mail)	SMTP в Настройки
3	ad-sync	Синхронизация AD	нет	да	да	/services/ad-sync
4	search-crawler	Поисковый индекс	да + cron	да	да (полный обход)	—
5	recycle-bin	Корзина	да + cron	да	да	—
6	event-extensions	Event Receivers	да	нет	нет	вкладка Event Receivers
7	timer-extensions	Timer Jobs	да	нет**	нет	вкладка Timer Jobs
8	list-export	Экспорт списков	да	нет***	нет	—
9	portal-backup	Резервное копирование	да	да	нет****	/services/portal-backup
10	jobs-cleanup	Журнал заданий	да + cron	да	да	retention на вкладке Задания

* Фактический seed новой инсталляции; EnabledByDefault в коде и флаги после миграций могут отличаться для отдельных служб — ориентируйтесь на таблицу выше и разделы ниже.
** Расписание задаётся у экземпляров Timer Job, не у строки службы.
*** Cron purge в БД есть; пункта «Расписание» в меню ⋮ нет.
**** Копия/проверка/восстановление — со страницы настроек и API, не через «Запустить» у строки службы.

---

1. audit — Аудит {#audit}

Ключ: audit
Описание в UI: Журналирование событий портала.

Назначение

Пишет события в audit_logs (и показывает их на Обзоре админки). Основной путь — не cron и не кнопка «Запустить», а Event Receivers с типом задания audit.logEvent.

По умолчанию

• Служба включена.
• Расписания нет (и в UI кнопка «Расписание» недоступна).

Типы заданий

job_type	Когда
audit.logEvent	Подписчик Event Receiver сработал на событие

Event Receivers (seed)

При установке создаются подписчики (если ещё нет), например:

• listItem.created / updated / deleted → аудит элементов списка
• в seed также могут быть шаблоны для page.* / file.uploaded — фактически эмитятся платформой прежде всего события элементов списка (listItem.*)

Подписчики: Админка → Event Receivers (или API /event-receivers).

Админка

Действие	Есть?
Вкл/выкл	да
Расписание	нет
Запустить	нет (API POST /services/audit/run формально есть, без осмысленного payload почти бесполезен)
Отдельные настройки	нет

Если выключить

Новые и ожидающие jobs с service_key=audit не выполнятся — записи в журнал аудита через этот канал перестанут появляться. Сама таблица audit_logs и UI обзора остаются.

Связанные материалы

• Журнал на Админка → Обзор
• Event Receivers

---

2. notifications — Уведомления {#notifications}

Ключ: notifications
Описание в UI: Отправка почты через SMTP (задания и Event Receivers).

Назначение

Шлюз исходящей почты портала, а не «ночная» пакетная служба. Пока служба выключена, портал не отправляет письма через этот канал (API, Event Receivers, ручной тест из Служб).

По умолчанию

• Служба выключена.
• Расписания в UI нет (почта идёт по событиям и API).

Подготовка

1. Админка → Настройки → SMTP / Почта — host, порт, учётные данные, From, опционально allowAuthenticatedSend.
2. Админка → Службы → Уведомления — Включить.

Тест SMTP в настройках проверяет сервер без требования, чтобы служба была включена. Реальная отправка через портал — только при включённой службе.

Настройки SMTP хранятся в portal_services.config ключа notifications. Fallback: переменные SMTP_* в окружении.

Когда уходит письмо

Источник	Поведение
Event Receiver notifications.sendEventEmail	На событие ставится job → Worker шлёт письмо по шаблону
POST /api/v1/mail/send	Очередь (async: true) или сразу (только admin, async: false)
⋮ → Запустить у службы	Prompt e-mail → тестовое письмо

Цепочка: событие / API → portal_jobs → Worker → SMTP (MailKit).

Типы заданий

job_type	Назначение
notifications.sendEmail	Прямая отправка: to, subject, text/html
notifications.sendEventEmail	Письмо из Event Receiver (шаблоны с {{eventName}}, {{userLogin}}, …)

Админка

Действие	Есть?
Вкл/выкл	да, через ⋮
Расписание	нет
Запустить	да (⋮, prompt e-mail)
Настройки	Настройки → SMTP, не /services/notifications
Справка ?	popover + ссылка на этот раздел

Если выключить

• /mail/send и ручной Запустить — ошибка;
• jobs с service_key=notifications падают;
• SMTP-настройки и тест SMTP остаются;
• подписчики ER могут создавать jobs, но отправка не пройдёт.

Не путать с пакетными обработчиками модулей (свой serviceKey в манифесте) и с реестром пакетов event-extensions.

Связанные материалы

• API: Почта
• SMTP в API админки
• Сценарии Event Receivers — уведомления

---

3. ad-sync — Синхронизация AD {#ad-sync}

Ключ: ad-sync
Описание в UI: Импорт и обновление доменных пользователей и групп из LDAP/AD.

Назначение

Периодический или ручной импорт пользователей (и опционально групп) из LDAP/Active Directory в Portal: создание/обновление учёток auth_source=domain, поля профиля, состав групп.

По умолчанию

• Служба выключена, cron выкл.
• Без настроенного LDAP строка в UI помечается недоступной (нельзя включить / запустить / задать расписание).

Подготовка

1. Службы → Синхронизация AD → ⚙ Настройки (/services/ad-sync) — оба аккордеона открыты по умолчанию:
   • Подключение — URL, Base DN, Bind DN/пароль, фильтры входа/поиска, атрибут логина; badge статуса;
   • Настройка синхронизации:
     • фильтры и лимиты sync пользователей / групп;
     • поля профиля — чекбоксы встроенного каталога (givenName, sn, department, …) + «Выбрать все / Снять все»;
     • дополнительные поля — ручной маппинг: подпись, атрибут LDAP, ключ (например отчество → middleName);
     • флаги групп и деактивации (у каждого — значок ⓘ с подсказкой).
2. На вкладке Службы — ⋮ → Включить, при необходимости Расписание, Запустить.

Карточка пользователя с импортированными полями: Админка → Пользователи → /users/{id}.

Флаги синхронизации

Разделы UI: Группы и Пользователи (это разные настройки).

Флаг (UI)	Config	Смысл
Синхронизировать группы AD	syncGroups	Импорт групп и состава участников. Если выкл — только пользователи
Удалять участников, которых нет в AD-группе	removeMissingGroupMembers	Исключение из группы Portal; на учётки не влияет
Удалять группы Portal, пропавшие из AD	removeMissingGroups	Удаление ранее импортированных групп вне фильтра; локальные группы не трогает
Деактивировать пользователей, отсутствующих в AD	cronDeactivateMissing	is_active=false для domain-пользователей вне выборки sync; ручной запуск и cron. Не связано с составом групп

Отчество в стандартном каталоге AD/Portal нет — добавьте в «Дополнительные поля» (LDAP middleName или свой атрибут).

Типы заданий

job_type	Назначение
adSync.run	Полный прогон синхронизации

Ответ job (пример структуры): { users: { synced, created, updated, reactivated, deactivated }, groups: { … } }.

Админка

Действие	Есть?
Вкл/выкл	да (если LDAP настроен), через ⋮
Расписание	да, модальное окно ⋮ → Расписание
Запустить	да (без confirm и без prompt; флаги из сохранённых настроек; результат — тост / вкладка Задания)
Настройки	/services/ad-sync
Справка ?	popover + ссылка на этот раздел

Если выключить

Синхронизация по cron и ручной запуск недоступны. Уже импортированные пользователи/группы остаются; вход через AD (если настроен отдельно) не обязательно зависит от этой службы.

Связанные материалы

• API: каталог / AD
• Группы доступа

---

4. search-crawler — Поисковый индекс {#search-crawler}

Ключ: search-crawler
Описание в UI: Полная переиндексация (сверка). Повседневные изменения индексируются сразу при сохранении.

Назначение

• Инкремент: при CRUD узлов, списков, страниц, документов индекс обновляется сразу (не через эту службу).
• Полный обход (searchCrawler.run): очистка/пересборка и сверка индекса — для ночной проверки или после «Очистить индекс».

По умолчанию

• Служба включена, cron 0 3 * * * (ежедневно 03:00).

Типы заданий

job_type	Назначение
searchCrawler.run	Полный обход индекса

Админка

Действие	Есть?
Вкл/выкл	да
Расписание	да
Запустить	да («Полный обход»)
Очистить индекс	POST /admin/search/clear или кнопка у службы (без постановки crawl)
Настройки	нет; статус — Обзор → Обслуживание

Если выключить

Полный обход и его cron jobs падают. Инкрементальная индексация при сохранении контента обычно продолжает работать (она не идёт через portal_jobs этой службы).

Списки/библиотеки с отключённым поиском (SearchEnabled=false) в индекс не попадают.

Связанные материалы

• API: Поиск

---

5. recycle-bin — Корзина {#recycle-bin}

Ключ: recycle-bin
Описание в UI: Автоочистка корзины удалённых элементов узлов (старше 30 дней).

Назначение

Окончательно удаляет из корзины объекты старше срока хранения. Срок зашит в код: 30 дней (RetentionDays), не редактируется в portal_services.config.

Типы объектов корзины (среди прочих): элемент списка, страница, файл библиотеки, список, библиотека.

Мягкое удаление и UI корзины узла работают независимо от того, включена ли эта служба — служба отвечает только за автоpurge.

По умолчанию

• Служба включена, cron 0 4 * * *.

Типы заданий

job_type	Назначение
recycleBin.purgeExpired	Удалить просроченные записи корзины

Админка

Действие	Есть?
Вкл/выкл	да
Расписание	да
Запустить	да (немедленный purge)
Настройки	нет; счётчик — Обзор → Обслуживание

Если выключить

Автоочистка и ручной purge через службу останавливаются; объекты могут копиться в корзине дольше 30 дней, пока службу не включат или не запустят вручную.

Связанные материалы

• Корзина (пользователь)

---

6. event-extensions — Event Receivers {#event-extensions}

Ключ: event-extensions
Описание в UI: Пользовательские обработчики событий из пакетов .portalevent.

Назначение

Реестр / gate для пакетных Event Receivers. Сама служба не «бегает по cron»: при установке пакета и привязке подписчика события ставят jobs с service_key (обычно event-extensions), Worker загружает DLL пакета и вызывает обработчик.

Рекомендуемый serviceKey в манифесте пакета: "event-extensions". Если указать другой ключ, в portal_services должна существовать и быть включена строка с этим ключом — иначе jobs упадут. Платформа не создаёт произвольные ключи автоматически (кроме upsert самой event-extensions при install).

По умолчанию

• Служба включена.
• Расписания и ручного запуска у строки службы нет.

Админка

Действие	Есть?
Вкл/выкл	да (глобальный рубильник пакетных ER на этом ключе)
Расписание	нет
Запустить	нет
Управление	вкладки Event Receivers (пакеты, привязки к спискам/событиям)

Если выключить

Jobs с service_key=event-extensions не выполняются. Встроенные audit / notifications живут на своих ключах и этим тумблером не гасятся.

Связанные материалы

• Event Receivers
• Манифест
• Hot deploy

---

7. timer-extensions — Timer Jobs {#timer-extensions}

Ключ: timer-extensions
Описание в UI: Пользовательские задания по расписанию из пакетов .portaltimer.

Назначение

Gate для пакетных Timer Jobs. Расписание задаётся у каждого экземпляра Timer Job (вкладка Timer Jobs), а не кнопкой «Расписание» у строки службы в списке Служб.

Планировщик: CronSchedulerService → постановка в portal_jobs → Worker → DLL пакета.

Рекомендуемый serviceKey в манифесте: "timer-extensions".

По умолчанию

• Служба включена.
• У строки службы cron/run в UI нет.

Админка

Действие	Есть?
Вкл/выкл	да
Расписание службы	нет (расписание у экземпляров TJ)
Запустить службу	нет (запуск экземпляра — на вкладке Timer Jobs)
Управление	вкладка Timer Jobs

Если выключить

Пакетные timer-jobs с этим service_key не ставятся/не выполняются.

Связанные материалы

• Timer Jobs
• Манифест

---

8. list-export — Экспорт списков {#list-export}

Ключ: list-export
Описание в UI: Фоновый экспорт элементов списка в XLSX через worker.

Назначение

Два режима:

1. listExport.run — пользователь запускает экспорт из UI списка → файл XLSX в object storage, срок жизни файла 24 часа (RetentionHours).
2. listExport.purgeExpired — по cron (в БД) удаляет просроченные файлы экспорта.

По умолчанию

• Служба включена.
• В БД: cron 0 3 * * *, job type listExport.purgeExpired.
• В UI Службы: кнопок «Расписание» и «Запустить» нет (purge идёт фоном по данным из БД; экспорт — из списка).

Типы заданий

job_type	Назначение
listExport.run	Собрать XLSX по exportId (+ фильтр q)
listExport.purgeExpired	Удалить файлы старше 24 часов

Админка / UX

Действие	Где
Заказать экспорт	UI списка (не строка службы)
Вкл/выкл службы	Службы — при выкл. и export, и purge падают
Расписание purge	только БД/API (PATCH /services/list-export), не кнопка в UI

Если выключить

Новые экспорты и очистка временных файлов через Worker не выполнятся.

---

9. portal-backup — Резервное копирование {#portal-backup}

Ключ: portal-backup
Описание в UI: Архивы PostgreSQL + S3 + portal_data в каталог на хосте.

Назначение

Разрешает очередь бэкапов и расписание в портале. Сама служба не пишет архив — это делает отдельный backup-runner (контейнер / systemd / CLI), который забирает задания из portal_backups.

Состав типичного архива: PostgreSQL, файлы (S3), данные установки (portal_data). Подробности установки и томов: Резервное копирование и восстановление.

По умолчанию

• Служба включена.
• Предложенное выражение cron 0 2 * * *, но cron_enabled=false, пока не настроены путь и проверка.

Очередь

Не portal_jobs, а portal_backups: виды validate, backup, restore.
Тип backup.enqueueCron в cron — метка для планировщика; Worker job processor его не «крутит» как обычный job.

Подготовка

1. Поднять backup-runner, смонтировать каталог (PORTAL_BACKUP_HOST_DIR / PORTAL_BACKUP_MOUNT_PATH для Docker).
2. Службы → Резервное копирование → Настройки (/services/portal-backup):
   • аккордеон Резервное копирование — путь (в Docker — mount path), retention, validate, создание копии, журнал, Runner online;
   • аккордеон Восстановление — выбор копии из restorable, confirm, очередь restore.
3. Расписание — Службы → ⋮ → Расписание (после validate + runner online).

Включение cron требует: служба вкл, путь проверен (lastValidatedOk), runner online.

Админка

Действие	Есть?
Вкл/выкл	да, через ⋮
Расписание	да (после validate + runner), модальное окно
Запустить у строки службы	нет (POST /services/portal-backup/run отвергается)
Копия / validate / restore	/services/portal-backup и backup API
Runner online	страница настроек + Обзор → Обслуживание (не таблица Служб)

Если выключить

Новые задания бэкапа/расписание из портала не ставятся. Уже лежащие архивы на диске не удаляются. CLI portal-cli backup может использоваться отдельно от UI-очереди — см. install-доку.

Связанные материалы

• Резервное копирование и восстановление
• API админки — backups

---

10. jobs-cleanup — Журнал заданий {#jobs-cleanup}

Ключ: jobs-cleanup
Описание в UI: Автоудаление записей журнала заданий старше срока хранения.

Назначение

Чистит таблицу portal_jobs (журнал/очередь заданий), а не бизнес-данные портала. Удаляются завершённые записи (completed / failed / dismissed) старше retentionDays. Строки pending и running не трогает.

По умолчанию

• Служба включена, cron 0 5 * * *.
• config.retentionDays = 30 (допустимо 1…3650).

Типы заданий

job_type	Назначение
jobs.purgeOlder	Удалить старые записи журнала

Админка

Действие	Есть?
Вкл/выкл	да
Расписание	да
Запустить	да (немедленный purge)
Срок хранения	Админка → Задания → retention (GET/PUT /api/v1/jobs/settings/retention)

Если выключить

Журнал заданий перестанет автоматически сокращаться; ручной purge через службу тоже недоступен.

---

Пакетные службы модулей

Встроенные службы из таблицы выше — фиксированный набор платформы.

Пакеты .portalevent / .portaltimer и модули (module.json) регистрируют обработчики и привязки. Обычно они используют serviceKey: "event-extensions" или "timer-extensions".

Если в манифесте указан собственный ключ (например korport.helpdesk.ticket-notifications):

• подписчик/job ссылается на этот ключ;
• в portal_services должна быть включённая строка с тем же service_key (иначе Worker откажет);
• отдельная строка в списке «Службы» для кастомного ключа не создаётся сама при install пакета — за исключением upsert event-extensions / timer-extensions.

Управление пакетами: вкладки Event Receivers и Timer Jobs, не дублирующие строки в списке встроенных служб.

---

Добавление обработчика задания (разработка)

1. Реализуйте обработчик в Worker (IJobHandler) или соберите пакет .portalevent / .portaltimer.
2. Для платформенного типа — регистрация в BuiltinServices / JobProcessor.
3. Для пакета — манифест + install; подписчик или экземпляр Timer Job через админку / API / module.json.

См. Job-модули, SDK Event Receiver, SDK Timer Job.

Переменные окружения Worker

• WORKER_POLL_INTERVAL_MS — интервал опроса очереди (по умолчанию 5000)
• WORKER_BATCH_SIZE — размер пакета (по умолчанию 10)
• CRON_RELOAD_INTERVAL_MS — перезагрузка расписания из БД (по умолчанию 60000)

Для почты и бэкапа дополнительно см. SMTP_*, PORTAL_BACKUP_* в установке и backup-restore.