Confluence 数据迁移
1.适用版本
此文档适用于「企业版」的 ONES 系统 4 月份上线的版本
| 适用版本 | 企业版/私有部署版本 |
2.Confluence 迁移助手简介
ONES Confluence 迁移助手能够将 Server 版 Confluence 中的空间、用户、权限等数据迁移至 ONES Wiki 与系统中。迁移数据与迁移效果具体见下方：
| Confluence数据类型 | 是否支持迁移 | 迁移效果 | 备注 |
|---|---|---|---|
| 空间 | 是 | 迁移空间名称 | |
| 页面 | 是 | 保留文本、表格、图片、代码段、超链接、待办事项、引用等内容，可保留大部分文本样式 | |
| 附件 | 是 | 保留页面中的上传的附件、通过部分插件生成的附件文件 | 如有超出 300M 的附件，需运维人员修改 ONES 系统的附件上限配置 |
| 宏 | 是 | 已支持的宏可迁移数据与保留样式；未支持的宏以占位符显示 | 可参考下文支持迁移的宏列表 |
| 页面树 | 是 | 保留页面树结构 | |
| 空间主页 | 是 | 保留 Confluence 空间主页，如果主页无内容，则使用 ONES Wiki 的默认主页 | |
| 博客 | 是 | 保留博客页面内容与权限配置 | 迁移后放置在「博客」节点下 |
| *孤儿页面 | 是 | 保留孤儿页面的页面内容与数据 | 迁移后放置在 「Confluence 特殊页面」 节点下 |
| 用户与用户组 | 是 | 迁移空间中的用户与用户组，保留用户的昵称、邮箱，保留用户组的名称与其中的用户 | |
| 页面相关人 | 是 | 保留页面创建者、编辑者、关注者 | 如果相关角色用户数据不存在，将使用迁移执行者账号进行替换 |
| 权限 | 是 | Confluence 空间主页的加密权限不保留 |
*孤儿页面：指在 Confluence 空间中父页面不存在的页面
2.1 支持迁移的宏
| Conflucnce宏/插件名称 | 迁移效果 | 备注 |
|---|---|---|
| 附件宏 | 保留数据，样式替换为 ONES Wiki 附件样式 | 跨页面引用附件暂无法展示 |
| 目录宏 | 静态形式展示页面目录，最多支持 7 个层级 | |
| 代码宏 | 保留数据，样式替换为 ONES Wiki 代码段样式 | |
| Jira-issue 宏 | 支持 URL 状态展示的单个 issue | |
| 状态宏 | 保留数据 | |
| 页面树插件 | 超链接形式展示，仅支持已迁移页面 | 暂不支持搜索、展开或折叠 |
| 展开宏 | 保留文本 | 暂不支持展开或折叠 |
| drawio 插件 | 保留图片与原始 drawio 文件（附件形式展示） | 暂不支持直接编辑 |
| markdown 宏 | 保留 Markdown 原始文本 | 暂不支持编辑 |
2.1.1 灵活的分批次迁移模式
ONES Confluence 迁移助手支持分批次规划迁移任务，可根据活跃度、价值度、业务关联度等方面灵活规划迁移，避免同时迁移大批量数据，造成迁移时间等待
3.迁移前准备
- 确认迁移方式。如果您不需要迁移用户、权限等数据，仅保留空间中的页面、附件与页面树结构，可选择手工导入 Confluence 数据包（xml zip）的方式迁移，详见：ONES Wiki 文档导入与导出。如果您需要在迁移时进行批量操作，并同时保留用户、权限数据，推荐使用迁移助手进行迁移
- 检查 Confluence 版本与部署方式。迁移助手支持 6.x、7.x Server 或 Data Server 版本数据迁移至 ONES Server，低于或高于上述版本的环境，请联系我们进行迁移评估
- 确认 Confluence 数据用量。空间数量在 400 以下、总数据量在 500G 以下的 Confluence 环境推荐使用自主迁移工具进行迁移，用量较高的环境建议联系我们的人工支持服务，以便帮助您更好地评估与监控迁移过程
- 确认 Confluence 与 Jira 用户同步状态。如果 Confluence 的用户与 Jira 用户同步，请在迁移前确认用户同步已完成
- 准备 Confluence 超级管理员账号。迁移助手需要填写具备相应权限的账号及密码，以便连接 Confluence 服务
- 迁移前建议将 Confluence 切换为维护模式，避免在迁移过程中产生新数据
- 如果计划由管理员统一进行数据迁移，建议登录具备权限的迁移专用账号
4.开始迁移
登录 ONES 团队管理员账号，在配置中心 - 迁移数据 中，点击「迁移 Confluence 数据」菜单
目前仅私有部署客户，云服务客户如需数据迁移，请联系我们的人工支持服务进行评估
4.1 迁移任务列表
4.1.1 查看迁移任务列表
进入 Confluence 数据迁移功能页面后，在迁移任务列表中，可浏览或查询全部迁移任务，包括已规划但未执行的任务，以及已迁移的任务。已完成或正在进行的任务支持查看迁移报告，便于在分批次迁移过程中跟踪迁移进度。
注意： 同一个 ONES 环境只能有一个正在迁移的任务
4.1.2 什么是迁移任务
Confluence 迁移支持分批次迁移，例如Confluence 中有 20 个空间，如果空间数据量较大，一次性迁移耗时较久，并且对迁移服务器造成性能压力。通过迁移任务拆分，可每次迁移 2 个空间，以降低迁移的耗时与等待。每一次迁移可被称为一个迁移任务。 利用迁移任务，管理员可根据迁移需求统一规划，安排时间进行分批次执行。在迁移测试阶段，亦可选取部分空间进行迁移效果验证。
- 任务名称：根据创建任务时间自动命名
- 任务状态：当前迁移任务的状态
- 已就绪：已创建成功且经过数据检查但未执行的迁移；
- 迁移中：正在执行迁移中的迁移
- 已终止：迁移过程中因程序错误出现停止或人为停止；终止后可「查看迁移报告」
- 已完成：迁移过程执行完毕，可「查看迁移报告」
- 迁移进度以空间数量表示，显示为：已迁移空间数量 / 本次迁移空间总数量
- 任务操作
- 点击详情，可弹窗查看该任务中迁移数据的具体情况，弹窗中展示空间名称、空间关键字、数据包大小、数据包磁盘位置、页面迁移进度
- 已就绪状态的任务，可选择「开始迁移」
- 开始迁移的任务，可终止迁移，但仅能终止任务中未开始迁移的空间，已开始迁移的空间只能等待完成，不能取消或中断
4.2 迁移详情
点击迁移任务名称，弹窗展示迁移详情。包括开始迁移时间、Confluence 连接环境，以及任务中所迁移的空间，按照迁移状态分类显示；
- 空间迁移状态中，「迁移完成」表示迁移过程结束的空间，「迁移中」表示正在执行迁移的空间，「迁移异常」表示迁移过程中出现 Confluence 环境无法连接、无法获取数据包等错误导致迁移未能正常结束的空间，「准备迁移」表示正在从 Confluence 导出、正在下载 Confluence 数据包以及排队等待处理的未迁移空间
- 列表中展示展示 Confluence 空间名称、关键字、页面迁移进度以及数据包大小
- 如果迁移的 Confluence 空间无任何页面，会在迁移到 ONES Wiki 后自动创建空间主页，因此页面迁移进度会展示为 1/1
4.3 特殊场景
- 迁移时可能会超出当前服务的 license 数量，不影响迁移
- 迁移后的用户不进行产品模块授权，导入后由管理员在账号设置中进行授权；
- 当已经有一个迁移任务正在执行时，其他已就绪的任务不可开始迁移
- 点击「开始迁移」，根据任务配置中的信息进行环境连接与数据获取，会等待一定的时间才会开始迁移；
- 点击「终止迁移」，仅能终止任务中未开始迁移的空间，已开始迁移的空间会继续执行
4.4 创建迁移任务
需要开始迁移时，点击右上角「新建迁移任务」，会进入创建向导
4.5 第一步：连接 Confluence
Confluence 迁移助手需要连接需要进行数据迁移的 Server 版 Confluence 环境，在该步骤需填写 Confluence 访问域名、管理员账号、ONES 访问域名、迁移操作者账号，并指定迁移任务名称。
注意：
- 建议选择 Confluence 低频使用时段进行数据迁移；
- 如果当前 ONES 环境还需迁移 JIRA 数据，建议与 Confluence 选择不同时段进行；
- 如果需要迁移的 Confluence 空间数量较多（超过 400 个）或数据用量较大（超出 500G），请联系 ONES 技术支持人员提供迁移支持服务
4.5.1 填写连接环境所需信息
- Confluence 域名：指访问 Confluence 环境时在浏览器地址栏中所输入的地址域名；
- Confluence 超级管理员账号及密码：具备超级管理员权限的账号，该账号用于访问 Confluence 环境并调用 Confluence 服务获取数据；
- ONES 访问域名：指访问 ONES 环境时在浏览器地址栏中所输入的地址域名；
4.5.2 勾选连接环境所需配置与条款
- 确认已配置 Confluence 允许远程调用 API：可根据设置说明操作，设置完毕后进行勾选
- 确认已配置 服务连接超时时间为 0：可根据设置说明操作，设置完毕后进行勾选 连接环境所需信息需全部填写并勾选后，才可点击「下一步」。点击「下一步」，根据所提供的域名进行环境连接验证
4.5.3 特殊场景
- 如果提示 Confluence 环境无法访问：请检查域名填写是否正确，并确认服务器连接是否正常
- 如果提示连接失败，请检查Confluence 超级管理员是否账号或密码不正确，或丢失超管权限；并检查ONES 服务与 Confluence 服务之间网络连接是否正常
4.6 第二步：选择空间
Confluence 环境连接成功后，进入「选择空间」步骤。
在空间列表中勾选本次任务计划迁移的空间，建议先选择较小的空间进行环境测试，测试通过后再进行正式迁移。ONES 系统的 Confluence 迁移助手支持分批次迁移，您可根据 Confluence 中的用量特征进行迁移规划：
- 迁移开始前，分析 Confluence 中的空间使用情况，例如先规划活跃度较高的空间，以减少对正式使用的影响
- 单个空间数据存储量较大的空间，配合存储量较小的空间进行规划，避免一次性迁移过大的数据量
空间列表按迁移状态分类展示，可快速选择「未迁移」的空间。通过搜索，可快速定位到某个待迁移的空间
4.6.1 特殊场景
- 至少选择一个需要迁移的空间，如果不选择空间，无法进行下一步；
- 空间数量越多，该步骤的耗时也会越长。如果空间数量超出 400 个，且数据总用量较高，建议联系人工支持迁移服务
- Confluence 服务的内存与磁盘剩余空间不足时，迁移可能会出现失败，建议迁移前检查 Confluence 服务器配置，磁盘剩余空间建议在待迁移数据量的 2 倍以上
4.7 第三步：同步用户
Confluence 迁移助手在该步骤将获取 Confluence 环境中的全部用户，包括用户组数据。以便迁移权限相关数据。在同步用户步骤，可选择将 Confluence 的用户数据以新建方式迁移至 ONES，也可选择将数据映射到 ONES 系统中已有用户。
4.7.1 邮箱异常用户
针对无法直接迁移至 ONES 的用户数据，需进行邮箱修改或合并，其中包括：
- 邮箱格式错误
指邮箱为空、邮箱格式不合法的用户数据。需修改邮箱为唯一且格式正确的邮箱；
- 邮箱重复 指 Confluence 中邮箱完全相同的邮箱，可选择合并迁移或不合并迁移，如果选择「合并」，重复邮箱用户将合并为一个用户，用户名按照 ASCII 码顺序选择第一个；如果选择「不合并」，需将重复邮箱中的每一条数据都设置新邮箱或映射到 ONES 已有用户
注意：邮箱错误且异常的用户，如果选择合并，需填写格式符合要求且在 ONES 系统中唯一的邮箱
异常邮箱数据全部设置了映射选项后，再次创建迁移任务时，如果未新增邮箱异常用户，列表显示为空
4.7.2 邮箱正常用户
对于邮箱格式正常的用户，如果在 ONES 系统中没有相同邮箱，默认将创建该用户；如果在 ONES 系统中已有相同邮箱，默认将映射该用户。 用户数据操作选择说明
- 创建：以 Confluence 环境中的用户数据（用户名、显示名、邮箱）在 ONES 系统中创建新用户
- 选择创建方式的用户，账号激活状态默认与 Confluence 账号保持一致，可修改为未激活状态
- 映射：将 Confluence 用户数据映射到一个 ONES 已有用户；
+ 选择映射后，右侧邮箱输入框将变为人员筛选框，输入并查找到对应成员后，用户名将显示为为所选用户的用户名
4.7.3 搜索用户
在搜索框中输入关键字，可搜索邮箱异常与正常用户。
4.7.4 特殊场景说明
- 为了保证 Confluence 用户数据获取的及时性与一致性，在同步用户步骤操作过程中，点击「上一步」退回后，再次进入该步骤时，无法保留未提交保存的映射规则，需对邮箱异常用户再次进行更新或映射设置；
- 选择「更新」操作的用户，如果填写邮箱格式错误，鼠标离开后会输入框下方会提示「邮箱格式不符合要求」；如果所填写邮箱在 ONES 系统中已存在，会提示「ONES 系统中有重复邮箱」；如果所填写邮箱在当前处理过程中已存在，会提示「已有重复邮箱」
- 迁移过程中，如果出现可正常迁移用户数据、但某条数据由于规则冲突无法写入数据库时，会使用当前登录账号身份承载该用户的业务数据；
4.8 保存任务
完成用户同步步骤后，点击「保存任务」可保存本次迁移任务所填写的环境连接配置、计划迁移的空间，并保存用户数据映射规则。
- 【重要】用户数据映射规则保存后将无法修改，建议在迁移前梳理 Confluence 用户数据并清理重复、格式错误的邮箱，对已离职用户、弃用账号等做好迁移规划
任务保存成功后，在任务列表中展示为「已就绪」状态，任务操作对应为「开始迁移」，点击详情可查看任务中待迁移的空间
4.9 开始迁移
完成用户同步步骤后，也可选择立即开始迁移数据。点击「开始迁移」后，如果当前没有正在迁移的任务，将回到任务列表界面并开始执行迁移；如果有正在迁移的任务，将提示同时只能有一个任务在运行，可选择保存任务。
4.10 下载迁移报告
已迁移完成的任务，可在任务列表界面下载迁移报告。迁移报告为 Excel 文件（xls)，下载后可使用表格查看器软件打开。
迁移报告中可查看任务概况、迁移出现异常的空间、页面、附件、用户数据
- 任务概况：包括任务名称、迁移任务状态、开始迁移与结束迁移时间、迁移空间总数、迁移完成空间数量、迁移异常空间数量、迁移用户总数、迁移完成用户数量与迁移异常用户数量
- 迁移异常空间：空间名称、空间关键字、空间 URL、迁移异常原因
- 迁移异常页面：页面标题、页面 URL、所属 Confluence 空间、迁移异常原因
- 迁移异常附件：附件标题、附件所属空间名称与关键字、空间 URL、迁移异常原因
- 迁移异常用户：Confluence 用户名、Confluence 用户邮箱、ONES 用户名、ONES 用户邮箱