Simmetric Chat
Zurück zur Dokumentation
Guide 08

Administration

Betriebshandbuch für Administratoren: Benutzer, Rollen (RBAC), Workspaces, Audit, Lizenzen und administrative Backups. Alle Operationen erfordern authMiddleware plus spezifische Berechtigungen - siehe die API Reference für das vollständige Endpoint-Inven…

3 Min. Lesezeit

Betriebshandbuch für Administratoren: Benutzer, Rollen (RBAC), Workspaces, Audit, Lizenzen und administrative Backups. Alle Operationen erfordern authMiddleware plus spezifische Berechtigungen - siehe die API Reference für das vollständige Endpoint-Inventar.

Bootstrap-Admin

Beim ersten Start (wenn SEED_BOOTSTRAP_ADMIN=true) erstellt der Server einen Admin mit Zugangsdaten aus der Env (SEED_ADMIN_USERNAME=admin, SEED_ADMIN_PASSWORD=admin123, [email protected]). Das Konto hat mustChangePassword=true → der erste Login erzwingt die Änderung. Setup Wizard via GET /api/system/is-initialized → POST /api/system/initialize.

Sicherheit: Ändere sofort das Bootstrap-Passwort und setze ein starkes JWT_SECRET in Produktion. Der Fallback scryptSync(JWT_SECRET, ...) für ENCRYPTION_KEY macht JWT_SECRET zu kryptographischem Material - setze es nicht exponiert.

Benutzer - /api/users

OperationEndpointBerechtigung
Paginierte ListeGET /usersrequireAdmin
DetailGET /users/:idself/admin
BearbeitungPUT/PATCH /users/:idself/admin (updateUserSchema)
LöschenDELETE /users/:idrequireAdmin
AvatarPOST/DELETE /users/:id/avatarJWT (multipart)

Delete: DELETE ist ein Hard Delete mit Cleanup der Relationen (UserRole, ProjectAccess, WorkspaceAccess) und Invalidierung des Auth-Caches; der Admin kann sich nicht selbst löschen. updateUserSchema validiert username/email/password/firstName/lastName/customInstructions/textSize (die Custom Instructions werden dem System-Prompt des Agenten vorangestellt); Nicht-Admins können ihr eigenes Passwort nicht über diesen Endpoint ändern.

Rollen & RBAC - /api/roles

31 Berechtigungen definiert in packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 13 Menü-Sektionen (MENU_SECTIONS, enthält uploads).

OperationEndpointBerechtigung
Sichtbare Menü-SektionenGET /roles/me/menu-sectionsJWT
RollenlisteGET /rolesrequireAdmin
DetailGET /roles/:roleIdrequireAdmin (UUID)
ErstellenPOST /rolesrequireAdmin (createRoleSchema, isDefault=false)
UpdatePUT /roles/:roleIdrequireAdmin (atomarer Replace der Berechtigungen)
Rollen-Menü-SektionenPUT /roles/:roleId/menu-sectionsrequireAdmin
LöschenDELETE /roles/:roleIdrequireAdmin
Zuweisen/EntziehenPOST /roles/assign /revokerequireAdmin

Standardrollen: admin (alle 31 Berechtigungen) und user (11 Berechtigungen: die 9 Basis plus memory:read/memory:write für die Per-User-Memories; filters:manage ist admin/superuser vorbehalten). "Superuser" entspricht admin. Die Berechtigungen werden via requirePermission(name) oder dem Shortcut requireAdmin geprüft. Die Zuweisung ist many-to-many (UserRole).

Workspaces & Projects

Workspace (/api/workspaces): Isolationseinheit für Chats, Dokumente, Agent Config.

  • Erstellung: workspace:create + License max_workspaces (Community 3, Enterprise ∞).
  • Zugriff: requireWorkspaceAccess Middleware (Join-Tabelle WorkspaceAccess).
  • Soft-Delete + Restore (PUT /:id/restore).
  • Chat-Ordner: /:id/folders[/:folderId] + Restore.

Project (/api/projects): gruppiert zusammengehörige Workspaces.

  • Erstellung: project:create + License max_projects.
  • Zugriff: requireProjectAccess (ProjectAccess).
  • Archiv-Export: GET /:projectId/export (Stream).
  • Usage Stats: GET /:projectId/usage.

Audit / Event Log - /api/event-logs

License audit_log_immutable (Enterprise). GET mit Filtern entityType/entityId/userId + Limit/Offset (Paginierung). eventLogService.logEvent delegiert das Schreiben an das Enterprise-Plugin (No-op in Community) und dispatcht die Webhooks fire-and-forget. Geloggte Entitäten (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. Wenn das Immutable-Flag aktiv ist, sind die Records nicht änderbar/löschbar (Append-Only auf App-Ebene).

Lizenzen

  • Community (Standard): begrenzte Flags (siehe 03 - Configuration).
  • Enterprise: LICENSE_KEY (JWT HS256) + LICENSE_SECRET. Payload validiert gegen licensePayloadSchema. Abgelaufen/ungültig → Fallback Community mit Warn, Graceful Degradation zur Runtime (kein Restart).
  • Endpoint: GET /api/license/info (öffentlich) → { license, features }.
  • Gating: requireFeature(flag) → 402; requireFeatureLimit(flag, model) → 402 wenn count >= limit (Enterprise = Infinity).

Administrative Backups

Siehe 05 - Feature Guide § Backup. Admin-Endpoints:

  • 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), manueller Trigger POST /:id/run.
  • Restore /api/backups/restore/:logId[/dry-run] (backup:restore:write).
  • Destinationstest POST /backup-destinations/:id/test.

Settings - /api/system/settings

GET/PUT Bulk (gibt { updated, rejected } zurück). Gruppen: LLM, Embedding/Vector, Ports/URLs, Auth, Branding (gated white_label), Feature, OCR, Synthesis, Retention. ALWAYS_READONLY-Keys werden abgelehnt. Chat Retention nur via PUT /api/system/chat-retention (audited, confirmDataLoss: true). Details in 03 - Configuration.

SSO - /api/sso

License sso_enabled. GET/PUT /config, POST /test. SAML/OIDC Enterprise-Konfiguration.