私有化项目协作工具历史数据迁移：导入与校验步骤

私有化项目协作工具的历史数据迁移，真正麻烦的部分往往不在迁移工具本身，而在两件事：数据怎么导进去，以及导完之后怎么确认它对。旧系统里几个月甚至几年的需求、任务、Bug、用例、文档和附件，一旦出现字段错位或关联断裂，排查成本会远高于迁移本身。

下面按实际执行顺序，把历史数据迁移拆成导入与校验两条主线：先定导入方案，再完成 Excel/CSV 与 Jira、Confluence 等来源的导入，最后用总量、明细、关联三层校验加附件、权限两项专项检查确认数据可用。每一步都给出动作、成功信号和失败时的处理方式。

先定导入方案：来源、范围与停写窗口

历史数据迁移不是单一动作。动手之前，先把来源、范围和停机安排定下来，后面的步骤才不会做反。

先分清数据从哪里来

不同来源对应不同的导入通道，选错通道会浪费大量时间。

在私有化项目协作工具里换环境或换工具，导入通道由来源决定。三种来源的准备重点并不相同：整站搬迁拼的是版本一致和附件完整，从 Jira 导入拼的是字段映射和关联保留，Excel 批量导入拼的是模板规范和分批策略。先对上自己属于哪一类，再选具体通道。

盘点范围与体量，先清理再迁移

盘点要输出一张清单：有哪些对象（需求、任务、Bug、用例、文档、附件）、各自条数、附件总体积和时间跨度。

盘点同时做清理。旧系统里的测试数据、重复记录、已停用的账号，导入后只会增加维护负担。以 Jira 为例，官方文档建议在迁移前删除不再使用的账号、问题类型和属性，既能减少配置工作量，也能缩短导入所需时间。

清理还有一个作用是控制导入体量。数据量越大，单次导入失败后重新执行的代价越高，这也是后面要分批导入的原因。

建立用户与字段映射表

映射分两块：人的对应和字段的对应。

用户映射优先靠邮箱一致。旧系统账号与禅道账号的邮箱对不上，导入后负责人这类字段就会错位，甚至变成空值。字段映射建议做成一张对照表，写清旧字段、新字段和转换规则。

状态、优先级、问题类型这类枚举值最容易出问题，因为两边取值集合通常不一样，需要提前定义转换规则，而不是导入后再手工逐条改。

完成一次完整备份，约定停写窗口

迁移前必须备份，而且备份要同时覆盖数据库和附件，只做其中一项都不算完整。

导入或搬迁期间要停止系统写入，避免迁移过程中产生新数据，导致新旧记录对不上。这个窗口需要提前和团队约定，尽量安排在非工作时间。

版本和权限也要提前核对：源环境与目标环境版本是否一致，执行导入的账号是否具备管理员权限。私有化部署意味着升级和兼容性由企业自己负责，动手前核对一次，比事后排查划算。

导入步骤一：用 Excel/CSV 模板批量导入需求、任务、Bug 与用例

散落在 Excel、内部工单表或自研系统里的数据，通常走文件导入。禅道的项目管理把需求、任务、Bug、用例放在同一套数据模型里，各类对象列表都提供导入导出入口，可以按对象批量操作。

从对象列表导出对应模板

进入对应对象的列表页，用导出功能下载模板文件，常见格式为 xlsx 或 csv。

模板字段会随版本调整，所以一定要用当前版本导出的模板，不要沿用历史文件，也不要自行改列名、删列或调整列顺序，否则整批数据都可能解析失败。

按字段规范整理数据

填写时重点看三类字段：

• 必填项：标题或名称通常是必填，缺失会导致该行被跳过。
• 枚举值：优先级、状态、类型等，取值必须落在系统允许的范围内。
• 关联字段：所属产品、模块、项目等，需要与目标系统中已有对象对应。

用 CSV 编辑时，中文容易因为编码不一致出现乱码，保存时统一为 UTF-8。日期格式也建议统一，避免被解析成文本。

分批上传并在预览中确认

数据量大时按项目或按时间分批导入，单批规模控制在几百条更稳妥。失败时定位范围小，重做成本也低。

上传后系统会先解析并给出预览。这一步不要跳过，逐行核对标题、模块、优先级等关键字段是否落到正确列，确认无误再保存。

处理失败行与补全关联

导入结果通常会显示成功和失败的行数。失败行要回去看具体原因，常见的有编码错误、枚举值不匹配、必填项为空。

还有一点需要提前预期：部分导入方式只完成基础字段，负责人、关联项目等字段可能需要在导入后补充。不要默认一次导入就能闭环，导入后要专门检查一遍关联字段是否完整。

测试用例往往是存量数据里体量最大的部分。禅道的测试用例管理支持通过 Excel 模板批量导入，并可在导入时选择是否覆盖重复用例，适合跨项目复用旧用例。

导入步骤二：从 Jira、Confluence 迁入既有研发数据

如果旧系统本身就是研发工具，可以用后台的数据导入功能迁移，比走 Excel 中转保留更多关联关系。

确认版本门槛与导入方式

