云主机CI/CD部署失败怎么办?

说实话，自从团队把CI/CD流水线搭起来之后，我每天早上的第一件事不再是倒咖啡，而是打开流水线看板看看昨晚的部署有没有成功。为什么?因为失败的次数实在是太多了。有时候是单元测试没过，有时候是镜像构建出了问题，还有时候镜像都推上去了，部署到云主机的时候却出了岔子。那种看着进度条走到最后一步突然变红的滋味，相信每个用过CI/CD的人都不陌生。

这篇文章我想把这些年遇到的云主机CI/CD部署失败的案例和解决方法，老老实实地整理出来。不是什么高深的理论，都是实战中一点点摸索出来的经验。

代码仓库层面的问题：拉不到代码，一切都白搭

CI/CD流水线的第一步通常是拉取代码。这一步看起来简单，但出问题的概率并不低。我遇到过好几次流水线在拉代码的阶段就直接报错了。

有一次，流水线突然开始报错，说“fatal: unable to access ‘仓库地址’: SSL certificate problem”。检查了半天，原来是代码仓库的SSL证书过期了，而CI/CD的构建节点上没有信任新的证书颁发机构。临时解决办法是在git clone命令后面加上这个参数“-c http.sslVerify=false”。但这个办法只能应急，长期来看还是要更新构建节点上的证书信任链。

另一个常见的问题是权限问题。代码仓库从公开变成私有了，或者换了访问凭证，但CI/CD系统里配置的还是旧的用户名和密码。我的一位同事遇到过这样的情况，他修改了自己代码仓库的密码，但是忘记在CI/CD系统里更新了。结果流水线跑起来的时候，认证失败，代码拉不下来。解决方案是在CI/CD系统的凭据管理里更新一下访问令牌或者密码。

还有一种情况比较隐晦，就是代码仓库的子模块。如果一个项目引用了其他仓库作为子模块，而CI/CD系统在拉取代码的时候没有初始化子模块，或者没有权限访问子模块所在的仓库，拉取就会失败。解决方案是在流水线的拉取代码步骤之后加上子模块初始化和更新的命令，并且确保CI/CD系统对子模块仓库也有访问权限。

依赖安装失败：环境不一致的老问题

代码拉下来之后，下一步通常是安装依赖。无论是Node.js的npm install，Python的pip install，还是Java的mvn package，这一步都特别容易出问题。

我记得有一次，一个前端项目的流水线在npm install的时候报错了，错误信息说某个包找不到。开发人员在本地跑得好好的，为什么到CI/CD环境里就找不到呢?后来发现，这个包是从一个私有的npm仓库安装的，而CI/CD环境里没有配置对这个私有仓库的访问。解决方案是在CI/CD环境里设置npm的registry配置，并且配置好认证信息。

另一个典型的案例是依赖版本锁定问题。有些项目用package-lock.json或者yarn.lock锁定了依赖的版本，但是这些锁文件里记录的下载地址是某个特定的镜像源。当CI/CD环境的网络访问不了这个镜像源的时候，依赖安装就会失败。解决方案是在CI/CD流水线里强制使用国内的镜像源，或者提前把依赖包缓存到构建节点上。

Python项目的问题也不少。有一次，一个Python项目的pip install一直失败，报错说编译某个C扩展的时候找不到Python.h头文件。检查了一下，CI/CD的构建节点上安装的是Python的运行环境，但没有安装Python的开发头文件包。在构建节点上安装python-dev或者python3-dev包之后，问题就解决了。

这里有一个经验：CI/CD的构建节点环境应该和开发环境尽量保持一致。最好用容器化的构建环境，把所有的依赖、工具链、编译环境都打包到镜像里。这样无论在哪个节点上构建，环境都是一样的，可以避免很多环境不一致导致的奇怪问题。

镜像构建失败：Dockerfile里的坑

如果用的是容器化部署，代码拉下来、依赖装好之后，下一步就是构建Docker镜像。镜像构建失败的原因五花八门，我见过的就有好几十种。

一个很经典的案例是，Dockerfile里用了COPY指令，要复制的文件或者目录在构建环境里不存在。开发人员在本地构建的时候，因为本地有一些临时生成的目录，构建没有问题。但是CI/CD环境是干净的，没有那些临时目录，COPY指令找不到源文件，构建就失败了。解决方案是把所有需要COPY的文件和目录都明确列出来，并且确保CI/CD环境里确实存在这些文件。

还有一个案例是网络问题导致的构建失败。Dockerfile里的RUN命令经常需要从网络上下载东西，比如apt-get install、pip install、curl下载。如果构建节点访问外网慢或者不通，这些命令就可能超时或者失败。解决方案是给Docker构建过程配置代理，或者把需要的软件包提前下载好放到本地仓库里。

Dockerfile的层缓存也是一个容易出问题的地方。CI/CD系统为了加速构建，通常会复用之前构建的镜像层缓存。但如果缓存出了问题，比如缓存了某个错误版本的层，后续构建就会一直失败。这时候需要在流水线里加上--no-cache参数，强制忽略所有缓存，重新构建镜像。

镜像大小的问题也值得一提。有些项目的Dockerfile写得不太讲究，构建出来的镜像有好几个GB。镜像太大，构建时间长，推送到镜像仓库的时间也长，而且很容易在推送过程中超时失败。优化镜像构建的方法我之前提到过，选择小的基础镜像、合并RUN指令、清理临时文件，这些都能显著减小镜像体积。

镜像推送失败：网络和权限的双重考验

镜像构建成功之后，需要推送到镜像仓库，供后续部署使用。推送失败的原因无非就是网络问题和权限问题。

