独立部署工具使用手册

1. 迁移前检查

• 确认迁移方式。如果您不需要迁移用户、权限等数据，仅保留空间中的页面、附件与页面树结构，可选择手工导入 Confluence 数据包（xml zip）的方式迁移，详见：ONES Wiki 文档导入与导出。如果您需要在迁移时进行批量操作，并同时保留用户、权限数据，推荐使用迁移助手进行迁移；
• 检查 Confluence 版本与部署方式。迁移工具支持 6.x、7.x、8.x  Server 或 Data Server 版本数据迁移至 ONES Server，低于或高于上述版本的环境，请联系我们的技术支持或服务人员进行评估；
• 确认 Confluence 数据用量。空间数量在 400 以下、总数据量在 500G 以下的 Confluence 环境推荐使用迁移工具进行迁移，用量较高的环境建议联系我们的迁移支持服务团队，以便帮助您更好地评估与监控迁移过程；
• 确认 Confluence 与 Jira 用户同步状态。如果 Confluence 的用户与 Jira 用户同步，请在迁移前确认用户同步已完成；

2. 迁移前准备的信息

• 准备 Confluence 数据库远程连接地址、端口、数据库管理员账号，并确认 Confluence 附件存储路径；
• Confluence 迁移工具为独立部署工具，请确保迁移工具部署服务器与 ONES 服务器之间网络连通；
• 迁移前建议将 Confluence 切换为维护模式，避免在迁移过程中产生新数据；
• 如果规划统一迁移，建议登录具备权限的迁移专用账号；
• 获取迁移工具安装包

3. 开始迁移

3.1 部署迁移工具

1. 将迁移工具文件上传到 Confluence 服务器
2. 打开控制台，进入迁移工具文件所在目录，执行启动命令

cat run.sh //输出执行命令，如果需要，可复制该命令的输出进行修改。例如，修改默认端口号。
./ run.sh //启动工具
tail -f nohup.out // 实时查看程序的输出，方便调试和监控

1. 执行完上述步骤后，打开浏览器，访问 Confluence 服务器 IP 地址 + 5002 端口号（默认端口号）；如果启动工具时，修改了默认端口号，这里需要调整为修改后的端口号。

2. 选择顶部标签页中的 Confluence 迁移工具

3.2 迁移任务列表

3.2.1 什么是迁移任务

Confluence 迁移支持分批次迁移，例如Confluence 中有 20 个空间，如果空间数据量较大，一次性迁移耗时较久，并且对迁移服务器造成性能压力。通过迁移任务拆分，可每次迁移 2 个空间，以降低迁移的耗时与等待。每一次迁移可被称为一个迁移任务。

利用迁移任务，管理员可根据迁移需求统一规划，安排时间进行分批次执行。在迁移测试阶段，亦可选取部分空间进行迁移效果验证。

• 任务名称：根据创建任务时间自动命名
• 任务状态：当前迁移任务的状态
• 已就绪：已创建成功且经过数据检查但未执行的迁移；
• 迁移中：正在执行迁移中的迁移
• 已终止：迁移过程中因程序错误出现停止或人为停止；终止后可「查看迁移报告」
• 已完成：迁移过程执行完毕，可「查看迁移报告」
• 迁移进度以空间数量表示，显示为：已迁移空间数量 / 本次迁移空间总数量
• 任务操作
• 点击详情，可弹窗查看该任务中迁移数据的具体情况，弹窗中展示空间名称、空间关键字、数据包大小、数据包磁盘位置、页面迁移进度
• 已就绪状态的任务，可选择「开始迁移」
• 开始迁移的任务，可终止迁移，但仅能终止任务中未开始迁移的空间，已开始迁移的空间只能等待完成，不能取消或中断

3.2.2 查看迁移任务列表

进入 Confluence 数据迁移功能页面后，在迁移任务列表中，可浏览或查询全部迁移任务，包括已规划但未执行的任务，以及已迁移的任务。已完成或正在进行的任务支持查看迁移报告，便于在分批次迁移过程中跟踪迁移进度。

注意：  同一个 ONES 环境只能有一个正在迁移的任务 

3.2.3 查看迁移详情

点击迁移任务名称，弹窗展示迁移详情。包括开始迁移时间、Confluence 连接环境，以及任务中所迁移的空间，按照迁移状态分类显示；

• 空间迁移状态中，「迁移完成」表示迁移过程结束的空间，「迁移中」表示正在执行迁移的空间，「迁移异常」表示迁移过程中出现 Confluence 环境无法连接、无法获取数据包等错误导致迁移未能正常结束的空间，「准备迁移」表示正在从 Confluence 导出、正在下载 Confluence 数据包以及排队等待处理的未迁移空间
• 列表中展示展示 Confluence 空间名称、关键字、页面迁移进度以及数据包大小
• 如果迁移的 Confluence 空间无任何页面，会在迁移到 ONES Wiki 后自动创建空间主页，因此页面迁移进度会展示为 1/1

