Simmetric Chat
К документации
Руководство 08

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

Операционное руководство для администраторов: пользователи, роли (RBAC), workspace, audit, лицензии и административные бэкапы. Все операции требуют authMiddleware плюс конкретные разрешения - полный инвентарь endpoint'ов см. в API Reference.

3 мин чтения

Операционное руководство для администраторов: пользователи, роли (RBAC), workspace, audit, лицензии и административные бэкапы. Все операции требуют authMiddleware плюс конкретные разрешения - полный инвентарь endpoint'ов см. в API Reference.

Bootstrap-админ

При первом запуске (если SEED_BOOTSTRAP_ADMIN=true) сервер создаёт админа с учётными данными из env (SEED_ADMIN_USERNAME=admin, SEED_ADMIN_PASSWORD=admin123, [email protected]). У аккаунта mustChangePassword=true → первый вход требует смены пароля. Setup wizard через GET /api/system/is-initialized → POST /api/system/initialize.

Безопасность: сразу смени bootstrap-пароль и задай сильный JWT_SECRET в продакшене. Fallback scryptSync(JWT_SECRET, ...) для ENCRYPTION_KEY делает JWT_SECRET криптографическим материалом - не раскрывай его.

Пользователи - /api/users

ОперацияEndpointРазрешение
Пагинированный списокGET /usersrequireAdmin
ДеталиGET /users/:idself/admin
ИзменениеPUT/PATCH /users/:idself/admin (updateUserSchema)
УдалениеDELETE /users/:idrequireAdmin
AvatarPOST/DELETE /users/:id/avatarJWT (multipart)

Delete: DELETE - это hard delete с очисткой связей (UserRole, ProjectAccess, WorkspaceAccess) и инвалидацией auth-кэша; админ не может удалить себя. updateUserSchema валидирует username/email/password/firstName/lastName/customInstructions/textSize (custom instructions добавляются в начало system prompt агента); не-админы не могут сменить свой пароль через этот endpoint.

Роли и RBAC - /api/roles

31 разрешение определены в packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 13 секций меню (MENU_SECTIONS, включая uploads).

ОперацияEndpointРазрешение
Видимые секции менюGET /roles/me/menu-sectionsJWT
Список ролейGET /rolesrequireAdmin
ДеталиGET /roles/:roleIdrequireAdmin (UUID)
СозданиеPOST /rolesrequireAdmin (createRoleSchema, isDefault=false)
UpdatePUT /roles/:roleIdrequireAdmin (атомарный replace разрешений)
Секции меню ролиPUT /roles/:roleId/menu-sectionsrequireAdmin
УдалениеDELETE /roles/:roleIdrequireAdmin
Назначение/ОтзывPOST /roles/assign /revokerequireAdmin

Роли по умолчанию: admin (все 31 разрешение) и user (11 разрешений: 9 базовых плюс memory:read/memory:write для per-user memory; filters:manage зарезервирован за admin/superuser). "Superuser" совпадает с admin. Разрешения проверяются через requirePermission(name) или shortcut requireAdmin. Назначение - many-to-many (UserRole).

Workspaces и Projects

Workspace (/api/workspaces): единица изоляции для чатов, документов, agent config.

  • Создание: workspace:create + license max_workspaces (Community 3, Enterprise ∞).
  • Доступ: middleware requireWorkspaceAccess (join table WorkspaceAccess).
  • Soft-delete + restore (PUT /:id/restore).
  • Папки чатов: /:id/folders[/:folderId] + restore.

Project (/api/projects): группирует связанные workspace.

  • Создание: project:create + license max_projects.
  • Доступ: requireProjectAccess (ProjectAccess).
  • Экспорт архива: GET /:projectId/export (stream).
  • Usage stats: GET /:projectId/usage.

Audit / Event Log - /api/event-logs

License audit_log_immutable (Enterprise). GET с фильтрами entityType/entityId/userId + limit/offset (пагинация). eventLogService.logEvent делегирует запись enterprise-плагину (no-op в Community) и dispatch'ит webhook fire-and-forget. Логируемые сущности (EntityType): user, workspace, project, chat, document, mcp_connection, dlp, archive/archive_page/archive_import, ocr_job, synthesis_run, wiki_edit, backup_destination/backup_job, provider, memory. Когда immutable-флаг активен, записи неизменяемы/неудаляемы (append-only на уровне приложения).

Лицензии

  • Community (по умолчанию): ограниченные флаги (см. 03 - Configuration).
  • Enterprise: LICENSE_KEY (JWT HS256) + LICENSE_SECRET. Payload валидируется по licensePayloadSchema. Истёк/невалиден → fallback Community с warn, graceful degradation в runtime (без restart).
  • Endpoint: GET /api/license/info (публичный) → { license, features }.
  • Gating: requireFeature(flag) → 402; requireFeatureLimit(flag, model) → 402 если count >= limit (Enterprise = Infinity).

Административные бэкапы

См. 05 - Feature Guide § Backup. Admin endpoint'ы:

  • Logs /api/system/backups (backup:log:read).
  • Destinations /api/backup-destinations (backup:destination:read/write, license max_backup_destinations).
  • Jobs /api/backup-jobs (backup:job:read/write), ручной trigger POST /:id/run.
  • Restore /api/backups/restore/:logId[/dry-run] (backup:restore:write).
  • Тест назначения POST /backup-destinations/:id/test.

Settings - /api/system/settings

GET/PUT bulk (возвращает { updated, rejected }). Группы: LLM, Embedding/Vector, порты/URL, Auth, Branding (gated white_label), Feature, OCR, Synthesis, Retention. Ключи ALWAYS_READONLY отклоняются. Chat retention только через PUT /api/system/chat-retention (audited, confirmDataLoss: true). Детали в 03 - Configuration.

SSO - /api/sso

License sso_enabled. GET/PUT /config, POST /test. Конфигурация SAML/OIDC enterprise.