上个月我们团队完成了一次大的系统迁移，把整个MR（合并请求）工作流从旧的代码托管平台迁移到了新的平台。

这次迁移说起来简单，就是换个平台而已，但真正做起来才发现，里面的坑真的很多。从迁移方案的设计、数据的迁移、流程的适配，到团队的培训、问题的处理，前后花了将近一个月的时间。

迁移的过程中遇到了各种各样的问题，有些是技术上的，有些是流程上的，还有些是人的问题。好在最后都一一解决了，迁移完成之后，新系统运行得很稳定，团队的反馈也不错。

这篇文章我想把这次迁移的经历分享出来。从迁移方案、执行步骤到遇到的问题和解决方案，聊聊系统迁移中的那些坑和总结的经验。

如果你也在做类似的系统迁移，或者打算做，希望这篇文章能给你一些参考，帮你少走一些弯路。

为什么要迁移

先说说为什么要迁移。

我们之前用的代码托管平台是一个比较老的系统，用了五六年了。这个平台在当时还是不错的，基本的代码托管、MR、CI/CD功能都有，团队用着也还行。

但随着团队的扩大和业务的发展，旧系统越来越跟不上需求了。主要有几个问题：

第一是性能问题。旧系统的性能越来越差，特别是代码库大了之后，打开一个MR要等好几秒，有时候甚至会超时。代码评审的体验很不好，大家都在抱怨。

第二是功能不足。旧系统的MR功能比较基础，缺少很多现代代码托管平台的功能，比如内联评论、建议修改、任务列表、审批规则等。这些功能对于提高代码评审效率很重要，但旧系统没有。

第三是集成困难。旧系统的API不够完善，和我们其他工具的集成很困难。比如我们想把MR和项目管理工具、CI/CD系统、通知系统做深度集成，但旧系统的API支持不了，只能做一些很基础的集成。

第四是维护成本高。旧系统是我们自己部署和维护的，需要专门的人来管。升级、备份、故障处理，都要花时间和精力。而且旧系统的社区越来越不活跃，遇到问题很难找到解决方案。

基于这些原因，我们决定迁移到一个新的代码托管平台。新平台是SaaS服务，不用自己维护，功能也很强大，API也很完善，能满足我们的需求。

决定迁移之后，我们就开始了迁移的准备工作。

迁移前的准备

迁移之前的准备工作非常重要，准备得越充分，迁移过程就越顺利。

首先是选型。我们对比了好几个主流的代码托管平台，从功能、性能、价格、服务、生态等多个维度做了评估。最后选了一个功能最全面、和我们现有工具集成最好的平台。

选型的时候我们没有只看价格，而是综合考虑了总拥有成本。虽然SaaS服务要付订阅费，但省去了自己维护的人力成本，而且功能更强，能提高团队的效率，总体来看是划算的。

然后是迁移方案的设计。我们没有一上来就开始迁，而是先设计了详细的迁移方案。方案包括：

迁移的范围：哪些代码库要迁，哪些配置要迁，哪些历史数据要迁。

迁移的顺序：先迁什么，后迁什么，怎么分批迁移，降低风险。

迁移的时间：什么时候开始，什么时候完成，每个阶段的时间节点。

回滚方案：如果迁移失败了，怎么回滚到旧系统，保证业务不受影响。

验证方案：迁移完成之后，怎么验证迁移是否成功，需要检查哪些内容。

方案设计好之后，我们和团队的所有人都做了沟通，让大家了解迁移的计划和影响，收集大家的意见和建议。

接下来是试点迁移。我们没有一下子把所有代码库都迁过去，而是先选了几个非核心的、小的代码库做试点。通过试点，我们熟悉了迁移的流程和工具，发现了一些方案中没有考虑到的问题，然后对方案做了调整。

试点迁移花了一周时间，效果还不错。试点成功之后，我们才开始大规模的迁移。

最后是团队培训。在正式迁移之前，我们组织了几次培训，教大家怎么使用新平台，新平台的MR流程和旧平台有什么不一样，有哪些新功能可以用。同时我们还写了详细的使用文档和常见问题解答，方便大家随时查阅。

这些准备工作花了将近两周时间，但非常值得。正是因为准备充分，后面的正式迁移才比较顺利。

迁移的执行

正式迁移我们是分批进行的，总共分了三批。

第一批是工具类和基础库。这些代码库相对独立，依赖关系简单，迁移风险小。我们先迁这些，积累经验，同时也让团队慢慢适应新平台。

第二批是业务服务。这些是核心的业务代码库，依赖关系比较复杂，迁移风险大。我们在第一批迁移稳定之后，才开始迁第二批。

第三批是遗留系统和归档项目。这些项目不常用，迁移的优先级低，放在最后迁。

每一批迁移的流程基本一样：

