Skip to content

feat: 多租户 Phase 1 - API 层多租户能力#260

Merged
MaojiaSheng merged 12 commits intomainfrom
feat/multi_tenant
Feb 24, 2026
Merged

feat: 多租户 Phase 1 - API 层多租户能力#260
MaojiaSheng merged 12 commits intomainfrom
feat/multi_tenant

Conversation

@qin-ctx
Copy link
Collaborator

@qin-ctx qin-ctx commented Feb 23, 2026

Description

实现多租户 Phase 1,建立身份、认证、授权的基础框架。包括两层 API Key 体系(Root/User,纯随机 token 无前缀)、三层 RBAC 角色模型(ROOT/ADMIN/USER)、认证中间件重写、Admin API 以及所有 Router 的依赖注入迁移。

Related Issue

Ref #158

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

核心模块

  • 新增 openviking/server/identity.py:定义 Role 枚举(ROOT/ADMIN/USER)、ResolvedIdentity、RequestContext 类型
  • 新增 openviking/server/api_keys.py:API Key Manager,支持 Root/User 两种纯随机 token 的生成、解析与管理,per-account 持久化到 /{account_id}/_system/users.json
  • 重写 openviking/server/auth.py:新增 resolve_identity()(HMAC 比对 root key -> 查 user key 索引)、get_request_context()、require_role() 角色守卫
  • 更新 openviking/server/config.py:api_key -> root_api_key,为 None 时进入 dev 模式
  • 更新 openviking/server/app.py:按 root_api_key 是否配置分派初始化逻辑

Admin API

  • 新增 openviking/server/routers/admin.py:工作区 CRUD、用户注册/移除/角色变更、Key 生成/重置等管理端点

Router 迁移

  • 所有 Router(filesystem, content, search, resources, sessions, relations, pack, system, debug, observer)从 Depends(verify_api_key) 迁移到 Depends(get_request_context)
  • Phase 1 仅替换依赖注入,ctx 接收但不向 service 层传递

客户端 SDK

  • HTTP 客户端移除 account_id/user_id 参数,身份由服务端从 API Key 解析
  • 新增 agent_id 参数,通过 X-OpenViking-Agent header 发送
  • Python CLI 新增 admin 命令组
  • Rust CLI 新增 admin 子命令

文档

  • 新增中英文 Admin API 文档 (docs/en/api/08-admin.md, docs/zh/api/08-admin.md)
  • 更新认证指南、配置指南、部署指南
  • 新增多租户示例 (examples/multi_tenant/)

测试

  • 新增 tests/server/test_admin_api.py:Admin API 集成测试
  • 新增 tests/server/test_api_key_manager.py:API Key Manager 单元测试
  • 新增 tests/server/test_identity.py:身份模块单元测试
  • 更新 tests/server/test_auth.py:认证中间件测试适配

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Additional Notes

  • Phase 1 仅完成 API 层的多租户能力定义,RequestContext 在 Router 层注入但不向 Service/VikingFS 层传递(Phase 2 完成)
  • 存储路径不变,VectorDB schema 不变
  • 嵌入模式原生支持多租户(调用方直接声明身份,无 API Key 认证)
  • 未配置 root_api_key 时自动进入 dev 模式,所有请求默认 ROOT 角色 + default 身份,行为与旧版一致

@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@qin-ctx qin-ctx changed the title [WIP] feat: 多租户 Phase 1 - API 层多租户能力 feat: 多租户 Phase 1 - API 层多租户能力 Feb 23, 2026
@MaojiaSheng MaojiaSheng merged commit b92f2c0 into main Feb 24, 2026
27 of 28 checks passed
@MaojiaSheng MaojiaSheng deleted the feat/multi_tenant branch February 24, 2026 05:40
@github-project-automation github-project-automation bot moved this from Backlog to Done in OpenViking project Feb 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants