编写 Confluence 迁移方案，核心是把“迁移什么、迁到哪里、怎么迁、怎么验、出问题怎么退”写成可执行、可核验的文档。方案先界定来源版本与空间范围，再盘点页面、附件、权限和宏等对象，建立字段与结构映射表，安排试迁移和抽样校验，最后明确切换窗口与回退触发条件。每一条结论都应配验证方法和责任人，让方案能直接用于评审和操作。
要点总览（TL;DR）
- 迁移方案先写清来源版本、目标平台与纳入排除范围，形成可签字确认的范围界定表。
- 字段与结构映射表固定六列：来源对象、来源字段、目标对象、目标字段、转换规则、异常处理，同名不同义以业务含义为准。
- 试迁移选取含复杂宏、大附件、多层权限的代表性空间，用抽样校验验证映射规则后再进入全量。
- 验收以数量核对、内容抽样、链接可达、权限可见性四类证据支撑，并留存签字记录。
- 切换一节写明只读时点、步骤顺序、回退触发阈值、决策人和来源系统保留期限。
来源、目标与迁移范围怎么界定
方案开头先锁定迁移方向与对象边界，这一节写不清，后面的映射表和验收标准都会失去基准。范围界定要回答四个问题：从哪里迁、迁到哪里、迁什么、不迁什么。
来源侧写明 Confluence 的版本和部署形态。云版与数据中心版在导出能力、可用格式和权限模型上存在差异，方案中应记录实际版本号，并注明导出能力已在来源系统验证过，而非依据文档推测。目标侧写明目标平台名称，以及目标空间或知识库的层级结构，例如按部门建空间、按项目建页面树，还是沿用原有空间划分。
纳入范围按对象分组界定，通常分为空间、页面树、附件、评论、权限五组。每组写明纳入的判定条件，例如“2023 年以后活跃的产品与研发空间”“页面树深度不超过五层的业务文档”。排除项要逐条给出理由，常见的有历史归档空间（访问频率低、迁移成本高）、个人草稿（归属不清、无共享价值）、已废弃项目空间（内容已被新空间取代）。排除不等于删除，来源系统在保留期内仍可查阅。
下表可直接填入方案，作为范围界定的交付物：
| 项目 | 填写内容 | 责任人 |
|---|---|---|
| 来源系统与版本 | Confluence 云版/数据中心版，版本号 | IT 负责人 |
| 目标平台与结构 | 目标平台名称，目标空间/知识库划分方式 | 平台管理员 |
| 纳入对象 | 空间清单、页面树范围、附件与评论范围、权限范围 | 内容所有者 |
| 排除对象及理由 | 逐条列出排除空间或对象，注明理由 | 内容所有者 |
| 范围确认签字 | 内容所有者、IT、安全合规 | 项目经理 |
本阶段输入与依赖清单
范围确定后，方案编写还依赖一批外部信息。这些信息没拿到就动笔，映射规则和验收标准只能靠猜。建议在方案中单列一节，把每项输入的获取方式、负责人和确认状态列成清单，未确认项标红，作为方案评审的前置条件。
需要提前拿到的输入包括：
- 来源侧导出能力与格式：Confluence 可用的导出方式（空间导出、页面导出、XML 备份等）及实际可用的格式，需在来源系统实际操作验证，记录验证人和验证时间。
- 目标侧导入能力与限制：目标平台支持的导入方式、字段长度上限、附件大小上限、单次导入数量限制，需向目标平台方确认，不能凭经验填写。
- 账号与权限对应关系：来源系统的用户、用户组清单，以及组织架构或统一身份源，作为权限映射的输入。
- 迁移窗口与停机容忍度：业务可接受的只读时长、可用的周末或夜间窗口，以及内容冻结的时间点。
- 干系人确认：内容所有者对范围的确认、IT 对环境和账号的确认、安全合规对数据出域和权限降级的确认。
清单中每一项都标注“已确认/待确认”，待确认项写明预计获取时间。方案评审时，待确认项过多说明准备不足，应推迟进入试迁移。
页面、附件与权限的映射方法
映射是迁移方案的技术核心，目标是把来源对象逐类对应到目标对象，并对无法直接对应的部分给出处理规则。建议用一张统一的映射表承载，字段固定为六列：来源对象、来源字段、目标对象、目标字段、转换规则、异常处理。
页面树与目录结构
页面树到目标目录的映射先定规则再定细节。常见做法是保留原有空间划分，页面层级按目标平台的目录深度上限做压缩，超过上限的层级合并到父页面下，并在页面开头加一段目录说明。压缩规则要写进映射表，注明哪些页面树会被压缩、压缩后如何导航。
正文元素逐类处理
富文本、表格、代码块、宏、内嵌附件需要逐类标注处理方式。表格和代码块通常可保留结构；宏是风险集中区，常用宏（如目录、状态、信息面板）一般有对应实现，自定义宏和第三方插件宏需要逐项评估，不能假设一一对应。每类元素在映射表中标注“自动转换/需人工复核/需重写”，人工复核项要估算工作量并分配责任人。
权限映射与降级
权限从来源的空间级、页面级权限对应到目标平台的角色体系。先建立“来源权限组合→目标角色”的对应表，对无法对应的组合给出降级方案，例如来源中“仅特定用户组可编辑”在目标端降级为“空间成员可编辑、其他只读”，并记录降级清单供安全合规确认。
同名不同义字段
字段映射以业务含义为准，不以字段名为准。来源和目标都有“状态”字段但取值体系不同时，应建立取值对照表；含义重叠但不完全一致的字段，按业务用途决定拆分或合并，并在映射表异常处理列写明理由。下表为映射表模板示例：
| 来源对象 | 来源字段 | 目标对象 | 目标字段 | 转换规则 | 异常处理 |
|---|---|---|---|---|---|
| 页面 | 标题 | 文档 | 标题 | 原样保留，超长截断并加后缀 | 截断清单人工确认 |
| 页面 | 正文宏 | 文档 | 正文块 | 常用宏映射，自定义宏转纯文本 | 列入人工复核清单 |
| 空间权限 | 用户组读写 | 知识库角色 | 成员/只读 | 按角色对照表转换 | 无法对应时降级并记录 |
试迁移怎么做、验什么
试迁移的作用是用小范围真实数据检验映射规则是否成立，而不是提前跑一遍全量。样本选择决定试迁移的价值：应包含复杂宏较多的空间、含大附件的空间、多层权限设置的空间，以及页面树较深的空间，覆盖映射表中最容易出问题的类别。
执行顺序建议按“单页面→单空间→多空间”递进，每一步记录执行时间、执行人、使用的导出格式和导入方式。记录方式统一用问题登记表，每条问题写明现象、涉及对象、对应映射规则、处理结论。问题处理完成后回写映射表，形成“发现问题—修订规则—再验证”的闭环。
抽样校验至少覆盖四类：页面数量是否与来源一致、正文渲染是否正常（表格、代码块、图片）、附件是否可下载打开、权限可见性是否符合预期。抽样比例按空间规模设定，例如每个样本空间抽取 10% 页面且不少于 20 页，权限按角色各抽 3 至 5 个账号验证。
试迁移通过标准应写成可判定的条件，例如“抽样页面正文渲染异常率低于 2%”“附件可下载率 100%”“权限抽查无越权可见”。达到标准才进入全量迁移；未达到则回到映射表修订，不带着已知问题扩大范围。
核验证据与验收标准
验收环节要回答“凭什么说迁移完成了”。方案中把验收拆成四类核对，每类写明核对项、抽样方法、通过标准和签字人，证据统一留存到指定位置，便于事后追溯。
| 核对类别 | 核对项 | 抽样方法 | 通过标准 |
|---|---|---|---|
| 数量核对 | 页面、附件、评论迁移前后计数 | 全量比对 | 差异项逐条说明原因 |
| 内容核对 | 正文、表格、代码块、图片 | 按空间抽样 10% | 异常率低于约定阈值 |
| 链接与引用 | 内部链接、外部链接、页面引用 | 抽样页面全量检查链接 | 失效链接有清单和处理结论 |
| 权限核对 | 按角色抽查可见与不可见 | 每类角色 3 至 5 个账号 | 无越权可见，降级项已确认 |
数量核对以来源系统导出清单与目标平台导入结果为基准，差异项不能简单归为“格式问题”，要逐条定位。链接核对中，指向已排除空间的链接应提前列入已知失效清单，与真正的迁移错误区分开。验收签字由内容所有者、IT 负责人和安全合规代表分别确认各自负责的核对项，签字记录与核对表一并归档。
迁移过程中的问题登记、任务分派和验收确认需要有人跟进到关闭。ONES 工作项可用于登记试迁移问题并指派责任人，ONES Wiki 可承载映射表、核对表和验收记录，让方案文档与执行记录保持在同一处，评审时直接查看状态而非另找表格。ONES 的 Confluence 迁移支持将空间、页面、附件和权限结构迁入 ONES Wiki，迁移数据包括用户、用户组、空间权限与页面权限，页面正文、附件、图片、常用宏及批注在支持范围内；具体版本兼容范围和附件、宏的限制需在方案中向平台方确认后填写。
切换安排与回退、停止条件
切换一节写的是上线当天的操作序列和退出路径，需要精确到时间点和责任人。先定切换窗口和来源系统转为只读的时点，只读时点之后来源侧的修改不再进入迁移范围，应提前通知内容所有者。切换步骤按顺序列出：冻结内容、执行最终增量迁移、目标平台抽检、开放访问、来源系统转只读归档，每一步写明执行人和预计耗时。
回退触发条件要写成可判定的阈值，而不是“出现严重问题”这类模糊表述。常见条件包括：关键内容缺失比例超过约定值、权限错配导致越权可见、核心导航链接大面积失效、目标平台在观察期内不可用超过约定时长。每个条件对应一个决策人，触发后由决策人判断执行回退。
回退操作方式写明具体路径：来源系统在保留期内保持可访问，回退即将访问入口切回来源系统，并暂停目标平台的写入。来源系统保留期限在方案中明确，例如切换后保留 3 个月，到期前由内容所有者确认无回退需求再下线。
停止条件针对迁移过程本身：试迁移未达到通过标准时暂停全量迁移；全量迁移中数量核对差异超过阈值时暂停并排查；安全合规未完成权限降级确认时不开放访问。切换后设置观察期，明确问题响应机制，包括响应人、响应时限和问题升级路径，观察期结束且验收签字完成后，迁移项目才算收尾。
常见问题
Confluence 云版和数据中心版的迁移方案写法有区别吗？
有区别，主要体现在来源侧导出能力和权限模型上。云版和数据中心版可用的导出方式、导出格式和权限粒度不同，方案中应记录实际版本号，并在来源系统实际操作验证导出能力，不能依据文档推测。权限映射部分也要按实际版本的空间级、页面级权限组合来建立对照表，无法对应的组合给出降级方案并记录。
迁移方案里要不要写具体工具的操作步骤？
建议写清工具选型结论和关键操作约束，不必把每一步点击写成手册。方案中应写明使用的迁移方式（如批量迁移、数据包导入）、导入格式、单次导入数量限制和附件大小上限，这些信息需向目标平台确认后填写。具体操作步骤可以另附操作手册，方案正文保留可评审的规则和判定条件。
试迁移通过后，全量迁移还需要重新抽样验收吗？
需要。试迁移验证的是映射规则是否成立，全量迁移后要按验收标准重新核对数量、内容、链接和权限。全量阶段的数据量和对象范围更大，可能出现试迁移样本未覆盖的页面类型或权限组合。验收核对表应写明抽样比例、通过标准和签字人，差异项逐条定位原因，不能简单归为格式问题。
回退触发条件里的阈值怎么定才合理？
阈值应结合业务对内容完整性和权限安全的要求来定，并在方案评审时由内容所有者、IT 和安全合规共同确认。常见做法包括：关键内容缺失比例超过约定值、权限错配导致越权可见、核心导航链接大面积失效、目标平台在观察期内不可用超过约定时长。每个条件对应一个决策人，触发后由决策人判断是否执行回退。阈值不追求统一数值，关键是可判定、有人负责。
迁移过程中发现宏无法对应，方案里怎么处理？
在映射表的异常处理列逐项登记，标注“需人工复核”或“需重写”，并估算工作量、分配责任人。常用宏一般有对应实现，自定义宏和第三方插件宏需要逐项评估，不能假设一一对应。评估结论回写到映射表，试迁移阶段重点验证这些高风险项，验收时把宏渲染结果纳入内容抽样核对。
