用户、分组与权限

:::info 学习目标 完成本篇后你能够：说出 User 模型四个关键字段各自管什么；用「三重作用」框架解释分组的全部行为；设计一套多租户分组方案（用户组/令牌组/auto 组）。 前置：第 3 篇完成。预计时长：45 分钟。 :::

:::note 本章术语速查（新手建议先读）

• 多租户：一套系统服务多个互不干扰的客户/团队。
• 分组（Group）：new-api 的核心维度——一个字段同时决定”能用什么渠道、走哪条路、按什么价格”。
• Role（角色）：1 普通用户 / 10 管理员 / 100 超级管理员。
• auto 分组：特殊值——自动选”第一个还有可用渠道的分组”，用于容灾。
• AuthVersion：用户改密码时 +1 的版本号，让所有旧凭证瞬间失效。 :::

网关是多租户系统：多个用户、多个团队、多种价位的令牌共享同一批上游渠道。new-api 用「分组（group）」这一个概念把多租户的三个独立诉求——谁能用什么、走哪条路、按什么价格——统一成一个可配置的维度。

用户模型：一个人，四个关键字段

model/user.go 的 User 结构里，与运行时行为强相关的字段：

字段	管什么
Role	控制台权限：1 常通 / 10 管理 / 100 root，对应三档鉴权中间件
Group	默认分组——本篇主角
Quota / UsedQuota	剩余/已用额度（内部计量单位，1 美元 = 500000，第 8 篇细讲）
AuthVersion	改密码/改分组时递增，使该用户全部旧凭据立即失效
AffCode	邀请返利体系（运营向）

AuthVersion 值得单独说：踢出一个用户的所有登录态与令牌，靠的就是把版本号 +1——鉴权链（第 3 篇）校验凭据时附带比对版本，旧凭据自然失效。不需要黑名单。

分组的三重作用

① 权限面。 service.GetUserUsableGroups(userGroup) 计算该用户的令牌允许切换到哪些分组（支持 +:/-: 特殊规则增减）。第 3 篇的 403「无权访问 X 分组」正是这道校验。

② 渠道选择。 渠道缓存按 group2model2channels 三级索引组织（第 10 篇）——同模型在不同分组走完全不同的渠道池。这是多租户隔离的物理边界：A 组用户无论怎么配置令牌，都碰不到 B 组的专属渠道。

③ 计费倍率。 GroupRatio（组倍率）与 GroupGroupRatio（用户组×请求组的嵌套倍率）参与价格公式（第 8 篇）。匹配顺序：先查「用户组×请求组」的特殊倍率，没有才落到普通组倍率——同一用户访问不同分组可以不同价，VIP 组可以整体八折再对特定组打折。

usingGroup 的最终判定

一次请求的生效分组按优先级覆盖（判定代码在第 3 篇摘录过）：

auto 是特殊值：按 autoGroups 配置顺序找到第一个有可用渠道的组，并在上下文标记 ContextKeyAutoGroup——“哪个组有货用哪个组”的动态路由，多渠道容灾利器。

渠道亲和：分组之上的选路微调

同组内还有一层「渠道亲和缓存」（controller/channel_affinity_cache.go）：同一用户/令牌的连续请求优先复用上次的渠道——对上游的缓存友好（如 KV cache、会话粘性）有立竿见影的效果。亲和未命中才落到第 7 篇的通用选路算法。

与其他模块的联系

• → 鉴权（第 3 篇）：分组的可用集合校验发生在 TokenAuth 内；AuthVersion 是鉴权失效机制的一部分；
• → 渠道（第 5 篇）：渠道的 Group 字段（逗号分隔多组）决定它出现在哪些组的索引里；
• → 计费（第 8 篇）：groupRatio 是价格公式的乘数之一；分组倍率变更经 Option 热更新即时生效；
• → 限流：ModelRequestRateLimit 的配额可按分组差异化配置。

常见踩坑

1. 令牌分组没配倍率——分组在可用集合但不在 GroupRatio 里，请求报”分组已被弃用”（auto 除外）；
2. 改了用户分组旧令牌仍能用——递增 AuthVersion 才是踢出旧凭据的正确姿势；
3. auto 组配了但组内全没渠道——auto 按顺序找第一个有渠道的组，全空则路由失败，先确认各组下有启用渠道；
4. 把分组当层级用——分组是平面的标签，不是树；需要层级关系时用 GroupGroupRatio 表达价格关系而非嵌套分组。

随堂练习（带验收标准）

1. 建两个分组（default 与 vip），各绑一个不同渠道，创建 VIP 用户的令牌请求。验收：vip 令牌只命中 vip 渠道，且日志里的分组字段正确；
2. 给 vip 组配 0.8 的组倍率，对比同一模型两组的消费日志。验收：倍率差体现在计费数字上；
3. 把令牌分组改成 auto 并配置 autoGroups 顺序，停掉第一组的渠道。验收：请求自动切到第二组；
4. 配一对 GroupGroupRatio（如 vip 组访问 special 组 0.9），验证特殊倍率优先于普通组倍率生效。