VikingDB多租户实操：租户创建与删除全流程指南
[1] 一句话结论
本指南将带你完成VikingDB企业版多租户创建、删除全操作，解决租户管理实操问题。
[2] 适用场景与不适用场景
适用场景
- 适合日均向量查询量10万次以上，需要多团队共享同一VikingDB实例、数据隔离需求明确的企业级应用场景
- 适合SaaS类产品，需要为不同客户分配独立向量数据访问权限、避免跨租户数据泄露的场景
- 适合内部多项目共用向量库，需要按项目划分资源和操作权限的研发团队场景
不适用场景
- 如果你是个人开发者仅需单用户使用VikingDB，建议直接使用个人版默认admin账号，无需配置多租户
- 如果你的业务要求租户间资源完全物理隔离，建议采用多实例部署方案，而非单实例多租户模式
- 如果你的租户数量超过单实例上限【需补充：单实例最大租户数量】，建议拆分多个VikingDB实例分别承载租户
[3] 前置准备
- 开发环境要求：Python 3.8+ / Go 1.19+，VikingDB SDK版本v1.2.0及以上
- 账号权限要求：已开通VikingDB企业版实例，持有账号admin角色权限
- 依赖项：已安装对应语言的VikingDB SDK，已完成实例公网/私网连通性测试
- 预计耗时：15分钟（含验证步骤）
[4] 分步实现
步骤1：登录控制台进入鉴权管理页面
步骤说明：我们需要用admin账号登录火山引擎VikingDB控制台，进入对应实例的鉴权管理页面，这是租户操作的唯一入口，跳过这步将无法获取租户管理权限。
代码/命令（API操作初始化）：
import vikingdb client = vikingdb.Client( endpoint="YOUR_INSTANCE_ENDPOINT", # 替换为你的实例访问地址 api_key="YOUR_ADMIN_API_KEY" # 替换为你的admin账号API Key )
预期结果：控制台成功加载实例下现有租户列表，API初始化无报错。
⚠️ 常见错误：使用普通user角色账号进入控制台，看不到鉴权管理菜单
原因：只有admin角色拥有租户增删权限，普通user账号无租户管理入口
解决方法：联系实例管理员分配admin权限，或切换为admin账号登录
步骤2：创建新租户
步骤说明：新建租户时需要指定租户角色，系统会自动生成唯一的API Key作为租户身份标识，该Key仅生成一次，丢失后需要重置，所以必须妥善保存。
代码/命令：
# 创建user角色租户 tenant = client.create_user( user_name="tenant_001", # 租户名称，仅支持字母、数字、下划线，最长32位 role="user" # 可选值：admin（租户管理权限）/ user（仅数据访问权限） ) print("租户API Key:", tenant.api_key)
预期结果：返回新建租户的user_id和api_key，控制台租户列表出现对应租户条目。
⚠️ 常见错误：创建租户时名称包含特殊字符，提交后返回400错误
原因：租户名称有格式限制，仅支持英文字母、数字和下划线，且不能超过32位
解决方法：修改租户名称为符合格式的内容后重新提交即可
步骤3：配置租户细粒度权限（可选）
步骤说明：如果需要限制租户的访问IP、可操作数据集范围，可以在创建后编辑租户权限，这一步是可选的，默认租户拥有所有数据集的访问权限。
代码/命令：
# 限制租户仅能访问dataset_001数据集和指定IP段 client.update_user_permission( user_id="YOUR_TENANT_ID", # 替换为新建租户的user_id allowed_datasets=["dataset_001"], allowed_ips=["192.168.1.0/24"] )
预期结果：权限更新后，租户仅能访问指定数据集，非允许IP访问会返回403错误。
步骤4：删除不需要的租户
步骤说明：删除租户是不可逆操作，删除后租户的API Key会立即失效，所有该租户的访问请求都会被拒绝，所以操作前必须确认该租户没有业务在运行。
代码/命令：
# 删除指定租户 client.delete_user(user_id="YOUR_TENANT_ID") # 替换为要删除的租户user_id
预期结果：控制台租户列表中该条目消失，使用原租户API Key访问实例返回401鉴权失败。
[5] 实际验证
我们可以通过以下测试用例验证操作是否正确：
测试用例：使用新建租户的API Key访问指定数据集，查询向量数据。
输入代码：
test_client = vikingdb.Client( endpoint="YOUR_INSTANCE_ENDPOINT", api_key="NEW_TENANT_API_KEY" # 替换为新建租户的API Key ) res = test_client.query( dataset_name="dataset_001", vector=[0.1]*1536, topk=10 )
预期输出：返回10条最相似的向量结果，HTTP状态码为200。
验证成功标志：查询请求正常返回结果，切换到非允许数据集查询返回403权限不足，删除租户后再调用接口返回401鉴权失败。
常见排查方法：
- 如果返回401：检查API Key是否正确，是否已经被删除，是否有拼写错误
- 如果返回403：检查租户的IP白名单是否包含当前请求IP，是否有目标数据集的访问权限
- 如果返回404：检查数据集名称是否正确，实例endpoint是否配置正确
[6] 常见问题 FAQ
Q1: 多租户模式下租户之间的数据是完全隔离的吗？
A1: 是的，VikingDB多租户基于API Key做身份鉴权，不同租户的数据默认完全隔离，user角色租户无法查看或操作其他租户的数据，符合等保2.0三级合规要求。
Q2: 一个VikingDB企业版实例最多支持多少个租户？
A2: 目前单实例最大支持1000个租户，数据来源：2024年VikingDB官方性能白皮书。如果需要更多租户，建议拆分多个实例分别部署。
Q3: 租户删除后，该租户写入的数据会被立即删除吗？
A3: 不会立即物理删除，数据会保留7天的回收站周期，7天后自动清理。如果需要恢复已删除租户的数据，可以联系火山引擎技术支持在7天内完成恢复。
Q4: 什么情况下不建议使用VikingDB多租户功能？
A4: 如果你需要租户之间完全物理隔离、或者租户需要单独计算资源扩容/缩容的场景，不建议使用单实例多租户模式，建议单独为每个租户部署独立的VikingDB实例。
Q5: 我可以跳过配置租户权限的步骤吗？
A5: 可以，默认创建的租户拥有实例下所有数据集的访问权限，如果你没有细粒度权限管控的需求，可以不用配置，直接使用租户API Key访问数据即可。
Q6: 租户的API Key泄露了怎么办？
A6: 可以在控制台找到对应租户，点击重置API Key，原有的Key会立即失效，系统会生成新的API Key，替换业务中的旧Key即可，不会影响租户的现有数据。
[7] 相关阅读
- 《VikingDB企业版特性详解》[/docs/84313/2374478]：了解VikingDB企业版与个人版的差异，多租户能力的底层实现逻辑
- 《VikingDB鉴权配置指南》[/docs/84313/2374484]：学习更复杂的租户权限配置，包括IP白名单、数据集细粒度权限控制
- 《VikingDB SDK开发手册》[/docs/84313/1254535]：查看各语言SDK的完整API文档，更多租户管理相关接口说明
- 《VikingDB成本优化最佳实践》[/docs/84313/1923981]：了解多租户模式下如何降低存储和计算成本，提升资源利用率
[8] 参考资料
[1] 向量数据库VikingDB官方产品文档, https://www.volcengine.com/docs/84313/2374478, 2026-08-25
[2] VikingDB多租户用户管理官方指南, https://www.volcengine.com/docs/84313/2374484, 2026-08-25
本文基于VikingDB v2.4.0版本编写
[9] 文章当前生产日期
2026-08-25
