new-api 系列（四）：令牌与用户管理

new-api令牌管理用户管理额度控制IP限制教程

系列目录

  1. （一）认识 new-api——新一代 AI API 管理网关
  2. （二）安装部署——从零搭建 new-api
  3. （三）渠道配置——接入各类模型提供商
  4. （四）令牌与用户管理（本文）
  5. （五）计价模型与成本控制
  6. （六）监控、日志与告警
  7. （七）生产环境部署与安全加固
  8. （八）进阶——多实例、负载均衡与 SSO
  9. （九）接入国内支付——支付宝、微信与自动充值
  10. （十）接入国际支付——Stripe、PayPal 与海外收银
# 令牌与用户管理 ## 令牌（Token） - sk- 开头的访问凭证 - 绑定用户，独立计费 - 支持额度上限 - 支持过期时间 - 支持 IP 白名单 - 支持模型限制 ## 用户（User） - 令牌的归属主体 - 一个用户可以有多个令牌 - 角色：管理员 / 普通用户 - 普通用户可登录面板（受限视图） ## 额度策略 - 无限额度（填 0 或留空） - 固定额度（用完即停） - 周期额度（月/日自动重置） - 额度预警通知 ## 安全控制 - IP 白名单 / 黑名单 - 模型白名单（用户只能调用指定模型） - 令牌吊销

令牌（Token）概述

令牌是 new-api 中用户访问 API 的凭证，所有通过 new-api 的请求都必须携带一个有效的令牌。它在系统中的角色类似 API Key，但比单纯的 Key 多了一层管理维度——它绑定了额度、权限、限流策略。

每个令牌以 sk- 开头，生成后需要安全保存，因为 new-api 不会明文存储完整令牌（只存储哈希值），关闭创建弹窗后就无法再次查看。

flowchart LR U["用户"] -->|"Authorization: Bearer sk-xxx"| NA["new-api"] NA --> V{"验证令牌"} V -- 有效 --> Q["检查额度"] Q --> R["检查模型权限"] R --> P["转发到渠道"] V -- 无效/过期 --> E["401 / 403"]

创建令牌

后台 →「令牌」→「添加令牌」：

字段 说明 示例
名称 令牌标识，方便管理 alice-dev、project-alpha
用户 绑定到哪个用户（不选则绑定当前登录用户） alice
剩余额度 Token 配额，美元计价（见下节详解） 10（10 美元额度）
过期时间 令牌失效日期 2027-01-01
IP 限制 白名单（每行一个 IP/CIDR） 10.0.0.0/8
模型限制 允许调用的模型（每行一个），留空不限制 gpt-4o-mini

创建后弹出令牌值（sk-xxxxxxxxxxxxxxxx），复制并安全保存。

额度策略详解

new-api 的「剩余额度」单位是美元（USD），有几种设置策略：

策略一：无限额度

填 0 或不填，令牌无额度限制。适合管理员自用或信任的用户。

策略二：固定额度

填一个正整数，如 10，代表 10 美元额度。用完后令牌自动禁用，用户请求返回 429。

实际消耗金额由模型定价决定（见第五篇计价模型）。如果未配置自定义价格，new-api 使用默认倍率计费：输入 Token 和输出 Token 按固定倍率折算为美元。

策略三：自动重置额度

在令牌编辑页面，可以设置「自动重置」：

  • 每日重置：每天 0 点额度恢复为初始值
  • 每月重置：每月 1 日 0 点额度恢复

适合按月给团队成员分配配额。

策略四：组合使用

令牌 A：无限额度，绑定管理员，自用
令牌 B：每月 5 美元，自动重置，给初级工程师
令牌 C：固定 20 美元，不给重置，一次性使用
flowchart LR NA["new-api"] --> QA["令牌 A: 无限额度 管理员自用"] NA --> QB["令牌 B: 每月 5 美元 自动重置"] NA --> QC["令牌 C: 固定 20 美元 用完即停"]

用户管理

用户与令牌的关系

new-api 中，令牌是用户的子资源：

用户 alice
├── 令牌 alice-pc（桌面端）
├── 令牌 alice-laptop（笔记本）
└── 令牌 alice-mobile（手机端）

这种设计的好处：

  • 一个用户可以有多个令牌，在不同设备上使用
  • 所有令牌共享同一用户身份，方便统计总用量
  • 某个设备令牌泄露，可以只吊销该令牌而不影响用户

用户角色

new-api 支持两种角色：

