jira迁移中附件大小限制的乌龙

jira迁移中附件大小限制的乌龙

去年十月，我亲手把一个运行了五年的 Jira Server 实例迁到 Cloud 版。迁移脚本跑了整整 14 个小时，进度条走到 99% 的时候，日志里弹出一行报错：附件上传失败，超出大小限制。那一刻我脑子里只有一个念头，不是“怎么修”，而是“这 14 个小时的数据会不会全白跑了？”

后来复盘整个事件，我发现真正的问题根本不在那行报错本身，而在于：所有人在迁移前都低估了附件大小限制引发连锁反应的能力。它不是技术障碍，是一个典型的“组织认知盲区”。技术文档会告诉你 Cloud 版单个附件限制是 10MB，但它不会告诉你，一个超限的附件能让已经迁移成功的几千条工单陷入“半迁移”状态；它更不会告诉你，附件引用链断裂之后，业务部门需要手工补数据的代价可能比迁移本身还大。

我写这篇文章，是想把那次乌龙里的完整决策链条、排查过程、以及后来我们团队在多个迁移项目里总结出来的一套判断逻辑讲清楚。如果你正在做 Jira 迁移，或者被分配了这个任务的评估工作，下面这些内容应该能帮你少踩一个我们踩过的坑。

一、核心结论：附件大小限制不是技术问题，是“信息不对称”问题

在展开讲细节之前，我想先把最核心的判断摆到台面上。

很多人第一次看到 Jira Cloud 的 10MB 附件限制，反应几乎一样：“那我把大的附件压缩一下不就完了？”这个反应本身就是问题，它把一个信息不对称问题错当成了文件处理问题。

我来说清楚什么叫信息不对称。在这个场景下，它指的是三件事：

• 第一，运维团队不知道业务附件里藏了多少“历史地雷”。 一个五年前的工单里拖着一个 80MB 的设计源文件，当年上传的人早就离职了，现在根本没人知道它存不存在。运维团队在迁移计划表里只看到了“附件总量 23GB”，看不到这个 80MB 的孤立文件会成为迁移脚本的终止信号。
• 第二，迁移工具不会主动告诉你哪些附件会失败。 Jira 官方迁移助手的逻辑是：先迁移工单元数据，再迁移附件。元数据成功、附件失败的时候，它不会回滚元数据，也不会生成一份“问题附件清单”。你只能在日志里一行一行翻。
• 第三，业务部门不知道迁移失败后的“补偿成本”有多大。 他们以为迁移是 IT 的事，失败了 IT 会搞定。但实际上，附件迁移失败后，需要业务人员逐条确认哪些附件丢了、哪些需要补传、哪些可以丢弃。这个沟通成本动辄几十个人天。

所以我的核心结论很简单：Jira 迁移中附件大小限制这件事，真正的风险不在“限制”本身，而在于迁移前后，技术团队和业务团队之间关于“哪些附件必须活下来”的信息从来没有对齐过。谁先把这件事对齐，谁就掌握了迁移的主动权。

这个结论不是事后总结，而是后面一切判断的前提。下面我会用真实场景把这个结论展开。

二、背景与真实场景：一次迁移，两种失败

1. 场景还原：什么样的团队最容易踩坑

我们当时的情况在国产研发团队里相当典型：一个 150 人左右的产品研发组织，从 2018 年开始使用 Jira Server 版管理项目和缺陷。五年下来，项目数量 47 个，工单总量超过 18 万条，附件总大小约 31GB。

迁移的触发原因也很有代表性：Atlassian 在 2020 年宣布停止销售新的 Server 许可证，2024 年 2 月正式终止对 Server 版的支持。我们必须在支持终止之前完成迁移，否则安全补丁就会断档。

当时摆在我们面前的路有三条：迁 Cloud、迁 Data Center、或者干脆换掉 Jira。团队最终选择了 Cloud 版，理由是维护成本低、不需要自己管服务器。但这个选择本身，就注定了附件大小限制会成为一个必答题，因为 Server 版管理员可以自定义附件上限（最高可设到 2GB），而 Cloud 版对所有租户一视同仁：单个附件 10MB。

