Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(concepts): add multi-tenant usage guide (#1029)
Qin Haojie85c1723078dd
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.mdindex 0b09170e3..9bb990a6b 100644--- a/docs/en/api/08-admin.md+++ b/docs/en/api/08-admin.md@@ -443,6 +443,7 @@ curl -X DELETE http://localhost:1933/api/v1/admin/accounts/acme \## Related Documentation+- [Multi-Tenant](../concepts/11-multi-tenant.md) - Tenant model, roles, and sharing boundaries- [API Overview](01-overview.md) - Authentication and response format- [Sessions](05-sessions.md) - Session management- [System](07-system.md) - System and monitoring APIdiff --git a/docs/en/concepts/11-multi-tenant.md b/docs/en/concepts/11-multi-tenant.mdnew file mode 100644index 000000000..9684edd8d--- /dev/null+++ b/docs/en/concepts/11-multi-tenant.md@@ -0,0 +1,300 @@+# Multi-Tenant++OpenViking multi-tenancy does not mean "deploy one isolated server per team." Instead, a single OpenViking Server uses three identity boundaries, `account`, `user`, and `agent`, to control sharing and isolation.++This model fits two common scenarios:++- Multiple teams or customers share one OpenViking service, but their data must stay isolated+- Multiple users and multiple agents inside one team need shared resources but isolated memories++## What It Enables++With multi-tenancy enabled, you can:++- Serve multiple teams, customers, or applications from one OpenViking Server+- Isolate different teams with `account`+- Share `resources` within the same `account`+- Isolate user memories and sessions with `user`+- Further separate agent memories, skills, and instructions with `agent_id`+- Manage permissions with ROOT / ADMIN / USER roles+- Support different integration patterns such as OpenClaw plugin, Vikingbot, CLI, and HTTP SDKs++## Core Identity Model++### `account_id`++`account` is the outer tenant boundary. You can think of it as a workspace, team, or customer space.++- Data is isolated across different `account` values by default+- ROOT can create and delete `account`s+- `resources`, `user`, `agent`, and `session` all live inside an `account`++### `user_id`++`user` is the per-account user boundary.++- User memories and user sessions are isolated by `user_id`+- A normal user can only access its own user space+- An admin can manage users inside the same `account`++### `agent_id`++`agent_id` separates agent-level space.++- In the default mode, agent space is derived from `user_id + agent_id`+- That means different agents for the same user can have different agent memories+- If `memory.agent_scope_mode = "agent"`, the same `agent_id` can share agent space across users in the same account++### Roles++| Role | Scope | Typical capabilities |+|------|-------|----------------------|+| ROOT | Global | Create/delete accounts, cross-tenant access, user management |+| ADMIN | Single account | Manage users in the same account, regenerate user keys |+| USER | Single account | Access its own user/agent/session data and shared resources in the same account |++## Authentication Modes++OpenViking Server supports two multi-tenant related authentication modes:++| Mode | Config | Identity source | Typical use case |+|------|--------|-----------------|------------------|+| `api_key` | `server.auth_mode = "api_key"` | Root key or user key | Standard deployment |+| `trusted` | `server.auth_mode = "trusted"` | Upstream-injected `X-OpenViking-Account` / `X-OpenViking-User` | Behind a trusted gateway |++### What `root_api_key` Does++Once `server.root_api_key` is configured, OpenViking enters formal multi-tenant mode:++- The root key manages accounts and users+- User keys are generated by the Admin API for normal data access+- The server resolves `account_id`, `user_id`, and role from the user key++If `auth_mode = "api_key"` and `root_api_key` is not configured, the server runs in dev mode:++- All requests are treated as ROOT+- The default identity is `default/default/default`+- This is only allowed on localhost++## Sharing and Isolation Boundaries++### Logical Layer++| Data type | Shared across accounts | Shared inside one account | Default isolation boundary |+|-----------|------------------------|---------------------------|----------------------------|+| `resources` | No | Yes | account |+| `user` | No | No | user |+| `agent` | No | Depends on `memory.agent_scope_mode` | Default: `user + agent` |+| `session` | No | No | user / session |++### Storage Layer++For users, URIs still look like normal `viking://...` paths:++```text+viking://resources/project-a/+viking://user/alice/memories/+viking://agent/91f3ab12cd34/memories/+```++But the underlying storage automatically gains an account prefix:++```text+/local/{account_id}/resources/project-a/+/local/{account_id}/user/alice/memories/+/local/{account_id}/agent/91f3ab12cd34/memories/+```++So multi-tenant isolation does not rely on a special public URI format. It relies on request context, `account_id`, `user_id`, and `agent_id`, applied consistently through the stack.++### Retrieval Layer++Semantic retrieval is tenant-aware as well:++- Non-ROOT requests are automatically filtered by `account_id`+- `resources` can include account-shared resources+- `memory` and `skill` are further filtered by the current `user space` and `agent space`++This keeps "what you can search" aligned with "what you can read."++## Standard Usage Flow++### 1. Enable multi-tenancy++```json+{+ "server": {+ "auth_mode": "api_key",+ "root_api_key": "your-secret-root-key"+ }+}+```++### 2. ROOT creates an account and the first admin++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-secret-root-key" \+ -d '{+ "account_id": "acme",+ "admin_user_id": "alice"+ }'+```++### 3. ADMIN or ROOT registers normal users++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <admin-or-root-key>" \+ -d '{+ "user_id": "bob",+ "role": "user"+ }'+```++### 4. Prefer user keys for normal application traffic++For normal reads, writes, searches, and session commits, prefer a user key:++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: <bob-user-key>" \+ -H "X-OpenViking-Agent: coding-agent"+```++This lets the server resolve identity directly from the key, without extra tenant headers.++### 5. Only ROOT uses explicit tenant headers for tenant-scoped data APIs++ROOT does not need tenant headers for Admin APIs, but it does need them for tenant-scoped data APIs such as `ls`, `find`, and `sessions`:++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: <root-key>" \+ -H "X-OpenViking-Account: acme" \+ -H "X-OpenViking-User: alice" \+ -H "X-OpenViking-Agent: coding-agent"+```++## Integration Patterns++### OpenClaw Plugin 2.0: one instance uses one user key++The current OpenClaw plugin follows a "plugin holds one user identity" model:++- Remote mode config is `baseUrl + apiKey + agentId`+- `apiKey` should normally be a user key+- The server resolves `account_id` and `user_id` from that user key+- The plugin explicitly passes `X-OpenViking-Agent`++Typical config:++```bash+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"+openclaw config set plugins.entries.openviking.config.apiKey "<user-api-key>"+openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"+```++Characteristics of this model:++- Simple integration, because the plugin does not manage account/user lifecycle+- Best for "one OpenClaw instance maps to one OpenViking user identity"+- `agentId` distinguishes different OpenClaw instances or agent roles+- `resources` can be shared inside the same account, while `user` and `agent` memory stay identity-scoped++### Why the OpenClaw plugin usually does not set `account` / `user`++In `api_key` mode, a user key is already enough to express identity:++- `account` and `user` are resolved server-side from the key+- The plugin only needs to provide `agentId`+- Internally, the plugin derives default `user` and `agent` memory scopes from the runtime identity++If you give the plugin a root key directly, normal tenant-scoped data APIs will lack `X-OpenViking-Account` and `X-OpenViking-User`, so that is not a good default for day-to-day access.++### Vikingbot: root key manages many end users++Vikingbot uses a different practice. It behaves more like a platform serving many end users:++- The bot connects to OpenViking with a root key+- The bot config fixes an `account_id`+- The bot automatically registers users inside that account+- The bot caches per-user user keys and uses them for memory commit/search whenever possible++Example config:++```json+{+ "bot": {+ "ov_server": {+ "server_url": "http://127.0.0.1:1933",+ "root_api_key": "test",+ "account_id": "default",+ "admin_user_id": "default"+ }+ }+}+```++Characteristics of this model:++- Good for one bot service serving many chat users+- All users inside the same account share `resources`+- User memories are isolated through auto-managed user identities+- The bot takes on more tenant lifecycle management logic than the OpenClaw plugin++## Which Practice to Choose++| Scenario | Recommended pattern |+|----------|---------------------|+| One OpenClaw instance maps to one fixed identity | OpenClaw plugin + user key |+| One gateway or bot service serves many end users | Vikingbot + root-key-managed users |+| A trusted gateway injects identity upstream | `trusted` mode |+| Local single-user experience without formal tenant isolation | Dev mode without `root_api_key` |++## Common Misunderstandings++### 1. `root_api_key` is not the normal business-access key++The root key is mainly for:++- Creating and deleting accounts+- Registering users+- Regenerating keys+- Operations and diagnostics++Normal application traffic should prefer user keys.++### 2. `agentId` does not define the tenant++`agentId` only defines the agent-level space.++- The tenant boundary is `account_id`+- The user boundary is `user_id`+- The agent boundary is `agent_id`++### 3. No `root_api_key` does not mean "formal single-tenant production mode"++That is only dev mode:++- All requests run as ROOT+- It is not suitable for public or shared deployments++### 4. OpenClaw plugin and Vikingbot are not the same multi-tenant pattern++- OpenClaw plugin is closer to "a client directly uses one user identity"+- Vikingbot is closer to "a platform manages many users and their user keys"++## Related Documentation++- [Authentication](../guides/04-authentication.md) - Auth modes, headers, and key rules+- [Configuration](../guides/01-configuration.md) - `root_api_key`, `auth_mode`, and `agent_id`+- [Admin API](../api/08-admin.md) - Admin API reference+- [API Overview](../api/01-overview.md) - CLI and HTTP connection patterns+- [Data Encryption](./10-encryption.md) - At-rest encryption in multi-tenant deployments+- [Multi-tenant Example](../../../examples/multi_tenant/README.md) - End-to-end management workflow+- [OpenClaw Plugin](../../../examples/openclaw-plugin/README.md) - OpenClaw integration+- [Vikingbot](../../../bot/README.md) - Bot-side multi-user integrationdiff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.mdindex f7f68be20..a14ebd3a7 100644--- a/docs/en/guides/04-authentication.md+++ b/docs/en/guides/04-authentication.md@@ -235,6 +235,7 @@ curl http://localhost:1933/health## Related Documentation+- [Multi-Tenant](../concepts/11-multi-tenant.md) - Capabilities, sharing boundaries, and integration patterns- [Configuration](01-configuration.md) - Config file reference- [Deployment](03-deployment.md) - Server setup- [API Overview](../api/01-overview.md) - API referencediff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.mdindex 2ecbab8b4..f1a542e9d 100644--- a/docs/zh/api/08-admin.md+++ b/docs/zh/api/08-admin.md@@ -443,6 +443,7 @@ curl -X DELETE http://localhost:1933/api/v1/admin/accounts/acme \## 相关文档+- [多租户](../concepts/11-multi-tenant.md) - 多租户模型、角色和共享边界- [API 概览](01-overview.md) - 认证与响应格式- [会话管理](05-sessions.md) - 会话管理- [系统](07-system.md) - 系统和监控 APIdiff --git a/docs/zh/concepts/11-multi-tenant.md b/docs/zh/concepts/11-multi-tenant.mdnew file mode 100644index 000000000..2b35db7f9--- /dev/null+++ b/docs/zh/concepts/11-multi-tenant.md@@ -0,0 +1,300 @@+# 多租户++OpenViking 的多租户不是“为每个团队部署一套独立服务”,而是在同一个 OpenViking Server 内,用 `account`、`user`、`agent` 三层身份边界来隔离和共享数据。++它适合两类典型场景:++- 多个团队或客户共享一套 OpenViking 服务,但数据必须隔离+- 一个团队内的多个用户和多个 Agent 需要共享资源、隔离记忆++## 能做什么++启用多租户后,你可以:++- 用一个 OpenViking Server 服务多个团队、客户或应用+- 用 `account` 隔离不同团队的数据+- 在同一个 `account` 内共享 `resources`+- 用 `user` 隔离用户级记忆和会话+- 用 `agent_id` 进一步区分 agent 级记忆、技能和指令空间+- 用 ROOT / ADMIN / USER 角色分层管理权限+- 支持 OpenClaw 插件、Vikingbot、CLI、HTTP SDK 等不同接入方式++## 核心身份模型++### `account_id`++`account` 是最外层租户边界,可以理解为工作区、团队或客户空间。++- 不同 `account` 之间的数据默认完全隔离+- Root 用户可以创建、删除 `account`+- `resources`、`user`、`agent`、`session` 都落在某个 `account` 下++### `user_id`++`user` 是 account 内的用户边界。++- 用户记忆和用户会话按 `user_id` 隔离+- 普通 user 只能访问自己的 user space+- admin 可以管理本 account 下的用户++### `agent_id`++`agent_id` 用于区分 agent 级空间。++- 默认模式下,agent space 由 `user_id + agent_id` 共同决定+- 这意味着同一用户的不同 agent 可以拥有不同 agent 记忆+- 如果 `memory.agent_scope_mode = "agent"`,则同一 `agent_id` 可在同 account 内跨用户共享 agent 空间++### 角色++| 角色 | 作用域 | 典型能力 |+|------|--------|----------|+| ROOT | 全局 | 创建/删除 account、跨租户访问、管理用户 |+| ADMIN | 单个 account | 管理本 account 的用户、重置 user key |+| USER | 单个 account | 访问自己的 user/agent/session 数据和 account 内共享资源 |++## 认证模式++OpenViking Server 支持两种多租户相关认证模式:++| 模式 | 配置 | 身份来源 | 适用场景 |+|------|------|----------|----------|+| `api_key` | `server.auth_mode = "api_key"` | Root key 或 user key | 标准部署方式 |+| `trusted` | `server.auth_mode = "trusted"` | 上游显式注入 `X-OpenViking-Account` / `X-OpenViking-User` | 受信网关后面 |++### `root_api_key` 的作用++配置 `server.root_api_key` 后,OpenViking 才进入正式多租户模式:++- Root key 用于管理 account 和 user+- User key 由 Admin API 生成,用于普通业务读写+- 服务端会从 user key 反解出 `account_id`、`user_id` 和角色++如果 `auth_mode = "api_key"` 且未配置 `root_api_key`,服务端会进入开发模式:++- 默认所有请求都被视为 ROOT+- 默认身份是 `default/default/default`+- 只允许绑定在 localhost 上使用++## 共享与隔离边界++### 逻辑层++| 数据类型 | 是否跨 account 共享 | account 内是否共享 | 默认隔离边界 |+|----------|---------------------|-------------------|--------------|+| `resources` | 否 | 是 | account |+| `user` | 否 | 否 | user |+| `agent` | 否 | 视 `memory.agent_scope_mode` 而定 | 默认 `user + agent` |+| `session` | 否 | 否 | user / session |++### 存储层++对用户来说,URI 仍然是统一的 `viking://...`:++```text+viking://resources/project-a/+viking://user/alice/memories/+viking://agent/91f3ab12cd34/memories/+```++但底层存储会自动带上 account 前缀:++```text+/local/{account_id}/resources/project-a/+/local/{account_id}/user/alice/memories/+/local/{account_id}/agent/91f3ab12cd34/memories/+```++因此多租户隔离不是靠“不同 URI 前缀”,而是靠请求上下文中的 `account_id`、`user_id`、`agent_id` 共同生效。++### 检索层++语义检索同样受租户约束:++- 非 ROOT 请求会自动按 `account_id` 过滤+- `resources` 会允许检索 account 内共享资源+- `memory` 和 `skill` 会进一步按当前 `user space` / `agent space` 过滤++这意味着“能搜到什么”与“能读到什么”保持一致,不会因为向量召回而越权。++## 标准使用流程++### 1. 启用多租户++```json+{+ "server": {+ "auth_mode": "api_key",+ "root_api_key": "your-secret-root-key"+ }+}+```++### 2. ROOT 创建工作区和首个管理员++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-secret-root-key" \+ -d '{+ "account_id": "acme",+ "admin_user_id": "alice"+ }'+```++### 3. ADMIN 或 ROOT 注册普通用户++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <admin-or-root-key>" \+ -d '{+ "user_id": "bob",+ "role": "user"+ }'+```++### 4. 普通业务访问优先使用 user key++常规读写、搜索、会话提交等请求,优先用 user key:++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: <bob-user-key>" \+ -H "X-OpenViking-Agent: coding-agent"+```++这样服务端可以直接从 key 反解身份,无需额外传 `account` / `user`。++### 5. 只有 ROOT 访问租户级数据 API 时才显式带租户头++ROOT 访问 Admin API 不需要租户头,但访问 `ls`、`find`、`sessions` 这类租户级数据 API 时,必须显式指定目标租户:++```bash+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \+ -H "X-API-Key: <root-key>" \+ -H "X-OpenViking-Account: acme" \+ -H "X-OpenViking-User: alice" \+ -H "X-OpenViking-Agent: coding-agent"+```++## 接入实践++### OpenClaw 插件 2.0:每个实例使用 user key++OpenClaw 插件当前的多租户实践是“插件侧只持有一个用户身份”:++- 远程模式配置 `baseUrl + apiKey + agentId`+- `apiKey` 推荐配置为某个 user 的 user key+- 服务端从 user key 自动解析 `account_id` 和 `user_id`+- 插件显式传递 `X-OpenViking-Agent`++典型配置:++```bash+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"+openclaw config set plugins.entries.openviking.config.apiKey "<user-api-key>"+openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"+```++这种模式的特点:++- 接入简单,插件不需要管理 account/user 生命周期+- 最适合“一个 OpenClaw 实例对应一个 OpenViking 用户”的场景+- `agentId` 决定 agent 级空间,便于区分不同 OpenClaw 实例或不同 agent 角色+- 同一 account 内的 `resources` 可共享,`user` / `agent` memory 会按身份隔离++### OpenClaw 插件为何通常不配 `account` / `user`++因为在 `api_key` 模式下,user key 已经足够表达身份:++- `account`、`user` 由服务端从 key 反解+- 插件只需要额外告诉服务端当前的 `agentId`+- 插件内部会根据运行时身份去解析默认的 `user` / `agent` 记忆空间++如果给插件直接配置 root key,则普通租户数据 API 会缺少 `X-OpenViking-Account` / `X-OpenViking-User`,这不适合作为日常读写方式。++### Vikingbot:root key 代管用户身份++Vikingbot 当前的实践与 OpenClaw 插件不同,它更接近“平台代理多个终端用户”:++- bot 连接 OpenViking 时持有 root key+- bot 配置固定的 `account_id`+- bot 会在该 account 下自动注册用户+- bot 会缓存每个 user 的 user key,并尽量用对应 user key 去提交/检索 memory++相关配置示例:++```json+{+ "bot": {+ "ov_server": {+ "server_url": "http://127.0.0.1:1933",+ "root_api_key": "test",+ "account_id": "default",+ "admin_user_id": "default"+ }+ }+}+```++这种模式的特点:++- 适合一个 bot 服务承载多个聊天用户+- 同一 account 下所有用户共享 `resources`+- 用户记忆通过自动注册的 user 身份隔离+- bot 侧需要承担更多租户生命周期管理逻辑++## 什么时候选哪种实践++| 场景 | 推荐方式 |+|------|----------|+| 一个 OpenClaw 实例对应一个固定身份 | OpenClaw 插件 + user key |+| 一个网关/机器人服务承载很多最终用户 | Vikingbot + root key 代管用户 |+| 受信网关统一注入身份 | `trusted` 模式 |+| 单机本地体验、无需真正租户隔离 | 开发模式(无 `root_api_key`) |++## 常见误区++### 1. `root_api_key` 不是常规业务 key++Root key 主要用于:++- 创建/删除 account+- 注册用户+- 重置 key+- 运维和调试++正常业务请求优先使用 user key。++### 2. `agentId` 不决定 account++`agentId` 只决定 agent 级空间,不决定租户归属。++- account 边界由 `account_id` 决定+- user 边界由 `user_id` 决定+- agent 边界由 `agent_id` 决定++### 3. 不配置 `root_api_key` 不等于“单租户正式部署”++这只是开发模式:++- 默认全部请求以 ROOT 身份运行+- 不适合暴露到公网或团队共享环境++### 4. OpenClaw 插件和 Vikingbot 不是同一种租户实践++- OpenClaw 插件:更像“客户端拿到一个 user 身份后直接访问”+- Vikingbot:更像“平台代理多个用户,并代为申请和管理 user key”++## 相关文档++- [认证](../guides/04-authentication.md) - 认证模式、请求头和 key 规则+- [配置](../guides/01-configuration.md) - `root_api_key`、`auth_mode`、`agent_id`+- [管理员(多租户)](../api/08-admin.md) - Admin API 参考+- [API 概览](../api/01-overview.md) - CLI / HTTP 连接方式+- [数据加密](./10-encryption.md) - 多租户下的静态数据加密+- [多租户示例](../../../examples/multi_tenant/README.md) - 完整管理流程示例+- [OpenClaw 插件](../../../examples/openclaw-plugin/README_CN.md) - OpenClaw 的接入方式+- [Vikingbot](../../../bot/README_CN.md) - bot 的多用户接入方式diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.mdindex d1d5d7159..e2c59e750 100644--- a/docs/zh/guides/04-authentication.md+++ b/docs/zh/guides/04-authentication.md@@ -235,6 +235,7 @@ curl http://localhost:1933/health## 相关文档+- [多租户](../concepts/11-multi-tenant.md) - 多租户能力、共享边界与接入实践- [配置](01-configuration.md) - 配置文件说明- [服务部署](03-deployment.md) - 服务部署- [API 概览](../api/01-overview.md) - API 参考