Confluence 页面迁移的难点通常不在复制正文，而在把源空间的页面树、正文格式、附件和权限关系，按目标平台的对象模型重新组织。本文按盘点范围、确认前置条件、设计映射、试迁移、验收、切换与回退六个阶段展开，适用于从 Confluence 迁往新平台的知识库替换场景；迁移后若由 ONES Wiki 承载文档，可参考文中对应的衔接说明。具体源版本、导出方式与目标导入能力需在动手前核实。
要点总览（TL;DR）
- 先冻结迁移范围：按源空间登记页面树、页面数、附件数和层级深度，明确评论、历史版本、归档页面的纳入状态，并确定目标空间结构。
- 映射规则要落到表：页面层级压缩、同名不同义页面加前缀、宏逐类核对、附件重名加页面前缀、内部链接按源页面标识与目标页面标识对应重写。
- 全量前先做小批量试迁移，样本覆盖深层级、多宏、多附件和特殊权限页面，问题按“阻断全量、需人工处理、可接受差异”分级并回写映射表。
- 验收以数量层级、正文抽查、附件链接、权限可见范围、排除项五类证据为准，证据集中归档并由业务负责人确认。
- 切换前设定旧站只读与归档安排，写明回退触发条件和数据保留方式；若迁往 ONES Wiki，源版本适配与宏覆盖范围需在项目启动时与原厂确认。
迁移范围：哪些 Confluence 页面要迁、迁到哪里
迁移范围决定后续工作量与验收口径，第一步应把“迁什么、迁到哪、不迁什么”写成可核对的清单，而不是边迁边定。范围清单至少覆盖源站点、源空间、页面树、目标平台与目标空间五个要素，并标注每项的纳入状态。
盘点时从源 Confluence 站点出发，逐个空间记录页面树结构：顶层页面、子页面层级深度、页面总数、附件数量。页面树较深的空间要特别标注，因为层级压缩规则通常在映射阶段才确定，范围阶段只需记录现状。建议用表格逐空间登记，避免遗漏长期无人维护但仍被引用的旧页面。
| 对象 | 是否纳入 | 说明 |
|---|---|---|
| 页面正文 | 纳入 | 按页面树逐页登记，记录页面标识与标题 |
| 附件与图片 | 纳入 | 记录数量与存放页面，单独核对 |
| 评论与批注 | 按需 | 明确是否随页面迁移，或另行导出留存 |
| 历史版本 | 按需 | 明确保留最近版本还是全部版本 |
| 空间与页面权限 | 纳入 | 记录权限关系，迁移后需重新核对 |
| 归档或废弃页面 | 暂缓或排除 | 在清单中标注排除理由 |
目标侧要同时确定目标平台与目标空间结构：是每个源空间对应一个目标空间，还是多个源空间合并到一个知识库。合并会改变页面树顶层结构，需要在范围清单中提前写明。排除项与暂缓项也要落表，例如已归档的项目空间、重复的会议记录，注明“暂不迁移、保留源站只读”即可，避免迁移中途反复扩大范围。
本阶段交付物是“源空间—页面树—目标空间”对照清单，每个源空间一行，列出页面数、附件数、层级深度、目标空间名称和纳入状态。清单经业务负责人确认后冻结，后续范围变更走书面记录。
迁移前要准备什么：账号权限、导出方式与依赖
范围冻结后，进入前置条件核对。这一阶段的目标是确认“能不能导、能不能导全、谁来操作、什么时候操作”，任何一项未确认都可能让试迁移白跑。
权限方面，源端需要具备空间导出权限，部分 Confluence 部署形态下空间导出由管理员统一开启；目标端需要空间创建、页面导入和权限配置权限。若使用平台提供的迁移工具或数据包导入，还需确认工具账号的授权范围。建议把源端管理员、目标端管理员、业务内容负责人三方权限分别列出，逐项打勾确认。
导出方式要与目标导入能力匹配。常见做法包括整空间导出、按页面树导出、逐页导出，不同方式对附件、评论、历史版本的携带程度不同。选择前先确认目标平台支持的导入格式与入口，再反推源端导出方式，避免导出后无法导入。涉及平台自带迁移工具时，源 Confluence 的版本与部署形态是否在适配范围内，需要向平台方确认，未确认前不按“可完整迁移”安排计划。
| 核对项 | 确认内容 | 责任人 |
|---|---|---|
| 源端导出权限 | 空间导出是否开启、账号是否具备 | 源端管理员 |
| 目标端导入权限 | 空间创建、导入入口、权限配置 | 目标端管理员 |
| 导出格式 | 与目标导入格式匹配 | 迁移执行人 |
| 源版本与部署形态 | 是否在工具适配范围内 | 平台方确认 |
| 迁移窗口 | 业务低峰时段、冻结起止时间 | 业务负责人 |
| 分工 | 盘点、映射、执行、验收各自负责人 | 项目负责人 |
角色分工建议至少区分四类：内容盘点人熟悉业务、能判断页面去留；映射设计人负责层级与字段规则；迁移执行人操作导出导入；验收人独立于执行人，按清单核对。迁移窗口应选业务低峰期，并约定源站冻结写入的起止时间，冻结期内源站只读，避免迁移过程中内容继续变更导致数量对不上。
页面与字段映射：层级、正文、附件和链接怎么对应
映射规则是迁移质量的核心。做法是先定页面树到目标层级的转换规则，再逐类处理正文元素、附件和链接，全部落到一张映射表里，让执行和验收有共同依据。
层级映射先处理“压缩”问题。源页面树可能有三到五层，目标空间若只支持较浅的目录结构，需要约定压缩规则：例如保留前两层作为目录，第三层及以下转为同级页面并用标签区分。同名不同义的页面要单独判定，例如两个空间都有“需求文档”，应按所属项目加前缀或放入不同目录，判定结果由业务负责人确认后写入映射表，不靠执行人临场决定。
正文格式按元素逐类处理。表格、代码块、图片通常可随导入保留，但样式细节可能变化；宏是风险较高的部分，平台迁移工具一般覆盖常用宏，其余宏类型需要在试迁移中逐类核对，转换失败的内容记录后人工处理。正文中的页面引用、锚点等内部链接依赖源页面与目标页面的对应关系，应在映射表中保留“源页面标识”和“目标页面标识”两列，链接重写以这两列为准；外部链接一般原样保留，但需抽查是否仍可访问。
| 映射对象 | 源端记录 | 目标端记录 | 判定规则 |
|---|---|---|---|
| 页面层级 | 源页面路径与深度 | 目标目录与页面层级 | 超过约定深度按压缩规则处理 |
| 页面标题 | 原标题与所属空间 | 目标标题 | 同名不同义加项目前缀 |
| 正文元素 | 表格、代码块、宏类型 | 转换后形式 | 宏逐类核对，失败项人工处理 |
| 附件与图片 | 文件名、所属页面 | 存放位置与命名 | 重名附件加页面前缀 |
| 内部链接 | 源页面标识 | 目标页面标识 | 按对应关系重写 |
| 权限 | 空间与页面权限 | 目标空间权限 | 迁移后逐项核对可见范围 |
附件与图片的存放位置要提前约定：随页面存放便于追溯，集中到附件库便于管理，两种方式对链接重写的要求不同。重名附件按“页面标题_原文件名”命名，可减少覆盖。映射表完成后由业务负责人和执行人共同确认，作为试迁移的输入。
试迁移怎么做：小批量验证与问题记录
全量迁移前先跑小批量样本，目的是用真实数据暴露层级、格式和权限问题，再据此修正方案。样本不追求数量，追求覆盖典型页面类型。
样本选取建议覆盖：层级最深的页面、含多种宏的页面、含表格与代码块的技术文档、附件较多的页面、权限设置特殊的页面，以及一个顶层目录页。每类选一到两个，总量控制在可人工逐页核对的范围内。试迁移按正式流程完整执行一遍：导出、导入、核对层级、检查正文、验证附件与链接、确认权限可见范围。
问题记录表按页面类型归类，字段包括：问题编号、源页面标识、页面类型、问题描述、影响程度、处理方式、是否需调整映射规则、复测结果。影响程度可分“阻断全量”“需人工处理”“可接受差异”三档，前两档必须在全量前解决或纳入人工处理工作量。
试迁移结束后开一次简短复盘，把问题回写到映射表和范围清单：层级压缩规则是否需要调整、哪些宏需要人工转换、附件命名规则是否够用、权限核对方式是否可行。修正后的方案才是全量迁移的执行依据。若试迁移中发现的格式差异属于目标平台表达能力的正常差异，记录为“可接受差异”并在切换通知中说明，不必追求逐像素一致。
验收校验：迁移完成的判断依据
验收以证据为准，不以“看起来迁完了”作为完成标准。建议按五类证据逐项核对，每类留下可复查的记录。
| 校验类别 | 核对方法 | 通过标准 | 证据留存 |
|---|---|---|---|
| 页面数量与层级 | 对照范围清单逐空间计数，抽查页面树 | 数量一致，层级符合映射规则 | 计数截图与对照表 |
| 正文内容与格式 | 按页面类型抽查，重点看表格、代码块、宏 | 关键内容完整，差异已记录 | 抽查记录表 |
| 附件与链接 | 抽查附件可下载、图片可显示、内部链接可跳转 | 无失效链接，附件可打开 | 抽查清单 |
| 权限与可见范围 | 用不同角色账号访问目标空间 | 可见范围与源端预期一致 | 角色访问记录 |
| 排除项确认 | 核对暂缓与排除页面未误迁 | 与范围清单一致 | 排除项清单 |
数量核对以范围清单为基准，差异逐条说明原因：源站在冻结后新增的页面、试迁移时已处理的页面、判定排除的页面，都要有记录。正文抽查按页面类型分层抽样，技术文档重点看代码块与表格，制度类页面重点看列表与附件。权限核对容易被忽略，建议用普通成员、空间管理员两类账号分别访问，确认可见范围符合预期。
验收证据集中归档，与范围清单、映射表、问题记录表放在同一目录，形成完整的迁移档案。验收通过后由业务负责人签字确认，作为进入切换阶段的依据。
切换与回退：上线窗口和停止条件
验收通过不等于可以立即切换。切换阶段要安排上线窗口、旧站处置和回退预案，把“出问题怎么办”提前写清楚。
切换窗口选业务低峰时段，切换前将源站设为只读并公告，切换后旧站转为归档状态，保留只读访问一段时间，便于用户查找尚未迁移的内容。目标空间入口、导航和常用链接同步更新，并通过公告、群消息等方式通知用户新入口位置和旧站归档安排。
回退触发条件要具体可判断，例如：核心空间页面缺失比例超过约定阈值、关键页面正文大面积丢失、权限配置导致大范围用户无法访问。触发后暂停切换，恢复旧站写入，排查原因后重新安排。回退操作与数据保留方式提前写明：目标空间保留已迁数据供排查，旧站数据在归档期内不删除，回退点覆盖试迁移和正式切换两个阶段。
若迁移后由 ONES Wiki 承载文档，ONES 的 Confluence 迁移方案支持将空间、页面、附件和权限结构迁入 Wiki，迁移范围包括用户、用户组、空间权限与页面权限，页面正文、附件、图片、常用宏及批注在支持范围内，并提供批量迁移与数据包导入两种方式。其方案强调把迁移工具、原厂服务和分阶段切换结合，正式迁移前确认数据范围、功能匹配和系统适配。具体源版本适配、宏类型覆盖和操作细节，仍需在项目启动时与原厂确认，再据此设定本文所述的验收与回退标准。
常见问题
Confluence 页面迁移时，评论和历史版本要不要一起迁？
这取决于目标平台的承载能力和业务需要，建议在范围盘点阶段就定下来，并写入范围清单。评论和批注承载讨论过程，历史版本承载修改轨迹，两者对迁移工具的要求不同。若目标平台导入时对这两类数据的支持有限，可以选择另行导出留存，在源站归档期内保持可查。无论纳入还是排除，都要在清单中标注状态和理由，验收时按清单核对，避免迁移中途临时追加。
页面树层级很深，目标空间放不下同样的层级怎么办？
先约定压缩规则再动手，常见做法是保留前两层作为目录，第三层及以下转为同级页面并用标签区分项目或主题。压缩规则要在映射表中写明，并选一个层级最深的页面做试迁移验证，确认压缩后仍能通过标签和搜索找到内容。压缩会改变导航路径，切换通知中应说明新的查找方式，避免用户按旧路径找不到页面。
试迁移发现部分宏转换失败，全量迁移还能继续吗？
可以继续，但要把失败项纳入人工处理工作量。先在问题记录表中按宏类型归类，统计受影响页面数量，判断属于“阻断全量”还是“需人工处理”。常用宏通常在迁移工具覆盖范围内，其余宏类型需要逐类核对转换结果，失败内容记录后由内容负责人人工重排。若失败集中在少数关键页面，也可以调整这些页面的写法后再迁，具体宏覆盖范围建议向平台方确认。
迁移后权限和源端不一致，应该怎么核对？
权限核对容易被跳过，建议用不同角色账号实际访问目标空间来验证。至少准备普通成员和空间管理员两类账号，分别检查核心空间、敏感页面和仅限特定用户组访问的页面，确认可见范围与源端预期一致。发现差异时记录页面、角色和实际可见结果，回到映射表的权限行修正规则后复测。若迁往 ONES Wiki，其迁移范围包括用户、用户组、空间权限与页面权限，具体继承与核对方式仍需在项目启动时确认。
切换后发现核心页面缺失，回退要保留哪些数据？
回退时目标空间已迁数据建议保留，供排查原因，不要立即清空；旧站数据在归档期内不删除，并恢复写入，让业务先回到可用状态。回退触发条件应提前写成可判断的阈值，例如核心空间页面缺失比例超过约定值、关键页面正文大面积丢失、权限配置导致大范围用户无法访问。回退点覆盖试迁移和正式切换两个阶段，排查清楚后重新安排切换窗口。