有一次，流水线在推送镜像的步骤卡了很久，最后报了一个超时错误。检查了构建节点的网络，访问镜像仓库是通的，但是速度非常慢。后来发现是因为镜像仓库的节点和构建节点不在同一个区域，跨区域传输一个几个GB的镜像，网络延迟高而且不稳定。解决方案是把镜像仓库和构建节点放在同一个云区域里，或者使用云厂商提供的内网镜像仓库地址来推送。

权限问题的表现通常是“denied: requested access to the resource is denied”。这种情况一般是CI/CD系统用来推送镜像的账号没有写入目标镜像仓库的权限。解决方案是在镜像仓库里给这个账号分配推送权限，或者在CI/CD系统里换一个有权限的账号。

还有一种情况是镜像标签冲突。如果同一个镜像仓库里已经存在相同标签的镜像，而且这个镜像不能被覆盖，推送就会失败。解决方案是给每个构建生成唯一的镜像标签，比如用构建编号或者Git提交哈希作为标签，而不是每次都覆盖latest标签。

部署到云主机的环节：SSH和脚本的问题

镜像推送成功之后，最后一步就是把新镜像部署到云主机上。这一步通常是CI/CD系统通过SSH连接到云主机，执行一些部署脚本。这一步出问题的概率是最高的，因为涉及到的环节最多。

我处理过一个比较头疼的案例。部署脚本能在云主机上手动执行成功，但是在CI/CD流水线里执行的时候就失败了。对比了手动执行的输出和流水线的输出，发现流水线里执行脚本的用户环境变量和手动登录的用户环境变量不一样。比如PATH变量，手动登录的时候包含了/usr/local/bin，而流水线通过SSH执行命令的时候，PATH里没有这个目录，导致一些命令找不到。

解决方案是在部署脚本开头显式设置环境变量，或者直接用命令的完整路径来调用。还有一种做法是用“source ~/.bashrc”加载用户的配置文件，但这个方法有时候也不可靠，因为CI/CD系统执行命令的时候可能用的是非交互式shell，不会加载bashrc。

另一个常见的问题是云主机上的旧容器没有清理干净。每次部署都会启动一个新的容器，但旧的容器没有被停止和删除，导致端口冲突或者磁盘空间被占满。部署脚本里应该加上停止旧容器和删除旧容器的步骤，确保每次部署都从一个干净的状态开始。

网络和安全组的问题在部署环节也很常见。新部署的容器可能监听了不同的端口，云主机的防火墙或者云厂商的安全组没有放行这个新端口，导致服务访问不到。部署脚本里最好加上检查防火墙规则的逻辑，或者在部署之前就把需要用到的端口在安全组里配置好。

流水线配置本身的问题：YAML文件的一个缩进

聊了这么多环境的问题，最后说说流水线配置文件本身的问题。现在主流的CI/CD系统都是用YAML文件来定义流水线的，比如GitLab CI的.gitlab-ci.yml，GitHub Actions的workflow文件。YAML文件的格式要求很严格，一个空格、一个缩进都可能让整个流水线解析失败。

有一次我在配置GitLab CI流水线的时候，定义了一个job，写完了之后提交上去，流水线根本没有运行，页面上报了一个“jobs:job1:script config should be a string or an array”的错误。仔细检查了一下，发现script关键字下面我写的命令没有用横杠，格式不正确，导致解析器没有正确识别。修正了格式，流水线就能正常运行了。

还有一次，流水线跑到一半就停了，没有报错也没有成功。后来发现是某个job的when条件写错了，导致这个job被跳过了，下游依赖这个job的任务就一直等待。认真检查流水线配置文件里的依赖关系、条件判断、超时设置，这些细节都可能是部署失败的导火索。

回滚策略：失败之后怎么办

说完了失败的原因，我想再聊几句失败之后该怎么办。CI/CD部署失败是常态，关键是要有一套快速回滚的机制。

我见过一个团队，部署失败之后，回滚需要手动操作，把之前备份的镜像找出来，重新部署到云主机上。这个过程少说也要十几分钟，服务的不可用时间就长了。更好的做法是在流水线里固化回滚的步骤，一旦部署失败，自动触发回滚流程，把上一个稳定版本的镜像重新部署上去。

还有一个经验是，不要所有的部署都走同一个流水线。开发环境的部署可以更激进一些，失败了可以慢慢排查。生产环境的部署要更保守，增加更多的手动确认步骤，部署之前做充分的预检查，部署之后做自动化测试验证服务是否正常。

总结

云主机CI/CD部署失败这件事，说起来复杂，其实拆解开来看就是几个环节的问题。代码拉取、依赖安装、镜像构建、镜像推送、部署到云主机，每个环节都可能出问题。每个环节的问题又有各自的排查方法。

我的经验是，遇到部署失败，不要慌，先看流水线的日志。日志里记录了每一步的执行过程和输出信息，错误信息通常会把原因说得很清楚。看不懂日志的时候，可以分段定位。手动执行流水线里的每一步，看哪一步会失败，然后重点排查那一步的环境和配置。

另外，CI/CD系统本身有很多调试手段。可以开启详细日志模式，可以在构建节点上执行自定义的调试命令，可以在流水线里加上打印环境变量的步骤。这些手段都能帮你更准确地定位问题。

这些年踩了这么多坑，我越来越觉得，CI/CD部署成功不是靠运气，而是靠完善的流程和反复的测试。每一个步骤都经过验证，每一个依赖都提前准备好，每一条命令都经过测试。这样即使出了问题，也能快速定位快速修复。