WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

docs/wiki/安全认证/OIDC认证调用流程.md

@@ -0,0 +1,91 @@
+---
+title: OIDC认证调用流程
+tags: [安全认证, OIDC, 认证, 登录, SSO]
+aliases: [OIDC, OIDC认证, SSO登录, 第三方登录]
+source: OIDC认证调用流程.md
+---
+
+# OIDC 认证调用流程
+
+本文档说明 WeKnora 当前 OIDC 登录能力的实际调用过程，覆盖前后端完整链路。
+
+> OIDC 认证是标准版多空间场景下的登录方式，[Lite 版](../项目概述/Lite与标准版区别.md)不需要
+
+## 整体设计说明
+
+本项目的 OIDC 登录采用 **后端发起授权参数生成、后端接收回调并完成 code 换 token、前端通过 URL hash 接收最终登录结果** 的模式。
+
+核心特点：
+
+1. **前端只负责发起跳转**，不直接和 OIDC Provider 交换 token
+2. **后端负责用授权码 `code` 向 OIDC Provider 换取 token**
+3. 后端拿到 OIDC 用户信息后，会查找本地用户；若不存在则自动创建本地账号和默认空间
+4. 最终签发 WeKnora 自己的本地 JWT，OIDC token 只用于后端换取用户身份
+
+> 自动创建用户与空间的逻辑与 [共享空间说明](../安全认证/共享空间说明.md) 的多空间模型相关
+
+## 相关接口
+
+| 接口 | 说明 |
+|------|------|
+| `GET /api/v1/auth/oidc/config` | 获取 OIDC 是否启用及 Provider 展示名称 |
+| `GET /api/v1/auth/oidc/url` | 生成第三方登录跳转地址 |
+| `GET /api/v1/auth/oidc/callback` | OIDC Provider 回调地址 |
+
+## 调用流程（4 个阶段）
+
+### 阶段一：前端发现能力
+
+前端调用 `/auth/oidc/config`，决定是否展示第三方登录入口。
+
+### 阶段二：浏览器跳转授权
+
+前端调用 `/auth/oidc/url` 获取授权地址，然后跳转到 OIDC Provider。
+
+### 阶段三：后端完成身份兑换
+
+Provider 回调后端 `/auth/oidc/callback`，后端用 `code` 换 token、拉取用户信息、关联或创建本地用户，并签发 WeKnora JWT。
+
+### 阶段四：前端接收最终结果
+
+后端 302 回前端，通过 `#oidc_result` 传递登录结果；前端在 `App.vue` 中统一解析。
+
+## 关键配置项
+
+| 配置项 | 说明 |
+|--------|------|
+| `OIDC_AUTH_ENABLE` | 是否启用 OIDC 登录 |
+| `OIDC_AUTH_CLIENT_ID` | OIDC Client ID |
+| `OIDC_AUTH_CLIENT_SECRET` | OIDC Client Secret |
+| `OIDC_AUTH_DISCOVERY_URL` | OIDC Discovery 地址 |
+| `OIDC_AUTH_SCOPES` | Scope 列表，默认 `openid profile email` |
+
+启用时的最小要求：`client_id` + `client_secret` + (`discovery_url` 或 `authorization_endpoint + token_endpoint`)
+
+## 本地联调示例（Dex）
+
+项目中已提供 Dex 示例配置：`misc/dex-config.yaml`。
+
+> 除 Dex 外，也可以使用 KeyCloak 等其他符合 OpenID Connect 协议的 Provider
+
+## 注意事项
+
+1. **`redirect_uri` 必须严格匹配** Provider 客户端配置
+2. **邮箱是本地账号关联主键** — 若 Provider 没返回 email，将无法完成登录
+3. **首次 OIDC 登录会自动创建用户和默认空间**
+4. **真正用于访问 API 的是本地 JWT**，不是 OIDC access token
+
+## 相关主题
+
+- [共享空间说明](../安全认证/共享空间说明.md) — 多空间场景下的用户与组织管理
+- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 版无需 OIDC（单空间）
+- [API文档概览](../API参考/API文档概览.md) — API 认证机制
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [共享空间说明](../安全认证/共享空间说明.md) — OIDC 创建的用户与空间可用于共享空间
+- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不需要 OIDC（单空间无需注册）
+- [API文档概览](../API参考/API文档概览.md) — API 的认证机制与 OIDC JWT 相关