特殊场景

• 迁移时可能会超出当前服务的 license 数量，不影响迁移
• 迁移后的用户不进行产品模块授权，导入后由管理员在账号设置中进行授权；
• 当已经有一个迁移任务正在执行时，其他已就绪的任务不可开始迁移
• 点击「开始迁移」，根据任务配置中的信息进行环境连接与数据获取，会等待一定的时间才会开始迁移；
• 点击「终止迁移」，仅能终止任务中未开始迁移的空间，已开始迁移的空间会继续执行

3.3 创建迁移任务

需要开始迁移时，点击右上角「新建迁移任务」，会进入创建向导

3.3.1 第一步：填写服务信息

1. Confluence 数据库信息。这些信息需要与客户 Confluence 运维人员进行获取。
   1. Confluence 数据库类型：可选 PostgreSQL、MySQL、Microsoft SQL Server
   2. 数据库名称
   3. 主机名
   4. 端口
   5. 数据库用户名：此处提供的用户需要具备数据库的全量表查询权限
   6. 数据库密码：可不填写
2. Confluence 附件存储信息
   1. Confluence 附件存储目录地址：Confluence 主目录地址 + /attachments；主目录查看方式为：系统设置-一般配置-查看系统信息-confluence信息 - Confluence 主目录

1. Confluence 版本号：访问 Confluence ，页面底部区域可查看版本号

3. ONES 服务信息
   1. ONES 服务器地址：填写 ONES 服务的 IP 地址和端口号
   2. ONES 管理员用户名和密码：ONES 多团队环境，填写的账号需要为组织管理员以及当前所有 ONES 团队的超级管理员；如果是 ONES 单团队环境，需要为超级管理员。

📢 注意

1. 建议选择 Confluence 低频使用时段进行数据迁移；
2. 如果当前 ONES 环境还需迁移 JIRA 数据，建议与 Confluence 选择不同时段进行；
3. 如果需要迁移的 Confluence 空间数量较多（超过 400 个）或数据用量较大（超出 500G），请联系 技术支持或服务人员进行评估

特殊场景

• 如果提示 ONES 服务无法访问：请检查服务器地址填写是否正确，并确认服务器间网络联通是否正常；
• 如果提示数据库连接信息异常：需要与管理员核实数据库连接信息是否正确；

3.3.2 第二步：选择团队

选择本次迁移的目标团队。注意需要选择具备超级管理员或管理权限的团队。

3.3.3 第三步：选择需要迁移的空间

在空间列表中勾选本次任务计划迁移的空间，建议先选择较小的空间进行环境测试，测试通过后再进行正式迁移，您可根据 Confluence 中的用量特征进行迁移任务批次的规划：

• 迁移开始前，分析 Confluence 中的空间使用情况，例如先规划活跃度较高的空间，以减少对正式使用的影响
• 单个空间数据存储量较大的空间，配合存储量较小的空间进行规划，避免一次性迁移过大的数据量

空间列表按迁移状态分类展示，可快速选择「未迁移」的空间。通过搜索，可快速定位到某个待迁移的空

特殊场景

• 至少选择一个需要迁移的空间，如果不选择空间，无法进行下一步；
• 空间数量越多，该步骤的耗时也会越长。如果空间数量超出 400 个，且数据总用量较高，建议技术支持或服务人员进行评估

3.3.4 第四步：同步用户

Confluence 迁移助手在该步骤将获取 Confluence 环境中的全部用户，包括用户组数据。以便迁移权限相关数据。在同步用户步骤，可选择将 Confluence 的用户数据以新建方式迁移至 ONES，也可选择将数据映射到 ONES 系统中已有用户。

3.3.4.1 邮箱异常用户

针对无法直接迁移至 ONES 的用户数据，需进行邮箱修改或合并，其中包括：

1. 邮箱格式错误

指邮箱为空、邮箱格式不合法的用户数据。需修改邮箱为唯一且格式正确的邮箱；

2. 邮箱重复

指 Confluence 中邮箱完全相同的邮箱，可选择合并迁移或不合并迁移，如果选择「合并」，重复邮箱用户将合并为一个用户，用户名按照 ASCII 码顺序选择第一个；如果选择「不合并」，需将重复邮箱中的每一条数据都设置新邮箱或映射到 ONES 已有用户

⚠️ 注意：邮箱错误且异常的用户，如果选择合并，需填写格式符合要求且在 ONES 系统中唯一的邮箱

