Simmetric Chat
Voltar para a documentação
Guia 08

Administração

Guia operativo para administradores: usuários, roles (RBAC), workspace, audit, licenças e backups administrativos. Todas as operações exigem authMiddleware mais permissões específicas - ver a API Reference para o inventário completo de endpoints.

3 min de leitura

Guia operativo para administradores: usuários, roles (RBAC), workspace, audit, licenças e backups administrativos. Todas as operações exigem authMiddleware mais permissões específicas - ver a API Reference para o inventário completo de endpoints.

Bootstrap admin

No primeiro arranque (se SEED_BOOTSTRAP_ADMIN=true), o servidor cria um admin com credenciais das env (SEED_ADMIN_USERNAME=admin, SEED_ADMIN_PASSWORD=admin123, [email protected]). A conta tem mustChangePassword=true → o primeiro login impõe a mudança. Setup wizard via GET /api/system/is-initialized → POST /api/system/initialize.

Segurança: muda imediatamente a password bootstrap e define um JWT_SECRET forte em produção. O fallback scryptSync(JWT_SECRET, ...) para ENCRYPTION_KEY torna JWT_SECRET material criptográfico - não o exponhas.

Usuários - /api/users

OperaçãoEndpointPermissão
Lista paginadaGET /usersrequireAdmin
DetalheGET /users/:idself/admin
ModificaçãoPUT/PATCH /users/:idself/admin (updateUserSchema)
EliminarDELETE /users/:idrequireAdmin
AvatarPOST/DELETE /users/:id/avatarJWT (multipart)

Delete: DELETE é um hard delete com cleanup das relações (UserRole, ProjectAccess, WorkspaceAccess) e invalidação da auth cache; o admin não pode eliminar-se a si mesmo. updateUserSchema valida username/email/password/firstName/lastName/customInstructions/textSize (as custom instructions são prepostas ao system prompt do agente); os não-admin não podem mudar a sua própria password deste endpoint.

Roles & RBAC - /api/roles

31 permissões definidas em packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 13 secções de menu (MENU_SECTIONS, inclui uploads).

OperaçãoEndpointPermissão
Secções menu visíveisGET /roles/me/menu-sectionsJWT
Lista de rolesGET /rolesrequireAdmin
DetalheGET /roles/:roleIdrequireAdmin (UUID)
CriarPOST /rolesrequireAdmin (createRoleSchema, isDefault=false)
UpdatePUT /roles/:roleIdrequireAdmin (replace atómico de permissões)
Secções menu do rolePUT /roles/:roleId/menu-sectionsrequireAdmin
EliminarDELETE /roles/:roleIdrequireAdmin
Atribuir/RevogarPOST /roles/assign /revokerequireAdmin

Roles por defeito: admin (as 31 permissões) e user (11 permissões: as 9 base mais memory:read/memory:write para as memórias per-utilizador; filters:manage está reservado a admin/superuser). "Superuser" coincide com admin. As permissões são verificadas via requirePermission(name) ou o shortcut requireAdmin. A atribuição é many-to-many (UserRole).

Workspaces & Projects

Workspace (/api/workspaces): unidade de isolamento para chats, documentos, agent config.

  • Criação: workspace:create + license max_workspaces (Community 3, Enterprise ∞).
  • Acesso: middleware requireWorkspaceAccess (join table WorkspaceAccess).
  • Soft-delete + restore (PUT /:id/restore).
  • Pastas de chat: /:id/folders[/:folderId] + restore.

Project (/api/projects): agrupa workspace correlacionados.

  • Criação: project:create + license max_projects.
  • Acesso: requireProjectAccess (ProjectAccess).
  • Export de arquivo: GET /:projectId/export (stream).
  • Usage stats: GET /:projectId/usage.

Audit / Event Log - /api/event-logs

License audit_log_immutable (Enterprise). GET com filtros entityType/entityId/userId + limit/offset (paginação). eventLogService.logEvent delega a escrita ao plugin enterprise (no-op no Community) e dispatcheia os webhooks fire-and-forget. Entidades logadas (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. Quando o flag immutable está ativo, os registos não são modificáveis/elimináveis (append-only a nível app).

Licenças

  • Community (default): flags limitados (ver 03 - Configuration).
  • Enterprise: LICENSE_KEY (JWT HS256) + LICENSE_SECRET. Payload validado contra licensePayloadSchema. Expirado/inválido → fallback Community com warn, graceful degradation em runtime (sem restart).
  • Endpoint: GET /api/license/info (público) → { license, features }.
  • Gating: requireFeature(flag) → 402; requireFeatureLimit(flag, model) → 402 se count >= limit (Enterprise = Infinity).

Backups administrativos

Ver 05 - Feature Guide § Backup. Endpoints admin:

  • 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 manual POST /:id/run.
  • Restore /api/backups/restore/:logId[/dry-run] (backup:restore:write).
  • Teste de destination POST /backup-destinations/:id/test.

Settings - /api/system/settings

GET/PUT bulk (devolve { updated, rejected }). Grupos: LLM, Embedding/Vector, portas/URL, Auth, Branding (gated white_label), Feature, OCR, Synthesis, Retention. As chaves ALWAYS_READONLY são rejeitadas. Chat retention apenas via PUT /api/system/chat-retention (auditado, confirmDataLoss: true). Detalhes em 03 - Configuration.

SSO - /api/sso

License sso_enabled. GET/PUT /config, POST /test. Config SAML/OIDC enterprise.