feat: implement lossless knowledge archive export and import functionality

Author: liuruibin

apps/knowledge/ARCHIVE.md

@@ -0,0 +1,49 @@
+# 知识库导入与导出
+
+知识库整体 ZIP 导出接口 `export_knowledge` 使用版本 2 归档。工作空间、系统资源和共享资源
+复用同一导出实现，共享资源与工作空间导入也复用同一导入实现。本次仅涉及后端。
+
+## 文件结构与兼容
+
+- `knowledge.json`：知识库设置，以及 `archive_version: 2` 标识的完整 `resources` 数据。
+- `knowledge.xlsx`：保留原来的表格表示，便于查看内容及兼容旧格式；新版导入以 JSON 中的
+  `resources` 为准，避免 Excel 单元格长度、工作表名称和标签分隔符造成数据损失。
+- `oss/file/{原文件ID}`：图片及内容所引用的文件。
+- `source_file/`：选择 `with_source_file=true` 时附带的普通文档原始文件。
+- `workflow.kbwf`：工作流知识库沿用原有工作流和工具导出格式。
+
+不含版本标识的旧 ZIP 继续走原有 Excel 导入流程；缺少新增配置时使用当前默认值。
+不支持的版本、缺失文件或损坏的资源关联会报错，不会静默降级为只导入文字。
+普通 Excel/ZIP 内容导出接口仍是原有用途，完整迁移请使用知识库整体 ZIP 导出。
+
+## 保存与恢复的数据
+
+| 范围 | 内容 |
+| --- | --- |
+| 知识库设置 | 名称、描述、类型、文件限制、外部服务开关与身份认证开关、知识库级处理策略、定时同步设置及保存的工作流同步输入 |
+| 文档和独立图片 | 原始名称、资源类型、启停状态、召回处理方式、阈值、文档处理策略、源信息、同步版本/时间及策略哈希 |
+| 分段 | 完整正文、标题、子块、结构化图片内容、启停及排序、来源快照、本地/同步状态、锚点关系 |
+| 图片资产 | 图片文件、标题、OCR、视觉描述、处理状态、来源与分段关联；即使未选择附带普通原始文件也会打包图片 |
+| 问题与标签 | 包括未关联的问题、问题与分段映射、标签及文档关联；标签中的冒号和竖线不丢失 |
+| 召回统计 | 文档、分段、问题及图片资产的次数和最后召回时间 |
+| 工作流 | 工作流定义、原有工具导入选项，以及默认模型设置 |
+
+导入生成新的知识库、文档、分段、问题、资产、标签和文件 ID，重建关联，并替换正文、
+结构化内容和元数据里的文件引用。文件通过目标环境的存储后端写入，不携带原数据库大对象地址
+或对象存储 key。内部文件 URL 转换为目标环境可使用的相对路径。
+
+外部服务开关按归档恢复，包括旧知识库空配置的兼容语义；新建知识库两个开关默认关闭的规则不变。
+已有的对话用户 API Key 和授权关系不随归档复制。已开启的定时设置在导入事务提交后注册调度任务，
+关闭的设置只保存配置。
+
+保留原有飞书连接凭据不导出的规则，同时单独保留其处理策略和定时设置；导入后需要重新配置
+飞书连接。模型/视觉工具保留配置引用，不导出模型凭据；目标环境需具备对应资源与权限。
+向量、分词索引、正在执行的任务以及同步执行日志不作为归档资源复制。导入后仍按原有流程选择
+嵌入模型并重建索引，外部连接和任务依赖需在目标环境配置完成。
+
+## 验证
+
+`python apps/manage.py test knowledge.test_archive` 覆盖真实 ZIP/JSON/XLSX 序列化往返、
+旧格式导入、图片二进制与关联恢复、设置/统计/工作流保留、长正文、空文档、原始文件选项、
+跨知识库文件保护以及损坏归档校验。数据库和文件存储写入在这些单元测试中被隔离；真实
+PostgreSQL、对象存储和调度器仍需在配置好的集成环境验收。

