# 独立部署工具使用手册

URL: https://docs.ones.cn/on-premises/7.33/product-manual/data-migration/confluence/standalone-migration-tool

## 1. 迁移前检查

- 确认迁移方式。如果您不需要迁移用户、权限等数据，仅保留空间中的页面、附件与页面树结构，可选择手工导入 Confluence 数据包（xml zip）的方式迁移，详见： [ONES Wiki 文档导入与导出](https://docs.ones.cn/on-premises/7.33/product-manual/ones-wiki/import-and-export/) 。如果您需要在迁移时进行批量操作，并同时保留用户、权限数据，推荐使用迁移助手进行迁移；
- 检查 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. 打开控制台，进入迁移工具文件所在目录，执行启动命令

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

1. 执行完上述步骤后，打开浏览器，访问 Confluence 服务器 IP 地址 + 5002 端口号（默认端口号）；如果启动工具时，修改了默认端口号，这里需要调整为修改后的端口号。
![独立部署工具使用手册](https://docs.ones.cn/assets/images/f08efba7f5d4ba1bf6a7-fb785b07af3916f3a8720207ba2c6fd6.png)

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

### 3.2 迁移任务列表

#### 3.2.1 什么是迁移任务

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

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

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

#### 3.2.2 查看迁移任务列表

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/b662924c47e56caac24d-cd2dd370910e9e0ebb2a00da5a14370f.png)

注意： 同一个 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 主目录
![独立部署工具使用手册](https://docs.ones.cn/assets/images/2f5e88ca649b9132e74d-666add904d396e3be2323c194aba8a2a.png)

1. Confluence 版本号：访问 Confluence ，页面底部区域可查看版本号
![独立部署工具使用手册](https://docs.ones.cn/assets/images/ea51f5d39f61945ab4fe-a2575098e0b15040b45b13e5b34b8e35.png)

1. ONES 服务信息
1. ONES 服务器地址：填写 ONES 服务的 IP 地址和端口号
2. ONES 管理员用户名和密码：ONES 多团队环境，填写的账号需要为组织管理员以及当前所有 ONES 团队的超级管理员；如果是 ONES 单团队环境，需要为超级管理员。
![独立部署工具使用手册](https://docs.ones.cn/assets/images/d531ad646ad99d612bd0-e1e75709e124602491190278649cf761.png)

📢 注意

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

##### 特殊场景

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

#### 3.3.2 第二步：选择团队

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/900071e47af6c707a374-adbd3a71dc8af9b5e572e524f0102990.png)

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/747fda1a2008eac9fa2b-d948dedb7d87c6bf83e0f025fa052fd9.png)

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

- 迁移开始前，分析 Confluence 中的空间使用情况，例如先规划活跃度较高的空间，以减少对正式使用的影响
- 单个空间数据存储量较大的空间，配合存储量较小的空间进行规划，避免一次性迁移过大的数据量
空间列表按迁移状态分类展示，可快速选择「未迁移」的空间。通过搜索，可快速定位到某个待迁移的空

##### 特殊场景

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

#### 3.3.4 第四步：同步用户

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/8615d3f265288b660c53-7459a86272ff4b26e4b4074fcab10942.png)

##### 3.3.4.1 邮箱异常用户

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

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/856eae2d259d4333d916-fe45ee97ac4454f1f198df916bc04c91.png)

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

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

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/01bc848ae8da42cbccca-e89436859a7c4a3c8b7bfc662ccd54c6.png)

##### 3.3.4.2 邮箱正常用户

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

用户数据操作选择说明

- 创建：以 Confluence 环境中的用户数据（用户名、显示名、邮箱）在 ONES 系统中创建新用户
- 更新：修改 Confluence 用户邮箱，并以新的邮箱在 ONES 系统中创建用户
- 映射：将 Confluence 用户数据映射到一个 ONES 已有用户；
![独立部署工具使用手册](https://docs.ones.cn/assets/images/84d3984828deca64d22f-a7286019d8c453e51ef454948911b68d.png)

##### 3.3.4.3 搜索用户

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/024283ee47783ab82a8b-dfb945af4d64855bac3f04211aa22e43.png)

##### 特殊场景说明

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

#### 3.3.5 保存任务

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

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/f4f4df854a2851ba97ea-e6f27ea1b1eb5f67fdb55020b0b681a3.png)

### 3.4 开始迁移

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

### 3.5 下载迁移报告

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

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

![独立部署工具使用手册](https://docs.ones.cn/assets/images/846e9dd7e9783cfd383f-180dbfa10d2771353bfdecef7254cf6a.png)

- 任务概况：包括任务名称、迁移任务状态、开始迁移与结束迁移时间、迁移空间总数、迁移完成空间数量、迁移异常空间数量、迁移用户总数、迁移完成用户数量与迁移异常用户数量
- 迁移异常空间：空间名称、空间关键字、空间 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 的默认的值

```text
wait_timeout = 28800
interactive_timeout = 28800
```

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

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

，见下图

：

![独立部署工具使用手册](https://docs.ones.cn/assets/images/25faf9fd2accc11114fb-a81b7f777497b088a9b54e5b66f9cdb5.png)