集成与部署 入门教程

本文围绕「集成与部署 入门教程」整理操作要点、适用场景和常见问题，帮助你先判断是否适合继续操作，再按步骤完成配置。

持续集成与持续部署：从零开始构建自动化交付流水线

持续集成与持续部署（CI/CD）是现代软件工程中提升交付效率的核心实践。其本质是将代码从开发环境到生产环境的流转过程自动化，消除手动操作（如通过FTP上传或登录服务器拉取代码）导致的版本不一致和配置遗漏风险。通过这套流程，代码提交后会自动触发测试、构建、打包及部署，形成可重复、可追溯的交付路径，从而保障发布质量与速度。

下一步：请求与响应格式 入门教程、请求与响应格式 实用技巧

---

Before you start

环境准备清单

启动CI/CD配置前，请确保满足以下三项基本条件：

• 版本控制工具就绪：主流工具为Git，建议仓库托管于GitHub、GitLab或Bitbucket。主分支（main或master）保持稳定，所有功能开发在独立分支进行，以便触发部署时能准确定位到可发布版本。
• 明确目标部署环境：需明确应用部署的类型——是传统云服务器（如ECS、EC2）、容器平台（如Docker、Kubernetes），还是静态托管服务（如Vercel、Netlify）。不同环境的脚本编写和凭证配置差异显著，务必提前规划。
• 注册CI/CD平台账户：免费且易用的选项包括GitHub Actions、GitLab CI/CD，以及需自托管的Jenkins。对于个人项目或小团队，GitHub Actions入门门槛最低，后续内容也将以此为例展开。

何时应三思而暂停

• 项目仍处于原型阶段，数据库结构频繁变更：流水线需为每次部署调整脚本，反而拖累开发节奏。
• 未曾获取目标服务器的访问密钥或部署Token：强行配置可能导致流程卡在最后一步，排查时间远超手动部署。
• 当前环境为生产环境，且未准备回滚方案：新手首运行流水线时，务必先用测试环境验证，切莫直接上线。

---

Steps

第一步：明确输出产物

CI/CD流程的第一步并非编写配置，而是明确交付内容。不同类型的项目，打包产物和部署目标差异巨大，如下表所示：

项目类型	打包产物	部署目标
静态网站	HTML/CSS/JS文件夹	Netlify、阿里云OSS静态桶
Node.js API	压缩包或Docker镜像	云服务器、Kubernetes
Python应用	pip依赖+源码	虚拟机、AWS Lambda
移动端App	.apk/.ipa文件	应用商店分发

以Node.js后端为例，输出物通常为包含package.json、node_modules（或锁定的依赖文件）及入口文件的压缩包，或一个Docker镜像。新手常见错误是选错格式，例如将整个开发目录（含.git、node_modules等）直接打包上传，导致包体臃肿，并可能泄露敏感信息（如.env文件）。

第二步：设置触发规则

流水线需明确启动条件。多数平台支持以下触发器：

• Push到特定分支：最常用，例如推送至main分支直接触发部署。
• Pull Request：适用于自动化测试，不直接触发部署。
• 定时触发：适合爬虫或数据同步类的定期部署。
• 手动触发：用于需要人工确认的发布场景。

新手常见误区：一开始就将“所有分支push”设为触发条件，导致开发分支的调试代码意外上线。推荐初始配置：仅main分支的push触发完整部署。

第三步：编写流水线YAML配置

以GitHub Actions为例，在项目根目录创建.github/workflows/deploy.yml：

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Build
        run: npm run build
      - name: Deploy
        run: |
          rsync -avz --delete dist/ user@server:/var/www/app/

注意：rsync命令中的--delete参数会删除目标目录中的多余文件。若服务器上包含其他非应用文件，该参数可能导致误删。建议首先在非生产环境使用--dry-run模拟测试，确认无误后再正式运行。

第四步：安全配置凭证

流水线需要访问目标服务器权限，切勿在配置文件中明文存储密码。正确做法如下：

