Confluence数据迁移
1.适用版本
此文档适用于「企业版-私有部署」的 ONES 系统
2.Confluence 迁移助手简介
ONES Confluence 迁移助手能够将 Server 版、Data Center 版以及 Cloud 版 Confluence 中的空间、用户、权限等数据迁移至 ONES Wiki 与系统中。迁移数据与迁移效果具体见下方：
Confluence 数据类型 | 是否支持迁移 | 迁移效果 | 备注 |
空间 | 是 | 迁移空间名称 | |
页面 | 是 | 保留文本、表格、图片、代码段、超链接、待办事项、引用等内容，可保留大部分文本样式 | |
附件 | 是 | 保留页面中的上传的附件、通过部分插件生成的附件文件 | 如有超出 300M 的附件，需运维人员修改 ONES 系统的附件上限配置 |
宏 | 是 | 已支持的宏可迁移数据或保留样式（详见2.1）；未支持的宏以占位符显示 | |
批注 | 是 | 保留批注对应位置和批注内容 | |
页面树 | 是 | 保留页面树结构 | |
主页 | 是 | 保留 Confluence 空间主页，如果主页无内容，则使用 ONES Wiki 的默认主页 | |
博客 | 是 | 保留博客页面内容与权限配置 | 迁移后放置在「博客」节点下 |
*孤儿页面 | 是 | 保留孤儿页面的页面内容与数据 | 迁移后放置在 「Confluence 特殊页面」 节点下 |
用户与用户组 | 是 | 迁移空间中的用户与用户组，保留用户的昵称、邮箱，保留用户组的名称与其中的用户 |
|
页面相关人 | 是 | 保留页面创建者、编辑者、关注者 | 如果相关角色用户数据不存在，将使用迁移执行者账号进行替换 |
权限 | 是 |
| Confluence 空间主页的加密权限不保留 |
*孤儿页面：指在 Confluence 空间中父页面不存在的页面
2.1支持迁移的宏
| Confluence 宏/插件名称 | 迁移效果 | 备注 |
|---|---|---|
| 附件宏 | 保留数据，样式替换为 ONES Wiki 附件样式 | 跨页面引用附件链接支持展示 |
| 目录宏 | 静态形式展示页面目录，最多支持 7 个层级 | |
| 代码宏 | 保留数据，样式替换为 ONES Wiki 代码段样式 | |
| Jira-issue 宏 | 支持 URL 状态展示的单个 issue | |
| 状态宏 | 保留数据和样式 | |
| 页面树插件 | 超链接形式展示，仅支持已迁移页面 | 暂不支持搜索、展开或折叠 |
| 展开宏 | 保留文本 | 暂不支持展开或折叠 |
| drawio 插件 | 保留图片与原始 drawio 文件（附件形式展示） | 支持直接编辑 |
| markdown 宏 | 保留 Markdown 原始文本 | 支持编辑 |
| 分栏宏 | 保留分栏结构 | |
| @成员宏 | 保留数据和样式 | |
| 信息面板宏 | 保留文本 | |
| 页面目录宏 | 保留样式和数据，迁移为 ONES Wiki 标题目录宏 |
2.1.1 支持灵活的分批次迁移模式
ONES Confluence 迁移助手支持分批次规划迁移任务，可根据活跃度、价值度、业务关联度等方面灵活规划迁移，避免同时迁移大批量数据，造成迁移时间等待
3. 迁移前准备
- 确认迁移方式。如果您不需要迁移用户、权限等数据，仅保留空间中的页面、附件与页面树结构，可选择手工导入 Confluence 数据包（xml zip）的方式迁移，详见：ONES Wiki 文档导入与导出。如果您需要在迁移时进行批量操作，并同时保留用户、权限数据，推荐使用迁移助手进行迁移
- 检查 Confluence 版本与部署方式。迁移助手支持 6.x、7.x 、8.x Server/Data Server 版本，以及 Cloud 版本数据迁移至 ONES 私有部署服务，低于或高于上述版本的环境，请联系我们的技术支持或服务人员进行评估
- 确认 Confluence 数据用量。空间数量在 400 以下、总数据量在 500G 以下的 Confluence 环境推荐使用自助迁移工具进行迁移，用量较高的环境建议联系我们的人工支持服务，以便帮助您更好地评估与监控迁移过程
- 确认 Confluence 与 Jira 用户同步状态。如果 Confluence 的用户与 Jira 用户同步，请在迁移前确认用户同步已完成
- 准备 Confluence 超级管理员账号。迁移助手需要填写具备相应权限的账号及密码，以便连接 Confluence 服务
- 迁移前建议将 Confluence 切换为维护模式，避免在迁移过程中产生新数据
- 如果规划统一迁移，建议登录具备权限的迁移专用账号
- 【重要】如果通过 nginx 代理访问 confluence，请确保迁移执行过程中，在相关的 nginx 配置添加或者修改下面的配置
client_max_body_size 0; # 不限制单次请求体大小
proxy_connect_timeout 1d; # 调整反向代理的超时限制
proxy_send_timeout 1d; # 调整反向代理的超时限制
proxy_read_timeout 1d; # 调整反向代理的超时限制
4. 迁移评估
Confluence 迁移工具提供了数据用量评估工具，通过评估 Confluence 数据量给出迁移方式建议与环境配置参考，以便降低迁移异常风险。
进入配置中心，点击右上角「自助迁移」按钮，在弹窗中点击「开始评估」即可运行评估工具。如果此前已经评估过，在这里会展示前一次评估结果。
迁移评估工具仅支持评估 Confluence Server/Data Center 版本数据
如果您已经通过其他方式获知了待迁移的 Confluence 环境数据量等信息，也可以点击「新建迁移任务」直接开始迁移。
4.1 填写数据库信息
进入评估模式后，首先需要填写 Confluence 数据库相关信息。这些信息可以咨询 Confluence 管理人员或团队 IT 管理人员
- 数据库类型：根据 Confluence 所选的数据库类型进行选取，目前支持评估 Mysql、PostgreSQL、Microsoft SQL Server 三种类型的数据库，其他类型的数据库如需评估，请联系我们的迁移服务团队；
- 主机名：数据库主机名
- 端口：数据库端口
- 数据库名称：数据库的名称
- 数据库用户名及密码：填写具备数据表查询权限的用户名与密码，该信息仅用于提供给 Confluence API 执行数据用量的查询操作，我们不会存储这些信息。
4.2 评估数据用量
根据您填写的数据库信息，我们将分析用量情况，并提供合适的迁移方式建议，您可以参考评估报告中的空间更新时间、页面数量来规划迁移空间与迁移顺序。
4.2.1 查看评估结果
- 数据迁移评估
包括迁移方式建议，迁移所需预估时间和环境配置建议
- 迁移方式：建议分为两种：自助迁移、人工支持服务迁移；
- 迁移所需预估时间：指在服务资源充足的情况下，一次性迁移全部数据的预估用时。以小时为单位；
- 环境配置建议：为了降低迁移异常风险，Confluence 服务器的磁盘剩余空间与内存需要与待迁移数据量匹配，这里会提供一些必要的扩容建议。
- Confluence 使用情况
包括空间数量、用户数量、数据量、附件存储量以及最大空间数据量，这个表格有助于您了解您的 Confluence 数据用量情况，以便提前进行必要的迁移准备。
4.2.2 下载评估报告
点击「下载评估报告」，您可以获得一个详细的数据表格，包括当前 Confluence 环境的数据用量概况，以及各个空间的用量清单。您可以参考该报告中的信息，例如：空间最近更新时间、空间页面数量等，进行迁移批次的划分。
5. 开始迁移
登录 ONES 团队管理员账号，在配置中心 - 导入数据 中，即可找到「从 Confluence 迁移数据」菜单
目前仅私有部署客户，云服务客户如需数据迁移，请联系我们的技术支持或服务人员进行评估
5.1迁移任务列表
5.1.1 查看迁移任务列表
进入 Confluence 数据迁移功能页面后，在迁移任务列表中，可浏览或查询全部迁移任务，包括已规划但未执行的任务，以及已迁移的任务。已完成或正在进行的任务支持查看迁移报告，便于在分批次迁移过程中跟踪迁移进度。
注意： 同一个 ONES 环境只能有一个正在迁移的任务
5.1.2什么是迁移任务
Confluence 迁移支持分批次迁移，例如Confluence 中有 20 个空间，如果空间数据量较大，一次性迁移耗时较久，并且对迁移服务器造成性能压力。通过迁移任务拆分，可每次迁移 2 个空间，以降低迁移的耗时与等待。每一次迁移可被称为一个迁移任务。
利用迁移任务，管理员可根据迁移需求统一规划，安排时间进行分批次执行。在迁移测试阶段，亦可选取部分空间进行迁移效果验证。
- 任务名称：根据创建任务时间自动命名
- 任务状态：当前迁移任务的状态
- 已就绪：已创建成功且经过数据检查但未执行的迁移；
- 迁移中：正在执行迁移中的迁移
- 已终止：迁移过程中因程序错误出现停止或人为停止；终止后可「查看迁移报告」
- 已完成：迁移过程执行完毕，可「查看迁移报告」
- 迁移进度以空间数量表示，显示为：已迁移空间数量 / 本次迁移空间总数量
- 任务操作
- 点击详情，可弹窗查看该任务中迁移数据的具体情况，弹窗中展示空间名称、空间关键字、数据包大小、数据包磁盘位置、页面迁移进度
- 已就绪状态的任务，可选择「开始迁移」
- 开始迁移的任务，可终止迁移，但仅能终止任务中未开始迁移的空间，已开始迁移的空间只能等待完成，不能取消或中断
5.2 迁移详情
点击迁移任务名称，弹窗展示迁移详情。包括开始迁移时间、Confluence 连接环境，以及任务中所迁移的空间，按照迁移状态分类显示；
- 空间迁移状态中，「迁移完成」表示迁移过程结束的空间，「迁移中」表示正在执行迁移的空间，「迁移异常」表示迁移过程中出现 Confluence 环境无法连接、无法获取数据包等错误导致迁移未能正常结束的空间，「准备迁移」表示正在从 Confluence 导出、正在下载 Confluence 数据包以及排队等待处理的未迁移空间
- 列表中展示展示 Confluence 空间名称、关键字、页面迁移进度以及数据包大小
- 如果迁移的 Confluence 空间无任何页面，会在迁移到 ONES Wiki 后自动创建空间主页，因此页面迁移进度会展示为 1/1
5.3 特殊场景
- 迁移时可能会超出当前服务的 license 数量，不影响迁移
- 迁移后的用户不进行产品模块授权，导入后由管理员在账号设置中进行授权；
- 当已经有一个迁移任务正在执行时，其他已就绪的任务不可开始迁移
- 点击「开始迁移」，根据任务配置中的信息进行环境连接与数据获取，会等待一定的时间才会开始迁移；
- 点击「终止迁移」，仅能终止任务中未开始迁移的空间，已开始迁移的空间会继续执行
5.4 开始迁移
需要开始迁移时，点击右上角「新建迁移任务」，会进入创建向导
5.5 第一步：连接 Confluence
Confluence 迁移助手需要连接需要进行数据迁移的 Server 版 Confluence 环境，在该步骤需填写 Confluence 访问域名、管理员账号、ONES 访问域名、迁移操作者账号，并指定迁移任务名称。
📢 注意
- 建议选择 Confluence 低频使用时段进行数据迁移；
- 如果当前 ONES 环境还需迁移 JIRA 数据，建议与 Confluence 选择不同时段进行；
5.5.1 迁移 Confluence Server/Data Center
5.5.1.1 填写连接环境所需信息
- 迁移来源服务类型
根据 Confluence 服务判断迁移来源，选择 Confluence Server/Data Center。
- 确认 ONES 访问域名
- 指访问 ONES 环境时在浏览器地址栏中所输入的地址域名，此处为默认填写。
- 填写 Confluence 信息
- Confluence 访问域名：指访问 Confluence 环境时在浏览器地址栏中所输入的地址域名；
- Confluence 超级管理员账号：具备超级管理员权限的账号，该账号用于访问 Confluence 环境并调用 Confluence 服务获取数据；
- Confluence 管理员密码：超级管理员账号对应的密码；
- Confluence 相关配置
- 确认 Confluence 服务已开启 API 访问：可点击问号图标查看操作方法，设置完毕后勾选「我已配置允许远程调用 Confluence API」
- 确认已修改 API 访问时间为 0：可点击问号图标参考设置，设置完毕后勾选「我已配置 Confluence 服务连接超时时间为 0」
连接环境所需信息需全部填写并勾选后，才可点击「下一步」。点击「下一步」，根据所提供的域名进行环境连接验证
5.5.1.2 特殊场景
- 如果提示 Confluence 环境无法访问：请检查域名填写是否正确，并确认服务器连接是否正常
- 如果提示连接失败，请检查Confluence 超级管理员是否账号或密码不正确，或丢失超管权限；并检查ONES 服务与 Confluence 服务之间网络连接是否正常
- 如果提示 DNS 解析失败：请确保 ONES 服务器的 DNS 能够正常解析所填写的 Confluence 域名，或在 Confluence 域名文本框中填写 Confluence 服务器的 IP 地址（请检查是否需包含端口或路径）
5.5.2 迁移 Confluence Cloud
5.5.2.1 填写连接环境所需信息
- 迁移来源服务类型
根据 Confluence 服务判断迁移来源，选择 Confluence Cloud。
- 确认 ONES 访问域名
- 指访问 ONES 环境时在浏览器地址栏中所输入的地址域名，此处为默认填写。
- 填写 Confluence 信息
- Confluence 站点链接：指访问 Confluence Cloud 服务时在浏览器地址栏中所输入的地址域名；
- API 令牌：用于调用 Confluence 内部接口，可访问 Confluence API 令牌管理 页面进行创建，获取 Token 后粘贴到输入框中。操作方法详见：如何创建 Confluence API Token
- Confluence 管理员邮箱：具备超级管理员权限的账号，该账号用于访问 Confluence 环境并调用 Confluence 服务获取数据；
- Confluence 管理员账号 Cookie、Confluence 控制台 Cookie：用于授权调用接口获取 Confluence Cloud 的空间列表、空间数据包，以及用于授权访问 Confluence Cloud 的用户数据，获取方法详见下方：5.5.1.2.1 部分
5.5.2.1.1 如何获取 Confluence 管理员账号 Cookie
访问 Confluence 站点首页：https://site.atlassian.net/wiki/home（请将 site 替换为您的 Confluence 站点），登录管理员账号（推荐使用 Chrome 浏览器）。登录成功后，右键点击页面，选择「检查」。
（1）切换到 Network 页签；
（2）在筛选框中输入「home」；
（3）点击筛选结果定位到的请求；
（4）向下滚动页面，找到 Cookie 字段，复制右侧字符串（注意全部选取，不要有遗漏）
（5）粘贴到迁移工具「Confluence 管理员 Cookie」中
5.5.2.1.2 如何获取 Confluence 控制台 Cookie
访问 Confluence Cloud 站点，登录管理员账号，点击右上角「设置」，选择「用户管理」（推荐使用 Chrome 浏览器）。打开页面后，右键点击页面，选择「检查」。
（1）切换到 Network 页签；
（2）在筛选框中输入「me」；
（3）查找筛选结果，找到
下方截图示意的
请求；
（4）向下滚动页面，找到 Cookie 字段，复制右侧字符串（注意全部选取，不要有遗漏）
（5）粘贴到迁移工具「Confluence 控制台 Cookie」中
5.5.2.2 特殊场景
- 如果 Confluence 站点无法访问，点击「下一步」会提示无法访问，请检查 Confluence 站点链接是否有误；
- 请妥善管理 API 令牌，如果点击「下一步」提示令牌失效，请检查令牌是否正确且有效
5.6 第二步：选择空间
Confluence 环境连接成功后，进入「选择空间」步骤。
5.6.1 迁移 Confluence Server/Data Center
5.6.1.1 选择空间
在空间列表中勾选本次任务计划迁移的空间，建议先选择较小的空间进行环境测试，测试通过后再进行正式迁移。ONES 系统的 Confluence 迁移助手支持分批次迁移，您可根据 Confluence 中的用量特征进行迁移规划：
- 迁移开始前，分析 Confluence 中的空间使用情况，例如先规划活跃度较高的空间，以减少对正式使用的影响
- 单个空间数据存储量较大的空间，配合存储量较小的空间进行规划，避免一次性迁移过大的数据量
空间列表按迁移状态分类展示，可快速选择「未迁移」的空间。通过搜索，可快速定位到某个待迁移的空间
5.6.1.2 特殊场景
- 至少选择一个需要迁移的空间，如果不选择空间，无法进行下一步；
- 空间数量越多，该步骤的耗时也会越长。如果空间数量超出 400 个，且数据总用量较高，建议技术支持或服务人员进行评估
- Confluence 服务的内存与磁盘剩余空间不足时，迁移可能会出现失败，建议迁移前检查 Confluence 服务器配置，磁盘剩余空间建议在待迁移数据量的 2 倍以上；
5.6.2 迁移 Confluence Cloud
5.6.2 选择空间获取方式
- 自动获取空间：通过 Confluence 接口获取 Confluence 空间列表，并通过接口导出空间数据包进行解析和导入。默认选择该数据获取方式，
- 读取 ONES 服务器数据：读取 ONES 服务器某个特定路径下的空间数据包，在下方列表列出，系统会记录数据包的迁移状态。
5.6.2.1 服务器数据包添加方法
- 导出 Confluence 空间：参考： 导出需要迁移的 Confluence 空间 xml 数据包（zip）
- 将多个 zip 文件，放置在 ONES 服务器
/data/ones/files/cf-zip-base路径下。如果导出多个空间，需放置多个 zip 包。
5.6.3 选择迁移空间
操作过程与「迁移 Confluence Server/Data Center」相同。
5.7 第三步：同步用户
Confluence 迁移助手在该步骤将获取 Confluence 环境中的全部用户，包括用户组数据。以便迁移权限相关数据。在同步用户步骤，可选择将 Confluence 的用户数据以新建方式迁移至 ONES，也可选择将数据映射到 ONES 系统中已有用户。
5.7.1 邮箱异常用户
针对无法直接迁移至 ONES 的用户数据，需进行邮箱修改或合并，其中包括：
- 邮箱格式错误
指邮箱为空、邮箱格式不合法的用户数据。需修改邮箱为唯一且格式正确的邮箱；
- 邮箱重复
指 Confluence 中邮箱完全相同的邮箱，可选择合并迁移或不合并迁移，如果选择「合并」，重复邮箱用户将合并为一个用户，用户名按照 ASCII 码顺序选择第一个；如果选择「不合并」，需将重复邮箱中的每一条数据都设置新邮箱或映射到 ONES 已有用户
注意：邮箱错误且异常的用户，如果选择合并，需填写格式符合要求且在 ONES 系统中唯一的邮箱
异常邮箱数据全部设置了映射选项后，再次创建迁移任务时，如果未新增邮箱异常用户，列表显示为空
5.7.2 邮箱正常用户
对于邮箱格式正常的用户，如果在 ONES 系统中没有相同邮箱，默认将创建该用户；如果在 ONES 系统中已有相同邮箱，默认将映射该用户。
用户数据操作选择说明
- 创建：以 Confluence 环境中的用户数据（用户名、显示名、邮箱）在 ONES 系统中创建新用户
- 更新：修改 Confluence 用户邮箱，并以新的邮箱在 ONES 系统中创建用户
- 映射：将 Confluence 用户数据映射到一个 ONES 已有用户；
5.7.3 搜索用户
在搜索框中输入关键字，可搜索邮箱异常与正常用户。
5.7.4 特殊场景说明
- 为了保证 Confluence 用户数据获取的及时性与一致性，在同步用户步骤操作过程中，点击「上一步」退回后，再次进入该步骤时，无法保留未提交保存的映射规则，需对邮箱异常用户再次进行更新或映射设置；
- 选择「更新」操作的用户，如果填写邮箱格式错误，鼠标离开后会输入框下方会提示「邮箱格式不符合要求」；如果所填写邮箱在 ONES 系统中已存在，会提示「ONES 系统中有重复邮箱」；如果所填写邮箱在当前处理过程中已存在，会提示「已有重复邮箱」
- 迁移过程中，如果出现可正常迁移用户数据、但某条数据由于规则冲突无法写入数据库时，会使用当前登录账号身份承载该用户的业务数据；
5.8 保存任务
完成用户同步步骤后，点击「保存任务」可保存本次迁移任务所填写的环境连接配置、计划迁移的空间，并保存用户数据映射规则。
用户数据映射规则保存后将无法修改，建议在迁移前梳理 Confluence 用户数据并清理重复、格式错误的邮箱，对已离职用户、弃用账号等做好迁移规划
5.9 开始迁移
完成用户同步步骤后，也可选择立即开始迁移数据。点击「开始迁移」后，如果当前没有正在迁移的任务，将回到任务列表界面并开始执行迁移；如果有正在迁移的任务，将提示同时只能有一个任务在运行，可选择保存任务。
5.10 下载迁移报告
已迁移完成的任务，可在任务列表界面下载迁移报告。迁移报告为 Excel 文件（xls)，下载后可使用表格查看器软件打开。
迁移报告中可查看任务概况、迁移出现异常的空间、页面、附件、用户数据
- 任务概况：包括任务名称、迁移任务状态、开始迁移与结束迁移时间、迁移空间总数、迁移完成空间数量、迁移异常空间数量、迁移用户总数、迁移完成用户数量与迁移异常用户数量
- 迁移异常空间：空间名称、空间关键字、空间 URL、迁移异常原因
- 迁移异常页面：页面标题、页面 URL、所属 Confluence 空间、迁移异常原因
- 迁移异常附件：附件标题、附件所属空间名称与关键字、空间 URL、迁移异常原因
- 迁移异常用户：Confluence 用户名、Confluence 用户邮箱、ONES 用户名、ONES 用户邮箱
- 引用链接修复异常：包括引用位置页面的标题、所在空间、页面链接（ONES）、引用来源页面标题、引用来源空间、页面链接（Confluence）、修复失败原因
常见问题
重复迁移的空间，是否会覆盖已经迁移的数据？
迁移是以空间为单位进行的，对于重复迁移的空间，会增量迁移一个新的空间，为避免重名，空间名称会增加编号后缀。
迁移空间失败，并且迁移报告中提示：空间数据包导出失败时，该如何排查和解决？
出现该异常，可能由于 Confluence 服务使用的数据库连接超时，对应排查手 段 （适用于 MySQL 数据库） 如 下：
- 确认原因：如果在日志中看到类似
Unable to rollback against JDBC Connection、communications link failure的错误，即为数据库连接超时 - 解决方案：修改配置
修改 Confluence 服务所使用的 mysql 配置文件，一般为 /etc/my.cnf ，在 [mysqld] 配置节点下面添加或者修改 wait_timeout 和 interactive_timeout 为 mysql 的默认的值
wait_timeout = 28800
interactive_timeout = 28800
迁移空间失败，并且迁移报告中提示：空间数据包下载失败时，该如何排查和解决？
出现该异常，可能由于 nginx 配置导致的连接超时，请参照以下说明调整 nginx 配置
client_max_body_size 0; # 不限制单次请求体大小
proxy_connect_timeout 1d; # 调整反向代理的超时限制
proxy_send_timeout 1d; # 调整反向代理的超时限制
proxy_read_timeout 1d; # 调整反向代理的超时限制
如果空间中包含引用自其他空间的页面链接，迁移完成后能否对应到 ONES Wiki 的目标页面？
可以的。迁移时会在当前任务和已经迁移完成的空间中，查找引用来源页面，并进行链接的替换。如果没有找到引用来源页面，会在迁移报告中列出引用位置页面和引用来源页面的原始链接，以便对应进行排查
，见下图
：