这个差异，在迁移前的评估报告里只占了一行字。当时我们都没觉得它会成为问题，因为“10MB 够用了”“超过 10MB 的附件应该不多吧”。这两个判断后来都被证明是错的。

2. 那 14 个小时到底发生了什么

迁移流程本身并不复杂，我们用的是 Atlassian 官方提供的 Jira Cloud Migration Assistant 插件。计划分三步：先在 Server 端做一次预检扫描，然后导出数据包，最后导入 Cloud 实例。

预检扫描的结果显示“可以迁移”，没有报任何阻断性错误。这个结果给了所有人一种虚假的安全感。

实际导入阶段，问题出在第三步。迁移助手的运行逻辑是这样的：

1. 先在 Cloud 端创建项目、用户、工单类型等元数据结构。
2. 再逐条导入工单的标题、描述、评论、状态、自定义字段值。
3. 最后根据工单 ID 关联附件，逐个上传。

问题就出在阶段 3 的执行策略上。迁移助手遇到一个超限附件时，不会跳过它继续处理下一个，而是会中断整个附件导入任务。更致命的是，它已经导入的工单数据不会回滚，也就是说，几千条工单的标题和评论已经写进 Cloud 了，但它们的附件全部卡住，包括那些大小合规的附件。

这就造成了一个非常棘手的“半迁移”状态：

• 业务团队打开 Cloud 看板，能看到工单，能看到讨论记录，但所有附件链接都是 404。
• 运维团队不敢重新跑迁移，因为不确定会不会产生重复数据。
• 更麻烦的是，有些工单的审批流依赖附件内容（比如设计稿确认、合同签批），附件缺失导致这些工单在业务意义上“不可用”。

这个状态持续了将近两天。期间我们的客服 Leader 在群里问了一句：“客户投诉的工单里，合同附件去哪了？”那是整个迁移过程中压力最大的时刻。

三、拆解常见误区：为什么“常识”在附件迁移里是错的

1. 误区一：“我们先把大附件压缩一下就好了”

这是我听过最多的一个反应。思路本身没问题，但它隐含了一个假设：你能够完整、准确地定位所有超限附件。

实际执行时会遇到三个障碍：

（1）Jira 原生管理后台不支持按附件大小筛选。 你可以在“附件”页面看到单个工单的附件列表，但没法跨项目查询“所有超过 10MB 的附件”。没有这个全局视图，压缩就只能是零散的、被动的。

（2）压缩不是万能的。 一个 80MB 的 PSD 设计源文件，压成 ZIP 大约能降到 60-70MB，仍然远超 10MB 限制。真正要让它在 Cloud 里可用，要么拆分成多个文件，要么迁移到外部存储。但拆分文件会破坏设计协作流程，设计师本来打开一个工单就能看到完整源文件，现在要下载三个分包再合并。

（3）压缩改变文件签名，可能触发审批流或合规要求。 有些合同附件、审计相关的 PDF，压缩后 MD5 值变了，在合规审计场景下可能不被接受。这个风险大多数技术团队在迁移前根本没有意识到。

所以“压缩”不是一个独立解决方案，它最多是方案的一部分。真正有效的做法是：迁移前先拿到完整附件清单和大小分布，然后逐文件判定处理策略。这个判定本身需要业务部门参与，IT 不能代劳。

2. 误区二：“超过 10MB 的附件肯定没几个，手动处理就行”

这个误区的根源，是低估了 Jira 在五年甚至更长时间里积累“附件膨胀”的速度。

我们在那次迁移之后，回查了 Server 端的附件数据库表，拿到了一组让我很意外的数据：

看清楚这组数据：超过 10MB 的附件数量只占 7.2%，但它们吃掉了 77% 的存储空间。而且绝对数量并不是“没几个”，将近 900 个超限附件，分布在 47 个项目、上千条工单里。手动逐个处理完全不可行。

更麻烦的是，这 900 个文件里大概有 30% 是 PDF 合同和签批单，15% 是设计源文件，还有一堆日志包、数据库备份，有些文件甚至和业务完全无关，是开发人员随手拖进工单的“临时中转”。

这组数据后来成了我们验证迁移方案是否可行的核心依据。每次有团队来咨询，我的第一个问题都是：“你知不知道自己的 Server 端有多少个 10MB 以上的附件，它们分别是什么类型？”能马上回答出来的团队，几乎没有。