异常邮箱数据全部设置了映射选项后，再次创建迁移任务时，如果未新增邮箱异常用户，列表显示为空

3.3.4.2 邮箱正常用户

对于邮箱格式正常的用户，如果在 ONES 系统中没有相同邮箱，默认将创建该用户；如果在 ONES 系统中已有相同邮箱，默认将映射该用户。

用户数据操作选择说明

• 创建：以 Confluence 环境中的用户数据（用户名、显示名、邮箱）在 ONES 系统中创建新用户
• 更新：修改 Confluence 用户邮箱，并以新的邮箱在 ONES 系统中创建用户
• 映射：将 Confluence 用户数据映射到一个 ONES 已有用户；

3.3.4.3 搜索用户

在搜索框中输入关键字，可搜索邮箱异常与正常用户。

特殊场景说明

• 为了保证 Confluence 用户数据获取的及时性与一致性，在同步用户步骤操作过程中，点击「上一步」退回后，再次进入该步骤时，无法保留未提交保存的映射规则，需对邮箱异常用户再次进行更新或映射设置；
• 选择「更新」操作的用户，如果填写邮箱格式错误，鼠标离开后会输入框下方会提示「邮箱格式不符合要求」；如果所填写邮箱在 ONES 系统中已存在，会提示「ONES 系统中有重复邮箱」；如果所填写邮箱在当前处理过程中已存在，会提示「已有重复邮箱」
• 迁移过程中，如果出现可正常迁移用户数据、但某条数据由于规则冲突无法写入数据库时，会使用当前登录账号身份承载该用户的业务数据；

3.3.5 保存任务

完成用户同步步骤后，点击「保存任务」可保存本次迁移任务所填写的环境连接配置、计划迁移的空间，并保存用户数据映射规则。

用户数据映射规则保存后将无法修改，建议在迁移前梳理 Confluence 用户数据并清理重复、格式错误的邮箱，对已离职用户、弃用账号等做好迁移规划

3.4 开始迁移

完成用户同步步骤后，也可选择立即开始迁移数据。点击「开始迁移」后，如果当前没有正在迁移的任务，将回到任务列表界面并开始执行迁移；如果有正在迁移的任务，将提示同时只能有一个任务在运行，可选择保存任务。

3.5 下载迁移报告

已迁移完成的任务，可在任务列表界面下载迁移报告。迁移报告为 Excel 文件（xls)，下载后可使用表格查看器软件打开。

迁移报告中可查看任务概况、迁移出现异常的空间、页面、附件、用户数据

• 任务概况：包括任务名称、迁移任务状态、开始迁移与结束迁移时间、迁移空间总数、迁移完成空间数量、迁移异常空间数量、迁移用户总数、迁移完成用户数量与迁移异常用户数量
• 迁移异常空间：空间名称、空间关键字、空间 URL、迁移异常原因
• 迁移异常页面：页面标题、页面 URL、所属 Confluence 空间、迁移异常原因
• 迁移异常附件：附件标题、附件所属空间名称与关键字、空间 URL、迁移异常原因
• 迁移异常用户：Confluence 用户名、Confluence 用户邮箱、ONES 用户名、ONES 用户邮箱
• 引用链接修复异常：包括引用位置页面的标题、所在空间、页面链接（ONES）、引用来源页面标题、引用来源空间、页面链接（Confluence）、修复失败原因

1. 常见问题

重复迁移的空间，是否会覆盖已经迁移的数据？

迁移是以空间为单位进行的，对于重复迁移的空间，会增量迁移一个新的空间，为避免重名，空间名称会增加编号后缀。

迁移空间失败，并且迁移报告中提示：空间数据包导出失败时，该如何排查和解决？

出现该异常，可能由于 Confluence 服务使用的数据库连接超时，对应排查手段（适用于 MySQL 数据库）如下：

1. 确认原因：如果在日志中看到类似 Unable to rollback against JDBC Connection 、communications link failure 的错误，即为数据库连接超时
2. 解决方案：修改配置

修改 Confluence 服务所使用的 mysql 配置文件，一般为 /etc/my.cnf ，在 [mysqld] 配置节点下面添加或者修改 wait_timeout 和 interactive_timeout 为 mysql 的默认的值

wait_timeout = 28800
interactive_timeout = 28800

如果空间中包含引用自其他空间的页面链接，迁移完成后能否对应到 ONES Wiki 的目标页面？

可以的。迁移时会在当前任务和已经迁移完成的空间中，查找引用来源页面，并进行链接的替换。如果没有找到引用来源页面，会在迁移报告中列出引用位置页面和引用来源页面的原始链接，以便对应进行排查

，见下图

：