docs: add Chinese RBAC guide and link with shared space docs

Replace the English docs/rbac.md with a comprehensive Chinese
docs/RBAC说明.md and a wiki-style summary under docs/wiki/安全认证/.
Explain how tenant RBAC relates to the shared space feature (they
are orthogonal: tenant RBAC is the vertical defense, shared space
is the horizontal collaboration channel) and cross-link the two
docs in both the flat and wiki trees. Update inbound references in
.env.example, docker-compose.yml, and the auth legacy env test to
point at the new file name.
This commit is contained in:
wizardchen
2026-05-21 12:27:10 +08:00
committed by lyingbug
parent 7aca1017db
commit 7ebb29cd3e
9 changed files with 349 additions and 380 deletions
+4
View File
@@ -42,6 +42,7 @@ aliases: [Home, Index, wiki首页]
| 页面 | 简介 |
|------|------|
| [OIDC认证调用流程](安全认证/OIDC认证调用流程.md) | OIDC 第三方登录的完整调用链路 |
| [租户RBAC说明](安全认证/RBAC说明.md) | 租户内角色矩阵、资源归属与审计 |
| [共享空间说明](安全认证/共享空间说明.md) | 跨租户协作与知识库/智能体共享 |
## 开发与部署
@@ -94,6 +95,7 @@ graph TB
集成扩展 --> VecDB[集成向量数据库]
安全认证 --> OIDC[OIDC认证调用流程]
安全认证 --> RBAC[租户RBAC说明]
安全认证 --> SharedSpace[共享空间说明]
开发部署 --> DevGuide[开发指南]
@@ -109,6 +111,8 @@ graph TB
Skills -.-> IM
IM -.-> DS
DS -.-> SharedSpace
OIDC -.-> RBAC
RBAC -.-> SharedSpace
OIDC -.-> SharedSpace
LITE -.-> SharedSpace
WebSearch -.-> VecDB
+112
View File
@@ -0,0 +1,112 @@
---
title: 租户RBAC说明
tags: [安全认证, RBAC, 权限, 多租户, 角色]
aliases: [RBAC, 角色权限, 租户角色, TenantRBAC]
source: RBAC说明.md
---
# 租户 RBAC 说明
本文档介绍 WeKnora 的**租户内权限控制(Tenant RBAC)**,包括角色矩阵、资源归属模型,以及它与 [共享空间](./共享空间说明.md) 的关系。
> 状态:已发布;由配置项 `tenant.enable_rbac` 控制,默认 `true`(强制鉴权)。
> 完整说明、灰度方案、Schema、路由守卫等参见 [`docs/RBAC说明.md`](../../RBAC说明.md)。
## 解决的问题
RBAC 引入前,只要通过 `X-API-Key` 或 JWT 认证成功,调用方在租户内基本等同管理员。一旦一个租户出现多名真人成员,就需要区分:
- 谁可以删除知识库、撤销 API Key;
- 谁可以编辑「自己」的 KB / Agent;
- 谁只读。
## 角色矩阵
| 角色 | 标识 | 关键能力 |
|------|------|----------|
| 只读 | `viewer` | 仅读 |
| 贡献者 | `contributor` | 可变更 `creator_id == 自己` 的资源;他人资源按 Viewer |
| 管理员 | `admin` | 可变更租户内任意资源;管理成员、共享基础设施 |
| Owner | `owner` | Admin + 可删租户;每个租户唯一 |
层级 `viewer < contributor < admin < owner`,高角色继承低角色。
### 鉴权层的例外
- **跨租户超管**:`enable_cross_tenant_access` 打开且账号 `CanAccessAllTenants=true`,通过 `X-Tenant-ID` 切换后等同 Admin。
- **API Key**:合成虚拟用户在所属租户内固定 Admin(删租户除外)。
- **孤儿租户自愈**:首位认证的真人自动晋升 Owner,避免 API Key-only 租户锁死。
## 资源归属
迁移 `000043` 在关键表加上 `creator_id`:
- `knowledge_bases.creator_id` —— 老数据回填为该租户的 Owner;
- `custom_agents.creator_id` + `runnable_by_viewer`(默认 `true`,允许 Viewer 在对话中调用)。
子资源沿 `chunk → knowledge → kb → creator_id` 链回溯。
由此得到两类守卫:
- **角色守卫**:只看角色,用于租户级基础设施(模型、向量库、IM 通道等)。
- **归属守卫**`OwnedXxxOrAdmin`:creator 或 Admin+ 二者其一即放行,用于具体资源写操作。
## 与共享空间的关系
| 维度 | 解决什么 | 主键 |
|------|---------|------|
| **租户 RBAC** | 同一租户内「你能对自己/别人/共享基础设施做什么」 | `tenant_members(user_id, tenant_id, role)` |
| **共享空间** | 跨租户「让别的租户的人也能用我的 KB / Agent」 | `organization_members` + 共享关系 |
两者**正交**:
- 共享空间不持有 KB / Agent,只记录「以何种权限共享到了哪个空间」;资源归属与 `creator_id` 不变;
- 一次对**他人共享过来**的 KB 的写操作,需要同时满足:共享时设了「可写」 + 你在该空间不是 Viewer + 源租户的 RBAC 仍然放行;
- API Key 跨空间访问**不会**带 Admin 光环——共享路径由 `organization_members.role` 决定,与 API Key 无关。
判定顺序见 `internal/middleware/kb_access.go`:
```text
KB 属于我当前租户?─是─► 走租户 RBAC(角色 + creator_id)
└─否─► KB 共享给我所在空间?─是─► 取 min(共享权限, 空间角色)
└─否─► 403 / 404
```
一句话:**租户 RBAC 是纵向的纵深防御,共享空间是横向的协作通道;跨租户写动作必须同时穿过两道闸口。**
## 配置
```yaml
tenant:
enable_rbac: true # false 则进入「仅记录不拦截」灰度窗口
enable_cross_tenant_access: false
auth:
registration_mode: self_serve # 或 invite_only
audit:
retention_days: 90 # 0 表示不清理
```
环境变量 `WEKNORA_TENANT_ENABLE_RBAC` / `WEKNORA_AUDIT_RETENTION_DAYS` 覆盖 YAML。`DISABLE_REGISTRATION=true` 等价于把 `registration_mode` 强制设为 `invite_only`。
## 审计
`audit_logs` 表记录:
- `rbac.member_added` / `removed` / `role_changed` / `left`
- `rbac.access_denied`(仅强制鉴权时;1 分钟滑动窗口去重)
每日后台 goroutine 清理超过 `audit.retention_days` 的旧行。
## 相关主题
- [共享空间说明](./共享空间说明.md) — 跨租户协作与共享,与 RBAC 正交
- [OIDC认证调用流程](./OIDC认证调用流程.md) — 多租户用户体系的认证入口
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 单用户场景下 RBAC 实际不发挥作用
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [共享空间说明](./共享空间说明.md) — 共享空间访问最终落到租户 RBAC 校验
- [OIDC认证调用流程](./OIDC认证调用流程.md) — JWT 解析后即进入 RBAC 角色匹配
@@ -60,6 +60,7 @@ source: 共享空间说明.md
## 相关主题
- [租户RBAC说明](./RBAC说明.md) — 单租户内的角色与资源归属,跨租户写操作需同时满足两边
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多租户场景下的用户认证
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源导入的知识库可被共享
@@ -70,6 +71,7 @@ source: 共享空间说明.md
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [租户RBAC说明](./RBAC说明.md) — 共享空间访问最终落到租户 RBAC 校验
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多租户用户体系支撑共享空间
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 导入的知识库可通过共享空间共享