3. 误区三：“迁移工具应该帮我们跳过超限附件”

坦率地说，Atlassian 官方的迁移助手在设计上确实存在改进空间。但把自己的迁移失败完全归咎于工具，会掩盖一个更根本的问题：迁移策略的选择权从来都在你自己手里，而不在工具那里。

市场上其实存在多种迁移路径：

• 全量迁移（官方助手）： 适合附件环境干净、超限附件已经清理完毕的场景。
• 按项目分批迁移： 先迁移附件合规的轻量项目，验证流程；再集中力量攻坚重附件项目。
• 工单元数据迁移 + 附件外挂： 只迁移工单结构和正文，附件整体迁移到 MinIO、阿里云 OSS 等对象存储，然后在工单里替换为外链。这个方案适合附件体量极大、且不要求在 Jira 内直接预览的场景。
• 使用第三方迁移工具： 有些商业化工具（比如 PingCode 提供的 Jira Importer）支持附件映射、自动跳过超限文件并生成排除报告，可以代替官方助手执行更精细的迁移策略。

工具一定有局限，但局限不应该变成借口。关键是迁移负责人在动手之前，有没有评估过不同路径在附件处理上的能力边界，有没有根据自己团队的附件特征选对工具。

四、专业判断逻辑：迁移前应该问的三组问题

1. 第一组：附件体量摸底，你真的了解自己的数据吗

在做任何迁移决策之前，必须先拿到两组数据：

（1）附件总体规模与超限数量。 可以直接查询 Jira 数据库的 fileattachment 表，按 filesize 字段降序排列。SQL 并不复杂，关键是要拿到“超过目标环境限制（Cloud 按 10MB，Data Center 按自定义值）的文件清单”。

（2）超限附件关联的工单分布。 这比第一个查询更重要。一个项目里有 50 个超限附件，和 50 个项目各有一个超限附件，处理难度完全不同。前者可以集中攻坚，后者需要跨项目协调。

如果一个团队在迁移前连这两组数据都拿不出来，我建议把迁移暂停，先把摸底做完。没有任何迁移方案可以在数据黑箱里做出正确决策。

2. 第二组：附件价值分类，哪些必须活着，哪些可以死

拿到附件清单之后，第二步不是处理文件，而是分类。这个环节最容易被跳过，但它的重要性甚至超过技术执行。

我们当时建立了一个四象限分类法，后来在几个迁移项目里反复验证有效：

这个分类工作不能让 IT 团队单独完成。 A 类和 B 类的判定需要业务负责人介入，因为他们才知道哪些文件“丢了会出事”。我们当时的做法是：IT 产出超限附件清单，按所属项目分发给各项目负责人，由他们在 48 小时内完成 ABCD 标注。逾期未标注的默认归为 D 类，并在邮件里明确告知后果。

这 48 小时是整个迁移准备里产出最高的时间窗口，它迫使业务团队正视一个他们从没想过的问题：“这个附件，到底有多重要？”

3. 第三组：工具与路径匹配，你能不能控制迁移的粒度

前两组问题解决的是“数据层面”的判断，第三组问题解决的是“执行层面”的选择。

我建议在选择迁移工具时，按照以下优先级来评估：

1. 它能不能在迁移前生成完整的附件审计报告？ 包括每个项目下的附件总数、总大小、超限文件清单、以及超限文件关联的具体工单 ID。没有这个能力，后续所有分类和决策都缺乏依据。
2. 它能不能支持断点续传或选择性迁移？ 如果你的迁移要跑十几个小时，中途因为一个超限附件中断而需要从头再来，这个代价太高了。理想的工具应该允许你跳过故障附件，记录跳过清单，然后继续处理剩余文件。
3. 它能不能在迁移后生成差异报告？ 告诉你有多少附件成功迁移、多少被跳过、多少迁移失败但可重试。这份报告是迁移验收的核心依据。

以 PingCode 的 Jira Importer 为例，我在一个客户项目中实际测试过它的迁移能力。它的逻辑和官方助手有一个关键差异：导入时不因单一附件超限而中止整个任务，而是将超限附件标记为“跳过”，继续处理后续合规文件。迁移完成后自动生成一份 CSV 格式的排除清单，列出所有被跳过的附件及其关联工单。这份清单可以直接发给业务团队做补传决策。