apps/knowledge/serializers/knowledge.py

@@ -65,7 +65,14 @@
     Termbase,
 )
 from knowledge.services.document_strategy import normalize_document_strategy
-from knowledge.services.knowledge_sync_schedule import remove_knowledge_sync_job
+from knowledge.services.knowledge_archive import (
+    ARCHIVE_VERSION,
+    export_resources,
+    portable_knowledge_meta,
+    restore_resources,
+    validate_archive,
+)
+from knowledge.services.knowledge_sync_schedule import deploy_knowledge_sync_job, remove_knowledge_sync_job
 from knowledge.services.multimodal_retrieval import (
     MAX_QUERY_IMAGE_COUNT,
     get_hit_asset_map,
@@ -664,6 +671,7 @@ def export_knowledge(self, with_source_file=False, with_valid=True):
                     QuerySet(File).filter(source_id__in=document_id_list, source_type=FileSourceType.DOCUMENT)
                 )
             source_file_map = {str(source_file.source_id): source_file for source_file in source_file_list}
+            source_files_by_id = {str(source_file.id): source_file for source_file in source_file_list}
 
             # 查询标签和文档标签关联
             tag_list = list(QuerySet(Tag).filter(knowledge_id=knowledge_id).values("id", "key", "value"))
@@ -685,7 +693,9 @@ def export_knowledge(self, with_source_file=False, with_valid=True):
             for doc in document_list:
                 if with_source_file:
                     doc.meta = {**doc.meta} if doc.meta else {}
-                    source_file = source_file_map.get(str(doc.id))
+                    source_file = source_files_by_id.get(str(doc.meta.get("source_file_id"))) or source_file_map.get(
+                        str(doc.id)
+                    )
                     if source_file:
                         doc.meta["source_file_id"] = str(source_file.id)
                     else:
@@ -747,15 +757,21 @@ def export_knowledge(self, with_source_file=False, with_valid=True):
                         f.write(source_file.get_bytes())
 
                 knowledge_json = {
+                    "archive_version": ARCHIVE_VERSION,
+                    "source_knowledge_id": str(knowledge.id),
                     "name": knowledge.name,
                     "desc": knowledge.desc,
                     "type": knowledge.type,
-                    "meta": {} if knowledge.type == KnowledgeType.LARK else (knowledge.meta if knowledge.meta else {}),
+                    "meta": portable_knowledge_meta(knowledge),
+                    "external_service": knowledge.external_service,
                     "file_size_limit": knowledge.file_size_limit,
                     "file_count_limit": knowledge.file_count_limit,
                     "tags": [{"key": t["key"], "value": t["value"]} for t in tag_list],
                     "termbase": terms,
                     "source_file_list": source_file_export_list,
+                    "resources": export_resources(
+                        knowledge, document_list, source_file_list, tempdir, source_file_export_list
+                    ),
                 }
 
                 with open(os.path.join(tempdir, "knowledge.json"), "w", encoding="utf-8") as f:
@@ -954,6 +970,7 @@ def import_knowledge(self, file, is_import_tool=False, with_valid=True):
 
             # knowledge.json -> knowledge
             knowledge_data = json.loads(zf.read("knowledge.json"))
+            resources = validate_archive(knowledge_data, zf)
             source_file_meta_map = {
                 str(source_file.get("id")): source_file
                 for source_file in knowledge_data.get("source_file_list", [])
@@ -981,12 +998,20 @@ def import_knowledge(self, file, is_import_tool=False, with_valid=True):
                 user_id=user_id,
                 workspace_id=workspace_id,
                 folder_id=folder_id,
+                **(
+                    {"external_service": knowledge_data["external_service"]}
+                    if "external_service" in knowledge_data
+                    else {}
+                ),
             )
             knowledge.save()
 
