OneAPI多租户权限分离隔离下游用户
为什么需要OneAPI多租户权限隔离
当团队或企业使用 OneAPI（一个统一管理多种 AI 模型 API 的网关）时，往往会有多个部门或外部用户同时接入。
如果不做租户隔离，一个用户就能调用所有已配置的模型，这不仅浪费额度，还存在数据泄露风险。
多租户权限分离的核心目的是：每个租户只能使用管理员允许的模型，无法越权访问其他租户的资源或未授权的 API。
前置准备：确认OneAPI环境与基本概念
- 确保 OneAPI 已正常运行 – 你可以通过浏览器访问管理后台（默认端口 3000），使用超级管理员账号登录。如果还没安装，请先参考官方文档部署。
- 理解几个关键概念：
- 租户（User/Team）：代表一个独立的使用单位，可以是一个部门、一个客户或一个子账号。
- 令牌（Token）：租户调用 API 时使用的密钥，不同令牌属于不同租户。
- 模型分组（Model Group）：将多个模型（如 GPT-4、Claude 3）组合成一个授权单位，方便分配给租户。
如果你是第一次接触 OneAPI，建议先在管理后台熟悉“用户管理”和“令牌管理”页面。
核心操作：创建租户、分配模型、生成令牌
步骤1：创建租户（子账号）
- 登录管理后台，左侧导航点击 用户管理。
- 点击 添加用户，输入用户名、显示名称（例如“研发部”或“客户A”），设置密码。关键在于选择角色为“普通用户”，这样该账号无法查看其他租户信息。
- 保存后，新用户即成为一个独立租户。
步骤2：配置模型分组（可选但推荐）
- 进入 模型分组 页面，点击 添加分组。
- 输入分组名称（如“开发组模型”），在右侧勾选允许该分组使用的模型（如只勾选 GPT-3.5-turbo 和 Claude-2）。
- 保存后，你可以在后续步骤中将这个分组直接分配给租户，避免每次单独勾选模型。
步骤3：为租户分配模型权限
- 回到 用户管理，点击刚刚创建的用户进入编辑页。
- 在 模型权限 区域，你可以直接勾选允许的模型，或者选择已创建的模型分组。注意：如果不做任何授权，该租户将无法调用任何模型。
- 保存用户配置。
步骤4：生成租户专属令牌
- 仍在该用户编辑页面，切换到 令牌 标签。
- 点击 添加令牌，设置令牌名称和过期时间（建议设置合理有效期，降低泄露风险）。
- 创建后复制令牌字符串。这个令牌将用于下游用户发起 API 请求，它会自动携带该租户的权限范围。
小提示：你可以为同一个租户生成多个令牌，每个令牌权限相同，方便分发或轮换。
验证隔离效果：用不同令牌测试访问
- 使用超级管理员令牌调用任意模型，确认能成功。
- 使用租户 A 的令牌调用其被授权的模型（如 GPT-3.5-turbo），应该正常返回。
- 使用租户 A 的令牌调用未被授权的模型（如 Claude-2），OneAPI 应返回 403 无权限 或类似错误。
- 如果租户 B 的令牌只能调用自己的模型，且无法访问租户 A 的模型，说明权限隔离生效。
验证命令示例（使用 curl）：
# 假设你的 OneAPI 地址是 http://localhost:3000
# 租户A的令牌，只能调用 GPT-3.5-turbo
curl http://localhost:3000/v1/chat/completions \
-H "Authorization: Bearer sk-tenantA-token123" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}]}'
# 尝试调用未授权的模型，应返回403
curl http://localhost:3000/v1/chat/completions \
-H "Authorization: Bearer sk-tenantA-token123" \
-H "Content-Type: application/json" \
-d '{"model": "claude-2", "messages": [{"role": "user", "content": "Hello"}]}'避坑指南与常见问题
1. 令牌泄露怎么办？
立即在管理后台删除该令牌，并为该租户生成新令牌。
同时建议开启令牌到期自动轮换。
2. 为什么租户能调用所有模型？
检查是否在用户编辑页的“模型权限”里勾选了“所有模型”，或者该用户是管理员角色。
确保角色为“普通用户”且未勾选全局权限。
3. 模型分组和直接勾选模型冲突吗？
不冲突。
如果同时设置了分组和单个勾选，最终权限是两者的并集。
为了清晰，建议统一使用分组管理。
4. 下游用户拿到令牌后，能通过API查看其他租户信息吗？
不能。
普通用户令牌只能调用模型接口，无法访问管理后台或用户列表。
OneAPI 天然隔离了管理 API 和模型 API。
总结
通过以上步骤，你已能在 OneAPI 中实现多租户权限分离，将下游用户严格隔离在各自的模型范围内。
核心操作就是：创建普通用户 → 分配模型权限 → 生成专属令牌 → 分发给下游用户。
验证时务必用不同令牌测试越权场景，确保隔离生效。
如果你在配置过程中遇到其他异常，可以查看 OneAPI 官方文档或社区讨论。
