787bc3a481
Add tenant-safe value, telemetry, connector, commercial, and production-readiness foundations.
6.3 KiB
6.3 KiB
知识库多租户隔离与安全编辑 开发 TODO
更新时间：2026-07-17
关联方案：CONCEPT.md
使用规则
- 任务边界、信任模型和上线约束以 CONCEPT 对应章节为准。
[x]只表示已有代码或容器验证证据；运维环境尚未验证的项目保持[ ]。- 所有后端测试必须在
local-x-financial-linux容器内运行，单命令最长 60 秒。
1. 调研与边界
- [CONCEPT: 背景与问题] 盘点旧文件、index、LightRAG、运行时缓存和 Qdrant 的全局共享路径。证据：
knowledge.py、knowledge_rag.py调用点扫描与两租户隔离测试。 - [CONCEPT: 目标与非目标] 冻结“租户可写 + 平台只读”的双层资源模型，不提供客户端 scope 选择或私网下载降级。证据：
KnowledgeStorageScope与 platform 只读反向测试。 - [CONCEPT: 用户与场景] 明确 API 用户、平台资料、Hermes 调度器和 ONLYOFFICE 文档服务四类主体。证据：认证端点、scheduler 和 session service 的显式调用契约。
2. 契约与设计
- [CONCEPT: 功能能力] 定义
tenants/{tenant}/、platform/、workspace 和 runtime cache key。证据：knowledge_tenant_scope.py。 - [CONCEPT: 方案设计] 为文档 DTO 增加
scope/readOnly，平台文档只能只读 fallback。证据：schemas/knowledge.py与平台文档测试。 - [CONCEPT: ONLYOFFICE 状态机] 定义
active → processing → consumed|failed和过期/重放拒绝。证据：KnowledgeOnlyOfficeSession模型、20260717_0027迁移与 replay 测试。
3. 后端实现
- [CONCEPT: 后端职责] 建立 tenant/platform 文件、index 与 LightRAG 存储作用域。证据：
knowledge_tenant_scope.py、knowledge_index_state.py、knowledge_rag.py。 - [CONCEPT: 后端职责] 将列表、详情、原文、上传、删除、同步和查询接入可信租户。证据：
knowledge.py、endpoints/knowledge.py、knowledge_sync.py。 - [CONCEPT: 权限与信任边界] 让 Orchestrator 从数据库 Agent Run 取 tenant，并让索引 worker 比对 route/ontology tenant。证据：
orchestrator_execution.py、knowledge_run_scope.py、knowledge_index_tasks.py、Agent Run 冲突测试。 - [CONCEPT: 后端职责] 定时器只枚举
Tenant.status=active，没有活跃租户时跳过。证据：knowledge_scheduler.py与 active/suspended 调度测试。 - [CONCEPT: 后端职责] 迁移旧全局制度到 platform 空间且不删除源文件。证据：
migrate_legacy_library_to_platform()与 legacy migration 测试。 - [CONCEPT: 权限与信任边界] 新增带数据库状态的 ONLYOFFICE token、平台只读预览和一次性 callback。证据：
knowledge_onlyoffice_security.py、knowledge_onlyoffice_callback.py。 - [CONCEPT: 权限与信任边界] 加固下载 origin、DNS/IP pinning、重定向、大小、MIME、ZIP 和 OOXML 校验。证据：
download_onlyoffice_document()与 SSRF/格式测试。 - [CONCEPT: 数据] 新增
20260717_0027，注册模型、schema ownership 和 migration preflight。证据：迁移文件、db/base.py、models/__init__.py、migration_preflight.py。 - [CONCEPT: 后端职责] 删除知识文件工具中已废弃的无状态弱 token 实现。证据：
knowledge_file_utils.py差异与全仓引用扫描。
4. 算法/规则实现
- [CONCEPT: 查询算法] 以租户哈希生成不可冲突的 workspace/cache key，再隔离检索 tenant 与 platform 候选。证据：workspace/cache/local chunks 两租户测试。
- [CONCEPT: 查询算法] 对两个隔离结果按 code 去重、score 排序并截取 top-k。证据：
_merge_scoped_search_results()。 - [CONCEPT: ONLYOFFICE 状态机] content token 默认 5 分钟，callback session 默认 4 小时且最长 12 小时。证据：JWT exp 差值断言与会话测试。
5. 前端实现
- [CONCEPT: 前端契约] 后端 DTO 已提供
scope/readOnly，现有列表可安全识别平台只读资源。证据：OpenAPI 回归与KnowledgeDocumentRead。 - [CONCEPT: 前端契约] ONLYOFFICE 默认返回 view 模式，只有管理员显式
editable=true才获得 edit 权限。证据：config 单元测试与平台编辑拒绝测试。 - [CONCEPT: 目标与非目标] 本切片不新增知识运营页面或视觉改版。证据：CONCEPT 非目标；本轮无知识前端文件变更。
6. 测试与验证
- [CONCEPT: 测试方案] 完成租户文件、平台只读、RAG namespace、scheduler 与 worker trust 测试。证据：容器内
test_knowledge_tenant_security.py6 项通过。 - [CONCEPT: 测试方案] 完成 token 绑定、平台只读、错 key、过期、单次回写、重放和 SSRF/OOXML 测试。证据：容器内
test_knowledge_onlyoffice_tenant_security.py8 项通过。 - [CONCEPT: 测试方案] 完成既有知识服务、RAG、同步、配置、解析、runtime 与 OpenAPI 回归。证据：容器内 8 个测试文件 31 项通过。
- [CONCEPT: 测试方案] 完成 migration、preflight 与 ownership 静态回归。证据：容器内 163 项通过、1 项因无 PostgreSQL 测试 DSN 跳过。
- [CONCEPT: 测试方案] 完成相关 Agent Run 与鉴权回归。证据：容器内 20 项通过。
- [CONCEPT: 指标与验收] 完成目标 Python 文件 Ruff 和 compileall。证据：容器命令均退出码 0。
- [CONCEPT: 测试方案] 在一次性 PostgreSQL 测试数据库执行迁移链。证据：共享迁移探针完成
base → 0028与0028 → 0025 → 0028，knowledge_onlyoffice_sessions和agent_asset_onlyoffice_sessions均正常落库；有事实 downgrade 仍由各迁移显式拒绝。
7. 文档收尾
- [CONCEPT: 本轮实现记录] 更新 CONCEPT、分阶段 TODO 和三份 bug 修复日志。证据：本目录两份文档及
dev-logs/bugs/knowledge-*.md。 - [CONCEPT: 风险与开放问题] 记录 JSON index 多进程竞争、平台发布流程和长时编辑边界。证据：CONCEPT 风险章节。
- [CONCEPT: 降级策略] 上线前确认 ONLYOFFICE 下载域名从应用容器解析为公网地址并使用可信 TLS。证据要求：生产
ONLYOFFICE_DOWNLOAD_ALLOWED_ORIGINS配置与容器 DNS/TLS 验证；当前开发网络解析到198.18.0.0/15时会按设计拒绝真实回写。