• GitHub Actions：使用Secrets（Settings → Secrets and variables → Actions）
• GitLab CI/CD：使用CI/CD Variables
• Jenkins：使用Credentials Binding插件

常用凭证类型包括：SSH Key（用于登录服务器）、API Token（用于云平台）、Docker Registry密码（用于推送镜像）。

第五步：添加验证与健康检查

部署完成后，增加一个简单的健康检查步骤，确保服务正常运行：

- name: Health check
  run: |
    curl -f http://your-server.com/health || exit 1

该步骤会自动检查服务是否返回200状态码。若失败，流水线将标记为失败，避免出现“部署成功但页面白屏”的误报。

---

Checks

部署前必做的验证

• 测试是否全部通过：流水线中的测试步骤应作为阻塞条件——测试失败则立即中止，不再执行后续步骤。
• 构建产物大小是否异常：可添加判断逻辑，若打包文件超过正常范围2倍（例如平时5MB突然增至50MB），则发出警告。这通常意味着意外包含了开发依赖或日志文件。
• 配置文件差异检查：使用diff工具对比当前部署的配置文件与仓库内的配置文件。许多生产事故源于“本地改了配置但忘记提交”。

部署后应检查的内容

检查项	方法	预期结果
服务是否启动	curl -I http://domain	HTTP 200/30x
API是否可用	调用关键接口（如/status）	返回正常数据
静态资源是否加载	浏览器打开页面，检查控制台404	无错误
数据库迁移是否执行	检查表结构版本号	与代码版本一致

实用技巧：部署完成后，先登录服务器执行ps aux | grep node确认新进程已启动，再用curl测试。这比直接刷新浏览器更可靠，因为浏览器缓存可能显示旧页面。

---

Troubleshooting

场景一：流水线跑完但服务未更新

最常见原因：部署步骤中的目标路径写错。登录服务器，查看部署脚本实际修改的目录，并与服务的根目录配置比对。例如Nginx的root配置指向/var/www/app，但rsync误写成/var/www/old-app。

解决方法：在部署步骤中添加pwd和ls -la输出日志，便于排查。同时确认rsync的源路径是否正确——新手常混淆dist/（复制目录内容）与dist（复制整个目录）的区别。

场景二：凭证错误导致部署失败

若出现类似Permission denied (publickey)的错误，按以下顺序排查：

1. 确认Secrets中填写的private key格式正确（以-----BEGIN OPENSSH PRIVATE KEY-----开头）
2. 确认服务器上的~/.ssh/authorized_keys包含对应的公钥
3. 确认目标用户的shell不是/sbin/nologin（用户无登录shell会导致SSH被拒绝）

常见陷阱：新生成的SSH Key未添加到ssh-agent，或Key的权限过高（chmod 600是必须的）。

场景三：版本号冲突或依赖不一致

本地能构建，但流水线上构建失败。典型原因是package-lock.json或yarn.lock未提交到仓库，或本地用Node.js 18，而流水线的runner默认用Node.js 16。

解决方案：在流水线配置中显式指定版本：

- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: 18
    cache: 'npm'

何时回滚而非修复？

部署后发现问题时，评估是立即修复还是回滚：

• 回滚：影响范围大（如主功能不可用）、修复需超过10分钟
• 热修复：问题局限于特定页面、可快速定位并修复

回滚最简单的方法是重新触发上一次成功部署的流水线——多数平台支持“重新运行任务”功能；也可使用git revert回退提交后重新push。切勿直接在服务器上修改文件，否则下次部署会覆盖手动改动。

---

FAQ

什么是持续集成与持续部署入门教程？

这是一套指导开发人员从零搭建CI/CD流程的教学内容，涵盖版本控制触发、自动化测试、构建打包、发布部署等环节。其目标在于让代码从提交到上线的过程可重复、可追溯，最大限度减少人为失误，提升团队交付的可预测性。本教程特别适合尚未引入自动化流水线的个人开发者或小团队，帮助