角色 权限
管理员 完整后台权限：管理渠道、令牌、用户、系统设置
普通用户 只能看自己的令牌和用量，不能修改全局配置

普通用户可以登录 new-api 面板（需要管理员在「设置 → 通用设置」中开启「允许用户登录」），查看自己的用量、管理自己的令牌。

创建用户

后台 →「用户」→「添加用户」：

字段 说明
用户名 登录名
密码 登录密码（如需面板登录）
角色 管理员 / 普通用户
邮箱 可选，用于通知

普通用户视角

普通用户登录后看到的是简化版面板：

  • 仪表盘：自己的用量概览
  • 令牌：管理自己的令牌（创建、查看额度）
  • 日志：只看自己令牌的请求记录

他们看不到渠道配置、其他用户、全局设置等管理功能。

flowchart LR ADMIN["管理员登录"] --> FULL["完整面板\n渠道 / 用户 / 令牌 / 设置"] USER["普通用户登录"] --> SIMPLE["简化面板\n自己的令牌 / 用量 / 日志"]

IP 白名单与黑名单

new-api 支持在令牌级别限制访问 IP，防止令牌泄露后被滥用。

白名单模式

在令牌的「IP 限制」字段填写允许的 IP（每行一个）：

10.0.0.100
10.0.0.0/24
192.168.1.0/24

支持格式：

  • 单个 IP：10.0.0.100
  • CIDR 网段：10.0.0.0/24
  • 多个混合填写

只有来源 IP 在白名单内的请求才被接受，其余返回 403 Forbidden。

场景：限制团队办公网络

# 公司 VPN 出口 IP
203.0.113.50

# 办公室网段
192.168.10.0/24

# 家庭宽带（固定 IP）
198.51.100.10

注意

  • IP 限制适用于令牌级别的访问控制，不替代网络层防火墙
  • 如果 new-api 前面有 Nginx/Caddy 反代，需确保反代正确传递 X-Real-IP 或 X-Forwarded-For 头，否则 new-api 看到的永远是反代的 IP
# Nginx 反代配置中必须加上
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

模型访问控制

令牌级别的模型限制让管理员精确控制用户能调用哪些模型。

白名单模式

在令牌的「模型限制」字段填写允许的模型（每行一个）：

gpt-4o-mini
claude-haiku-4-5-20251001
deepseek-chat

用户只能调用列表中的模型，请求其他模型返回错误。

场景举例

  • 成本敏感用户：只给便宜模型 gpt-4o-mini、deepseek-chat
  • 特殊项目：给项目组单独开放 claude-opus-4-8 的令牌
  • 分级服务：基础版令牌只能用快模型，高级版令牌能用全部模型

令牌生命周期管理

令牌过期

设置过期时间后，到期自动失效，用户请求返回 401。适合：

  • 短期外包项目
  • 试用期用户
  • 临时调试令牌

令牌吊销

后台 →「令牌」列表 → 找到令牌 → 点击「禁用」或「删除」。

  • 禁用：令牌暂时失效，可以重新启用，日志保留
  • 删除：永久删除，日志仍保留（用于审计）

令牌轮换

定期更换令牌是最佳安全实践：

  1. 创建新令牌
  2. 通知用户切换到新令牌
  3. 确认切换完成后禁用旧令牌
  4. 观察一段时间后删除旧令牌

用量查询

后台 →「日志」页面，可按令牌名筛选，查看该令牌的所有请求记录：模型、Token 消耗、耗时、渠道。也支持导出 CSV 用于做账单。

对普通用户，他们登录面板后在「日志」页面只能看到自己令牌的记录。

系列导航

系列导航

实操清单

  • 创建独立管理员账号（sdmike，role 100），替换默认 root
  • 创建普通用户（pearl，role 1）
  • 为用户创建令牌（当前共 4 个令牌）
  • 处理负额度令牌：令牌「default」（id:4）余额为 -95，已超支——决定是充值、清零还是禁用
  • 对关键令牌配置 IP 白名单（当前所有令牌均未配置）
  • 对成本敏感用户开启模型白名单（model_limits_enabled，当前所有令牌均未启用）
  • 设置令牌过期时间（当前所有令牌 expired_time = -1，永不过期，确认符合预期）
  • 验证普通用户（pearl）可以登录面板并看到受限视图
  • Caddy 反代已配置，ServerAddress 已正确填写（https://airouter.k330.com）
  • 在日志页面按令牌过滤，确认各令牌用量记录正常