X-Financial/document/development/2026-07-17/feature/knowledge-tenant-security/CONCEPT.md

知识库多租户隔离与安全编辑 概念文档

更新时间：2026-07-17

功能一句话

让每个企业只读写自己的知识文件、元数据和 LightRAG/Qdrant 命名空间，同时以平台制度只读层和一次性 ONLYOFFICE 会话安全地贯通知识查询、预览与编辑。

背景与问题

原知识库把所有企业的文件、.index.json、.lightrag、运行时缓存和 Qdrant workspace 放在同一全局空间。API、后台索引和定时任务还能在没有可信 tenant_id 时继续工作，导致同名文件覆盖、跨租户列表/详情/原文读取、索引串读和错误的默认租户归属风险。

ONLYOFFICE 原回调仅依赖可伪造或可重放的短 payload，并直接下载回调 URL。匿名请求可以借此访问内部地址、跟随重定向、下载超大或错误格式内容，最终覆盖知识文件。预览会话与编辑会话也没有不可变的租户、资源、文档 key、版本和一次性状态绑定。

目标与非目标

目标

• 文件、索引 JSON、LightRAG 本地状态、运行时实例和 Qdrant workspace 全部按可信租户隔离。
• 旧全局制度资料无损复制到显式 platform 空间，并始终以只读方式提供给租户。
• 列表、详情、原文、上传、删除、同步和查询均从认证用户或数据库 Agent Run 获取租户，不接受客户端上下文覆盖。
• ONLYOFFICE token 同时绑定 tenant、resource scope、document、key、version、editable、audience、expiry 和 JTI。
• 编辑回调以数据库状态机实现一次性消费；预览会话永不回写。
• 回调下载仅访问配置的文档服务，拒绝重定向、私网/回环/链路本地解析、DNS 重绑定、超限和非 OOXML 内容。
• 定时索引只枚举租户注册表中的 active 租户，不再使用默认租户。

非目标

• 不允许租户经普通 API 新建或修改平台制度；平台资料由受控部署流程维护。
• 不把租户知识数据合并成一个共享向量集合后再依赖过滤器补救。
• 不为私网 ONLYOFFICE 地址提供安全降级开关；不满足公网解析要求时回写必须 fail-closed。
• 不在本切片中实现知识内容质量评估、模型微调或新的知识运营前端。

用户与场景

• 租户管理员：上传、覆盖、删除和触发当前企业的知识同步。
• 普通员工：联合查询本企业知识与平台只读制度，预览有权限的原文。
• 知识运营人员：在受控编辑模式中修改租户 Office 文档，保存后形成新版本。
• Hermes 调度器：逐个处理活跃租户的增量知识，不创建或猜测默认租户。
• 平台管理员：通过部署资产提供跨租户可见但不可写的平台制度。

功能能力

• 租户目录：storage/knowledge/tenants/{tenant_id}/。
• 平台目录：storage/knowledge/platform/，所有业务入口只读。
• 每个作用域独立 .index.json、.lightrag、workspace 和运行时缓存键。
• 租户查询采用“租户空间 + 平台只读空间”隔离检索后融合，不在存储层混库。
• 旧 storage/knowledge/{固定目录} 与旧索引首次启动时复制到平台空间，源文件不删除。
• ONLYOFFICE content token 默认 5 分钟；callback session 默认 4 小时、最长 12 小时，并在首次写回前原子进入 processing。
• 回写成功进入 consumed，失败进入 failed；已消费、失败、撤销或过期会话不能再次写入。
• 后台索引线程从数据库 Agent Run 的 route/ontology 双份租户上下文重新校验，线程参数只能作为一致性断言。

方案设计

前端契约

• 知识文档新增 scope 与 readOnly 字段。
• 平台文档可以查看、下载和预览，但编辑入口必须隐藏或禁用。
• ONLYOFFICE 配置默认 mode=view；只有租户管理员显式请求 editable=true 时才返回编辑配置。
• 回调和 content URL 中的 token 是文档服务专用凭证，不暴露为普通用户授权能力。

后端职责

• knowledge_tenant_scope：校验租户标识，生成文件路径、workspace 和缓存键，执行旧资料到平台空间的无损迁移。
• knowledge：编排租户/平台文档、权限、文件操作、查询融合和 ONLYOFFICE 配置。
• knowledge_index_state：管理当前作用域的 JSON 元数据与 ingest 状态。
• knowledge_rag：只使用当前作用域的 working dir、workspace、缓存实例与 Qdrant 命名空间。
• knowledge_run_scope：从持久化 Agent Run 的 route/ontology 双份上下文还原并校验后台任务租户。
• knowledge_onlyoffice_security：签发/验证会话、原子消费 JTI、执行安全网络下载与 OOXML 校验。
• knowledge_onlyoffice_callback：按 token 中已验证的资源作用域定位文件，校验基线后回写新版本。
• knowledge_scheduler：从 tenants.status=active 枚举租户并创建显式内部身份。

数据

新增 migration-owned 表 knowledge_onlyoffice_sessions：

• 身份：jti、tenant_id、resource_scope、document_id。
• 不可变绑定：document_key、document_version、audience、editable、created_by、expires_at。
• 生命周期：active → processing → consumed | failed，另支持 revoked。
• 平台会话仍绑定发起租户，但数据库约束要求 editable=false。
• tenant_id 外键指向租户注册表；租户删除时清理其会话。
• 存在会话证据时 migration downgrade 拒绝有损删除。

