[Feature]: Multi-Tenant Phase 1 - API 层多租户能力定义

[qin-ptr]

背景

OpenViking 当前为单租户架构：

• 认证：单一全局 api_key，HMAC 比对
• 无 RBAC：所有认证用户拥有完全访问权限
• 无存储隔离：所有数据共享同一命名空间
• 服务层：OpenVikingService 持有单例 _user，不支持请求级用户上下文

需要实现多租户支持。Phase 1 聚焦 API 层能力定义，建立身份、认证、授权的基础框架，为 Phase 2 存储隔离做准备。

设计方案

设计文档：docs/design/multi-tenant-design.md
RFC 讨论：#157

三层 API Key 体系

类型	前缀	解析结果	存储位置
Root Key	ovk_root_	role=ROOT	ov.conf server 段
Account Key	ovk_acct_	(account_id, role=ACCOUNT_ADMIN)	AGFS /_system/keys.json
User Key	ovk_user_	(account_id, user_id, role=USER)	取决于方案选型（见设计文档 2.2 节）

三层 RBAC

角色	能力
ROOT	一切：创建/删除账户、生成 Account Key、跨租户访问
ACCOUNT_ADMIN	管理本账户用户、下发 User Key、账户内全量数据访问
USER	访问自己的 user/agent/session/resources scope

认证流程

1. 从 X-API-Key 或 Authorization: Bearer 提取 Key
2. 若未配置 root_api_key（单租户 dev 模式）：返回固定 ROOT 身份，行为与当前一致
3. 按前缀分派到对应的 Key 解析逻辑
4. 从 X-OpenViking-Agent header 读取 agent_id
5. 构造 RequestContext(UserIdentifier, Role) 注入到 Router

Phase 1 边界

• RequestContext 在 Router 层注入，不向 Service/VikingFS 层传递（Phase 2 完成）
• 存储路径不变，VectorDB schema 不变
• 嵌入模式不做多租户

任务拆解

实施顺序：T1 → T3 → T2 → T4 → T5 → T10/T11 并行 → T12 → T14-P1

T1: 身份与角色类型定义

新建 openviking/server/identity.py：

• Role(str, Enum): ROOT / ACCOUNT_ADMIN / USER
• ResolvedIdentity: 认证中间件输出，字段均为 Optional
• RequestContext: 请求级上下文（UserIdentifier + Role），贯穿 Router → Service → VikingFS

T3: ServerConfig 更新

修改 openviking/server/config.py：

• api_key → root_api_key（ROOT 身份认证）
• 新增 multi_tenant: bool（部署模式开关，见设计文档第 8 节）
• 新增 private_key（仅 User Key 方案 A 需要）

T2: API Key Manager

新建 openviking/server/api_keys.py：

• 内存缓存 account keys 和 accounts 注册信息，持久化到 AGFS /_system/keys.json
• resolve(api_key): 按前缀分派，解析为 ResolvedIdentity
• create_account / delete_account / register_user / remove_user 等管理方法

T4: 认证中间件重写

重写 openviking/server/auth.py：

• resolve_identity(): 提取 Key → APIKeyManager 解析 → 返回 ResolvedIdentity
• get_request_context(): ResolvedIdentity → RequestContext（填充默认值）
• require_role(*roles): 角色守卫工厂，用于 Admin API 权限检查

T5: App 初始化集成

修改 openviking/server/app.py：

• 按 config.multi_tenant 分派：多租户模式初始化 APIKeyManager + 注册 Admin API；单租户模式跳过
• 初始化时序：service.initialize() → APIKeyManager.load()

T10: Router 依赖注入迁移

修改所有 router（filesystem, content, search, resources, sessions, relations, pack, system, debug, observer）：

• Depends(verify_api_key) → Depends(get_request_context)
• Phase 1 仅替换依赖注入，service 调用签名不变

T11: Admin Router

新建 openviking/server/routers/admin.py：

• POST /api/v1/admin/accounts — 创建账户 (ROOT)
• GET /api/v1/admin/accounts — 列出账户 (ROOT)
• DELETE /api/v1/admin/accounts/{account_id} — 删除账户 (ROOT)
• POST /api/v1/admin/accounts/{account_id}/users — 注册用户 (ROOT, ACCOUNT_ADMIN)
• DELETE /api/v1/admin/accounts/{account_id}/users/{uid} — 移除用户 (ROOT, ACCOUNT_ADMIN)
• POST /api/v1/admin/accounts/{account_id}/key — 生成 Account Key (ROOT)
• GET /api/v1/admin/accounts/{account_id}/users/{uid}/key — 下发 User Key (ROOT, ACCOUNT_ADMIN)

T12: 客户端 SDK 更新

• HTTP 客户端新增 agent_id 参数，通过 X-OpenViking-Agent header 发送
• CLI ovcli.conf 新增 agent_id 字段
• 身份由服务端从 API Key 解析，客户端不再构造 UserIdentifier

T14-P1: 认证与管理测试

• APIKeyManager 单元测试（key 生成/解析/注册检查）
• 认证中间件测试（三种 key 类型、dev 模式、require_role 守卫）
• Admin API 测试
• 回归测试（现有测试适配 dev mode）

关联

• Phase 2 实施：Phase 2 Issue 将在创建后关联
• 设计讨论：RFC: Multi-Tenant Design #157