OpenProject Jira 迁移字段映射完全参考:从项目、工作包到用户与自定义字段

原创2026-09-14 22:39:141,851 阅读
文章标签:后端前端企业应用研发协作协同办公

OpenProject Jira 迁移字段映射完全参考:从项目、工作包到用户与自定义字段

导读

本文是 OpenProject Jira Migrator(Jira Data Center 导入工具)的字段映射参考手册,系统梳理迁移过程中 Jira 数据如何一一对应到 OpenProject 的字段:哪些字段被迁移、哪些被明确丢弃、哪些以何种规则自动创建或去重。通过本文,你将掌握项目级字段、Issue → 工作包字段、用户与组、自定义字段四大类映射的全部规则,以及大小写不敏感匹配、变更历史分组、附件静默失败等关键行为陷阱,为制定迁移前的数据清洗方案和迁移后的核对清单提供直接依据。

说明:Jira Migrator 是 OpenProject 官方正在积极开发的导入工具,目前仅支持 Jira Data Center 10.x 与 11.x,不支持 Cloud 实例,仅建议在测试环境使用。本文映射规则对应仓库中 docs/installation-and-operations/jira-migration 目录下的 Field Mapping Reference,并与 Jira 迁移总览、自定义字段迁移 相互补充。

项目级字段映射

迁移每个项目时,Jira 的项目字段按以下规则转换:

Jira 字段 迁移为 OpenProject 你需要知道的事
旧/重命名后的项目 key 项目标识符(Project identifier) 如果 Jira 项目被重命名过,旧 key 在迁移后依然能解析到同一个项目
项目描述 项目描述 —
项目 key 项目标识符 —
项目名称 项目名称 —

此外,每个被迁移的项目都会被创建为 私有(private)且激活(active),且没有父项目——这并非来源于 Jira 中的任何设置,而是迁移工具本身的创建方式。

Issue → 工作包字段映射

这是映射参考的核心部分。以下表格完整列出每个 Jira Issue 字段在 OpenProject 工作包中的去向。