docs/wiki/安全认证/RBAC说明.md

@@ -0,0 +1,114 @@
+---
+title: 空间RBAC说明
+tags: [安全认证, RBAC, 权限, 多空间, 角色]
+aliases: [RBAC, 角色权限, 空间角色, TenantRBAC]
+source: RBAC说明.md
+---
+
+# 空间 RBAC 说明
+
+本文档介绍 WeKnora 的**空间内权限控制（Workspace 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`，高角色继承低角色。
+
+Owner 的数量约束是“至少一位”，而不是“只能一位”。系统允许同一空间存在多个活跃 Owner；降级或移除 Owner 时，只有会导致空间失去最后一位 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 角色匹配

docs/wiki/安全认证/共享空间说明.md

@@ -0,0 +1,78 @@
+---
+title: 共享空间说明
+tags: [安全认证, 共享空间, 协作, 多空间, 权限]
+aliases: [共享空间, SharedSpace, Organization, 组织]
+source: 共享空间说明.md
+---
+
+# 共享空间说明
+
+本文档说明 WeKnora 中的**共享空间**功能，包括空间创建与加入、成员角色与权限、知识库与智能体共享规则。
+
+> 共享空间是标准版功能，[Lite 版](../项目概述/Lite与标准版区别.md)不提供
+
+## 共享空间概述
+
+共享空间是跨空间协作的载体。用户可以在同一系统内属于不同空间（账户），通过**加入同一共享空间**，实现：
+
+- 共享知识库：将本空间的知识库共享到空间，供空间内其他成员使用
+- 共享智能体：将本空间的智能体共享到空间，供空间内其他成员在对话等场景中使用
+- 访问他人共享的知识库和智能体
+
+### 核心概念对照
+
+| 概念 | 说明 |
+|------|------|
+| 共享空间 | 系统中的「组织」（Organization），用于跨空间共享 |
+| 空间创建者 | 自动成为管理员，不可被移除或降级 |
+| 空间成员 | 管理员 / 编辑者 / 只读 三种角色 |
+| 知识库/智能体归属 | 始终属于一个空间；共享不改变归属 |
+
+## 角色与权限
+
+| 能力 | 管理员 | 编辑者 | 只读 |
+|------|:-:|:-:|:-:|
+| 查看、检索共享知识库 | ✓ | ✓ | ✓ |
+| 编辑共享知识库内容 | ✓ | ✓ | ✗ |
+| 将知识库共享到本空间 | ✓ | ✓ | ✗ |
+| 管理空间设置与成员 | ✓ | ✗ | ✗ |
+| 生成/刷新邀请码 | ✓ | ✗ | ✗ |
+
+## 知识库共享规则
+
+- 只有知识库所属空间下的用户才能发起共享
+- 发起人必须是目标空间的**管理员**或**编辑者**
+- 共享时指定权限：只读或可写
+- 同一知识库可共享到多个空间，各自独立配置权限
+
+## 智能体共享规则
+
+- 智能体共享到空间时**仅支持只读**
+- 同一智能体可共享到多个空间
+
+> 智能体须已配置完成（如已选模型、若使用知识库则已选 rerank 模型等）方可共享。模型配置参见 [内置模型管理](../核心功能/内置模型管理.md)
+
+## 智能体停用机制
+
+- 停用是当前空间对**通过共享空间获得的智能体**的个人偏好设置
+- 仅影响本空间在对话中选择智能体时的展示，不改变共享关系
+- 不影响其他成员
+
+## 相关主题
+
+- [空间RBAC说明](./RBAC说明.md) — 单空间内的角色与资源归属，跨空间写操作需同时满足两边
+- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
+- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多空间场景下的用户认证
+- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源导入的知识库可被共享
+- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前需确保模型已配置
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [空间RBAC说明](./RBAC说明.md) — 共享空间访问最终落到空间 RBAC 校验
+- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
+- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多空间用户体系支撑共享空间
+- [数据源导入开发](../集成扩展/数据源导入开发.md) — 导入的知识库可通过共享空间共享
+- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前的模型配置要求