企业官网建设流程全解析

知识库数据迁移完全指南：从 Confluence/语雀迁出，零数据丢失保姆级教程

2024年Confluence停售Server版，大量团队被迫寻找替代方案，但"替代"不只是选一个新工具——最让人头疼的是怎么把几千篇历史文档、几万条评论附件完整地搬过去，本文整理了一套经过验证的迁移方案，涵盖Confluence、语雀等主流平台的迁出流程，以及迁入自建知识库的完整步骤。

数据迁移为什么容易翻车？

在动手迁移之前，先搞清楚最容易出问题的三个环节：

1. 格式丢失

Confluence里的表格、代码块、宏（Macro）在导出成HTML后经常会变形，语雀的画板、数据表等富组件导出后也未必能原样还原，迁移前一定要先搞清：源平台哪些内容类型能导出，目标平台哪些格式能接收。

2. 附件断裂

文档里引用的图片、附件在迁移后经常出现"链接失效"的问题，原因通常是导出包里图片路径是相对路径，导入新系统后路径规则不一致导致引用断裂，需要在导入前后做路径映射处理。

3. 权限丢失

源平台上精心配置的空间权限、页面权限，导出文件里一般不会携带这些信息，迁移后需要在新平台上重新配置权限体系，这个工作量容易被低估。

主流平台迁出方案

从 Confluence 迁出

Confluence 官方提供了 HTML 导出功能，在"空间管理 → 内容工具 → 导出"中，选择 HTML 格式导出即可获得一个 ZIP 包，这个包包含了空间内所有页面的 HTML 文件及附件。

注意事项：

• HTML 导出会保留页面层级结构，但宏内容（如 Jira 图表、动态表格）可能变成静态占位符
• 附件会放在attachments文件夹下，HTML 中的引用是相对路径
• 如果页面数量超过 500 篇，建议分批次导出，避免超时

进阶方案：Confluence 也提供了 REST API，可以通过脚本批量获取页面内容（Wiki Markup 格式或 Storage Format），相比 HTML 导出更结构化，便于二次处理，有技术能力的团队可以考虑这个路线。

从语雀迁出

语雀的知识库支持"导出为 Markdown"和"导出为 HTML"两种格式，在知识库设置中操作，Markdown 导出对后续导入文本编辑器更友好。

注意事项：

• 语雀的画板、数据表等独家组件导出后通常是图片或静态内容
• 如果团队在语雀上重度使用"小记"功能，这些碎片内容需要单独处理
• 导出文件名默认是文档标题，长文件名可能在某些系统中有兼容性问题

从其他平台迁出

大多数文档平台（飞书文档、石墨文档、Notion等）都支持类似的一键导出功能，思路一致：先导出 → 检查格式 → 按需预处理 → 导入新系统。

迁入 zyplayer-doc：分步拆解

如果你评估后选定了 zyplayer-doc 作为目标平台，以下是完整的迁入流程。

第一步：创建空间结构

迁移不是简单地把文档"倒进去"，而是一次整理知识结构的机会，建议：

• 先在 zyplayer-doc 里按照目标结构创建好空间和目录
• 目录层级不超过 3 层
• 每个空间指定一个负责人，负责后续内容维护

第二步：选择导入方式

zyplayer-doc 提供了两种导入方式：

方式一：ZIP 批量导入（适合大多数场景）

将导出的 HTML 或 Markdown 文件打包成 ZIP，在目标目录下使用"批量导入"功能上传，系统会自动解析 ZIP 包内的文件结构，按原有层级创建文档，并自动处理附件路径。

方式二：CLI 工具批量上传（适合技术团队）

如果有大量本地 Markdown 文件，可以用 zyplayer-doc 的官方 CLI 工具批量上传：

# 将整个目录的内容上传到指定空间和父目录zy-cli page upload--spaceId你的空间ID--parentId父目录ID--dir./导出的文档目录/

CLI 方式的好处是支持断点续传、错误重试，适合几百篇以上文档的大批量迁移。

第三步：检查与修复

导入完成后，逐项检查：

• 格式检查：随机抽检 20-30 篇不同类型（纯文本、表格、代码块、混合）的文档，确认渲染正常
• 附件检查：确认图片、文件附件的引用链接可以正常打开
• 搜索检查：全文搜索几个关键词，确认新导入的文档能被搜到

第四步：重建权限

根据源平台的权限策略，在 zyplayer-doc 上逐空间重新配置，zyplayer-doc 支持空间、目录、文档、用户、部门五个层级的交叉授权，可以覆盖绝大多数权限场景。

如果公司有统一的 LDAP 或 SSO 账号体系，可以先接入，后续权限配置可以按部门批量操作，效率更高。

第五步：切换与过渡

迁移完成后的切换期建议这样安排：

• 第一周：新旧系统并行运行，旧系统设为只读
• 第二周：核心用户（各部门文档负责人）先切换到新系统
• 第三周：全员切换，旧系统下线或仅保留归档
• 过渡期：在各工作群里反复告知新入口地址，减少"找不到"的求助

迁移避坑清单

写在最后

数据迁移不是一个纯技术问题——迁移过程中的"顺便整理"和"权限重构"可能比搬运本身更有长期价值，建议把迁移当成一次知识库的"春季大扫除"，该归档的归档、该合并的合并、该删除的删除，让新工具承载的是更干净、更有序的知识体系。

zyplayer-doc 官网提供了在线体验站点，可以先上去动手试试导入功能，确认格式兼容性后再正式启动迁移。