第一步，通知相关团队。在迁移之前，提前通知相关的开发人员，告诉他们迁移的时间和注意事项，让他们在迁移期间不要提交代码。

第二步，同步代码库。用迁移工具把代码库从旧平台同步到新平台，包括所有的分支、标签、提交历史。同步完成之后，做一次校验，确保代码和历史完全一致。

第三步，迁移配置。把代码库的相关配置迁移过去，比如分支保护规则、MR审批规则、Webhook、CI/CD配置等。

第四步，迁移MR和评论。把未关闭的MR以及相关的评论、审批记录迁移过去。这一步比较麻烦，因为不同平台的MR数据结构不一样，需要做转换。

第五步，切换流量。把代码库的读写流量切换到新平台，旧平台设为只读。这一步是迁移的关键节点，切换之后，所有的开发工作都在新平台上进行。

第六步，验证。切换之后，做全面的验证，包括代码拉取、提交、推送、MR创建、评审、合并、CI/CD触发等，确保一切正常。

第七步，观察。切换之后，我们会观察一两天，看看有没有什么问题。如果有问题，及时处理。如果问题严重，就回滚到旧平台。

每一批迁移大概花两三天时间，三批加起来花了一周多。整个过程还算顺利，没有出现大的故障。

遇到的问题和解决方案

虽然准备得很充分，但迁移过程中还是遇到了不少问题。这里挑几个比较典型的说说。

第一个问题是大代码库的迁移超时。

我们有一个特别大的代码库，有好几年的历史，提交记录几十万条，代码文件几万个。迁移这个代码库的时候，迁移工具跑了好几个小时，最后超时失败了。

我们试了好几次都失败了，后来查了一下，发现是迁移工具对大代码库的支持不好，内存不够用。

解决方案是，我们换了一种迁移方式。先用git clone把代码库完整地克隆到本地，然后用git push --mirror推送到新平台。这样虽然慢一点，但稳定可靠，不会超时。同时我们把提交历史做了一定的裁剪，只保留最近三年的历史，更早的历史归档到旧平台。

用这种方式，大代码库的迁移终于成功了。

第二个问题是MR评论的迁移不完整。

旧平台的MR评论和新平台的评论数据结构不一样，迁移工具只能迁移评论的内容，不能迁移评论的位置和上下文。比如旧平台中针对某一行代码的评论，迁移到新平台之后，变成了普通的评论，看不到是针对哪一行代码的。

这个问题对我们影响比较大，因为很多未关闭的MR有大量的行内评论，迁移之后这些评论的上下文丢失了，评审的人看不懂评论在说什么。

解决方案是，我们写了一个自定义的迁移脚本，专门处理MR评论的迁移。脚本会解析旧平台的评论数据，找到对应的代码行，然后在新平台中创建对应的行内评论。虽然不能做到100%还原，但大部分评论都能正确迁移。

对于那些实在无法迁移的评论，我们在新平台的MR中加了一个备注，说明这些评论是从旧平台迁移过来的，原始上下文可以在旧平台查看。

第三个问题是CI/CD配置的适配。

旧平台和新平台的CI/CD配置格式不一样，旧平台用的是一种格式，新平台用的是另一种格式。我们有几十个代码库，每个都有CI/CD配置，如果一个个手动改，工作量太大了。

解决方案是，我们写了一个转换脚本，能自动把旧格式的CI/CD配置转换成新格式。转换完之后，再人工检查一遍，确保转换正确。对于一些复杂的配置，手动调整一下。

用这种方式，大大减少了人工修改的工作量，而且降低了出错的概率。

第四个问题是Webhook的迁移。

我们有很多Webhook，把MR的事件推送到其他系统，比如通知系统、项目管理系统、自动化测试系统等。旧平台的Webhook payload格式和新平台不一样，迁移之后，这些Webhook都不能用了。

解决方案是，我们在中间加了一个适配层。适配层接收新平台的Webhook，转换成旧平台的格式，再推送给下游系统。这样下游系统不需要改，就能继续工作。

同时我们也在逐步改造下游系统，让它们直接支持新平台的Webhook格式，最终把适配层去掉。

第五个问题是团队的适应问题。

技术问题好解决，人的问题有时候更难。团队里有些人用旧平台用了很多年，已经习惯了，对新平台有抵触情绪。迁移之后，他们觉得新平台这也不好那也不好，甚至有人想换回旧平台。

解决方案是，我们做了大量的沟通和培训。一方面，耐心地教大家使用新平台，展示新平台的优势和新功能；另一方面，收集大家的反馈，能优化的优化，能解决的问题及时解决。

同时我们也树立了一些榜样，让那些学得快、用得好的同事分享经验，带动其他人。过了一段时间之后，大家慢慢适应了新平台，也发现了新平台的好处，抵触情绪就消失了。

