Simmetric Chat
返回文档
指南 08

管理

面向管理员的操作指南：用户、角色（RBAC）、workspace、audit、许可证和行政备份。所有操作都需要 authMiddleware 加上特定权限 - 完整 endpoint 清单见 API Reference。

2 分钟阅读

面向管理员的操作指南：用户、角色（RBAC）、workspace、audit、许可证和行政备份。所有操作都需要 authMiddleware 加上特定权限 - 完整 endpoint 清单见 API Reference。

Bootstrap admin

首次启动时（如果 SEED_BOOTSTRAP_ADMIN=true），服务器会用 env 中的凭据创建 admin（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。ENCRYPTION_KEY 的 scryptSync(JWT_SECRET, ...) fallback 使 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 cache 失效；admin 不能删除自己。updateUserSchema 校验 username/email/password/firstName/lastName/customInstructions/textSize（custom instructions 会前置到 agent 的 system prompt）；非 admin 不能从此 endpoint 更改自己的密码。

角色与 RBAC - /api/roles

31 个权限定义在 packages/shared/src/constants/permissions.ts（PERMISSION_NAMES）。13 个菜单 section（MENU_SECTIONS，包含 uploads）。

操作Endpoint权限
可见菜单 sectionGET /roles/me/menu-sectionsJWT
角色列表GET /rolesrequireAdmin
详情GET /roles/:roleIdrequireAdmin（UUID）
创建POST /rolesrequireAdmin（createRoleSchema、isDefault=false）
UpdatePUT /roles/:roleIdrequireAdmin（权限的原子 replace）
角色菜单 sectionPUT /roles/:roleId/menu-sectionsrequireAdmin
删除DELETE /roles/:roleIdrequireAdmin
分配/撤销POST /roles/assign /revokerequireAdmin

默认角色：admin（全部 31 个权限）和 user（11 个权限：9 个基础权限加上用于 per-user memory 的 memory:read/memory:write；filters:manage 保留给 admin/superuser）。"Superuser" 等同于 admin。权限通过 requirePermission(name) 或 shortcut requireAdmin 校验。分配是 many-to-many（UserRole）。

Workspaces 与 Projects

Workspace（/api/workspaces）：chat、document、agent config 的隔离单元。

  • 创建：workspace:create + license max_workspaces（Community 3，Enterprise ∞）。
  • 访问：requireWorkspaceAccess middleware（join table WorkspaceAccess）。
  • Soft-delete + restore（PUT /:id/restore）。
  • chat 文件夹：/: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 插件（Community 中为 no-op）并 fire-and-forget 分发 webhook。记录的实体（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 flag 激活时，记录不可修改/删除（应用层 append-only）。

许可证

  • Community（默认）：受限 flag（见 03 - Configuration）。
  • Enterprise：LICENSE_KEY（JWT HS256）+ LICENSE_SECRET。Payload 用 licensePayloadSchema 校验。过期/无效 → fallback Community 并记录 warn，运行时 graceful degradation（无需 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）。
  • Destination 测试 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 配置。

交叉链接