按禅道官方文档说明，Jira 数据导入支持 Jira Software Server/Data Center 与 Cloud，覆盖 Jira 7.x 到 10.x（Server）。导入方式有三种，选哪种取决于旧系统是本地部署还是云版本，以及能否拿到数据库。

版本前提要提前确认。从禅道开源版 21.6 起，支持通过数据库导入或文件导入迁移 Jira 数据；22.1 起支持接口导入。Jira 侧，数据库导入仅支持 8.8 及以上版本，更低版本建议先升级再备份数据库。若还要一并导入 Jira 中新增的问题类型、自定义字段和工作流，需要企业版 11.6 及以上版本。完整的迁移方式对照可以参考 Jira 国产替代方案。

Confluence 数据导入适用于企业版及以上的私有部署服务，支持 Confluence 6.x、7.x、8.x（Server）。空间、页面、附件、用户和权限可以一并迁入，分别对应禅道的文档库、文档和相关权限配置。

导入前整理旧系统数据

这一步直接决定导入后要返工多少：

• 删除不再使用的账号，并保证旧系统与禅道账号、邮箱一致，便于自动匹配。
• 删除未使用的问题类型和属性，减少配置工作量。
• 评估项目状态。已归档项目导入后状态会变为已关闭，回收站中的项目不会被导入，其余项目导入后状态为进行中，所以要先想清楚哪些项目真要迁。

后台执行导入并核对结果

入口在后台的数据导入功能中，选择从数据库导入或从文件导入，再按旧系统是本地部署还是云版本选择对应方式。

导入前务必先备份禅道数据库，导入过程中停止使用禅道，避免正在写入的数据丢失。导入完成后，先核对导入的对象数量和项目状态，再进入下一节的校验环节。

导入后校验：三层核对加两项专项检查

导入完成不等于迁移完成。校验要覆盖三个层次，再补两类专项检查。

校验的分工是：总量核对能看出有没有丢，明细抽验能看出有没有错，关联走查能看出迁过来的数据能不能真正用。

下文逐层说明每层怎么落地。

第一层：总量核对

对比新旧系统各对象的条数，是判断有没有丢数据最快的方法。

导出两边的记录数，逐类比对需求、任务、Bug、用例等对象。条数一致是最低要求；出现差异时，差异必须能被解释，比如测试数据被主动清理、回收站项目未导入。无法解释的差异要当问题处理，不能直接归零。

第二层：明细抽验

总量对得上，不代表内容没错。总条数一致但字段错位的情况并不少见。

按项目或按时间抽查一批记录，逐项核对标题、状态、优先级、负责人、创建时间等关键字段。抽样要有覆盖性，不同项目、不同数据来源、不同时间批次都抽一点，避免只看到整理得最好的那部分。

第三层：关联走查

数据能不能用，取决于关联关系是否完整。

抽查需求、任务、Bug、用例之间的链路，确认相关对象之间可以相互跳转。典型的断裂是任务找不到对应需求，或 Bug 无法追溯到用例，这类问题单看条数发现不了。

两项专项检查：附件与权限

附件和权限独立于业务数据，容易被漏掉。

附件要抽样下载，确认能正常打开。文档、图片这类附件通常存放在独立目录，备份或迁移时容易遗漏，出现记录能打开、图片却看不到的情况。

权限要抽查用户、用户组和权限分配，确认与预期一致。私有化环境下组织结构和权限往往重新配置过，导入后核对一次，可以避免上线后出现越权或看不到数据的问题。

校验不通过怎么办：定位、修复与回退

校验发现问题时，不要直接在系统里手工改数据。先定位原因，再决定是补导还是重做。

按「先结构、后内容」的顺序定位

定位顺序建议从上到下：先看导入日志和失败行提示，判断是否有解析或字段错误；再看各对象条数差异，判断是整体缺失还是个别项目；最后看具体记录的字段和关联，确认是映射问题还是关联丢失。

映射问题通常集中出现，同一类字段的所有记录都会错，修复时批量处理即可；关联丢失则更分散，需要按项目逐个排查。先判断问题类型，再选修复方式，能省掉大量重复排查。

重做导入与回退方案

如果问题集中在个别批次，可以清理该批数据后重新导入。重做前先把这次导入产生的数据清干净，否则会出现重复记录。

如果问题面较大或系统出现异常，就用回退方案。迁移前的那次完整备份就是回退方案：直接还原到迁移前状态，定位原因后重做。这也是备份必须同时覆盖数据库和附件的原因。

导入完成、校验通过后，建议新旧系统双轨并行一段时间：新系统跑真实业务，旧系统留作对照，发现差异及时调整。双轨期的长短取决于业务复杂度，数据量小、依赖少的团队可以短一些，大型团队要留足。

对私有化项目协作工具而言，历史数据迁移的导入与校验并不是一次性的收尾工作，而是一条完整的执行链：定方案、导数据、做校验、留回退，每一环都直接影响迁移后系统的可用性。想先了解整站搬迁、外部数据导入和两者叠加三种场景的完整对照，可以再看这份私有化部署项目管理系统如何迁移历史数据的操作指南。