Confluence 页面迁移可以按“定范围—导出与盘点—字段与结构映射—试迁移—校验—切换与回退”六步推进。每一步都产出可核对的清单或记录，再进入下一步。迁移前需要明确源端 Confluence 的版本与空间范围、目标平台的承载形态，以及哪些页面属于必迁、可延后或不迁。本文按操作顺序说明每一步的具体做法、交付物和判断条件，迁移后的文档承载可自然衔接到 ONES Wiki 等平台。
要点总览（TL;DR）
- Confluence 页面迁移按“定范围—导出与盘点—字段与结构映射—试迁移—校验—切换与回退”六步推进，每一步都产出可核对的清单或记录。
- 范围盘点要区分必迁、可延后、不迁三类，统计页面数、附件数、评论数、标签数和链接数量，并标注模板页、宏页、归档页等特殊类型。
- 字段映射按“源字段—目标字段—转换规则—负责人”组织，同名字段先判定语义再决定转换方式；宏与富文本采用降级策略并记入差异清单。
- 先选页面类型齐全、数量可控的小空间试迁移，验证映射规则和工具链后再按批次放大。
- 校验以数量比对、正文抽样、链接可达性和层级权限抽查为准，切换阶段设置写入冻结窗口并保留原站只读作为回退点。
迁移范围怎么定：先锁定空间、页面树和附件
范围界定决定后续工作量和校验口径。做法是先按空间圈定候选范围，再沿页面树逐层标记，把“迁哪些页面”变成一张可核对的清单，而不是凭印象估算。
具体操作分四步：
- 按空间列出候选页面树，逐页标记为必迁、可延后、不迁三类。必迁通常是仍在使用的制度、流程、产品文档；可延后是低频访问但需保留的历史资料；不迁包括测试页、个人草稿、已废弃内容。
- 统计数量：页面数、附件数、评论数、标签数，以及内外部链接数量。这些数字是后续校验的基准，统计口径要写清楚，例如评论是否含已删除评论、附件是否按版本计数。
- 标注特殊页面类型：模板页、含宏的页面、归档页、会议记录类页面。它们往往需要单独制定映射或降级规则，提前标出可以避免在映射阶段返工。
- 记录源端版本与目标端承载形态，确定迁移方向。源端版本影响导出格式的可用选项，目标端是知识库、Wiki 还是文档系统，决定页面树如何对应目录结构。
这一步的交付物是一份迁移范围清单，包含页面树截图或导出、三类标记结果、数量统计表和排除项说明。清单需要业务负责人确认，确认后的范围在试迁移前不再随意扩大。
导出与盘点：把 Confluence 内容变成可处理的数据
范围确定后，需要把 Confluence 内容取出为可逐页处理的中间数据。常见路径有两条：按空间整体导出，或逐页导出。空间导出适合批量处理，能一次拿到页面树和大部分元数据；逐页导出适合页面数量少、或需要单独处理特殊页面的场景，控制更细但耗时更长。两条路径可以组合使用，例如整体导出后再对特殊页面单独补导。
导出后要重点保留以下元数据，它们是后续映射和校验的依据：
- 页面 ID 与父页面 ID，用于还原层级关系；
- 作者、创建时间与最后更新时间；
- 标签、附件清单及附件版本；
- 页面所在空间与原始 URL，用于旧链接跳转。
宏、嵌入内容和评论在导出中容易出问题。宏可能被导出为占位符或静态文本，嵌入的表格、图表可能丢失交互能力，评论可能只保留部分字段。处理方式是在导出后逐类抽查，把无法完整保留的内容记入差异清单，并在映射阶段决定转为静态内容、附件还是人工重建。
这一步的交付物是导出包加一张页面清单表。清单表建议包含页面 ID、标题、父页面、作者、时间、标签、附件数、特殊类型标记、迁移状态等列。后续映射、试迁移和校验都以这张表为唯一基准，避免多份数据口径不一致。
字段与结构映射：同名字段含义不同怎么处理
映射阶段要逐项确定源字段与目标字段的对应关系，并写清转换规则和负责人。建议用“源字段—目标字段—转换规则—负责人”四列组织映射表，每个字段一行，规则写到可执行的程度。
| 字段 | 映射要点 | 常见冲突与处理 |
|---|---|---|
| 标题 | 直接对应，保留原文 | 目标端标题长度限制更短时，截断并记录原题；重名页面加空间前缀区分 |
| 父页面/层级 | 按页面树还原父子关系 | 目标端目录层级有限制时，深层页面提升到最近的可承载层级，并在正文首行注明原路径 |
| 正文 | 富文本转为目标格式 | 格式不支持时降级为静态文本，保留可读性优先于样式还原 |
| 附件 | 按页面挂载，保留文件名 | 同名附件加序号；超出大小限制的附件单独列出人工处理 |
| 标签 | 转为目标端标签或分类 | 目标端标签数量或字符受限时合并同类标签，保留映射对照 |
| 作者与时间 | 尽量保留原作者和更新时间 | 目标端不支持写入原时间时，在页面属性或正文中记录 |
| 权限 | 空间权限与页面权限分别对应 | 权限模型不同时，先按“可见范围”归类，再逐类映射，无法对应的收紧为最小可见范围 |
同名字段含义不一致是映射中最容易出错的地方。例如源端的“标签”是自由文本，目标端的“标签”是受控分类；源端的“作者”指最后编辑人，目标端指创建人。处理方法是先判定字段语义，再决定直接转换、规则转换还是人工处理，判定结论写进映射表，避免执行时各人理解不同。
宏与富文本采用降级策略：能对应到目标端等价能力的直接转换；不能对应的转为静态内容或附件；完全无法承载的记入差异清单，由内容负责人决定是否重建。权限映射以“谁能看到什么”为准，先梳理源端权限分组，再对应到目标端的空间与页面权限，映射后做抽查验证。
试迁移怎么做：选一个小空间跑通全流程
试迁移的目的是用最小范围验证映射规则和工具链是否可行，把问题暴露在小范围内。选择试迁移空间的标准是页面类型齐全、数量可控：包含普通文档页、含宏页面、带附件的页面和至少一层子页面，总页数控制在几十页量级，便于逐页核对。
执行顺序建议按“结构—正文—附件—权限”推进：先建目录结构并导入页面骨架，确认层级正确；再导入正文并抽查格式；然后挂载附件；最后配置权限。批次上可以按页面树分支分两到三批，每批完成后记录问题再进入下一批。
试迁移过程中维护一张问题清单，记录问题页面、现象、原因分类（映射规则问题、工具限制、源数据问题）和处理结论。属于映射规则的，回到映射表修正；属于工具限制的，确定降级方案；属于源数据的，标记为不迁或人工修复。试迁移通过的标准是：页面数与附件数与清单一致，抽样正文无明显格式错乱，链接可达，权限抽查符合预期。
试迁移通过后，按空间或页面树分支把全量拆成若干批次，每批沿用已验证的规则和顺序执行。批次大小以单批可在一天内完成校验为宜，批与批之间保留问题修正的时间。
核验与证据：迁移完成后怎么判断迁对了
校验要给出可量化的口径，避免只凭目测确认。建议从四个维度核验，每项都留下记录：
- 数量比对：目标端页面数、附件数、标签数与页面清单表逐项比对，差异逐条说明原因。
- 正文抽样：按页面类型分层抽样，普通页、宏页、附件页各抽若干，比对标题、段落结构、表格和关键内容是否完整。
- 链接检查：抽查内外部链接是否可达，重点检查跨页面引用和指向附件的链接。
- 层级与权限抽查：随机抽取深层页面确认父子关系正确，抽取若干用户验证其可见范围与源端一致。
校验记录建议以清单形式留存，包含检查项、抽样范围、结果、差异描述、处理状态和签收人。差异处理记录要写清是接受降级、人工修复还是判定为不迁。签收责任人由业务负责人和迁移执行人共同确认，签收后才进入切换阶段。
如果迁移目标为 ONES Wiki，其 Confluence 迁移方案覆盖空间、页面、附件和权限结构，迁移数据包括用户、用户组、空间权限与页面权限，并支持页面正文、附件、图片、常用宏及批注的迁移，迁移方式支持批量迁移与数据包导入。校验时可以把上述数量比对和抽样口径直接套用，常用宏之外的宏和批注之外的内容需要单独列入差异清单评估。
切换与回退：什么条件下继续，什么条件下停
切换阶段的核心是控制写入和保留退路。做法是分批切换，每批切换前设置写入冻结窗口：在冻结时间内源端停止编辑，完成该批次的最终导出、导入和校验，校验通过后开放目标端编辑，源端转为只读。
原站保留只读是回退点的基础。只读期间源端内容不再更新，一旦目标端出现严重问题，可以恢复源端写入并暂停后续批次。触发回退或暂停的判断条件建议提前写明，例如：数量差异超过约定阈值且无法解释、关键页面正文大面积错乱、权限抽查出现越权可见、链接可达率明显偏低。条件由项目负责人和业务负责人共同确认后执行。
迁移收尾包括三件事：旧链接跳转，把源端常用入口指向目标端对应页面；通知，向使用团队说明新入口、只读期限和反馈渠道；归档，在只读期结束后按约定归档源端空间，避免两套入口长期并行维护。ONES 的迁移方案把迁移工具、原厂服务和分阶段切换结合起来，并在正式迁移前确认数据范围、功能匹配和系统适配，这一思路与上述分批切换和回退安排一致，具体节奏需按项目实际情况确定。
常见问题
Confluence 页面迁移需要停机吗？写入冻结窗口怎么安排？
不需要整站长时间停机，但切换阶段建议按批次设置短时写入冻结窗口。做法是每批切换前在约定时间内让源端停止编辑，完成该批的最终导出、导入和校验，通过后开放目标端编辑，源端转为只读。
冻结窗口的长度取决于单批页面数量和校验耗时，批次大小以单批能在一天内完成校验为宜。冻结期间需要提前通知使用团队，并明确反馈渠道，避免有人在冻结窗口内继续编辑造成数据不一致。
页面里大量使用宏和嵌入内容，迁移时怎么处理？
宏和嵌入内容在导出中可能变成占位符或静态文本，嵌入的表格、图表也可能失去交互能力。处理方式是导出后逐类抽查，把无法完整保留的内容记入差异清单，再在映射阶段决定转为静态内容、附件还是人工重建。
如果迁移目标为 ONES Wiki，其迁移范围包括常用宏及批注，常用宏之外的宏需要单独列入差异清单评估。建议在试迁移阶段就把使用频率高的宏跑一遍，确认转换效果后再决定全量策略。
迁移后原 Confluence 页面链接失效怎么办？
旧链接处理要在切换收尾阶段完成。导出时保留页面原始 URL 和页面 ID，建立源页面与目标页面的对应关系表；切换后把源端常用入口指向目标端对应页面，并在只读期内保留跳转说明。
对于外部系统或邮件中散落的旧链接，可以在源端空间首页放置迁移公告和新入口指引。只读期结束后按约定归档源端空间，避免两套入口长期并行维护。
作者、创建时间这些元数据迁不过去，会影响校验吗？
元数据迁移情况取决于目标端是否支持写入原字段。如果目标端不支持写入原时间或原作者，可以在页面属性或正文中记录，并在页面清单表中保留原始值作为对照。
校验时数量比对和正文抽样仍是主要口径，元数据差异单独列入差异清单说明处理方式。关键是迁移前在映射表中写清每个元数据字段的处理规则，避免执行时口径不一。
试迁移通过后，全量迁移按什么节奏分批比较稳妥？
建议按空间或页面树分支拆分批次，每批沿用试迁移已验证的规则和执行顺序。批次大小以单批能在一天内完成校验为宜，批与批之间留出问题修正的时间。
每批完成后做数量比对和抽样检查，确认无异常再进入下一批。如果某批出现数量差异无法解释、关键页面正文大面积错乱或权限越权可见，应暂停后续批次，回到映射表修正后再继续。
