016、CI/CD流水线：用GitHub Actions把部署从玄学变成肌肉记忆

016、CI/CD流水线用GitHub Actions把部署从玄学变成肌肉记忆上周深夜线上服务突然告警。紧急回滚时发现测试环境通过的镜像在生产环境死活起不来。查了三个小时最后发现是某位同事在Dockerfile里写死了测试数据库的IP。这种“本地跑得好好的上线就崩”的剧情各位应该不陌生吧今天我们就用GitHub Actions搭建一套CI/CD流水线把这种部署玄学变成可重复的肌肉记忆。为什么GitHub Actions是FastAPI项目的绝配以前团队用Jenkins每次配置都要点一堆页面插件冲突更是家常便饭。GitHub Actions的最大优势是“配置即代码”——你的流水线定义就放在仓库的.github/workflows里版本控制、代码评审、修改历史全都有了。对于FastAPI这种现代Python框架Actions的轻量级容器化执行环境简直是天作之合。从最简单的测试流水线开始先别急着搞复杂的多阶段部署。咱们在项目根目录创建.github/workflows/test.ymlname:Run Testson:push:branches:[main,develop]pull_request:branches:[main]jobs:test:runs-on:ubuntu-latestservices:postgres:image:postgres:13env:POSTGRES_PASSWORD:postgresoptions:---health-cmd pg_isready--health-interval 10s--health-timeout 5s--health-retries 5steps:-uses:actions/checkoutv3-name:Set up Python 3.10uses:actions/setup-pythonv4with:python-version:3.10-name:Install dependenciesrun:|python -m pip install --upgrade pip pip install -r requirements.txt # 测试依赖单独安装别污染生产环境 pip install pytest pytest-asyncio httpx-name:Run migrationsenv:DATABASE_URL:postgresql://postgres:postgreslocalhost:5432/test_dbrun:|alembic upgrade head # 这里踩过坑Actions的service容器端口不是默认的5432 # 要用localhost访问别信某些教程写的service名字-name:Run tests with pytestenv:DATABASE_URL:postgresql://postgres:postgreslocalhost:5432/test_dbREDIS_URL:redis://localhost:6379run:|pytest -v --covapp --cov-reportxml # 记得在pytest配置里标记异步测试 # 不然async def的测试用例会直接跳过-name:Upload coverage to Codecovuses:codecov/codecov-actionv3with:file:./coverage.xmlfail_ci_if_error:true这个配置有几个关键点services块里定义了PostgreSQL容器测试时直接连localhost就行。环境变量通过env传递避免硬编码。覆盖率报告生成后直接上传到Codecov后续可以配置质量门槛。加上代码质量检查的钩子测试通过只是底线代码风格和类型安全同样重要。在test job后面追加几个步骤-name:Lint with flake8run:|pip install flake8 black isort flake8 app --count --selectE9,F63,F7,F82 --show-source --statistics black --check app isort --check-only app-name:Type checking with mypyrun:|pip install mypy mypy app --ignore-missing-imports # 忽略缺失导入是因为第三方库的类型提示参差不齐 # 重点检查我们自己写的业务逻辑很多人觉得代码风格检查太“形式主义”直到你凌晨三点调试一个因为缩进错误导致的诡异bug。把这些检查自动化团队协作时能省下大量沟通成本。构建Docker镜像并推送到Registry测试通过后该打包镜像了。创建新的build.yml工作流注意这里用了needs: test来依赖测试阶段name:Build and Pushon:workflow_run:workflows:[Run Tests]types:-completedbranches:[main]jobs:build:if:${{github.event.workflow_run.conclusion success}}runs-on:ubuntu-lateststeps:-uses:actions/checkoutv3with:ref:${{github.event.workflow_run.head_sha}}# 这个ref写法很重要确保构建的是触发测试的那个提交-name:Set up Docker Buildxuses:docker/setup-buildx-actionv2-name:Login to DockerHubuses:docker/login-actionv2with:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_TOKEN}}# 千万别用密码用Access Token# 去年有团队密码泄露被挖矿的案例-name:Build and pushuses:docker/build-push-actionv4with:context:.push:truetags:|yourusername/fastapi-app:latest yourusername/fastapi-app:${{ github.sha }}cache-from:typeghacache-to:typegha,modemax# 开启缓存下次构建能快不少注意这里用了workflow_run触发器只有测试工作流成功完成才会触发构建。镜像打了两个标签latest和git commit SHA后者在回滚时特别有用。部署到生产环境的策略选择部署环节最考验设计水平。根据你的基础设施可以选择几种模式Kubernetes滚动更新如果用了k8s-name:Update k8s deploymentrun:|kubectl set image deployment/fastapi-deployment \ fastapi-containeryourusername/fastapi-app:${{ github.sha }} kubectl rollout status deployment/fastapi-deploymentSSH到服务器手动重启传统VPS方案-name:Deploy to productionuses:appleboy/ssh-actionv0.1.5with:host:${{secrets.PROD_HOST}}username:${{secrets.PROD_USER}}key:${{secrets.SSH_PRIVATE_KEY}}script:|cd /opt/fastapi-app docker-compose pull docker-compose up -d docker system prune -f # 记得清理旧镜像不然磁盘很快会满重要建议生产部署一定要加手动批准步骤。在workflow里添加environment配置配合GitHub的Protected Environments功能关键时刻能救命。那些年我们踩过的坑秘密管理GitHub Secrets有大小限制64KB大文件如服务账号JSON得用base64编码后存。更复杂的建议用Vault或AWS Secrets Manager。矩阵测试Python 3.8、3.9、3.10都要测用矩阵策略strategy:matrix:python-version:[3.8,3.9,3.10]本地调试用act工具可以在本地运行Actions但Docker in Dockerdind相关的工作流可能跑不起来要有心理准备。超时问题默认6小时超时对于长测试可能不够。在job级别设置timeout-minutes: 120。缓存优化pip和Docker层缓存一定要配否则每次都要从头下载既慢又费流量。个人经验谈CI/CD流水线不是一蹴而就的。我们团队的第一版只有pytest测试后来逐步加了代码检查、安全扫描、性能基准测试。关键是要让流水线“活”起来——每次失败都要分析原因是测试不稳定还是代码真有bug必要时调整流水线而不是绕过检查。另一个建议在README最显眼的位置放上CI徽章。看到所有检查都是绿的那种安全感比任何文档都管用。当绿色成为团队的集体习惯代码质量自然就上去了。最后记住自动化不是为了淘汰人而是让人去做更有价值的事。以前部署要手动执行十几步操作现在点个按钮就行。省下来的时间可以多写两个测试用例或者优化一下数据库查询。工程师的成就感不就来自这些细节的持续改进么