OneAPI多租户权限隔离防止下游密钥泄露
为什么需要OneAPI多租户权限隔离
如果你在用OneAPI给不同团队或客户分配API密钥，但每个密钥都拥有全部模型权限，一旦某个下游用户泄露或滥用密钥，其他租户的调用就会受影响甚至被盗刷。多租户权限隔离就是让每个租户只能访问自己被授权的模型、渠道和速率限制，即便密钥泄露，攻击者也拿不到其他租户的资源。
本文适合刚接触OneAPI的运维人员，按步骤操作即可实现安全隔离。
动手前的环境检查清单
开始前请确认：
- OneAPI版本不低于 0.5.0（旧版本可能不支持完整的租户隔离）
- 已部署OneAPI并能正常登录管理面板（默认地址
http://你的IP:3000） - 已添加至少 两个渠道（例如OpenAI和Azure）作为测试资源
- 准备好一个普通账号邮箱（用于创建租户）
如果还不熟悉OneAPI部署，可以参考官方GitHub仓库的docker-compose配置。
三步配置租户权限与密钥隔离
第一步：创建租户并绑定用户
- 使用管理员账号登录OneAPI管理面板。
- 进入 用户管理 → 添加用户，填入邮箱、密码，角色选择 普通用户。点击确认。
- 进入 令牌管理 → 添加令牌，选择刚创建的用户，设置令牌名称、过期时间，并勾选你需要限制的模型组（例如只允许GPT-4调用）。注意：不要勾选“无限额度”，建议填写每日调用上限。
- 将该令牌（即API Key）提供给下游租户使用。
配置要点：每个租户对应一个独立用户，每个用户下生成专用令牌。
不同租户的令牌之间完全没有关联。
第二步：通过渠道组限制模型来源
为了避免租户使用未授权的渠道，需要创建渠道组并绑定模型：
- 进入 渠道管理，将每个渠道分配到一个 渠道分组（例如
group-a、group-b）。 - 在 令牌管理 编辑刚才创建的令牌，在“模型设置”中填入允许的模型名（如
gpt-4），在“渠道分组”中填入允许的渠道分组（如group-a）。 - 保存后，该令牌只能通过
group-a渠道调用gpt-4，不会访问其他渠道。
第三步：设置速率限制与额度警报
- 在 令牌管理 中设置 速率限制（如每分钟10次），防止单个租户爆发式调用。
- 开启 额度限制，填写每日/每月上限。
- 建议在 系统设置 → 通知 中配置钉钉/邮件告警，当某个令牌达到80%额度时接收通知。
最容易踩的三个坑
坑1：忘记取消“无限额度”
新建令牌时默认勾选“无限制”，务必手动关闭，否则即便权限隔离了，流量也能刷爆。
坑2：渠道分组写错或漏填
如果令牌的渠道分组与渠道实际分组不一致，调用会报错“No available channels”。检查步骤：在令牌编辑页确认渠道分组名与渠道管理中的分组名完全一致（区分大小写）。
坑3：令牌未绑定用户
直接通过管理员创建令牌而不指定用户，该令牌会属于管理员账户而不是租户。一定是先创建普通用户，再在该用户下生成令牌。
模拟下游泄露：验证隔离是否生效
- 取一个租户令牌，用
curl测试调用受限模型：
curl http://你的IP:3000/v1/chat/completions \
-H "Authorization: Bearer 你的租户令牌" \
-d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'应正常返回结果。
- 尝试调用该令牌未被授权的模型（如
gpt-3.5-turbo），应返回404 model not found或403。 - 尝试用该令牌调用其他渠道（如更改模型为
claude-2），必须返回无可用渠道错误。 - 用另一个租户的令牌重复上述测试，应互不影响。
如果以上全部通过，说明多租户权限隔离已生效。
高频提问与排错
Q：租户令牌泄露了怎么办？
A：在令牌管理中立即删除或禁用该令牌，然后通知租户重新生成。不会影响其他租户。
Q：为什么设置了渠道分组但调用还是成功？
A：检查令牌的“模型设置”是否明确限制了模型名，若留空则表示允许所有模型，渠道分组限制无效。
Q：同一个用户可以有多个令牌吗？
A：可以，每个令牌独立限制，适合为同一个租户的不同应用分配不同权限。
完成上述配置后，你的OneAPI服务就能安全地托管多个租户，即使下游密钥泄露也不会波及全局。
如果遇到其他异常，建议优先查看OneAPI日志（docker logs -f one-api）定位问题。
