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