这个设计把一个“阻断性故障”变成了“可管理的待办事项”，这才是迁移工具应该提供的控制粒度。

五、具体案例与数据观察：从“乌龙”到“可控”的路径

1. 案例一：如何处理 D 类附件大规模清理的阻力

在上述四象限分类里，D 类（可丢弃）文件通常占了超限附件总数的 25%-40%。理论上直接删除就行，但实际操作中你会遇到一种情况：没人敢签字确认这些文件真的可以删。

我们当时遇到过一个典型场景：运维扫描出一个 320MB 的 tar.gz 文件，附着在一个已关闭三年的缺陷工单下面。文件内容是某次生产事故的完整日志备份。运维觉得可以删，项目经理觉得“万一以后要追溯呢”。僵持了三天。

最后破局的方法不是技术性的，而是流程性的。我们定了三条规则：

1. D 类文件不直接删除，而是先打包迁移到低成本存储。 找一台 NAS 或者云上的低频存储桶，把所有 D 类附件整体迁出，保留六个月。六个月后如果无人提出需要，自动清理。这样既释放了 Jira 的迁移压力，又给了业务团队一个“反悔窗口”。
2. 原工单的附件链接替换为外部存储链接。 这样即使以后真有人要追溯，也能找到文件，不会出现“工单说参考附件但附件已消失”的尴尬。
3. 超过六个月未访问的 D 类文件，归档前自动通知工单的原始报告人。 如果报告人已离职，通知当前的项目负责人。

这三条规则推下去之后，那个僵持了三天的 320MB 日志文件在四十八小时内就走完了“迁出-换链-确认”流程。因为规则给了所有人安全感：数据不会真的消失，只是换了个地方存。

2. 案例二：PingCode 在一个 300 人企业中的迁移实践

2024 年年初，我参与了一个客户项目的迁移评估。这个客户是一家金融科技公司，研发团队约 320 人，从 2017 年开始使用 Jira Server。他们的附件体量相当惊人：总大小 87GB，超过 10MB 的文件多达 3400 个，最大的一个附件是一个 1.8GB 的虚拟机镜像，某位 QA 工程师三年前在工单里上传的。

这个体量下，官方迁移助手已经完全不适用。团队评估了三条路：迁 Data Center、继续留在 Server（接受无官方支持）、或者换成 PingCode。

最终决策的关键变量有三项：

• 合规需求： 金融客户要求数据必须部署在境内服务器，且需要信创适配。Jira Cloud 的标准实例部署在海外，不能满足监管要求。
• 附件迁移能力： PingCode 的迁移工具支持附件自动映射，超限文件不阻断整体流程，并在迁移完成后输出差异报告。这个特性直接解决了他们最担心的“半迁移”风险。
• 总拥有成本： Jira Data Center 的年订阅费加上自建高可用集群的运维成本，三年 TCO 测算下来比 PingCode 高出约 40%。而继续留在不受支持的 Server 版本上，安全风险成本无法量化但被合规部门明确否决。

迁移过程历时六周，分为三个阶段：

第一阶段（摸底与清理）： 用两周时间跑完附件四年象限分类，识别出 D 类文件约 1200 个（35%），直接归档到对象存储。A 类和 B 类文件判定由各部门负责人签字确认。

第二阶段（分项目迁移）： 按项目优先级分三批迁移，每批之间间隔三天用于验证。第一批 5 个核心项目迁移耗时 8 小时，附件成功率达到 94%。失败的 6% 主要是 C 类文件超限，转入第三阶段处理。

第三阶段（补传与替换）： C 类超限附件移至外部存储，在工单内替换为外链。A 类中无法压缩的合同文件，通过 PingCode 的知识管理模块建立独立文档页，在工单中引用文档链接而非直接挂附件。

最终这个项目在预定时间内完成，迁移后的第一个月内未收到一例附件丢失的投诉。这个结果的关键，不是工具多强，而是迁移策略严格遵循了“先分类、再清理、分批迁、后补传”的四步法。

3. 数据观察：附件大小限制的“长尾效应”

