OneAPI多租户权限分离杜绝下游数据互通泄露

为什么需要多租户权限分离

在团队使用 OneAPI 管理 AI 接口时，经常出现一个租户通过同一个渠道查看或调用其他租户的模型配额、对话记录。
这种“下游数据互通泄露”不仅违背最小权限原则，还可能引发费用纠纷。
OneAPI 本身支持多租户和细粒度权限控制，但默认配置不会自动隔离。
本文会从零开始，带你完成权限分离设置，确保每个租户只能访问自己的数据和额度。

准备工作

在开始操作前，确认你已经拥有 OneAPI 管理后台的超级管理员权限。
如果还没有部署 OneAPI，可以先用 Docker 快速启动：

docker run --name one-api -d -p 3000:3000 -e TZ=Asia/Shanghai --restart always ghcr.io/songquanpeng/one-api:latest

启动后访问 http://你的服务器IP:3000，用默认账号（root / 123456）登录，立刻修改密码。
至少准备好两个测试账号（团队），用于验证隔离效果。

分步配置：创建租户并设置独立令牌

1. 创建不同租户（团队）

进入管理后台 → 用户管理 → 点击“添加用户”。

• 用户名：team_a（示例）
• 角色：选择“普通用户”
• 填写显示名称、邮箱（可选）
• 点击“保存”

用同样方法创建 team_b。
两个用户即代表两个独立租户。

2. 为每个租户生成专用 API 令牌

分别以两个租户账号登录 OneAPI 用户面板（不是管理后台），在“令牌管理”中点击“添加令牌”。

• 名称：team_a_token
• 过期时间：建议选“永不过期”或合理时限
• 额度倍率：保持默认（1）
• 点击“提交”

复制生成的令牌字符串（以 sk- 开头），妥善保存。注意：同一令牌只能由一个租户使用，不可跨租户复用。

3. 配置渠道与用户组映射（关键）

回到管理后台 → 渠道管理 → 编辑你要分配的渠道（如 OpenAI、Azure 等）。

• 在“用户组”字段中填入你希望使用该渠道的组名（例如 team_a_only）
• 保存渠道

然后在 用户管理 中找到 team_a，在“用户组”列填入相同的组名（team_a_only）。
同理，给 team_b 单独建一个渠道或同一渠道不同分组，并配置对应的用户组。

原理： 用户组匹配渠道的用户组时，该用户才能调用对应渠道。
不同租户分配到不同组，即使使用了同一个底层 AI 服务，他们也只能看到自己组的模型和额度。

避坑指南：常见配置错误

令牌创建时选错用户

必须先用租户账号登录用户面板创建令牌，不要用管理员账号代劳。
否则令牌持有的权限是管理员的，会导致所有租户数据暴露。

用户组名称大小写不一致

OneAPI 的用户组匹配是严格大小写的。TeamA 和 teamA 视为不同组，导致租户无法调用渠道。
建议统一使用小写字母加下划线。

忘记给渠道绑定用户组

如果渠道的用户组留空，则所有用户（包括不同租户）都能看到它，隔离失效。
务必为每个敏感渠道指定明确的用户组。

效果验证：确认数据隔离

1. 用 team_a 的令牌调用 OneAPI 的 /api/usage 接口获取用量：

curl -H "Authorization: Bearer " https://你的OneAPI域名/api/usage

返回结果应该只包含 team_a 的用量信息。

1. 用同样方式测试 team_b 的令牌，返回 team_b 的数据。
2. 尝试用 team_a 的令牌访问 team_b 专有的模型（例如渠道名为 Azure-gpt4-team_b），应返回 403 或 没有权限。

如果以上步骤都通过，说明多租户权限分离配置成功，下游数据互通泄露风险已消除。

延伸与建议

• 如果租户数量较多，建议通过 OneAPI 的“分组管理”功能批量分配用户到组，减少手动操作。
• 定期审计所有令牌和用户组映射，确保没有多余的跨组权限。
• 本文仅针对 OneAPI 单实例隔离场景。如果你还需要多实例或多地域隔离，可参考官方文档进一步配置。