RFC: Multi-Tenant Design

[qin-ptr]

多租户设计方案

设计文档：docs/design/multi-tenant-design.md

概述

为 OpenViking 实现完整的多租户支持，包括：

• 三层 API Key 体系：Root Key（系统管理员）、Account Key（租户管理员）、User Key（普通用户）
• 三层 RBAC：ROOT / ACCOUNT_ADMIN / USER 角色权限控制
• 存储隔离：AGFS 路径按 account_id 前缀隔离 + user_space/agent_space 目录层级；VectorDB 按 account_id + owner_space 过滤
• Admin API：账户/用户管理端点
• 部署模式：通过 multi_tenant 配置开关支持单租户/多租户两种部署模式（待评审）

分期实施

阶段	范围	Issue
Phase 1	API 层多租户能力定义：身份类型、API Key 管理、认证中间件、RBAC、Admin API、Router 迁移、客户端 SDK	#158
Phase 2	存储层隔离实现：VikingFS 目录隔离、VectorDB 租户过滤、Service 层 ctx 传递、目录初始化	#159

待评审决策项

以下设计点需要在评审中讨论确定：

1. User Key 方案选型（设计文档 2.2 节）

• 方案 A：加密式 token——AES 加密 account_id:user_id，确定性推导，不存储 key 本身。适用于 user 过多、存储同步压力大的场景。需要 ov.conf 配置 private_key。
• 方案 B：随机 key + 查表——每个 user key 都存储到 keys.json。实现最简单，无密码学依赖。可单独换某个用户的 key。

选型影响：ov.conf 是否需要 private_key 字段、APIKeyManager 的实现逻辑、keys.json 的存储结构。

2. Agent 目录归属模型（设计文档 4.3 节）

• 方案 A：按 agent_id 共享——目录仅由 agent_id 决定，多个用户共用同一份 agent 数据。适用于团队共享工具型 agent。
• 方案 B：按 user_id + agent_id 隔离——每个用户与 agent 的组合有独立数据空间。适用于个人助手类 agent。

选型影响：agent 记忆/技能/指令的可见范围和 agent_space_name() 实现。

3. 单租户兼容（设计文档第 8 节）

• 方案 A：支持双模式——通过 multi_tenant 配置开关区分。单租户保持当前扁平路径，行为不变；两种模式互斥、不可切换。代码需按模式分派。
• 方案 B：仅多租户——所有部署统一走多租户路径结构。现有数据需要迁移或重新导入。代码无分支。

[ZaynJarvis]

User Key 方案 A: Alice 密钥泄漏可以让 Alice 换名字 X ？然后 Admin 扫库迁移 Alice 资产到 X，这样不需要 private key 轮转，不影响其他用户。另外资产移交可以是 admin 通用接口。

用户记忆、资源、session 属于用户本人

资源按之前的设计应该不会按用户分 folder?

resource 结构变成

/{account_id}/resources/{user_space}/

从这里看，目前这个版本发布后不支持 resource 共享。

未来 ACL 扩展方向（本版不实现）

但租户兼容可以考虑仅多租户方案 (大多数用户可能不关注实际文件结构)，启动时根据 data 内容自动迁移后启动完成

[ZaynJarvis]

另外有个问题 agent_id 怎么注入到 ov cli ？

1. openviking register <agent_name> 过程 < 指令有可能被忽略
2. 还是 openviking add xxx --agent=opencode < --agent option 可能被忽略

【done】用 process env or separate conf file

[qin-ctx]

设计决策确定

1. 去掉 Account Key：三层 Key（root/account/user）简化为两层（root/user）。ADMIN 不再由 key 类型决定，而是用户在 account 内的角色属性，存储在 users.json 中。一个 account 可以有多个 admin。
2. Account = 工作区：Account 是由 ROOT 创建的工作区（workspace）。/_system/accounts.json 维护全局工作区列表，每个工作区有独立的用户注册表 /{account_id}/_system/users.json。系统启动时自动创建 default 工作区。
3. User Key 方案 B：随机 key + 查表存储。不需要 private_key 配置，不需要加密库。key 丢失后重新生成，旧 key 立即失效。
4. Agent 目录方案 B：按 user_id + agent_id 隔离。agent_space_name() = md5(user_id + agent_id)[:12]，每个用户与 agent 的组合有独立数据空间。
5. 破坏性改造：不保留单租户模式，统一多租户路径结构。所有 account（含 default）使用 /{account_id}/... 层级路径。
6. 嵌入模式支持多租户：通过构造参数传入 UserIdentifier，默认使用 default 工作区 + default 用户。
7. API Key 无前缀：所有 key 为纯随机 token（secrets.token_hex(32)），不携带身份信息。服务端通过先比对 root key、再查 user key 索引的方式确定身份。
8. Resources account 级共享：resources 在 account 内共享，不按 user_space 隔离。路径为 /{account_id}/resources/...。
9. ROOT 支持全部功能：ROOT 权限为超集，既能做管理操作也能使用常规产品功能。dev 模式默认 ROOT 角色。
10. 配置简化：ov.conf server 段移除 private_key 和 multi_tenant，仅保留 root_api_key 和 cors_origins。
11. 创建 account 同时指定首个 admin：POST /admin/accounts 一步完成工作区创建 + 首个 admin 注册 + 返回 user key。
12. 队列/Observer account 级可见性：底层单例，查询时按 account_id 过滤。放在 Phase 2。

新增任务

• T15：数据迁移脚本（python -m openviking migrate），将旧版单租户数据迁移到多租户路径结构，Phase 2 实现
• T16-P1：Phase 1 用户文档更新（配置、认证、部署、API 概览、快速开始）
• T16-P2：Phase 2 用户文档更新（架构、存储、URI、变更日志）

Key 存储方案

评审讨论了 key 存储结构的三种方案（user_id 做主键 / key 做主键 / 双索引），确定采用方案 A（user_id 做主键）。文件结构用于持久化和人工排查，运行时认证全走内存索引（dict[key] → identity），O(1) 查找。