Confluence 附件迁移可以按“盘点、映射、试迁、校验、分批切换”五步推进：先导出空间与页面清单，统计附件数量、大小、版本和引用关系；再确定目标端的目录层级、命名与权限规则，建立页面—附件—版本映射表；随后选一个低风险空间试迁，核对文件数量、大小、版本与正文引用；通过后分批切换，并保留原空间只读作为回退点。本文适用于 Confluence 向目标知识库搬迁附件的实施阶段，不涉及工具选型与报价核算。
要点总览（TL;DR）
- 附件迁移按“盘点、映射、试迁、校验、分批切换”推进，盘点清单是后续试迁与验收的比对基准。
- 盘点要记录空间、页面路径、附件名、类型、大小、版本数与引用页面，并单独标注孤立附件、超大附件和外链附件。
- 映射表以页面 ID 为主键，附件与所属页面绑定并逐版本对应，正文内嵌图片和附件宏引用单独列出替换规则。
- 试迁选附件类型齐全、体量适中、引用关系有代表性的低风险空间，先迁页面结构、再迁附件、最后修正正文引用。
- 核验以数量、总字节数、版本保留和引用可打开为判定项，切换前预设暂停条件并保留原空间只读作为回退点。
迁移范围：先盘清 Confluence 里有哪些附件
附件迁移的返工大多源于盘点不完整：迁移到一半才发现某个空间有大量超大文件，或者页面正文引用的图片在附件列表里找不到对应项。盘点阶段的目标是把源端“有什么、在哪里、被谁引用”变成一份可逐项核对的清单，后续试迁和验收都以它为基准。
盘点对象按四个维度组织：空间、页面树、附件类型与大小、版本数。空间决定迁移批次，页面树决定目标端目录结构，附件类型与大小影响传输方式和存储规划，版本数决定是否需要保留历史版本。建议从 Confluence 的空间导出或管理接口获取页面清单，再逐页拉取附件元数据，形成如下结构的清单表：
| 空间 | 页面路径 | 附件名 | 类型 | 大小 | 版本数 | 引用页面 | 处理方式 |
|---|---|---|---|---|---|---|---|
| 示例：研发中心 | /架构/接口规范 | api-spec-v3.pdf | 2.4 MB | 3 | 接口规范、联调说明 | 随页面迁移 | |
| 示例：研发中心 | /架构/部署图 | deploy.png | 图片 | 860 KB | 1 | 部署图（正文内嵌） | 随页面迁移并修正引用 |
盘点时需要区分三类对象，它们的迁移处理方式不同：正文内嵌图片随页面正文一起渲染，迁移后要检查引用路径是否仍指向新附件；附件文件是独立上传到页面的文件，需要与所属页面绑定；页面历史版本中的附件容易被忽略，如果业务要求保留历史版本，盘点时就要把版本数一并记录，并在验收时单独核对。
引用关系是盘点的重点字段。同一份附件可能被多个页面正文或宏引用，迁移后这些引用都要指向新位置，否则会出现“文件迁过去了但页面打不开”的情况。盘点时记录每个附件被哪些页面引用，可以用页面导出内容中的附件链接做匹配，也可以借助 Confluence 的附件使用情况查询逐项确认。
清单中还要单独标注三类特殊附件：孤立附件，即没有页面引用的上传文件，需要业务方确认是保留还是丢弃；超大附件，超过目标端单文件限制的文件要提前规划拆分或改用其他存储方式；外部链接附件，即以链接形式引用外部地址的文件，迁移时只需保留链接并验证可访问性，不涉及文件本体搬迁。盘点完成后由各空间负责人确认清单，确认后的版本作为后续试迁比对的基准。
目标端准备：目录结构、命名与权限怎么定
目标端的结构规则要在迁移开始前定下来，否则映射阶段会反复调整。需要确定四件事：空间与目录层级如何对应、重名附件怎么处理、权限如何继承、存储容量与单文件限制是多少。
目录层级建议以源端空间对应目标端的空间或知识库，源端页面树对应目标端的目录树，保持“空间—页面—子页面”的层级关系不变，这样用户迁移后的查找习惯不需要重建。如果源端存在多层嵌套或跨空间引用，先在结构方案中列出对应关系，避免迁移时临时决定。
附件命名冲突是常见问题。Confluence 允许不同页面存在同名附件，目标端如果按目录扁平存储就可能重名。处理规则可以按“页面路径 + 原文件名”生成唯一名称，或在冲突时追加序号并记录到映射表；无论采用哪种规则，都要保证映射表能反查回原文件，便于验收和回退。
权限继承方式需要明确：附件是跟随所属页面的权限，还是单独设置附件级权限。多数知识库以页面权限为准，附件继承页面权限，这种方式的维护成本低，但要求迁移前把页面权限关系理清。如果业务上存在“页面可见但附件仅部分人可见”的场景，要在方案中单独列出，并在迁移后逐项复核。
存储容量与单文件大小限制要向目标端确认，确认结果直接回写到盘点清单的“处理方式”列：超过限制的文件标记为拆分、压缩或外链保留。这一步没有确认清楚，试迁阶段就会暴露失败项，导致返工。
字段与引用映射：页面、附件、版本如何对应
映射表是附件迁移的核心交付物，作用是把源端的每个对象对应到目标端的具体位置，并在出现差异时能定位到原因。建议的映射表结构如下：
| 源页面 ID | 源页面标题 | 源路径 | 目标对象 ID | 目标路径 | 附件名 | 源版本号 | 目标版本号 | 引用页面 | 映射状态 | 备注 |
|---|---|---|---|---|---|---|---|---|---|---|
| 10021 | 接口规范 | /架构/接口规范 | 待填 | /研发知识库/架构/接口规范 | api-spec-v3.pdf | 3 | 待填 | 接口规范、联调说明 | 自动对应 | — |
| 10035 | 部署图 | /架构/部署图 | 待填 | /研发知识库/架构/部署图 | deploy.png | 1 | 待填 | 部署图（正文内嵌） | 需人工处理 | 正文引用需替换 |
页面层面的映射字段包括源页面 ID、标题、路径与目标端对象 ID、路径。页面 ID 是稳定标识，标题和路径可能因重命名而变化，映射时以 ID 为主键，标题和路径作为核对字段。附件与所属页面通过页面 ID 绑定，同时记录源版本号与目标版本号，多版本附件要逐版本对应，不能只迁最新版。
正文内嵌图片与附件宏引用的替换是映射中最容易断链的部分。内嵌图片在迁移后需要指向新附件地址，附件宏则需要按目标端支持的展示方式重建。处理方式是在映射表中为每个引用单独列一行，标注“引用类型、原引用位置、目标引用方式、替换状态”，迁移后逐项验证链接可打开。无法自动对应的宏或引用进入人工处理队列，由页面负责人确认展示方式后再处理。
映射状态建议统一为“自动对应、需人工处理、已处理、已核验”四类，便于统计进度。人工处理队列要指定负责人和处理时限，避免积压到切换前才集中处理。
试迁移：选一个空间跑通全流程
试迁的目的是用一个小范围验证盘点清单和映射规则是否成立，而不是提前完成全量迁移。选样标准是附件类型齐全、体量适中、引用关系有代表性，并且业务影响低。一个包含文档、图片、表格、压缩包且存在跨页面引用的中等规模空间，比一个只有少量文档的空间更能暴露问题。
执行顺序建议为：先迁页面结构，确认目录层级和页面权限对应正确；再迁附件，按映射表逐项上传并记录结果；最后修正正文引用，检查内嵌图片和附件宏是否指向新位置。这个顺序的好处是每一步的失败项都能单独定位，不会把结构问题和引用问题混在一起。
试迁过程中要保留日志：每个页面的迁移时间、附件成功与失败数量、失败原因、人工处理项。日志与盘点清单逐项比对，形成差异清单，差异项分为“规则问题”和“个案问题”两类。规则问题要回到映射表修正规则后重跑，个案问题进入人工处理队列。
试迁完成后，由空间负责人按差异清单确认：数量是否一致、大小是否一致、版本是否保留、引用是否可打开。确认通过的规则才能用于后续批次；未通过的规则先修正再扩大范围。
核验与证据：怎么判断附件迁移成功
判断附件迁移是否完成，要依据可核对的数字和可打开的链接，不能只凭页面“看起来正常”。核验项按四个层面组织：
- 数量与大小：清单总数、成功数、失败数、总字节数逐项比对，失败项要有明确原因和处理结论。
- 版本核对：多版本附件逐版本检查是否保留历史版本，版本号与映射表一致。
- 引用核对：抽查页面正文中的图片和附件链接，确认可以打开且指向正确文件，重点检查跨页面引用的附件。
- 人工验收：由页面负责人抽样打开附件、下载文件、查看历史版本，确认后签字。
证据留存建议包括：盘点清单终版、映射表、试迁日志与差异清单、验收核对表、差异处理记录。验收核对表按空间和批次组织，每一行对应一个附件或一组引用，记录核对人、核对时间和结论。差异处理记录要写清未通过项的原因、处理方式和最终状态，作为回退判断的依据。
如果目标端是 ONES Wiki，其 Confluence 迁移场景覆盖空间、页面、附件和权限结构，迁移数据包括用户、用户组、空间权限与页面权限，页面正文、附件、图片、常用宏及批注在支持范围内，迁移方式支持批量迁移与数据包导入。附件版本保留范围和具体宏的对应情况需要在迁移前逐项确认，验收时按确认结果核对。迁移完成后，文档与工作项的关联、页面权限和评审流程可以在 ONES 中继续维护，附件作为页面内容的一部分随权限继承。
分批切换与回退：出问题时怎么停、怎么退
正式切换按空间或部门分批推进，每批安排独立的时间窗，前一批验收通过后再启动下一批。批次顺序建议先低风险、低引用密度的空间，再处理核心知识库。每批切换前确认该批的映射表、试迁差异清单和验收核对表均已闭环。
暂停条件要提前量化，例如单批附件失败率超过约定阈值、缺失文件数超过约定数量、关键页面引用无法打开，出现任一情况即暂停该批并排查，不带着问题进入下一批。阈值由项目组在切换前确定，写入切换计划。
回退路径依赖原 Confluence 空间的只读保留。切换后原空间保留只读一段时间，期间不删除、不改动，作为回退点；如果新环境出现无法快速修复的问题，可以恢复原空间访问并暂停后续批次。只读保留期限根据业务确认周期确定，到期前完成最终验收再决定是否下线。
切换后还要处理旧链接跳转和用户通知：旧页面地址如果无法自动跳转，要在原空间放置迁移说明和新的访问入口；通知内容说明新位置、权限变化和问题反馈渠道。ONES 的 Confluence 替换方案建议把迁移工具、原厂服务和分阶段切换结合起来，在正式迁移前确认数据范围、功能匹配和系统适配，这一建议同样适用于附件迁移的切换安排，具体实施方式需结合项目评估确认。
常见问题
盘点时发现附件被多个页面引用，迁移后引用关系怎么保证不断？
盘点阶段就要把引用关系作为独立字段记录，写明每个附件被哪些页面正文或宏引用。映射阶段为每个引用单独列一行，标注引用类型、原引用位置、目标引用方式和替换状态，迁移后逐项打开验证。跨页面引用的附件是重点检查对象，建议在验收核对表中单独分组，由引用页面的负责人确认链接可打开且指向正确文件。
附件有多个历史版本，迁移时只迁最新版可以吗？
是否保留历史版本取决于业务要求，需要在盘点阶段就确定，并写入清单的版本数字段。如果业务要求保留历史版本，映射时要逐版本对应，验收时单独核对版本号是否与映射表一致。只迁最新版会丢失历史记录，适合那些历史版本已无追溯价值的附件，但这一判断应由页面负责人确认，不宜由迁移执行方单方面决定。
试迁时附件数量对得上，但页面里的图片打不开，问题出在哪？
这类情况通常出在正文引用替换环节，文件本体已迁过去，但页面正文中的图片地址仍指向原位置。排查顺序是：先确认该图片在映射表中是否单独列出了引用行，再检查替换状态是否标记为已处理，最后打开目标页面查看引用路径是否指向新附件。如果引用由宏生成，需要按目标端支持的展示方式重建，无法自动对应的进入人工处理队列。
分批切换时，什么情况下应该暂停而不是继续下一批？
暂停条件要在切换前量化并写入计划，常见判断项包括单批附件失败率超过约定阈值、缺失文件数超过约定数量、关键页面引用无法打开。出现任一情况即暂停该批排查，不带着问题进入下一批。阈值由项目组结合业务容忍度确定，核心知识库批次可以设置更严格的阈值。
原 Confluence 空间保留只读多久比较合适？
只读保留期限取决于业务确认周期，需要覆盖新环境的完整验收和用户反馈处理时间。保留期间原空间不删除、不改动，作为回退点；到期前完成最终验收，再决定是否下线。如果新环境出现无法快速修复的问题，可以恢复原空间访问并暂停后续批次，因此保留期限不宜短于一个完整的业务确认周期。
目标端是 ONES Wiki 时，附件迁移有哪些需要提前确认的点？
ONES 的 Confluence 迁移场景覆盖空间、页面、附件和权限结构，迁移数据包括用户、用户组、空间权限与页面权限，页面正文、附件、图片、常用宏及批注在支持范围内，迁移方式支持批量迁移与数据包导入。附件版本保留范围和具体宏的对应情况需要在迁移前逐项确认，验收时按确认结果核对。迁移完成后，文档与工作项的关联、页面权限和评审流程可以在 ONES 中继续维护，附件作为页面内容的一部分随权限继承。
