用户管理

用户管理模块提供 Snail AI 平台的用户账号管理能力，包括用户的创建、编辑、删除，角色权限分配，密码管理，以及 Token 配额授权等功能。系统基于 Sa-Token 实现认证鉴权，支持管理员和普通用户两级角色体系。

核心概念

用户实体

每个用户账号包含以下核心属性：

字段	类型	说明
id	number	用户唯一 ID，系统自动生成
username	string	登录用户名
email	string	用户邮箱，可用于登录和授权码生成
role	number	角色标识：2 = 管理员，其他 = 普通用户
roleName	string	角色显示名称（"管理员" / "普通用户"）
tokens	number	用户的 Token 配额余量
totals	number	用户的总 Token 配额
expireDt	string	账号有效期
createDt	string	账号创建时间
updateDt	string	最后更新时间

角色系统

Snail AI 采用简洁的两级角色体系，满足大多数企业场景的权限需求。

管理员 (Admin)

属性	说明
角色标识	role = 2
超级角色	系统内部使用 R_SUPER 标识超级管理员
核心权限	拥有系统所有功能的完整访问权限

管理员可执行的操作包括：

• 用户管理：创建、编辑、删除用户账号；修改用户角色；重置用户密码
• 智能体管理：创建和管理所有智能体；设置企业精选
• 模型管理：配置和管理全局模型；设置默认模型
• 知识库管理：创建和管理所有 RAG 知识库
• MCP 管理：配置和管理所有 MCP 服务
• 系统配置：查看仪表盘、管理资源、查看全局追踪数据
• 授权管理：为用户分配 Token 配额和生成授权码

普通用户 (Normal User)

属性	说明
角色标识	role != 2（通常为 1 或其他值）
核心权限	使用已发布的智能体进行对话，管理个人资源

普通用户可执行的操作包括：

• 对话交互：与已订阅或已分配的智能体进行对话
• 智能体市场：浏览市场中的智能体并进行订阅
• 个人设置：修改个人密码、查看个人信息
• 个人资源：上传和管理个人范围内的资源

权限对照表

功能模块	管理员	普通用户
用户管理	完全控制	仅查看和修改自己的信息
智能体管理	创建/编辑/删除所有智能体	使用已授权的智能体
模型管理	全局配置和管理	使用全局模型，管理个人模型
RAG 知识库	创建/管理所有知识库	无
MCP 服务	配置/管理所有 MCP	无
可观测性	查看所有追踪数据	查看个人对话追踪
仪表盘	完整访问	受限访问
授权管理	生成授权码、分配配额	无

用户 CRUD 操作

创建用户

管理员可以在用户管理页面创建新的用户账号。

操作步骤：

1. 进入用户管理页面
2. 点击新建用户按钮
3. 填写用户信息表单：

表单字段	必填	说明
用户名	是	登录用户名，系统内唯一
邮箱	否	用户邮箱地址
密码	是	初始登录密码
角色	是	选择"管理员"或"普通用户"
配额	否	初始 Token 配额数量

4. 点击确认完成创建

API 接口：

POST /user

请求体：

{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "password": "initial_password",
  "role": 1,
  "totals": 100000
}

编辑用户

管理员可以修改用户的角色、邮箱等信息。

API 接口：

PUT /user/{id}

请求体：

{
  "role": 2,
  "email": "newemail@example.com"
}

修改用户角色

可以单独修改用户的角色，而无需更新其他字段。

API 接口：

PUT /user/{id}/role?role=2

查询用户列表

支持按邮箱搜索和分页查询。

API 接口：

GET /user/page/list?page=1&size=20&email=zhang

响应结构：

{
  "data": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": 2,
      "roleName": "管理员",
      "tokens": 500000,
      "totals": 1000000,
      "expireDt": "2026-12-31 23:59:59",
      "createDt": "2025-01-01 00:00:00",
      "updateDt": "2025-06-15 12:00:00"
    }
  ],
  "page": 1,
  "size": 20,
  "total": 1
}

密码管理

管理员重置密码

管理员可以为任意用户重置密码，适用于用户忘记密码的情况。

API 接口：

PUT /user/{id}/password

请求体：

{
  "password": "new_password_123"
}

安全提示

重置密码后，请及时通知用户，并建议用户在首次登录后立即修改密码。

用户修改密码

用户可以自行修改自己的登录密码，需要提供旧密码进行验证。

API 接口：

PUT /user/password

请求体：

{
  "oldPassword": "current_password",
  "newPassword": "new_secure_password"
}

密码安全建议

• 密码长度建议不少于 8 位
• 建议包含大小写字母、数字和特殊字符的组合
• 定期更新密码，建议每 90 天更换一次
• 避免使用与用户名、邮箱相同或相似的密码

Token/配额授权

Snail AI 通过 Token 配额机制控制用户对 AI 服务的使用量。每次模型调用会消耗一定数量的 Token，当配额耗尽后，用户将无法继续使用对话功能。

配额概念

字段	说明
tokens	当前剩余 Token 数量
totals	总分配的 Token 数量
expireDt	配额有效期，过期后即使有余量也无法使用

Token 消耗规则

每次与智能体对话时，系统根据模型的输入和输出 Token 数自动扣减用户的 Token 配额：

配额分配

管理员可以为用户分配 Token 配额：

1. 创建时分配：在创建用户时通过 totals 字段设置初始配额
2. 授权码方式：通过生成授权码进行配额分配（见下一节）

授权码

授权码是 Snail AI 提供的一种灵活的 Token 配额分发机制，管理员可以生成授权码发送给用户，用户通过兑换授权码获得 Token 配额和使用期限。

生成授权码

管理员可以为指定邮箱的用户生成授权码。

API 接口：

POST /user/authorize/code

请求体：

{
  "email": "zhangsan@example.com",
  "days": 30,
  "totals": 100000
}

请求参数说明：

字段	类型	说明
email	string	目标用户的邮箱地址
days	number	授权有效天数，从兑换日开始计算
totals	number	授予的 Token 配额数量

授权码使用流程

授权码适用场景

• 试用分发：为潜在用户生成限时试用授权码
• 按需充值：按项目或部门需求分批分配配额
• 活动推广：在推广活动中批量生成授权码
• 到期续期：为到期用户生成续期授权码

API 接口总览

方法	路径	说明	权限
GET	/user/page/list	分页查询用户列表	管理员
POST	/user	创建用户	管理员
PUT	/user/{id}	更新用户信息	管理员
PUT	/user/{id}/role	修改用户角色	管理员
PUT	/user/{id}/password	重置用户密码	管理员
PUT	/user/password	修改自己的密码	所有用户
POST	/user/authorize/code	生成授权码	管理员

最佳实践

初始化部署

1. 使用默认管理员账号 admin / admin123 首次登录
2. 立即修改默认管理员密码，确保系统安全
3. 根据组织结构创建用户账号，分配适当的角色
4. 为每个用户设置合理的 Token 配额和有效期

日常管理

• 定期审查账号：清理不活跃的账号，回收未使用的配额
• 角色最小化：只为真正需要的人员分配管理员角色
• 配额监控：定期检查用户的配额使用情况，及时补充
• 密码策略：建议用户定期更换密码，管理员发现异常时主动重置

安全注意事项

重要安全提醒

• 首次部署后必须修改默认管理员密码
• 管理员角色应严格控制分配范围
• 授权码生成后应通过安全渠道发送给用户
• 建议在生产环境中启用 HTTPS 加密通信

下一步

• 智能体管理 -- 了解如何创建和配置智能体
• 仪表盘 -- 查看系统总览和用户活跃数据
• 资源管理 -- 管理用户头像等文件资源