在做完几个迁移项目后，我注意到了一个规律：附件大小问题并不是在所有时间点上都同等紧急。它在迁移前三个月开始被感知，在迁移执行窗口内达到峰值，然后在迁移结束后仍然有持续数周的长尾。

这种长尾效应表现在三个层面：

• 补传长尾： 即使迁移工具生成的差异报告很清楚，业务团队也需要时间来确认、替换和补传。平均而言，迁移后完全关闭所有附件遗留问题需要 2-3 周。如果迁移在月底或季末执行，这个窗口会和业务繁忙期重叠，导致延迟进一步拉长。
• 引用断裂长尾： 有些工单的评论里直接提到了附件文件名或内嵌了附件链接。迁移后链接变化，评论的可读性受损。这个问题在迁移前几乎不可能全部发现，只能在迁移后由使用者在实际工作中遇到一例修一例。
• 心理长尾： 迁移后很长一段时间里，业务团队会对新系统的附件功能保持“不信任”状态，他们会倾向于用邮件或网盘传文件来“双重备份”。这个行为本身会导致信息散落，削弱迁移的效果。

认识到长尾效应的存在，就能在迁移计划里预留出足够的缓冲期。我的建议是：正式迁移结束后，至少保留四周的“附件问题集中处理期”，指定专人负责响应和关闭附件相关工单，直到工单量降到每周 5 个以下再关闭这个阶段。

六、不同情况下的行动建议

1. 情况 A：你还在评估阶段，尚未启动迁移

这是做出正确决策的最佳时机。建议按以下顺序行动：

1. 查询附件数据库表，产出完整的大小分布报告。 这是所有后续判断的基础，不要跳过。
2. 根据超限附件的数量和类型，判断迁移复杂度。 如果超限附件不超过 200 个且集中在少数项目，可以考虑手动处理加官方助手迁移。如果超过 500 个，建议认真评估带附件映射能力的第三方迁移工具。
3. 制定附件分类标准，并提前和业务部门沟通。 不要在迁移启动前一周才把附件清单扔给业务负责人，他们不可能在那么短的时间内完成有效判断。
4. 选择一个迁移窗口，避开业务高峰期。 季度末、年末、大版本发布周都不合适。最好选在业务相对平稳的月份，同时预留四周的附件长尾处理时间。

2. 情况 B：你已经开始迁移，但被附件限制卡住了

不要慌，更不要立刻重新跑全量迁移。已经陷入“半迁移”状态时，建议如下：

1. 停止当前迁移任务，导出已完成和失败的文件清单。 先搞清楚哪些数据是安全的，哪些是受损的。
2. 评估受损范围。 如果失败附件关联的工单数量有限（比如低于 5%），可以考虑手工补传这些附件，然后重新触发这些工单的索引更新。
3. 如果失败范围很大（超过 20% 的工单受影响），考虑清理目标环境后重新迁移。 但这次必须先在源端完成附件分类和超限处理。
4. 无论采用哪种方案，务必通知所有用户迁移出现了延迟，并告知新的预期完成时间。 沉默是信任的杀手，特别是在迁移这种敏感时期。

3. 情况 C：你已经完成迁移，但陆续发现附件缺失

这是“长尾效应”在起作用。此时的核心任务是：

1. 建立一个集中的“附件问题登记入口”。 让所有用户在发现附件缺失时能快速提单，而不是在群里 @ 你。
2. 按工单优先级处理补传。 优先处理涉及客户可见工单、审批流工单的附件缺失问题。
3. 定期发布恢复进度通告。 周更即可，告诉团队这周修复了多少、还有多少待处理。公开透明是最好的焦虑缓解剂。

七、不同情况下的取舍：什么值得争取，什么应该让步

1. 完整性 vs 迁移速度，你只能选一个

在迁移附件时，一个必须做出的取舍是：你要追求 100% 的附件完整性，还是接受一个“足够好”的迁移结果以换取更快的完成时间？

我在前几个项目中倾向于前者，后来发现这是错的。原因有三：

