管理员指南
用户管理
管理用户账户、角色、分组、额度、登录绑定、安全凭证和订阅。
- 用户管理仅 Admin 和 Root 可访问，从侧边栏「管理员」 → 「用户」或访问
/users进入。 - 用于查看和筛选用户，管理角色、状态与管理员权限，维护账户资料、额度、登录绑定、订阅、Passkey 与 2FA，以及删除用户。
- 注册与登录方式、分组价格、订阅套餐等全局规则分别见身份验证配置、计费与支付配置和订阅管理。
用户管理概览
页面顶部为关键词搜索框和「状态」「角色」「用户分组」筛选，右侧为「添加用户」和「查看」；每行末尾为编辑（铅笔）按钮和「…」操作菜单。
- 用户管理-用户列表
列表字段
用户列表默认展示以下信息。右上角「查看」按钮可以控制部分列的显示或隐藏。
| 列 | 说明 |
|---|---|
| ID | 用户的唯一数字标识。 |
| 用户名 | 上方为登录用户名；设置了备注时，用户名旁显示备注标签（仅管理员可见，悬停查看全文）；显示名称与用户名不同时显示在下方。 |
| 状态 | 已启用、已禁用或已注销。「已注销」是用户在个人设置中自行注销的账户，记录保留在列表中，不显示任何操作。 |
| 可用余额 | 列名带当前显示单位，如「可用余额 ($)」。上行为剩余额度（为负时标红），下行为已用额度，两者都为 0 时显示「无余额」；显示单位跟随平台的计费设置。 |
| 用户分组 | 用户当前所属分组。分组会影响可用模型、渠道匹配和计费倍率等后续规则。 |
| 角色 | 用户、管理员或 Root。 |
| 邀请信息 | 已邀请人数、邀请收益额度和邀请人 ID；三项都为空时显示「—」。 |
| 时间 | 上行为创建时间，下行为最后登录时间（从未登录时为「-」）；按此列排序时按创建时间排序。 |
| 操作 | 铅笔图标为编辑；「…」菜单含启用/禁用、提升/降级、管理绑定、管理订阅、重置 Passkey、重置 2FA、删除。Root 行的禁用、重置 Passkey、重置 2FA、删除置灰，且没有降级；已注销用户不显示任何操作。 |
角色层级、状态和权限
角色层级
| 角色 | 后端值 | 管理范围 |
|---|---|---|
| 用户 | 1 | 普通使用者，不可访问用户管理页面。 |
| Admin | 10 | 可管理普通用户；不能管理同级 Admin 或 Root 的账户资料和安全设置。 |
| Root | 100 | 可管理普通用户和 Admin；对 Root 账户可编辑资料、管理绑定和订阅，界面不提供禁用、降级、删除、重置 Passkey 和重置 2FA。 |
角色状态
- 用户管理-操作菜单
点击「…」展开操作菜单，可执行启用、禁用、提升、降级；这四项操作提交前都需要完成安全验证。
| 操作 | 适用对象 | 行为与限制 |
|---|---|---|
| 启用 | 已禁用用户 | 将状态改为启用。操作仍需满足目标角色层级权限。 |
| 禁用 | 已启用用户 | 将状态改为禁用；Root 不能被禁用。禁用适合临时阻止登录和调用，不会删除账户记录。 |
| 提升 | 普通用户 | 只有 Root 可以把普通用户提升为 Admin。 |
| 降级 | Admin | 将 Admin 改为普通用户；Root 不能被降级。降级时会清除该账户的细粒度权限覆盖并撤销现有会话。 |
角色或状态发生认证敏感变化时，系统会更新认证状态、清理相关缓存并撤销用户会话。
管理员权限
管理员权限即 Admin 权限矩阵。Root 新建或编辑角色为「管理员」的用户时，抽屉下方显示「管理员权限」区块，可为该账户覆盖默认的 Admin 权限：每个资源一行，点击权限按钮授予或撤销，资源名旁的 ⓘ 显示各项说明。修改权限需要完成安全验证，保存后立即生效。普通 Admin 看不到该区块。
| 资源 | 权限名称 | API 动作键 | Admin 默认 | 说明 |
|---|---|---|---|---|
| 审计日志 | 查看其他账户审计日志 | read | 否 | 查看普通用户和 Admin 的审计记录，始终不含 Root 级别记录。 |
| 渠道管理 | 读取渠道 | read | 是 | 查看渠道列表和不含完整密钥的渠道信息。 |
| 渠道管理 | 运维渠道 | operate | 是 | 测试渠道、刷新余额，以及启用或禁用渠道等运维动作。 |
| 渠道管理 | 编辑渠道路由 | write | 是 | 编辑模型、分组和路由规则等非敏感设置。 |
| 渠道管理 | 编辑敏感渠道设置 | sensitive_write | 否 | 创建渠道，或修改密钥、Base URL、覆盖规则等敏感配置。 |
| 渠道管理 | 查看渠道密钥 | secret_view | 否 | 预留用于在安全验证后查看完整渠道密钥。 |
| 任务插件 | 绑定任务插件 | bind | 否 | 列出已注册的任务插件，并在创建或编辑任务插件渠道时绑定。 |
安全验证
以下操作提交前会弹出验证对话框（标题如「验证后删除用户」），需要当前操作者再次验证身份，通过后才会执行：
- 启用、禁用、提升、降级用户；
- 删除用户；
- 重置 Passkey、重置 2FA；
- 在「管理绑定」中解除绑定；
- 编辑用户时修改密码或管理员权限；
- 创建角色为「管理员」的用户。
验证方式与个人账户的敏感操作相同：已启用 2FA 或已注册 Passkey 时使用 2FA 或 Passkey，否则使用账户密码，没有密码的账户使用已绑定的第三方登录，见身份验证配置。
- 创建普通用户、只修改显示名称/分组/备注、「调整额度」和订阅管理不需要安全验证。
- 关闭密码登录或 Passkey 功能后，对应方式不能用于验证；操作者没有其他可用方式时无法完成上述操作，应先在个人设置中启用 2FA。
用户管理操作
搜索、筛选和排序
| 控件或参数 | 说明 |
|---|---|
| 关键词 | 匹配用户名、邮箱和显示名称；输入纯数字时还会精确匹配用户 ID。 |
| 状态筛选 | 可筛选「已启用」「已禁用」「已注销」。 |
| 角色筛选 | 可筛选「用户」「管理员」「Root」。 |
| 用户分组筛选 | 按用户当前分组筛选，选项来自系统已配置的分组。三个筛选均为单选，可组合使用。 |
| 排序 | 点击「ID」「用户名」「可用余额」「用户分组」「时间」列头可升序或降序排序；「时间」列按创建时间排序。 |
| 分页 | 查询、筛选和排序在服务端完成后再分页。桌面端默认每页 20 条，移动端默认每页 10 条；服务端单次最多返回 100 条。 |
添加用户
- 用户管理-新建用户
- 点击右上角「添加用户」。
- 填写用户名和密码；创建时密码不能为空。
- 按需填写显示名称，留空时系统使用用户名。
- 选择「普通用户」（默认）或「管理员」角色，点击「保存更改」；创建管理员时需先完成安全验证。
- 仅 Root 可添加管理员用户。
- Root 添加或编辑管理员用户时，可在抽屉下方的「管理员权限」区块为其设置权限，见管理员权限。
字段说明：
| 字段 | 必填 | 校验与行为 | 注意事项 |
|---|---|---|---|
| 用户名 | 是 | 最长 20 个字符；用户名要求必须唯一。 | 用户名不可更改 |
| 角色 | 是 | 当前界面可选「普通用户」或「管理员」；不能创建 Root。 | Admin 只能创建普通用户；Root 可以创建普通用户和 Admin。 |
| 显示名称 | 否 | 最长 20 个字符；留空时使用用户名。 | 用于列表和用户界面展示，不改变登录用户名。 |
| 密码 | 是 | 长度为 8–128 个字符。 | 不要把初始密码写入截图、工单或共享文档。 |
编辑用户信息
- 用户管理-更新用户
- 在目标用户行点击铅笔图标。
- 核对用户名，修改允许编辑的字段。
- 若要调整剩余额度，点击「调整额度」打开独立对话框 → 选择模式 → 输入金额并确认，不要直接修改只读额度字段。
- 点击「保存更改」；修改了密码或管理员权限时，需先完成安全验证。等待成功提示后重新加载列表。
可编辑字段：
| 字段 | 编辑规则 | 说明 |
|---|---|---|
| 用户名 | 只读。 | 不可修改登录用户名。 |
| 显示名称 | 可修改，最长 20 个字符。 | 更新列表和用户端展示名称。 |
| 密码 | 留空表示保持不变；输入新密码时必须满足 8–128 个字符。 | 修改密码会撤销该用户现有浏览器会话，用户需要重新登录。 |
| 分组 | 从当前可用分组中选择。 | 用户当前所属分组。分组会影响可用模型、渠道匹配和计费倍率等后续规则；修改分组同样会撤销该用户现有会话。 |
| 剩余额度 | 用户钱包的余额 | 使用「调整额度」进行余额增减或覆盖 |
| 备注 | 仅管理员可见，最长 255 个字符。 | 适合记录内部说明，不要写入密钥、Token 或不必要的个人敏感信息。 |
| 管理员权限 | 仅 Root 编辑 Admin 时显示。 | 见管理员权限；修改后保存需完成安全验证。 |
| 角色 | 不可在编辑抽屉中修改。 | 使用「…」菜单中的「提升」「降级」。 |
| 绑定信息 | 只读展示 GitHub ID、Discord ID、OIDC ID、WeChat ID、邮箱、Telegram ID。 | 仅可查看；完整绑定列表（含 LinuxDO 和自定义 OAuth）和解除绑定需从菜单进入「管理绑定」。 |
用户绑定管理
- 用户管理-账户绑定管理
管理绑定对话框可以展示邮箱、GitHub、Discord、OIDC、微信、Telegram、LinuxDO 以及已配置的自定义 OAuth 提供商。停用的提供商仍可能因历史绑定出现在列表中。
查看或解除绑定：
- 点击目标用户的「 ... 」展开操作菜单，选择「管理绑定」。
- 对话框默认显示已绑定方式；点击「显示全部」可同时查看未绑定和已禁用的提供商，按钮随之变为「仅已绑定」。
- 核对用户名、用户 ID、提供商名称和外部账号标识。
- 若需要解除绑定，点击用户已绑定提供商卡片右上角的解除绑定图标，在「确认解绑」中确认，再完成安全验证。
- 管理绑定对话框只提供解除绑定，不会替用户建立新的邮箱、OAuth、Passkey 或其他登录方式。
- 解除绑定前应确认用户仍有密码或其他可用恢复方式；解除后，用户不能再通过该身份登录。
用户订阅管理
- 用户管理-用户订阅管理
点击目标用户的「 ... 」展开操作菜单，选择「管理订阅」打开管理订阅面板：
- 可以查看该用户的订阅记录、套餐、来源、状态、有效期和额度使用情况。
- 订阅管理面板还提供添加订阅、重置订阅额度、订阅作废和订阅删除操作。
订阅列表字段与状态
| 字段 | 说明 |
|---|---|
| ID | 订阅记录的唯一标识。 |
| 套餐 | 套餐名称和订阅来源；管理员代绑的来源通常为 admin。 |
| 状态 | 生效、已作废、已过期。 |
| 有效期 | 开始时间和结束时间，按创建该订阅时的套餐有效期计算。 |
| 总额度 | 显示已用额度/总额度；总额度为 0 时显示「无限制」。单位跟随实例计费设置。 |
| 操作 | 行内菜单提供「重置额度」「作废」「删除」；添加订阅使用顶部的「新增订阅」。 |
添加订阅
- 在顶部套餐选择框中选择一个管理端可用套餐。
- 核对套餐名称、价格显示和目标用户。
- 点击「新增订阅」，等待成功提示。
- 创建成功后重新加载列表，检查来源、有效期和额度。
- 添加订阅是管理员代绑，不会创建支付订单，但接口要求实例已完成支付合规确认，并会再次校验套餐 ID 和单用户购买上限。
- 购买上限统计该用户在此套餐下已经存在的全部订阅记录，包括生效、已过期、已作废的订阅记录；只有删除旧记录才会释放名额。
重置订阅额度
- 在目标套餐的有效订阅行打开操作菜单，选择「重置额度」。
- 确认该操作会影响该用户该套餐下的所有有效、未过期订阅额度。
- 根据需要保留或关闭「推进下次重置时间」。该开关默认开启。
- 确认后查看返回的重置数量并重新加载列表。
重置会把匹配订阅的已用额度清零。开启推进时，系统按套餐当前的重置规则重新计算下一次重置时间；关闭时只清零已用额度并保留原重置时间。
订阅作废与订阅删除
「重置额度」和「作废」仅对「生效」状态的订阅可用；「删除」对任何状态的订阅都可用，删除生效中的订阅前，请先确认是否应改用「作废」。
| 影响方面 | 订阅作废 | 订阅删除 |
|---|---|---|
| 处理方式 | 在原记录上将 status 改为 cancelled，并把 end_time 设置为当前时间 | 从 user_subscriptions 表中物理删除整条记录 |
| 订阅记录 | 保留订阅历史、套餐信息、额度总量、已使用额度、来源和分组快照 | 记录及其中保存的权益、额度、状态、时间和分组快照全部消失 |
| 后续新请求 | 不再被识别为有效订阅，不能作为新的订阅额度来源 | 同样不再被识别为有效订阅 |
| 用户分组 | 可能触发分组回退 | 也可能触发同样的分组回退，然后删除快照 |
| 钱包余额 | 不增加钱包余额 | 不增加钱包余额 |
| 支付金额 | 不退款，不修改支付订单 | 不退款，不修改支付订单 |
| 未使用额度 | 不返还，amount_used 不清零 | 随订阅记录一起消失，但不会转入钱包或其他账户 |
| 使用日志/任务日志 | 不删除 | 不删除，日志中的订阅 ID 可能变成历史引用 |
| 购买次数限制 | 由于记录仍存在，仍会计入套餐购买次数 | 删除后不再计入现存记录数量 |
| 恢复方式 | 没有“恢复作废”操作，只能重新创建订阅 | 没有恢复入口，通常无法找回 |
| 进行中的请求/任务 | 因记录仍存在，后续结算或退款通常仍可按订阅 ID 完成 | 后续按订阅 ID 查询可能失败，结算或退款可能无法完成 |
实际使用建议
- 需要停止订阅继续生效，但保留完整历史记录：使用“作废”。
- 仅在确认记录错误、测试数据或确实不需要保留历史时使用“删除”。
- 如果涉及退款，应单独执行退款流程，不能把作废或删除当作退款。
- 删除前应确认没有正在处理的请求、异步任务或待完成的退款。
重置 Passkey
- 用户管理-重置 Passkey
- 在用户行菜单选择「重置 Passkey」。
- 核对确认框中的用户名。
- 确认并完成安全验证后，系统删除该用户现有的 Passkey 凭证，并撤销其全部登录会话。
- 用户需要重新注册 Passkey，之后才能继续使用无密码登录。
重置前，确认该用户仍有可用的登录方式：已设置密码、已绑定可用的第三方账号，或已绑定可接收重置邮件的邮箱。否则用户在重置后无法登录，也无法重新注册 Passkey。
重置 2FA
- 用户管理-重置 2FA
- 在用户行菜单选择「重置 2FA」。
- 确认将删除现有的 2FA 因子和备用码。
- 确认并完成安全验证后，系统更新认证版本并撤销该用户的全部登录会话。
- 用户需要在个人设置中重新配置 2FA。
删除用户
- 在目标行打开「…」菜单，选择「删除」。
- 在确认框「您确定吗？」中核对用户名和「此操作无法撤销」提示，点击「删除」。
- 完成安全验证后等待成功提示，并重新加载列表。
硬删除会清理用户主记录及源码明确关联的认证数据，包括：
- API Token 和其他用户认证令牌；
- 浏览器会话和认证流程记录；
- Passkey 凭证；
- 2FA 配置和备用码；
- 内置第三方身份占用记录；
- 自定义 OAuth 绑定。
- 当前页面的删除按钮调用
DELETE /api/user/:id，执行永久硬删除。 - 只有角色层级严格高于目标角色的操作者可以执行，Root 账户不能通过此流程删除。
- 删除前应先导出或保存组织要求留存的审计信息，因为当前页面没有恢复入口。
- 用户硬删除不可撤销。若只是暂时阻止登录和调用，请使用「禁用」；只有在确认数据范围、留存要求和后续恢复方案后，才执行「删除」。
- 此处删除的用户会从列表中消失；用户在个人设置中自行注销的账户则以「已注销」状态保留在列表中，不提供任何操作。