OpenProject Jira 迁移后核对清单从批准导入到清理验证的完整实操指南【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openprojectJira Data Center 迁移到 OpenProject 的导入只是开始——真正决定迁移质量的是导入之后的核对与手工收尾工作。本文以 OpenProject 官方 Jira 迁移后核对清单 为主体结合仓库中 Jira Migrator 的源码实现附件下载、导入状态机、字段映射等完整展开导入后立即处理 → 手工重建内容 → 清理与验证三大阶段的每一项任务并给出对应的操作路径、排查方法与源码依据。读完本文你将能在分批迁移、LDAP 登录冲突、附件静默失败、重复类型合并、残留 Jira 标记清理等场景下独立完成一次可靠、可验证的迁移收尾。背景为什么需要迁移后清单OpenProject 的 Jira Migrator 目前仍处于 beta 阶段详见 Jira 迁移总览它只能导入基础数据项目、问题Issue、基础自定义字段、用户、状态Status与类型Type。而工作流、权限、敏捷看板、问题关联、Sprint 分配、实际工时、关注者等大量内容不在导入范围内。更关键的是导入工具本身存在若干静默行为——例如附件下载失败不会中断导入只会留下一行服务器日志。因此官方将迁移过程设计为review 模式导入完成后数据先进入可检查、可回滚的暂存状态一旦点击Approve批准数据即被固化回滚选项永久失效。这也正是迁移后核对清单存在的根本原因一切必须在批准之前完成核对一切无法自动迁移的内容必须在批准之后手工重建。如果你的迁移是分批进行的请特别注意清单中导入后立即要做的部分每批次都要重复执行它不是一次性事件——每个新批次都可能带来新用户、新的附件失败与新的登录冲突。导入后立即要做的事1. 在 review 模式下抽查导入数据批准前请务必停留在 review 模式对已导入的工作包Work Package、附件和自定义字段做抽样检查。官方清单强调一旦批准无法撤销。建议抽样关注的点工作包的 Subject、描述与评论的格式转换是否正确Jira wiki markup 会被自动转换为 OpenProject 的 Markdown自定义字段的值是否完整落位尤其是选择类List与层级类Hierarchy字段附件数量是否与 Jira 侧一致数量不一致通常意味着发生了静默失败见下一节。在批准导入前逐项抽查导入的工作包、附件与自定义字段。2. 专门核对附件迁移错误静默失败最易遗漏这是整个清单中最容易踩坑的一项。与其他所有数据不同附件的迁移失败不会中断导入也不会在 review 界面出现任何提示——无论是因为 Jira 侧下载失败broken download还是 OpenProject 侧上传被拒rejected upload导入都会继续最终成功完成但部分附件已经丢失。唯一的排查线索是服务器日志中的两行关键字Attachment creation failed for filename Download attachment failed for filename在批准之前请搜索这两行日志逐条定位它们涉及的 Jira issue确认缺失的附件是什么、是否重要。从源码可以印证附件迁移的实现路径jira_create_project_work_package_attachments_job.rb 按 issue 逐个读取其fields.attachment调用 jira_client.rb 中的download_attachment方法通过OpenProject::SsrfProtection.get从 Jira 拉取文件内容再经由Attachments::CreateService上传到工作包。下载环节的异常SSRF 拦截、SSL 错误、超时、非 2xx 响应都会被转换为对应的SsrfError/ConnectionError/ApiError。因此凡是 Jira 侧文件不可达、超时、或超过 OpenProject 单文件大小限制的情况都可能产生上述日志行。也正因如此官方在迁移前清单中要求你提前核对 OpenProject 的最大附件大小设置Administration → Files → Attachments避免大批量导入后才发现附件集体缺失。3. 批准或回滚Approve / Revert抽样核对满意后选择Approve或Revert操作效果注意事项Approve批准激活新创建的用户将导入数据固化为正式数据永久禁用回滚选项弹出确认警告批准后任何数据问题只能手工修复Revert回滚删除本次导入运行import run创建的全部数据不影响之前批次导入的数据同样有确认警告每个导入批次在 review 模式下都必须做出批准或回滚的决定。注意review 模式下新创建的用户始终保持锁定locked状态只有批准导入后才会被激活——而且只激活本次运行新建 在 Jira 中处于 active 状态的用户。这一行为与字段映射参考中Active flag → Account status的映射一致在仓库的状态机模型 jira_import_state_machine.rb 与回滚任务 jira_revert_import_job.rb 中均有对应实现。4. 重置密码 / 发送邀请所有新建用户Jira 的密码无法迁移。每个新创建的用户在 OpenProject 中只会得到一个随机生成的密码因此批准后必须逐一重置密码或通过 OpenProject 发送邀请邮件通知用户使用新凭据登录。官方已提出在批准时自动化的功能请求JIM-116但在该功能落地前这一步只能手工完成。这也意味着在批准导入时应把激活用户与通知用户作为一个连续动作来计划。5. 检查并修复 LDAP 登录冲突如果你的组织通过LDAP登录 OpenProject这是必做项。由于导入工具本身没有 LDAP 概念字段映射参考明确说明每个新用户都以普通本地账户 随机密码创建从不关联 LDAP 源一旦某个 Jira 用户名与 LDAP 目录中的真实登录名重合该用户真实的 LDAP 密码在迁移后就会失效——因为新建的本地账户抢先占用了这个登录名。修复方式没有批量化手段必须逐账户手工处理将导入的登录名与你的 LDAP 目录逐一比对对每一个匹配到的账户编辑该用户并手动指定正确的 LDAP 认证源每批次迁移后都要重复此检查因为每个新批次都可能引入新用户。这一问题的根源在迁移前清单中已提前预警如果你的团队通过 LDAP 登录应在迁移前确认 Jira 用户名与 LDAP 登录名是否一致并在迁移前同步 Jira 的外部用户目录LDAP/AD否则过期数据会被直接带入。需要手工重建的内容以下内容对应你在迁移前确认哪些内容不迁移评审中决定保留而非接受丢失的部分。每项都需要在批准导入后手工重建或另行迁移。工作流WorkflowsJira 的哪些角色允许哪些状态流转不会迁移。导入只会自动创建一个基础的、宽松的permissive工作流设置。你需要到Administration → Work packages → Workflows手工重建所需的状态流转。官方已规划自动迁移支持JIM-153当前 OpenProject 的工作流是按 Type 全局定义的——如果不同的 Jira 项目对同一 issue type 使用了不同的工作流方案这种差异目前也无法保留。权限方案与角色Permissions / Roles除导入自动创建的一个基础角色外Jira 的权限方案与角色体系不会迁移。请到Administration → Roles and permissions按需创建角色并分配权限规划中的功能JIM-97。结合仓库实现导入任务 jira_create_project_role_job.rb 会查找名为JiraMember的角色见 jira_create_project_work_package_attachments_job.rb 中Role.find_by!(name: JiraMember)的用法——这印证了导入期只会建立最基础的成员角色完整的权限矩阵必须由管理员在迁移后配置。敏捷看板Agile boardsScrum/Kanban 看板设置、过滤器、泳道swimlanes均不会迁移。需要利用 OpenProject 的 Backlogs 或 Agile boards 模块手工重建规划中JIM-106。问题关联与子任务/父子层级Issue linksblocks、relates to、duplicates 等不迁移规划中JIM-76子任务与父子层级不迁移规划中JIM-75。重建方式二选一通过工作包的关系面板手工重建如果你在迁移前已导出结构可编写脚本调用 OpenProject API 批量重建。Sprint 分配、Epic 链接、Story Points这三类内容都不会迁移详见迁移前清单中的Not migrated列表Epic Link / Epic Name、Sprint field、Story Points 均在其中。请基于迁移前导出的数据手工恢复。工时记录Logged time entriesJira 的实际工时记录worklog不会迁移——只有原始估算Original time estimate和剩余估算Remaining time estimate两个字段会映射到 OpenProject 的估算工时 / 剩余工时规划中JIM-93。恢复方式通过 OpenProject 的工时跟踪Time tracking重新录入或使用迁移前导出的 worklog 数据通过 API 批量导入。关注者Watchers工作包级别的关注者不会迁移规划中JIM-180。请根据迁移前导出的关注者列表在批准后手工逐个重新添加。Confluence 内容与Confluence相关的任何内容都完全不在该工具的范围内。如果需要请为 Confluence 数据单独规划迁移方案不要指望 Jira Migrator 处理。清理与验证1. 重新整理自定义字段迁移后的自定义字段默认落入一个通用分组generic group且默认不附加到大多数项目上。需要到 Administration → 自定义字段 中重新规划分组、并将字段挂接到对应项目。2. 合并重复的 Type / Status / Priority如果你在迁移前没有统一 Jira 中的 Type、Status、Priority 命名那么拼写真实不同非仅大小写差异的名称会各自生成独立的 OpenProject 记录。以 字段映射参考 中的规则为例匹配/唯一性判定忽略大小写但不忽略拼写——To Do与TO DO会正确合并但To-Do与To Do、Doing与In Progress会被视为两个不同记录。针对每种情况清理步骤为Type将受影响的工件重新指派到正确类型然后删除不再使用的重复类型Status更新受影响的工作包为正确状态然后删除不再使用的重复状态Priority对每个不需要的值先删除它并选择要将受影响工作包重新指派到的优先级值再删除不再使用的重复优先级。最佳实践在下次迁移前先在 Jira 侧修正命名避免再次手工重做一遍。此问题可通过 迁移前清单 中的统一 Type/Status/Priority 命名步骤预防。3. 将迁移来的状态标记为已关闭没有任何迁移状态会被自动标记为 closed——即使该状态在 Jira 中代表已完成如 Done、Closed、Resolved。如果跳过这一步所有依赖开放 vs. 已完成的过滤与报表都会出错。请到Administration → Work packages → Status为对应状态手工勾选已关闭标记。这与字段映射参考中 Status 的映射说明完全一致migrated status is never automatically marked as closed。4. 调整优先级顺序、设置项目默认类型优先级迁移只带名称不保留 Jira 的严重程度顺序、颜色与图标。由于 OpenProject 在 issue 未设置优先级时会回退到列表中排第一的优先级务必按你的实际严重程度重新排序Administration → 枚举值 → 优先级默认类型迁移来的类型不会被标记为项目默认类型即使它在 Jira 中就是默认。请按需在项目中手工设置默认类型。这两项如果已在迁移前清单中记录为待修复项则此步骤可直接对照执行。5. 修复估算 / 剩余工时已知 bug值需除以 60受已知 bugJIM-185影响迁移后的估算工时与剩余工时数值存在偏差需要将受影响的值除以 60。修复方式手工逐个修正或通过批量更新 / 脚本统一除以 60。6. 查找并修复内嵌图片描述和评论中的内嵌图片仍指向原始 Jira 服务器——它们没有被重新托管到 OpenProject相关跟踪JIM-53。一旦 Jira 被下线这些图片将全部失效。请在 Jira 下线前完成下载这些图片重新上传并替换工作包描述/评论中的引用。7. 抽查活动历史合并粒度与时间戳 bug合并粒度接近同时发生的多次编辑会被合并为较少的活动条目除非其中两条都修改了描述因此 OpenProject 的活动标签页看起来会比 Jira 原始历史更粗时间戳 bug已确认在带评论的状态流转之后产生的评论时间戳有时会显示迁移日期而非原始日期JIM-152。建议挑选几个被频繁编辑的 issue将 OpenProject 的活动历史与 Jira 原始视图逐条对照确认哪些信息在合并/时间戳修正中丢失是否需要额外说明。8. 清理未转换的 Jira 标记文本以下 Jira 宏/标记不会被转换其原始标签文本会以纯文本形式残留在描述与评论中内容本身完整只是标签丑陋且不可点击提示框宏{info}/{warning}/{note}/{tip}{toc}布局宏{expand}/{section}/{column}裸 issue-key 链接[PROJECT-123]附件链接[^file.pdf]处理方式手工查找并删除残留的宏标签文本将[PROJECT-123]、[^file.pdf]之类的引用改写成可正常点击的链接。这一行为在字段映射参考的 Description 映射说明中也有明确记载从源码看格式转换由 jira_wiki_markup_converter.rb 负责未识别的宏按保留内容、遗留标签文本处理。若在迁移前将这类内容改写为纯文本/标题或完整 URL则可以避免此轮清理见迁移前清单。9. 更新外部集成、Webhook 与工具迁移前清单要求你列出所有直接引用 Jira 数字 ID的外部集成自定义脚本、报表工具等——因为这些数字 ID 不会随迁移保留而 Jira issue key如PROJECT-123则通过 OpenProject 的语义别名机制继续可用。批准导入后按清单逐项重新配置这些集成依赖 Jira 数字 ID 的脚本/报表 → 改造成依赖 issue key 或 OpenProject 内部 IDWebhook 端点 → 更新为新系统的回调配置其他工具 → 验证其数据源与认证方式是否仍有效。分批迁移时的执行要点如果采用分批迁移batch除导入后立即要做的步骤逐批重复外还需注意自定义字段的合并仅在同一批次内生效拥有相同选项的 Jira 自定义字段只有在同一批次导入时才会合并为同一个 OpenProject 字段跨批次即使选项完全相同也会各自生成独立字段详见迁移前清单的 Batching 部分。因此合并 Type/Status/Priority 的清理工作在每批结束后都要评估用户与用户组可以跨批次拆分后一批次会识别已存在的账户按 email 或 login 匹配并复用不会重复创建LDAP 登录冲突与密码重置每批新增用户都要重复执行切勿只在首批执行一次可以将批次用于管理 Enterprise 席位限额每个批次批准时只激活该批新建的用户从而分阶段激活避免一次性触顶席位上限。总结Jira → OpenProject 迁移的最后一公里由三件事组成批准前的核对抽查数据、排查附件静默失败、处理 LDAP 冲突、批准后的重建工作流、权限、看板、关联、工时、关注者、以及持续的清理验证合并重复枚举、标记关闭状态、修复估算值、清理残留标记、修复内嵌图片。其中附件静默失败与 LDAP 登录冲突是官方文档特别标注的两类看不见的坑务必借助服务器日志与逐账户比对来完成排查。所有无法迁移的内容都能在 字段映射参考 中找到权威说明迁移前的准备工作见 迁移前清单。只要把本文清单中的每一项在对应批次节点上落实就能最大程度降低迁移上线后才发现的数据缺口与返工成本。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