Jira 字段 迁移为 OpenProject 你需要知道的事
Affects Versions(影响版本) 不迁移 —
Assignee(经办人) Assignee(负责人) —
Attachments(附件) Attachments(附件) 重新上传到工作包,原作者信息尽可能保留
Change history(变更历史:状态变化、字段编辑等) Activity 条目 保留,但分组粒度比 Jira 原始历史更粗——见 迁移后检查清单
Comments(评论) Activity/notes 作者与日期保留;文本从 Jira 标记转换
Components(组件) 不迁移 —(规划中:JIM-107)
Creator(创建人) Author(作者) —
Description(描述) Description(描述) 从 Jira 标记转换为 OpenProject 标记——标题、粗体/斜体、链接、代码/引用块、表格均会转换。部分元素不转换:{info}/{warning}/{note}/{tip} 提示框、{toc}、以及 {expand}/{section}/{column} 布局完全无法识别——其内容会保留,但原始的 {macro} 标签文本会残留为可见、未转换的文本,既不会干净移除也不会被样式化。裸 issue key 链接(如 <a href="https://link.gitcode.com/i/1eb566411ae06c3c6408b1dcb743a925" target="_blank">PROJECT-123])和附件链接(如 [^file.pdf])也会保留为字面、不可点击的文本。见 [迁移前检查清单 与 迁移后检查清单
Due date(截止日期) Due date(截止日期) —
Environment(环境) 不迁移 —
Fix Versions(修复版本) 不迁移 —(规划中:JIM-154)
Issue creation date(创建日期) 工作包创建日期 设置为迁移运行时的日期,而非 Jira 中 issue 的原始日期(跟踪:JIM-189)
Issue id(内部 ID) 不迁移 Jira 内部 ID(规划中:JIM-8)
Issue key(如 PROJECT-123) 工作包标识符(Work package identifier) 旧/重命名后的 issue key 在迁移后同样保持可用,与项目 key 的机制一致
Issue links(阻塞、关联等) 不迁移 —(规划中:JIM-76)
Issue type(问题类型) Type(类型) 按名称匹配(不区分大小写);无匹配时自动创建新 Type,并挂接到正确的项目(镜像 Jira 按项目区分的 Issue Type Scheme)。只有名称被迁移。迁移的 Type 不会被标记为项目默认类型,即使它在 Jira 中就是默认值
Logged work / time entries(已记录工时) 不迁移 只有两个估算字段会迁移,实际记录的时间不会迁移(规划中:JIM-93)
Original time estimate(原始时间估算) Estimated hours(估算工时) —
Priority(优先级) Priority(优先级) 按名称匹配(不区分大小写);缺失时自动创建。如果 Jira 中 issue 没有优先级,则使用 OpenProject 的默认优先级。只有名称被迁移——Jira 的严重程度顺序、颜色和图标都不保留,这一点不仅影响外观:当 issue 未设置优先级时,OpenProject 会回退到列表中排在最前的那个优先级
Remaining time estimate(剩余时间估算) Remaining hours(剩余工时) —
Reporter(报告人) 不迁移 Jira 的 "Reporter" 概念在 OpenProject 中不存在,被丢弃;只有 Creator 变为 Author
Resolution(解决结果) 不迁移 Jira 将 issue 关闭的原因(Fixed、Won't Fix、Duplicate、Cannot Reproduce)与其工作流状态(Status)分开跟踪。只有 Status 被迁移——关闭原因被完全丢弃,多个不同的 Jira 解决结果可能映射到同一个 OpenProject 状态且不留任何痕迹(规划为自定义字段:JIM-149;更广泛的原生支持跟踪于 FND-231)
Resolution date(解决日期) 不迁移 —
Security Level(安全级别) 不迁移 —
Status(状态) Status(状态) 按名称匹配(不区分大小写);缺失时自动创建。只有名称被迁移——迁移的状态永远不会被自动标记为 OpenProject 中的 "closed"(关闭),即使它在 Jira 中代表已结束状态(如 Done、Closed、Resolved)。这会影响任何依赖"哪些工作包实际已完成"的过滤和报表
Sub-tasks / parent-child links(子任务/父子链接) 不迁移 —(规划中:JIM-75)
Summary(摘要) Subject(主题) —
Votes(投票) 不迁移 OpenProject 中不存在此概念(变通方案规划中:JIM-207)
Watchers(关注者) 不迁移 —(规划中:JIM-180)
Web link(Web 链接) 不迁移 OpenProject 中不存在此概念(变通方案规划中:JIM-206)

用户与组映射

Jira 字段 迁移为 OpenProject 你需要知道的事
Active flag(激活标志) 账户状态 创建时锁定(locked);只有在你 批准导入 后才会自动解锁,且仅针对在 Jira 中处于激活状态的用户
Display name(显示名) First / last name(名/姓) 自动拆分;单词名会同时用于名和姓
Email(邮箱) Email(邮箱) 如果 Jira 用户没有邮箱,会生成一个占位邮箱以便账户仍能创建。不总是 Jira 值的 1:1 复制——见下文邮箱/用户名冲突处理
Jira group membership(Jira 组成员关系) OpenProject 组成员关系 按名称匹配或创建。注意:会拉取用户在 Jira 中的全部组列表,而不仅是与迁移项目相关的组
Username(用户名) Username(用户名) 也不总是 1:1 复制——见下文邮箱/用户名冲突处理
Password(密码) 随机生成 Jira 密码无法迁移,因此每个新用户之后都需要重置密码或发送邀请(规划中:JIM-116)

自定义字段

自定义字段的迁移规则自成体系,包括字段类型映射、支持/不支持的字段类型及各种边界情况,完整内容请参阅 自定义字段迁移文档。其要点包括:迁移器会自动检测导入 issue 中实际使用的自定义字段并创建对应的 OpenProject 自定义字段;所有新建的自定义字段被放置在工作包表单配置的 "Jira import" 分组中,默认不分配到任何现有项目。

值得注意的行为细节

以下行为直接决定迁移结果是否符合预期,建议在迁移前逐条对照:

  • 状态/类型/优先级匹配忽略大小写,但不忽略拼写。 "To Do" 与 "TO DO" 会正确匹配到同一状态;但 "To-Do" 与 "To Do"、或 "Doing" 与 "In Progress" 会各自创建独立的状态/类型/优先级。若希望它们合并,请在迁移前统一各 Jira 项目间的命名。
  • 变更历史是分组而非 1:1 复制。 同一人在同一分钟内对同一字段的多次编辑会合并为一条 activity 条目(除非其中两条都触及描述)——因此 OpenProject 的 activity 标签页会比 Jira 原始历史更"粗粒度",且并非总以 OpenProject 的常规格式呈现字段变更详情。此外还有一个比分组更严重的已确认 bug:紧随 Jira "带评论的状态转换"之后的评论时间戳可能损坏,显示为迁移日期而非真实日期。跟踪于 JIM-152。
  • 内联图片仍指向原 Jira 服务器。 嵌入在描述/评论中的图片不会被重新托管到 OpenProject——一旦 Jira 实例退役,这些图片就会失效,除非手动重新上传。跟踪于 JIM-53。
  • 导入器没有 LDAP 概念。 每个新用户都被创建为普通的本地账户并配以随机密码——即使你的 OpenProject 使用 LDAP 登录,也不会关联到任何 LDAP 源。如果 Jira 用户名与真实 LDAP 登录名匹配,该用户真实的 LDAP 密码在迁移后将失效,因为新建的本地账户会"抢占"该登录名。每个受影响账户都需要手动修复——见 迁移前检查清单 与 迁移后检查清单。
  • 附件是"一切失败都大声报错"的唯一例外。 在其他任何环节,导入过程中的问题都会抛出错误并中止整个运行。附件则不同:下载失败或上传被拒会被静默记录并跳过,导入继续执行并可能"成功完成"但缺失部分附件。审查/批准界面不会显示任何摘要或警告——如何检查见 迁移后检查清单。迁移后检查清单还给出了日志中的具体特征:服务器日志中会出现 Attachment creation failed for <filename> 或 Download attachment failed for <filename> 字样,需要在批准前检索这些日志并核对对应工作包。
  • 重复运行导入对用户是安全的——重试时已导入的用户不会被重复创建。用户账户本身不会重建,但组成员关系每次都会重新同步。
  • 邮箱/用户名冲突是解决而非拒绝。 如果 Jira 用户的邮箱已存在于 OpenProject,导入器不会直接失败:若现有账户在同一次导入运行中尚未关联到其他 Jira 用户,则复用该账户;否则通过在邮箱后追加 Jira 用户 key 来消歧(如 email+JIRAKEY@domain.com),使两个账户共存。如果 Jira 用户名已存在于 OpenProject,则在用户名后追加 Jira 用户 key 消歧(如 name+JIRAKEY)。
  • 批准时的用户激活是有条件的,而非自动的。 每个导入的用户都以 locked 状态创建,无论其在 Jira 中的状态如何。批准导入只会解锁同时满足以下条件的用户:(a) 由本次运行新建(而非复用了现有 OpenProject 账户),且 (b) 在 Jira 中标记为 active。复用/匹配的账户保持原状。
  • @提及通过实时 API 查询解析,而非仅依赖已知用户。 对描述或评论中出现的每个不同的 [~username] 提及,导入器都会直接调用 Jira 的用户端点——即使该用户在其他任何地方都未被引用(例如从未担任经办人、作者或关注者)。若解析成功并完成导入,提及会渲染为真正的 OpenProject <mention> 标签(可点击、触发通知);若无法解析,则回退为纯文本 @username。
  • 姓名拆分是朴素的。 firstname/lastname 通过在 Jira displayName 的最后一个空白字符处拆分得到——并非真正的姓名解析逻辑。单词型显示名会被复制到两个字段。OpenProject 名称中不允许的字符会在拆分前被剔除。
  • 工作包序列计数器在导入后按项目回填,设置为导入工作包中找到的最高序列号——纯粹是为了保证迁移后新建的工作包不会与已导入的标识符冲突。

源码视角:映射背后的实现佐证

字段映射参考文档描述的行为可以在仓库源码中得到印证,以下路径可供深入研读:

  • Wiki 标记转换管线:描述、评论等文本的 Jira 标记 → Markdown 转换由 app/services/import/jira_wiki_markup_converter.rb 驱动,其核心逻辑是 JiraWikiMarkup::Parser 解析 AST 后再由 JiraWikiMarkup::Renderer 渲染(见 app/services/import/jira_wiki_markup/ 下的 parser.rb、nodes.rb、renderer.rb)。这解释了文档中"标题、粗体/斜体、链接、代码/引用块、表格会转换,而部分 {macro} 不被识别"的现象——转换器只实现了已识别的节点类型。
  • 变更历史与评论时间戳:活动条目的写入与时间戳处理位于 app/services/import/jira_import_journals.rb,其中 update_creation_entry 等方法直接操作工作包 journals 的 created_at、updated_at 与 validity_period,与文档描述的"变更历史分组、时间戳可能显示迁移日期"(JIM-152)的行为边界直接相关。
  • 配置与连接模型:导入配置的持久化模型为 app/models/import/jira.rb,它校验 URL 必须为 http/https,并通过 Import::JiraClient(app/services/import/jira_client.rb)建立与 Jira 的 API 连接;围绕导入运行还衍生出 app/models/import/jira_import.rb、jira_import_state_machine.rb 以及导入各实体(项目、issue、状态、类型、优先级、用户等,见 app/models/import/ 目录)等模型,共同构成"审查 → 批准/回滚"状态机的基础。
  • 导入服务层:app/services/import/jiras/ 下的 create_service.rb、set_attributes_service.rb、update_service.rb 负责导入配置的创建与更新,与文档"只有名称跨迁移、自动创建缺失的类型/状态/优先级"等按名匹配策略共同构成导入主流程。

迁移前与迁移后的闭环建议

字段映射参考中反复出现两个配套文档,构成完整的迁移闭环:

  • 迁移前检查清单:重点解决"哪些数据会丢失、是否可接受",包括统一 Jira 各项目间的 Status / Type / Priority 命名(避免因拼写差异产生重复实体)、导出不会被迁移的数据(如日志工时、关注者、史诗链接、Story Points、子任务关系)等。
  • 迁移后检查清单:覆盖批准前的抽样核对与附件日志检索、批准后的密码重置/LDAP 冲突修复、手动重建工作流/权限/看板/关联关系,以及"将迁移的状态手动标记为 closed、重排优先级、按项目设置默认类型"等清理动作。

由于导入器当前仍处于 beta 阶段且仅覆盖基础数据(项目、标识符、issue、基础自定义字段、用户、状态、类型),官方建议:先备份 OpenProject 实例、在测试环境用小数据子集验证映射与附件、确认无误后再执行完整迁移,并在批准前完成全部核对——因为一旦批准,回滚将不再可能(详见 Jira 迁移总览)。

登录后查看全文
openproject