+            if resources is not None:
+                restore_resources(knowledge, knowledge_data, zf)
+
             # 图片
             old_to_new_file_map = {}
-            for name in namelist:
+            for name in namelist if resources is None else []:
                 if name.startswith("oss/file/") and name != "oss/file/":
                     old_id = name.split("/")[-1]
                     if not old_id:
@@ -1003,15 +1028,17 @@ def import_knowledge(self, file, is_import_tool=False, with_valid=True):
                     old_to_new_file_map[old_id] = str(new_file.id)
 
             # knowledge.xlsx -> doc + para + problem
-            xlsx_bytes = io.BytesIO(zf.read("knowledge.xlsx"))
-            workbook = openpyxl.load_workbook(xlsx_bytes)
+            sheets = []
+            if resources is None:
+                xlsx_bytes = io.BytesIO(zf.read("knowledge.xlsx"))
+                sheets = openpyxl.load_workbook(xlsx_bytes).worksheets
 
             document_model_list = []
             paragraph_model_list = []
             problem_paragraph_object_list = []
             doc_tags_map = {}
 
-            for sheet in workbook.worksheets:
+            for sheet in sheets:
                 doc_name = sheet.title
                 rows = list(sheet.iter_rows(min_row=2, values_only=True))
                 if not rows:
@@ -1112,14 +1139,15 @@ def import_knowledge(self, file, is_import_tool=False, with_valid=True):
             QuerySet(Paragraph).bulk_create(paragraph_model_list) if len(paragraph_model_list) > 0 else None
 
             # 问题
-            problem_model_list, problem_paragraph_mapping_list = ProblemParagraphManage(
-                problem_paragraph_object_list, knowledge_id
-            ).to_problem_model_list()
-            bulk_create_in_batches(Problem, problem_model_list, batch_size=1000)
-            bulk_create_in_batches(ProblemParagraphMapping, problem_paragraph_mapping_list, batch_size=1000)
+            if resources is None:
+                problem_model_list, problem_paragraph_mapping_list = ProblemParagraphManage(
+                    problem_paragraph_object_list, knowledge_id
+                ).to_problem_model_list()
+                bulk_create_in_batches(Problem, problem_model_list, batch_size=1000)
+                bulk_create_in_batches(ProblemParagraphMapping, problem_paragraph_mapping_list, batch_size=1000)
 
             # Tag
-            tag_list = knowledge_data.get("tags", [])
+            tag_list = knowledge_data.get("tags", []) if resources is None else []
             if tag_list:
                 tag_model_list = []
                 tag_key_value_to_model = {}
@@ -1170,6 +1198,9 @@ def import_knowledge(self, file, is_import_tool=False, with_valid=True):
 
             update_resource_mapping_by_knowledge(str(knowledge_id))
 
+            if (knowledge.meta.get("sync_setting") or {}).get("enabled"):
+                transaction.on_commit(partial(deploy_knowledge_sync_job, str(knowledge_id)), robust=True)
+
             zf.close()
             return {"knowledge_id": str(knowledge_id), "type": knowledge.type}
 

apps/knowledge/serializers/knowledge_workflow.py

@@ -584,7 +584,16 @@ def import_(self, instance: dict, is_import_tool, with_valid=True):
             )
             tool_model_list = [self.to_tool(tool, workspace_id, user_id) for tool in tool_list]
             KnowledgeWorkflow.objects.filter(workspace_id=workspace_id, knowledge_id=knowledge_id).update_or_create(
-                knowledge_id=knowledge_id, workspace_id=workspace_id, defaults={"work_flow": work_flow}
+                knowledge_id=knowledge_id,
+                workspace_id=workspace_id,
+                defaults={
+                    "work_flow": work_flow,
+                    **(
+                        {"default_model_setting": knowledge_workflow["default_model_setting"]}
+                        if "default_model_setting" in knowledge_workflow
+                        else {}
+                    ),
+                },
             )
 
             if is_import_tool: