Jira/Mantis数据迁移到kanass：字段映射与批量导入实战指南

做了这么多年项目管理系统选型和迁移我碰到最多的一个场景就是团队在Jira或者Mantis上跑了一两年的项目各种历史问题、缺陷、评论、附件全堆在里面后来因为成本、开源化、私有化部署这些原因决定换到kanass。系统选型倒是快真正让人头疼的是历史数据怎么搬过来。直接手动复制粘贴不现实几百上千条issue一个个录能把人录疯。这篇文章就专门讲清楚怎么把Jira和Mantis的数据快速、稳定地导入到kanass包括字段映射、状态转换、附件处理、批量导入策略和排查技巧适合正在做系统迁移的运维、QA、项目管理人员以及准备接手这类活儿的开发同学参考。数据迁移这件事表面上看是“把A系统的数据搬到B系统”但实际做起来你会发现它更像是一次数据重构。Jira也好Mantis也好它们的数据模型和kanass并不是一一对应的直接硬倒肯定出问题。所以文章里我会把每一步的关键决策和踩过的坑都写出来尽量让你少走弯路。1. 迁移前先搞清楚这几件事1.1 为什么从Jira/Mantis搬到kanass先说kanass。kanass是基于禅道开源版发展出来的项目管理平台功能覆盖产品管理、项目管理、测试管理、缺陷管理、计划任务、文档管理这些常见场景。它跟Jira、Mantis最大的区别在于kanass是一个集成的管理平台而不只是一个issue跟踪系统。Jira的核心是issue工作流Mantis的核心是bug跟踪而kanass更强调“产品-项目-测试-缺陷”的整体链路打通。很多团队选择kanass是因为它开源、可私有化部署、没有用户数限制而且界面和操作习惯更贴合国内团队的协作方式。但历史数据的迁移就成了绕不开的坎。Jira里可能有一堆史诗、故事、任务、子任务Mantis里有各种自定义字段和大量bug历史记录这些数据如果丢了对团队来说损失很大所以必须想办法完整迁移。1.2 迁移数据范围怎么定这里要先想清楚一件事到底哪些数据需要迁移不是所有数据都值得搬。常见需要迁移的数据包括问题/缺陷本身标题、描述、类型、状态、优先级、指派人、创建人、创建时间、更新时间、截止时间。评论和操作历史Jira里的comment、状态流转记录Mantis里的bugnote和bug历史。附件设计图、日志文件、截图、测试报告等。用户信息创建人、指派人、评论人这些都需要在kanass里有对应的用户账号。版本、模块、组件Jira的Fix Version、ComponentMantis的Version、Category这些可以直接映射到kanass的产品和项目维度。自定义字段Jira的customfield_xxxMantis的custom field这部分最容易出问题。工作日志/工时Jira的Time Tracking日志Mantis的elapsed_time等。至于那些已经关闭很久、没有任何参考价值的旧工单以及一些临时性的测试数据我建议你迁之前先做一次清理。我之前帮一个团队迁移时发现他们Jira里有三千多条垃圾issue全是自动化测试产生的一键bug迁过去纯粹是污染数据。所以先盘点再迁移永远比先迁移再清理划算。1.3 三条导入路径怎么选目前把Jira/Mantis数据导入kanass主流的路径有三条每条的适用场景不一样。导入路径操作方式优点缺点适用场景CSV/Excel导入从源系统导出CSV整理成kanass导入模板操作简单不需要开发字段映射要手动对照附件和评论需要额外处理中小规模数据几千条以内字段相对规范API导入调用kanass的API接口写脚本批量写入灵活支持复杂映射可以做增量导入需要开发量要处理接口限流和错误重试数据量大、字段复杂、需要持续同步的场景直接操作数据库把源库数据清洗后直接写入kanass数据库速度最快适合海量数据风险高容易破坏数据结构不推荐非专业人士操作极端大批量数据且对kanass内部表结构非常熟悉从我个人的实践来看80%的团队用第一种方式就能解决问题。kanass后台自带导入功能支持CSV格式只要你把源数据整理成它需要的列导入过程就成功了一大半。API方式适合那种需要把Jira/Mantis和kanass长期并行运行、两边数据需要持续同步的情况。数据库直导我一般只用来处理附件和历史日志这种“批量化”数据不想碰主表因为一旦写坏数据全乱。2. Jira数据导入kanass完整实操2.1 Jira侧的数据导出从Jira导数据最常见的方式是用过滤器导出CSV。操作路径是进入某个项目或过滤器点击“导出”按钮选择CSV所有字段。这里有个关键点Jira新版的CSV导出默认只能导出当前过滤器的字段如果你的自定义字段很多最好在导出前编辑过滤器列确保所有需要的列都出现在导出结果里。我建议用“所有字段”导出因为这样CSV里会包含类似customfield_10001这样的原始字段名后期映射时不容易漏。不过问题来了这种CSV里字段名是英文内部名而不是界面显示的中文名。比如“Summary”对应标题“Description”对应描述“Issue Type”对应问题类型你在整理时心里要有数。除了问题的基本信息还需要额外处理以下数据附件Jira的附件默认不包含在CSV导出里。你需要登录Jira服务器找到JIRA_HOME/data/attachments目录按项目或问题ID把附件文件拷出来。如果你用的是云版Jira那就只能通过一个个问题页面去下载或者用第三方插件批量导出。工作日志CSV导出里通常不会有Time Spent的工作日志明细。要拿完整日志可以通过Jira的REST API读取或者直接在数据库里查worklog表。如果量不大也可以在Jira界面里逐个问题导出工作日志。用户列表CSV里只会有用户名如果要在kanass里创建对应的用户还得导出一份用户清单。可以在Jira用户管理里面导出CSV用户列表或者用数据库里的cwd_user表。2.2 字段映射对照表字段映射是整个导入过程中最核心的步骤。Jira里的字段不能原封不动地搬进kanass因为两者的数据模型不一样。我以最常见的字段为例整理了一张对照表Jira字段kanass字段说明Summary标题直接映射Description描述富文本内容需要检查格式兼容Issue Type类型需要按类型映射见下文Status状态需要按状态映射见下文Priority优先级需要按优先级映射Assignee指派给要求用户先存在于kanassReporter创建人要求用户先存在于kanassCreated创建时间注意时区转换Updated更新时间注意时区转换Due Date截止时间直接映射Fix Version版本在kanass中先创建对应版本Component模块在kanass中先创建对应模块Parent父任务用于恢复父子任务结构customfield_xxx自定义字段需要在kanass预先创建自定义字段Time Spent/Original Estimate消耗工时/预估工时通过工作日志导入这里最需要注意的问题是状态映射。Jira的状态和kanass的状态不是一一对应的必须先把Jira里实际用到的所有状态枚举出来然后逐项映射。下面是我常用的映射规则Jira状态kanass状态Open激活In Progress处理中Resolved已解决Reopened激活Closed已关闭如果你在Jira里自定义了很多特殊状态比如“Blocked”“QA Verified”之类建议在kanass里也提前配置对应的自定义状态再导入否则数据到kanass后会被塞进默认状态看起来会很奇怪。优先级映射相对简单Jira的Highest、High、Medium、Low、Lowest可以分别映射到kanass的紧急、高、中、低、最低。如果你的Jira优先级有自定义值同样需要先建立映射表。2.3 导入kanass的具体步骤我是这么操作的整个流程走下来比较稳第一步在Jira里导出CSV所有字段保存后用文本编辑器打开确认编码为UTF-8。这里不要直接拿Excel打开保存否则编码经常会变成ANSI后面导入中文直接乱码。第二步把CSV列名改造成kanass导入模板对应的列名。比如把Summary改成“标题”把Description改成“描述”把Issue Type改成“类型”。不要小看这一步列名对不上导入工具根本识别不了。第三步处理类型和状态的值。把Jira的类型值Story、Task、Bug、Epic映射为kanass的类型名称把状态值Open、In Progress等映射为kanass的状态名称。这一步我通常直接用Excel的vlookup或者写个小脚本批量替换。第四步在kanass后台创建好对应的项目、产品、版本、模块、自定义字段以及所有用户账号。顺序很重要先建这些基础数据再导入问题。第五步进入kanass后台的数据导入功能选择CSV文件按模板对应关系进行导入。导入后系统一般会返回成功和失败记录失败的数据会提示原因比如“指派人不存在”“状态不合法”等。第六步导入完成后做抽查。我会按创建时间抽几单、按状态抽几单、按优先级抽几单点开看看描述、评论、附件是否都正确。抽查通过的才能算迁移成功。2.4 WBS层级、工作日志这类特殊数据怎么处理如果你用了Jira的工作分解结构WBS模板插件那除了普通过程还得考虑父子任务的层级关系。kanass是支持父子任务结构的关键在导入时要把“父任务编号”给对。我在CSV里加了一列“父任务编号”填写Jira里子任务对应的父任务Key比如PROJ-100导入后kanass会自动把结构还原成父子关系。如果没有这一列导入后的任务就是平铺的层级结构全丢了。工作日志这块稍微麻烦一点。CSV导入本身不支持直接写入工作日志我建议分两步走先用CSV把问题和任务导入kanass然后利用kanass的API按问题ID把Jira的工作日志逐条写入kanass的“工时”记录里。这里要注意工时单位Jira默认是秒kanass一般按小时显示换算关系不要搞错。3. Mantis数据导入kanass完整实操3.1 Mantis的数据结构特点Mantis和Jira不一样它是典型的PHPMySQL架构几乎所有数据都存在数据库表里。核心表包括mantis_bug_tablebug主表包含summary、description、status、priority、severity、reporter_id、handler_id等。mantis_bugnote_tablebug评论表对应Jira的comment。mantis_bug_file_table附件信息表记录文件名、文件类型、文件内容如果存数据库或文件路径如果存文件系统。mantis_custom_field_table和mantis_custom_field_string_table自定义字段定义和值。mantis_bug_history_tablebug历史记录。因为这个特点从Mantis导数据其实比Jira更灵活。你既可以在页面上用“导出CSV”功能也可以直接写SQL查询把需要的数据拼成一张宽表再导出CSV。我个人更推荐SQL方式因为自定义字段在页面导出时不一定带得全而SQL可以自由联表查询。3.2 字段与状态映射Mantis字段到kanass的映射跟Jira的映射逻辑类似但有几个Mantis特有的点要额外注意。Mantis字段kanass字段说明summary标题直接映射description描述直接映射status状态注意Mantis用数字代码表示状态priority优先级注意Mantis的priority也是数字severity严重程度Mantis特有映射为kanass的严重程度reporter_id创建人需要转换成用户名handler_id指派给需要转换成用户名date_submitted创建时间直接映射last_updated更新时间直接映射project_id项目先建立项目映射category_id模块/分类先建立模块映射custom字段自定义字段需要额外拼接这里最大的坑是Mantis的状态和优先级都是数字代码不是文字。比如status字段里10代表new新建20代表feedback反馈30代表acknowledged已确认40代表confirmed已确认/复现50代表assigned已指派80代表resolved已解决90代表closed已关闭。如果你不把这些数字转换成文字导入到kanass后状态会变成一堆数字或者全变成默认状态。严重程度也一样Mantis的severity有feature特性、trivial很轻微、text文字、minor轻微、major一般、crash崩溃、block阻塞等转换到kanass里需要映射成无、轻微、一般、严重、致命这些级别。3.3 Mantis导入步骤从Mantis导入kanass我建议的步骤是第一步导出基础数据。写一条SQL把bug主表、项目名、分类名、用户名关联起来查出summary、description、status、priority、severity、reporter名、handler名最后用mysqldump或Navicat导出成CSV。第二步在SQL查询里嵌套CASE WHEN直接把status、priority、severity的数字代码转换成kanass对应的中文字段值。这一步如果在数据库查询阶段就做好后面整理CSV会轻松很多。第三步导出自定义字段。先查mantis_custom_field_table拿到字段ID和字段名再查mantis_custom_field_string_table拿到每个bug对应的字段值最后用行转列的方式拼到同一张表里。推荐直接写一条GROUP_CONCAT的SQL或者用Python在内存里合并都可行。第四步导出评论bugnote。mantis_bugnote_table里记录了bugnote_text_id、reporter_id、date_submitted需要关联mantis_bugnote_text_table拿到评论内容。把评论数据单独存一个CSV导入主bug后再用API补写到对应的kanass缺陷下。第五步在kanass后台导入主CSV校验基础数据是否完整。第六步通过API导入评论、历史记录、工时等附加数据。3.4 自定义字段和附件的处理Mantis的自定义字段是很多团队重度使用的功能。常见的有“复现步骤”“影响版本”“浏览器环境”“客户名称”等等。导入前建议在kanass里先创建好同名的自定义字段否则数据没有地方放。处理自定义字段时我习惯先把所有字段值都丢到CSV里再用Excel的筛选功能检查字段值的格式。比如Mantis里如果存在“环境”字段里面可能存的是多行文本包含换行符导入时Excel很容易把换行符拆成新的行导致整个CSV错位。解决办法是用文本编辑器或者脚本把字段内的换行符统一替换成br或特殊分隔符导入到kanass后再替换回换行。附件处理这块Mantis有两种存储方式如果$g_file_upload_method DISK附件在服务器文件系统上数据库里的mantis_bug_file_table只保存文件路径如果是DATABASE方式附件内容直接以BLOB存在数据库里。磁盘方式处理起来最方便把整个上传目录拷出来按bug_id重命名放到kanass的附件目录即可。数据库方式就需要先把BLOB导出成文件再走附件导入。文件名有中文或特殊字符时要注意编码避免导入后下载链接打不开。4. 大批量数据迁移的落地策略4.1 分批导入数据量上了几万条之后一次性全部导入基本都会出问题要么后端超时要么内存溢出。我的做法是分批导入每次500到1000条导入完一批休息几秒再导下一批。这跟从Oracle、Hive那些数据库做大批量数据导入是一个思路分批永远比一次性稳妥。如果你用API导入还可以在脚本里加上失败重试和日志记录。我一般会写一个Python脚本批量从CSV里读取问题数据调用kanass的API创建问题如果返回错误就记录下来不中断整个流程。这样即使有几十条数据格式有问题也不影响其他数据入库。4.2 附件批量同步附件是迁移过程中最容易被忽略也最容易翻车的地方。我建议先统计一下源系统附件总数和总大小评估一下磁盘空间。Jira附件目录动辄几个GB直接复制到服务器时要预留充足空间。同步附件时我踩过一个坑文件名里带特殊字符比如#、%、导入kanass后要么下载不了要么路径直接错乱。后来我统一在同步之前做了一次文件名清洗把特殊字符替换成下划线同时在数据库里同步更新映射关系问题才解决。附件和问题的关联最稳的方式是保持编号一致。比如Jira里问题是PROJ-100对应多个附件那我就在附件目录里建一个子目录叫100把该问题的所有附件放进去导入时脚本根据问题编号自动关联。4.3 用户和权限很多人迁移时只关注问题数据忘了用户结果导入后“指派给”全部指向不存在的人。正确的顺序是先导入用户再导入问题。Jira的用户名、Mantis的reporter_id在导出时就要转换成用户名。如果遇到同一个用户在不同系统里用了不同的名字比如邮箱一样但用户名不同需要先做一个用户映射表。kanass里的用户只能通过账号匹配如果账号不存在导入会报错。另外要说一句密码是不可能迁移过去的。kanass用户导入后建议用“重置密码并发送邮件”的方式让用户自己设置新密码或者临时设置一个初始密码让用户首次登录后自行修改。权限这块也要重新配。Jira里的项目角色、Mantis的权限级别跟kanass的权限模型不一样。导入数据只能保证数据在权限一定还要在kanass里按项目重新配置比如谁可以看这个项目谁可以操作缺陷谁可以管理版本等等别指望数据导完权限也跟着过来。4.4 校验与回滚数据导完之后一定要做校验别急着让团队正式使用。我常用的校验方法是数数。导入前统计源系统的问题总数、评论总数、附件总数、用户总数导入后再在kanass里分别统计同样维度的数量两边对比误差在合理范围内才算通过。数量对不上就要查原因比如是不是有数据被漏掉是不是有数据重复导入了。回滚方案也很重要。建议在导入前对源数据做完整备份至少把原来的Jira/Mantis数据库导出成SQL文件存起来。如果导入kanass后发现不可控的问题还能回到原始状态重新来。同时导入日志要保留每批导入的记录都存下来方便排查是哪一批数据出了问题。5. 常见问题与排查技巧实录5.1 常见问题速查表我把自己遇到过的、以及身边朋友遇到过的典型问题整理成了一个速查表直接按表排查就行。现象可能原因解决办法导入后中文乱码CSV文件编码不是UTF-8用文本编辑器另存为UTF-8编码不要用Excel直接另存状态全部变成默认值源系统状态值是英文或数字未做映射提前把状态值转换为kanass状态名称指派人/创建人丢失用户账号不存在于kanass先导入用户再导入问题附件全部缺失Jira导出CSV不包含附件单独从服务器下载附件按问题ID关联时间差了8小时Jira导出的时间是UTC导入前先把时间字段转换为本地时区数据重复导入前一次导入失败后未清理又导了一次导入前用问题唯一编号做去重或用kanass的外部ID字段自定义字段值丢失目标系统里没有创建对应自定义字段先在kanass创建相同的自定义字段再导入评论/历史记录没有导入只导了CSV主表通过API或数据库导出评论、历史记录再补写父任务结构变平铺未填写父任务编号导入前补充父任务编号列附件下载链接失效文件名含特殊字符或关联编号不一致清洗文件名校验附件与问题编号的关联关系5.2 排查技巧排查迁移问题我的经验是先小后大。不要在正式环境直接全量导入先在测试环境导5到10条数据验证流程。小批量跑通了再放大到几百条最后全量。导入过程中产生的错误日志一定要留好。kanass导入失败时会提示原因比如“用户不存在”“字段值太长”“日期格式不正确”这些信息直接告诉我数据源哪里需要修。我一般会把错误提示按类型汇总一次统一修改CSV而不是一条条去改。如果数据量很大建议写一个校验脚本。比如统计CSV里每列的空值率、枚举值分布导入前就能发现很多问题。我之前导一个Mantis项目时脚本跑出来发现priority字段里有几个值是0属于脏数据如果直接导入这几条的优先级就会异常。这种问题靠人工肉眼根本发现不了。5.3 说几个我踩过的坑第一个坑是Jira导出的CSV里描述字段包含换行符。用Excel打开时包含换行符的单元格会被拆成多行整个CSV结构就乱了。这件事我是在导入前用文本编辑器检查时发现的后来统一把描述里的换行符替换成了br标记导入完再转换回来。第二个坑是Mantis的状态数字。我一开始假想过导入工具能不能自动识别结果发现完全不识别所有bug导入后都是同一个状态。后来我直接在SQL查询里用CASE WHEN把数字状态转成中文字段从根上解决了。第三个坑是时区。Jira导出的时间字段是UTC时间标准格式导入到kanass后直接显示成UTC时间团队成员看到的跟原系统差8小时。后来我在整理CSV时用脚本把UTC时间统一转换成Asia/Shanghai时区再导入才不再有这个问题。第四个坑是附件关联。Jira的附件文件名是纯数字没有可读性我一开始以为按文件名就能关联到问题后来发现文件名跟问题ID对不上。正确做法是去jiraattachment表里把对应关系查出来或者直接把附件按问题ID放到子目录里整理。没有查关联关系之前几百个附件全部变成了“无法关联”的孤儿文件白白浪费了半天时间。迁移这种事做得多了你会发现技术难点其实都不是不可逾越的真正费时间的是数据清洗和字段映射。所以我的建议是迁移前一定要花时间做数据盘点和映射设计先在测试环境完整演练一遍再上生产环境。不要上来就全量导入不然你大概率会在那些“看似简单”的地方翻车。如果你正在准备把Jira或Mantis的数据导入kanass希望这篇文章能帮你把坑提前避开。按这个流程走下来几千条数据加几百个附件一个下午搞定是完全可行的。