Simmetric Chat
Volver a la documentación
Guía 08

Administración

Guía operativa para administradores: usuarios, roles (RBAC), workspace, audit, licencias y backups administrativos. Todas las operaciones requieren authMiddleware más permisos específicos - ver la API Reference para el inventario completo de endpoints.

3 min de lectura

Guía operativa para administradores: usuarios, roles (RBAC), workspace, audit, licencias y backups administrativos. Todas las operaciones requieren authMiddleware más permisos específicos - ver la API Reference para el inventario completo de endpoints.

Bootstrap admin

En el primer arranque (si SEED_BOOTSTRAP_ADMIN=true), el servidor crea un admin con credenciales desde env (SEED_ADMIN_USERNAME=admin, SEED_ADMIN_PASSWORD=admin123, [email protected]). La cuenta tiene mustChangePassword=true → el primer login impone el cambio. Setup wizard vía GET /api/system/is-initialized → POST /api/system/initialize.

Seguridad: cambia de inmediato la contraseña bootstrap y establece un JWT_SECRET fuerte en producción. El fallback scryptSync(JWT_SECRET, ...) para ENCRYPTION_KEY convierte JWT_SECRET en material criptográfico - no lo expongas.

Usuarios - /api/users

OperaciónEndpointPermiso
Lista paginadaGET /usersrequireAdmin
DetalleGET /users/:idself/admin
ModificaciónPUT/PATCH /users/:idself/admin (updateUserSchema)
EliminarDELETE /users/:idrequireAdmin
AvatarPOST/DELETE /users/:id/avatarJWT (multipart)

Delete: DELETE es un hard delete con cleanup de las relaciones (UserRole, ProjectAccess, WorkspaceAccess) e invalidación de la auth cache; el admin no puede eliminarse a sí mismo. updateUserSchema valida username/email/password/firstName/lastName/customInstructions/textSize (las custom instructions se anteponen al system prompt del agente); los no-admin no pueden cambiar su propia contraseña desde este endpoint.

Roles & RBAC - /api/roles

31 permisos definidos en packages/shared/src/constants/permissions.ts (PERMISSION_NAMES). 13 secciones de menú (MENU_SECTIONS, incluye uploads).

OperaciónEndpointPermiso
Secciones menú visiblesGET /roles/me/menu-sectionsJWT
Lista de rolesGET /rolesrequireAdmin
DetalleGET /roles/:roleIdrequireAdmin (UUID)
CrearPOST /rolesrequireAdmin (createRoleSchema, isDefault=false)
UpdatePUT /roles/:roleIdrequireAdmin (replace atómico de permisos)
Secciones menú del rolPUT /roles/:roleId/menu-sectionsrequireAdmin
EliminarDELETE /roles/:roleIdrequireAdmin
Asignar/RevocarPOST /roles/assign /revokerequireAdmin

Roles por defecto: admin (los 31 permisos) y user (11 permisos: los 9 base más memory:read/memory:write para las memorias per-usuario; filters:manage está reservado a admin/superuser). "Superuser" coincide con admin. Los permisos se verifican vía requirePermission(name) o el shortcut requireAdmin. La asignación es many-to-many (UserRole).

Workspaces & Projects

Workspace (/api/workspaces): unidad de aislamiento para chats, documentos, agent config.

  • Creación: workspace:create + license max_workspaces (Community 3, Enterprise ∞).
  • Acceso: middleware requireWorkspaceAccess (join table WorkspaceAccess).
  • Soft-delete + restore (PUT /:id/restore).
  • Carpetas de chat: /:id/folders[/:folderId] + restore.

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

  • Creación: project:create + license max_projects.
  • Acceso: requireProjectAccess (ProjectAccess).
  • Export de archivo: GET /:projectId/export (stream).
  • Usage stats: GET /:projectId/usage.

Audit / Event Log - /api/event-logs

License audit_log_immutable (Enterprise). GET con filtros entityType/entityId/userId + limit/offset (paginación). eventLogService.logEvent delega la escritura al plugin enterprise (no-op en Community) y dispatchea los webhooks fire-and-forget. Entidades logueadas (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. Cuando el flag immutable está activo, los registros no son modificables/eliminables (append-only a nivel app).

Licencias

  • Community (default): flags limitados (ver 03 - Configuration).
  • Enterprise: LICENSE_KEY (JWT HS256) + LICENSE_SECRET. Payload validado contra licensePayloadSchema. Expirado/inválido → fallback Community con warn, graceful degradation a runtime (sin restart).
  • Endpoint: GET /api/license/info (público) → { license, features }.
  • Gating: requireFeature(flag) → 402; requireFeatureLimit(flag, model) → 402 si 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).
  • Test de destination POST /backup-destinations/:id/test.

Settings - /api/system/settings

GET/PUT bulk (devuelve { updated, rejected }). Grupos: LLM, Embedding/Vector, puertos/URL, Auth, Branding (gated white_label), Feature, OCR, Synthesis, Retention. Las claves ALWAYS_READONLY son rechazadas. Chat retention solo vía PUT /api/system/chat-retention (auditado, confirmDataLoss: true). Detalles en 03 - Configuration.

SSO - /api/sso

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