ContextQMD
Back to Openviking

OpenViking Multi-Tenant 示例

examples/multi_tenant/README.md

0.3.145.8 KB
Original Source

OpenViking Multi-Tenant 示例

演示 OpenViking 多租户管理功能：账户创建、用户注册、角色管理、Key 管理、数据访问。

架构

                        Admin API (ROOT key)
                       ┌─────────────────────────┐
                       │  Create/Delete Accounts  │
                       │  Register/Remove Users   │
                       │  Set Roles, Regen Keys   │
                       └────────┬────────────────┘
                                │
                                ▼
┌──────────┐  User Key   ┌──────────────────┐  Root Key   ┌──────────┐
│  Alice   │ ──────────► │  OpenViking      │ ◄────────── │  Admin   │
│  (ADMIN) │             │  Server          │             │  (ROOT)  │
└──────────┘             │                  │             └──────────┘
┌──────────┐  User Key   │  ov.conf:        │
│  Bob     │ ──────────► │  root_api_key    │
│  (USER)  │             └──────────────────┘
└──────────┘

认证体系

Key 类型创建方式角色能力
Root Keyov.conf 中配置ROOT全部操作 + Admin API
User KeyAdmin API 创建ADMIN 或 USER按 account 访问
角色作用域能力
ROOT全局全部操作 + 创建/删除 account、管理用户
ADMIN所属 account常规操作 + 管理本 account 的用户
USER所属 account常规操作（ls、read、find、sessions 等）

Quick Start

1. 配置 Server

复制配置文件并填入你的模型 API Key：

bash
cp ov.conf.example ov.conf
# 编辑 ov.conf，填入 embedding 和 vlm 的 api_key

关键配置项——root_api_key 启用多租户认证：

json
{
  "server": {
    "root_api_key": "my-root-key"
  }
}

不配置 root_api_key 时，认证禁用，所有请求以 ROOT 身份访问（开发模式）。

2. 启动 Server

bash
# 方式一：指定配置文件
openviking-server --config ./ov.conf

# 方式二：放到默认路径
cp ov.conf ~/.openviking/ov.conf
openviking-server

# 验证
curl http://localhost:1933/health
# {"status": "ok"}

3. 运行示例

Python SDK：

bash
# 安装依赖
uv sync

# 运行（使用默认参数）
uv run admin_workflow.py

# 自定义参数
uv run admin_workflow.py --url http://localhost:1933 --root-key my-root-key

CLI：

bash
# 运行（使用默认参数）
bash admin_workflow.sh

# 自定义参数
ROOT_KEY=my-root-key SERVER=http://localhost:1933 bash admin_workflow.sh

示例流程

两个示例（Python SDK 和 CLI）覆盖完全相同的流程：

 1. Health Check              无需认证，验证服务可用
 2. Create Account            ROOT 创建 account "acme"，同时创建首个 admin "alice"
 3. Register User (ROOT)      ROOT 在 "acme" 下注册普通用户 "bob"
 4. Register User (ADMIN)     alice (ADMIN) 在 "acme" 下注册用户 "charlie"
 5. List Accounts             ROOT 列出所有 account
 6. List Users                列出 "acme" 下所有用户及角色
 7. Change Role               ROOT 将 bob 提升为 ADMIN
 8. Regenerate Key            为 charlie 重新生成 key，旧 key 立即失效
 9. Access Data               bob 使用 user key 访问数据
10. Error Tests               非法 key、权限不足、重复创建、旧 key 等负面用例
11. Remove User               删除 charlie，验证其 key 失效
12. Delete Account            删除 account "acme"，验证 alice 的 key 也失效

CLI 命令参考

bash
# Account 管理
openviking admin create-account <account_id> --admin <admin_user_id>
openviking admin list-accounts
openviking admin delete-account <account_id>

# User 管理
openviking admin register-user <account_id> <user_id> [--role user|admin]
openviking admin list-users <account_id>
openviking admin remove-user <account_id> <user_id>
openviking admin set-role <account_id> <user_id> <role>
openviking admin regenerate-key <account_id> <user_id>

文件说明

admin_workflow.py    Python SDK 示例（httpx 调用 Admin API + SyncHTTPClient 访问数据）
admin_workflow.sh    CLI 示例（openviking admin 命令，同等流程）
ov.conf.example      Server 配置文件模板（含 root_api_key）
pyproject.toml       项目依赖
README.md            本文件

Admin API 参考

方法端点所需角色说明
POST/api/v1/admin/accountsROOT创建 account + 首个 admin
GET/api/v1/admin/accountsROOT列出所有 account
DELETE/api/v1/admin/accounts/{id}ROOT删除 account
POST/api/v1/admin/accounts/{id}/usersROOT, ADMIN注册用户
GET/api/v1/admin/accounts/{id}/usersROOT, ADMIN列出用户
DELETE/api/v1/admin/accounts/{id}/users/{uid}ROOT, ADMIN移除用户
PUT/api/v1/admin/accounts/{id}/users/{uid}/roleROOT修改用户角色
POST/api/v1/admin/accounts/{id}/users/{uid}/keyROOT, ADMIN重新生成 user key

相关文档