权限与信任边界

• HTTP 文档 API 只使用 CurrentUserContext.tenant_id。
• 同步任务只使用认证用户租户；后台线程再与数据库 Agent Run 租户交叉校验。
• 平台 scope 必须由服务端显式构造，客户端不能通过参数选择。
• 租户文档 ID 在其他租户下按不存在处理；平台文档仅作为只读 fallback。
• ONLYOFFICE token 必须同时通过签名、issuer、audience、scope、时间、数据库行和全部资源字段比较。
• callback token 只有写入状态 2/6 才尝试 claim；key 不匹配时不会消耗会话。
• 下载 URL 的 origin 必须等于配置白名单；DNS 解析的全部地址必须为公网地址，实际连接固定到已校验 IP，HTTPS 仍校验原主机证书和 SNI。
• 不跟随 3xx；限制响应大小、MIME、ZIP 条目数、解压体积、路径穿越、加密条目和 OOXML 目录结构。

查询算法

租户查询先在两个物理隔离空间各自检索，再对候选做确定性融合：

tenant_workspace = base + "__tenant_" + SHA256(tenant_id)[0:20]
platform_workspace = base + "__platform"

merged_hits = top_k(
  deduplicate(tenant_hits ∪ platform_hits, by=code),
  order_by=score DESC
)

运行时缓存同样使用租户哈希键，不把原始 tenant ID 放进 Qdrant workspace 名称。

ONLYOFFICE 状态机

issue(view)  → active ── callback status 2/6 ──拒绝写入
issue(edit)  → active ── atomic claim ──→ processing
                                          ├─验证/下载/写入成功→ consumed
                                          └─任一步失败────────→ failed

active -- exp 超时 --> 验证拒绝
consumed/failed/revoked -- replay --> 409/拒绝

降级策略

• 租户缺失、格式非法或与 Agent Run 冲突：拒绝任务，不回退默认租户。
• 平台迁移源不存在：建立空平台作用域，不影响租户空间。
• 平台或租户 RAG 不可用：保留已有本地检索降级；不会改查其他租户 workspace。
• ONLYOFFICE 地址、JWT、DNS、MIME 或 OOXML 校验失败：返回错误并保持原文件不变。
• 当前容器若通过网络代理把文档域名解析为非公网保留地址，真实回写会按安全策略拒绝；部署需提供满足公网解析与 TLS 的文档服务或安全反向代理。

测试方案

• 服务：两租户同名文件、列表/详情/原文隔离、平台只读 fallback、无 scope fail-closed。
• RAG：workspace、缓存键、本地 chunks 和运行签名隔离。
• 后台：只枚举 active tenant；worker 从 Agent Run 重取租户并拒绝 route/ontology 冲突。
• ONLYOFFICE：tenant/resource/key/version/aud/exp/JTI 绑定，平台只读，会话过期，错 key 不 claim，成功只写一次，重放拒绝。
• SSRF：错误 origin、私网 DNS、重定向、IP pinning、超限、错误 MIME、损坏 OOXML。
• 迁移：revision/down_revision、表/外键/check、非 PostgreSQL 拒绝、ownership/preflight 和有证据 downgrade 拒绝。
• 所有后端验证只在 local-x-financial-linux 容器内执行，单命令超时不超过 60 秒。

指标与验收

• 100% 租户知识文件、索引、LightRAG 与 Qdrant workspace 可由可信 tenant 唯一确定。
• 跨租户文档读取、删除、同步和查询用例 100% 拒绝或不可见。
• 平台文档 readOnly=true，任何编辑回调均不产生文件副作用。
• 同一 callback JTI 最多一次进入 processing，重复回调 100% 拒绝。
• 非白名单 origin、非公网解析、重定向、超限或非 OOXML 回写 100% fail-closed。
• 定时任务只为注册表 active 租户建任务；无活跃租户时不生成默认数据。
• 新增/修改 Python 文件通过 Ruff 与 compileall，定向知识安全、既有知识回归和迁移 ownership 测试全部通过。

风险与开放问题

• 当前 JSON 索引采用原子文件级写入之外的旧读改写模型；同一租户多进程高并发上传仍应在后续演进为数据库元数据或跨进程锁。
• 平台制度的发布、签名和回滚需要独立的受控平台资产流程，本切片只保证业务 API 只读。
• 部署必须确认 ONLYOFFICE 下载域名从应用容器解析为真实公网地址；不得为开发便利开放私网通配。
• 长时编辑使用 4 小时 callback session；超过时限需重新打开文档生成新会话。

本轮实现记录

• 2026-07-17：完成租户/平台文件与 RAG 命名空间拆分、旧资料无损平台迁移、API 与后台任务可信租户接线。
• 2026-07-17：完成 DB-backed ONLYOFFICE 一次性会话、平台只读预览、文档 key/version 基线校验和 SSRF/大小/MIME/OOXML 防护。
• 2026-07-17：完成 20260717_0027 迁移、模型 ownership/preflight 注册、定时器 active tenant 枚举及容器定向回归；共享 PostgreSQL 探针完成 base → 0028 与 0028 → 0025 → 0028，Knowledge/AgentAsset 两类会话表均正常落库。