这些问题虽然都解决了，但也花了我们不少时间和精力。如果提前能预料到这些问题，准备得更充分一些，迁移会更顺利。

迁移后的效果

迁移完成之后，我们观察了一段时间，整体效果还是不错的。

第一是性能提升明显。新平台的响应速度比旧平台快很多，打开MR、加载代码、搜索内容，都很流畅。大家不再因为系统慢而烦躁了，代码评审的效率提高了不少。

第二是功能更丰富。新平台的MR功能很强大，内联评论、建议修改、任务列表、审批规则、自动合并等功能，都很好用。特别是建议修改功能，评审人可以直接建议修改某一行代码，作者可以一键应用，大大提高了评审的效率。

第三是集成更顺畅。新平台的API很完善，和我们其他工具的集成做得很好。现在MR的状态可以自动同步到项目管理工具，CI/CD的结果可以实时显示在MR中，评审通过之后可以自动合并，整个流程非常顺畅。

第四是维护成本降低。新平台是SaaS服务，不用我们自己维护了。以前需要一个人花不少时间在系统维护上，现在这些时间都省下来了，可以做更有价值的事情。

当然也有一些不完美的地方。比如新平台的某些功能和我们的习惯不太一样，需要时间适应；比如SaaS服务偶尔会有短暂的不可用，虽然时间很短，但还是有影响；比如订阅费用比自己维护要高一些，虽然省了人力成本。

但总体来说，迁移的收益大于成本，我们对这次迁移的结果是满意的。

经验总结

这次迁移给了我们很多经验和教训，总结一下。

第一，迁移前的准备怎么强调都不为过。

很多人做迁移，着急开始，准备工作做得不充分，结果迁移过程中问题百出。我们这次因为准备得比较充分，虽然也遇到了问题，但都在可控范围内。

迁移前一定要做好选型、方案设计、试点验证、团队培训这些工作。花在准备上的时间，会在迁移过程中加倍赚回来。

第二，一定要有回滚方案。

迁移不是100%能成功的，一定要有回滚方案。如果迁移失败了，或者迁移后出现了严重问题，能快速回滚到旧系统，保证业务不受影响。

我们的回滚方案是，旧平台在迁移后保持只读状态至少一个月，如果新平台出了严重问题，可以随时切回去。虽然最后没有用到回滚，但有这个方案在，心里就踏实。

第三，分批迁移，降低风险。

不要想着一次性全部迁完，那样风险太大。分批迁移，先迁简单的、非核心的，积累经验，再迁复杂的、核心的。每一批迁移稳定之后，再迁下一批。

分批迁移虽然时间长一点，但风险小很多，出了问题影响范围也小。

第四，重视数据迁移的完整性。

系统迁移不只是迁代码，还要迁配置、MR、评论、历史数据等。这些数据的完整性很重要，如果迁丢了，会影响团队的工作。

迁移之后一定要做全面的验证，确保所有数据都完整迁移了。特别是MR和评论这些非结构化的数据，最容易出问题，要重点检查。

第五，人的问题和技术问题同样重要。

系统迁移不只是技术问题，也是人的问题。团队能不能接受新系统，能不能快速上手，直接影响迁移的成败。

迁移前要做好沟通和培训，让大家了解迁移的原因和好处。迁移过程中要及时收集反馈，解决大家遇到的问题。迁移后要持续支持，帮助大家适应新系统。

第六，迁移后要有一段时间的并行支持。

迁移完成之后，不要马上把旧系统关掉。旧系统保持只读状态一段时间，作为备份和参考。同时团队要在新系统上工作一段时间，发现和解决遗留问题。

等新系统稳定运行一段时间，确认没有问题了，再彻底关掉旧系统。

写在最后

这次MR工作流迁移，是我们团队今年做的比较大的一次系统迁移。前后花了将近一个月的时间，遇到了不少问题，也学到了很多东西。

系统迁移是一件看起来简单、做起来复杂的事情。它不只是把数据从一个地方搬到另一个地方，还涉及到流程的适配、工具的集成、团队的适应等方方面面。任何一个环节出了问题，都可能影响迁移的成败。

但只要准备充分、方案合理、执行细致、沟通到位，系统迁移是可以顺利完成的。而且迁移完成之后，新系统带来的收益，会让你觉得之前的辛苦都是值得的。

如果你也在做或者打算做系统迁移，希望这篇文章能给你一些帮助。迁移的过程可能会很辛苦，但只要坚持下来，就能看到好的结果。

最后用一句话来结束这篇文章："系统迁移就像搬家，打包的时候很麻烦，搬的时候很辛苦，但住进新家之后，一切都是值得的。"

愿你的下一次系统迁移，顺利而成功。