• Jira 里确实存在一定比例的附件，在业务意义上已经失效。为了一份三年前的临时日志去花几个小时处理，性价比极低。
• 追求 100% 附件完整性，最终的“收尾成本”会呈指数上升。最后 5% 的附件处理耗时，往往相当于前面 95% 的总和。
• 业务团队对附件完整性的容忍度比你想象的高。只要 A 类文件齐全、B 类中高频使用的文件到位，他们不会在意某个已关闭缺陷里少了一张截图。

所以我的取舍标准是：A 类文件 100% 保留，B 类文件 95% 以上迁移成功，C 类和 D 类一律降级或丢弃，不在迁移阶段纠缠。这个目标在实际操作中是可实现、可验收的。

2. 统一处理 vs 按项目定制，效率与适配的平衡

另一个常见的纠结是：对所有项目和所有附件采用统一的处理策略，还是按项目、按类型分别定制？

我的建议是：对附件处理规则可以统一，但处理责任必须分散。

统一的是什么？是所有超限附件的处理标准。比如：“所有 D 类文件一律迁至低频存储，六个月后自动删除”，这个规则可以一刀切，不需要每个项目单独讨价还价。

分散的是什么？是 A、B、C 类文件的判定责任。判定权必须交给业务部门，因为只有他们能承担判定错误的后果。IT 团队负责提供清单、设定截止时间、执行批量操作，但不替业务做价值判断。

这样分工的好处是：IT 不用担心“删错了怎么办”，业务部门不用担心“IT 不懂乱删”。责任边界清晰，效率反而最高。

3. 迁完即止 vs 持续治理，附件的长期管理策略

很多团队把迁移当成一个“一次性项目”，迁完就翻篇。但如果你不改变附件的管理方式，几年后你会发现同样的问题又回来了。

迁移其实是一个很好的契机，去建立附件治理的长期规则。下面几条规则是我们迁移后实施的，到现在运行了近一年，效果不错：

• 每个项目设置附件总容量上限。 超过上限后，最旧的附件自动转入冷存储。这个机制倒逼项目主动清理，而非无限堆积。
• 新建工单的附件大小默认限制为 20MB。 需要上传更大文件时，引导用户使用外部存储链接。这不是技术限制，而是流程引导。
• 每季度生成一次附件增长报告。 直接发到各个项目的负责人，标明哪些项目的附件增速异常。

这些规则不是为了限制用户，而是为了避免下一次迁移再踩同一个坑。附件治理不是一次性工程，它应该成为团队的基础习惯。

八、总结：从“乌龙”到“可控”的三个核心转变

回顾我经历过的几次 Jira 迁移，附件大小限制从来不是最复杂的技术问题，但它一定是最容易被低估的系统性风险。要从“乌龙”走向“可控”，团队需要在三个维度上完成转变：

第一，认知转变：附件迁移不是 IT 的独立任务，而是一项需要业务团队深度参与的数据整理工作。 IT 负责提供数据、工具和流程框架，业务团队负责附件的价值判定。任何一方缺席，迁移结果都会出问题。

第二，流程转变：迁移不再是一次性的大爆炸式切换，而是“摸底→分类→清理→分批迁→补传”的五阶段流程。 每个阶段都有明确的任务边界和验收标准，前一阶段不完成不进入下一阶段。这种节奏感是防止“半迁移”灾难的唯一有效手段。

第三，工具转变：选择迁移工具时，不是看它“能不能把数据搬过去”，而是看它“能不能让你控制搬的粒度、跳过的东西、以及失败后的恢复路径”。 官方助手在简单场景下够用，但在附件体量大、合规要求高的场景下，具备附件审计、选择性迁移和差异报告能力的工具才是正确选择。

下一步行动非常简单：如果你现在正坐在电脑前评估一次 Jira 迁移，请先打开你的数据库查询工具，跑一条查询，看看你 Server 端有多少个超过 10MB 的附件，它们关联了多少个工单，分别属于哪些项目。这个数字本身，就是你接下来应该走哪条路的最清晰的指示灯。

拿到数字之后，本文第三节的分类框架、第四节的判断逻辑、第五节的案例数据、第六七节的决策路径，应该能够帮你比绝大多数人更早地识别风险、做出正确的取舍。毕竟，在 Jira 迁移这件事上，最贵的成本不是工具，不是时间，而是一个没人提前告诉你的“乌龙”。