本地跑得好好的一上服务器就死——这句话我听过无数次自己也经历过无数次。Python项目尤其容易踩这种坑因为解释器版本、依赖版本、系统库、环境变量任何一环对不上行为就可能完全两样。我真正下决心把CI/CD持续集成/持续部署用起来是吃完一次深夜部署的亏之后改了一个接口本地测试全绿push完手动登录服务器部署结果因为服务器上的依赖跟本地差了两个小版本线上接口直接报错大半夜爬起来回滚。那之后我给自己定了个规矩凡是Python项目必须让自动化流水线来把关。这篇文章把我这几年在Python项目上搭建持续集成/持续部署的经验整理了一下。工具上会覆盖GitHub Actions、GitLab CI和Jenkins三种主流方案内容上从流水线怎么写、质量关卡怎么设到部署链路怎么打通、坑位怎么避尽量做到可以直接照着做。不管你是个人开发者还是在带一个Python小团队这套经验都可以作为参考。1. 为什么Python项目特别需要一套自动化流水线很多人问过我这项目就我一个人写跑通就行搞CI/CD是不是过度设计了我的回答是CI/CD解决的不是人多人少协作的问题而是人为失误的问题。Python项目的运行时状态非常依赖环境这决定了它比编译型语言更怕环境漂移。1.1 环境漂移本地能跑不等于服务器能跑Python解释器有版本差异3.9、3.10、3.11、3.12每个版本的语法支持和标准库行为都有变化。更不用提第三方库一旦requirements.txt没有精确锁版本安装时的解析结果可能千差万别。我遇到过很典型的场景在3.11本地环境写的代码用了一个新特性团队另一个成员是3.8环境跑都跑不起来。还有系统层面libssl的版本、GLIBC的版本、编译工具链的缺失都会让一样的代码在另一台机器上表现完全不同。CI/CD解决这个问题的思路是把构建和验证固定在一个干净的、可复现的环境里执行每次都从零开始按同一套规则装依赖、跑测试。这样就能把我机器上明明是好的彻底变成过去式。1.2 质量对不上账合并代码前根本没人跑过测试如果没有CI大部分项目的测试是最后一个开发者在提交前随手跑一下或者干脆不跑。代码review的时候reviewer也不会为了几十行改动去拉代码、装环境、跑全量测试。于是经常出现合并的时候没问题发版的时候发现主分支上有个测试早就红了。CI的作用就是给仓库装一道自动门。每次push或PR流水线自动把当前代码放到干净的运行环境里跑一遍静态检查和测试。没过门禁代码就进不了主干。这个自动化门禁的价值不在于它多聪明而在于它不会偷懒、不会手软。1.3 人工部署链路越长出错的概率越高从代码写好到线上可用中间涉及拉代码、装依赖、改配置、重启服务、检查日志。这些动作只要是人来做就存在操作遗漏、顺序记错、命令输错的可能性。而且部署过程不可重复——这次手动操作成功了不代表下次还能复制。我统计过自己手动部署一次平均要8到12分钟而且精神高度紧张生怕哪一步敲错。CI/CD自动化之后同样的过程被压缩到2到3分钟还不会漏步骤。后面我会给出具体配置你照着抄就行。1.4 CI和CD的职责边界聊工具之前先把概念理清。持续集成CI是从代码提交开始自动完成代码下载、环境安装、静态检查、单元测试、构建产物等步骤目标是尽早发现集成问题。持续部署CD是在CI全部通过之后自动把产物发布到目标环境目标是让发布变成可靠且可重复的动作。在流水线里CI是前面的质检车间CD是后面的物流派送。很多团队一开始只做CI等测试质量和产物都稳定了再逐步把部署环节自动化——这个演进路径我个人很推荐。2. 工具选型GitHub Actions、GitLab CI、Jenkins怎么挑才不后悔先说结论没有最好的工具只有最匹配当前环境的组合。我见过有人为了统一硬把所有项目塞进同一个CI平台结果维护成本翻倍也见过有人因为不想学新工具守着老旧Jenkins流水线吃尽苦头。下面把三套主流方案摆一起对比。维度GitHub ActionsGitLab CIJenkins托管方式SaaS免运维支持SaaS和自托管自托管需要自己维护配置格式YAMLYAMLGroovyJenkinsfile与代码仓库绑定强GitHub仓库内配置强GitLab项目内配置弱可对接很多平台Python环境准备actions/setup-python一键多版本用Docker镜像跑job天然隔离需要在节点上准备Python或配合Docker上手成本低中高适合场景开源项目、GitHub托管的个人/小团队公司内部GitLab仓库已有Java/中间件Jenkins基础设施的团队2.1 GitHub Actions个人和小团队的首选我对个人开发者和开源项目的默认推荐是GitHub Actions。理由有三条一是跟GitHub仓库集成得最深开箱即用不需要额外安装任何服务二是官方actions维护得很好比如actions/setup-python一条配置就能准备指定版本的Python并自动配置缓存对Python项目非常友好三是社区生态成熟绝大多数常见需求都有现成action。它的局限在于代码托管位置。如果你希望仓库自建在公司内网、完全私有化GitHub免费版就不太合适了。另外免费额度对个人项目够用但团队项目跑得频繁时要注意并发数和时长配额。2.2 GitLab CI自建仓库与流水线一体化如果代码托管在自己部署的GitLab上用GitLab CI是顺理成章的选择。GitLab CI最突出的设计是CI/CD和代码仓库同源.gitlab-ci.yml就在项目仓库里天然支持merge request流水线、环境管理、受保护分支。GitLab CI的job默认运行在Docker executor准备的容器里这意味着每个job都从干净容器启动里面装什么Python版本、什么系统包由镜像定义宿主机环境完全不干扰CI结果。很多本地能跑、CI挂的问题用这个模式能直接规避。一个最简的.gitlab-ci.yml示例stages: - test - deploy variables: PIP_CACHE_DIR: $CI_PROJECT_DIR/.cache/pip cache: paths: - .cache/pip test: stage: test image: python:3.11-slim before_script: - pip install -r requirements-dev.txt script: - ruff check . - pytest tests/ deploy: stage: deploy image: python:3.11-slim before_script: - apt-get update apt-get install -y openssh-client script: - eval $(ssh-agent -s) - echo $DEPLOY_SSH_KEY | tr -d \r | ssh-add - - ssh $DEPLOY_USER$DEPLOY_HOST cd /srv/myapp git pull source .venv/bin/activate pip install -r requirements.txt sudo systemctl restart myapp only: - main environment: name: production这个示例已经包含测试和部署两段SSH密钥通过CI变量注入。特别注意GitLab CI会打印执行命令密钥尽量避免出现在命令里能加到runner的protected variable里就加。2.3 Jenkins从Java生态走过来的团队怎么接Python团队如果已经用Jenkins跑Java项目部署复用已有Jenkins集群来处理Python流水线是合理的选择。但注意不能简单把Java的流水线模板照搬给Python。Jenkins下跑Python通常的做法是用一个Docker容器作为构建节点在容器里装好指定的Python版本和工具链。构建服务器上如果再装一个pyenv来管理多版本会灵活很多。Jenkinsfile用Groovy写门槛比YAML高一些pipeline { agent { docker { image python:3.11-slim } } stages { stage(Install) { steps { sh pip install -r requirements-dev.txt } } stage(Lint) { steps { sh ruff check . } } stage(Test) { steps { sh pytest tests/ } } stage(Deploy) { when { branch main } steps { sh ./deploy.sh } } } }和GitHub Actions、GitLab CI相比Jenkins插件体系庞大能做复杂场景的定制但代价是维护成本高——版本升级、插件安全、节点管理都要持续投入。如果只是为了跑通一条Python部署流水线Jenkins的初始成本可能会让你觉得杀鸡用了牛刀。3. 搭建CI质量关卡从push到lint、测试、构建全自动3.1 一个能直接用的GitHub Actions CI工作流假设项目是一个FastAPI应用仓库结构大致是这样myapp/ ├── .github/workflows/ │ └── ci.yml ├── app/ │ └── main.py ├── tests/ │ └── test_health.py ├── requirements.txt └── requirements-dev.txt在.github/workflows/ci.yml里写入name: CI on: push: branches: [main, develop] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [3.10, 3.11, 3.12] steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: ${{ matrix.python-version }} cache: pip - name: 安装依赖 run: | python -m pip install --upgrade pip pip install -r requirements-dev.txt - name: 静态检查 run: ruff check app tests - name: 单元测试 run: pytest tests/ --covapp --cov-reportxml - name: 构建验证 run: python -m build这是最基础的CI能直接跑。下面逐个解释这些关键部分为什么这么写。3.2 Python版本矩阵多测一个版本多一份底气matrix配置让同一个job在多个Python版本上各跑一遍。要覆盖几个版本取决于项目运行在哪些环境。如果只是个小脚本只测3.11也够如果项目会被部署到服务器或者被别人安装使用我建议至少覆盖3.10到3.12。为什么这么看重多版本Python各版本之间有太多隐性差异。3.10引入match语句3.11对异常组和类型标注有增强3.12开始setuptools不再默认安装——这些都会影响依赖安装和运行行为。只在本地3.11跑过换到3.12环境很可能踩到setuptools的坑这个问题我后面排错部分专门讲。多版本矩阵的代价是流水线耗时成倍增加所以用fail-fast: true默认就是true只要任意一个版本失败就停止其他还在跑的版本节省资源。想收集所有版本的失败信息再一并修可以显式写成false。3.3 质量关卡的顺序先跑快的再跑慢的流程设计成依赖安装 - 静态检查 - 单元测试 - 构建验证。顺序不是随手排的核心原则是越便宜、越能快速反馈的检查越靠前。静态检查Ruff/Flake8通常几秒到十几秒就能跑完能挡住绝大部分风格问题、未使用变量、语法级错误。它先跑能在几分钟的测试前就帮开发者发现问题。单元测试更贵尤其涉及数据库或外部服务的可能要几分钟所以要等静态检查通过了再跑。最后的构建验证是把包真正构建一遍保证项目能被正确打包能拦截代码没问题但打不成包的问题。这个顺序还有一个隐性好处日志阅读体验。流水线失败时开发者第一眼看到的是最前面的红色step把它放得足够靠前能省去翻大量测试日志的麻烦。3.4 依赖拆分开发依赖和运行依赖别混在一起requirements.txt放运行依赖requirements-dev.txt放测试工具pytest、ruff、pytest-cov等。很多项目把两种依赖混在一个文件里CI里装了一堆不需要的包增加安装时间和出错概率。我一般这样组织requirements.txt只写生产环境需要的库比如fastapi、uvicorn、sqlalchemy。requirements-dev.txt里写-r requirements.txt pytest pytest-cov ruff这样CI里执行pip install -r requirements-dev.txt会先按生产依赖再按开发依赖安装职责清晰。3.5 依赖缓存把流水线从五分钟压到一分钟Python依赖安装是CI里最耗时的一步。一些项目不做缓存每次全部重新下载、重新编译几十个包的时候安装时间非常可观。GitHub Actions的setup-python从v5开始支持cache: pip会根据requirements文件内容生成缓存key自动把pip下载过的wheel缓存起来。依赖文件没变下次流水线直接命中缓存安装时间能省40%以上。这里有个重要认知缓存key必须精确到依赖文件内容。setup-python自带的缓存用的是requirements.txtrequirements-dev.txt的组合哈希。如果改了requirements文件缓存自动失效重来这是正确的行为——旧缓存里的wheel和新的依赖清单不匹配继续用反而会出问题。用GitLab CI时如果多个job都装依赖可以加一个全局cache定义paths指向PIP_CACHE_DIR让不同job之间共享pip缓存。缓存目录建议放在项目内相对路径比如$CI_PROJECT_DIR/.cache/pip这样cache配置和清理都方便。依赖下载速度在国内网络环境下会有明显差异。服务器或CI节点上我习惯配置PyPI镜像源比如清华、阿里云的PyPI镜像在pip.conf或GitLab CI变量里设置PIP_INDEX_URL就能显著减少拉取时间。4. 让CD真正落地从SSH直接部署到Docker镜像方案4.1 先选部署形态再写部署脚本部署部分的配置高度依赖目标环境。我建议先回答三个问题目标机器是裸机/虚拟机还是容器环境进程用systemd托管还是容器编排数据库、缓存等依赖服务在哪里部署形态优点缺点适合场景裸机/虚拟机 systemd直观、排查方便、无额外抽象环境隔离弱多项目容易互相影响个人项目、小团队、长期固定服务器Docker容器环境隔离好、镜像一致性强、回滚速度快需要维护Dockerfile和镜像仓库需要快速回滚和多环境复用的项目云平台托管免运维、扩缩容方便绑定具体平台迁移成本高弹性要求高的业务4.2 方案ASSH直接部署最简单的CD是让流水线通过SSH连上服务器在服务器上执行拉代码、装依赖、重启服务的命令。name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest environment: production steps: - uses: actions/checkoutv4 - name: SSH 部署到生产服务器 uses: appleboy/ssh-actionv1.0.0 with: host: ${{ secrets.DEPLOY_HOST }} username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.DEPLOY_SSH_KEY }} script: | cd /srv/myapp git pull origin main source .venv/bin/activate pip install -r requirements.txt --upgrade python manage.py migrate sudo systemctl restart myapp这个方案实现成本低但对服务器的规范要求反而更高。服务器上必须有独立的虚拟环境用systemd管理服务而且要保证git pull不会失败。否则一旦服务器上有未提交的改动、或某个依赖装了一半部署就会卡在中间状态。我在实际使用中发现git pull在服务器上并不是最稳妥的更新方式。服务器上如果有本地改动pull会直接冲突终止。我更倾向于在服务器上执行git fetch origin main git reset --hard origin/main但这会把服务器上任何临时改动覆盖掉所以只适合服务器目录就是纯粹部署目录的场景。更安全的做法是打包发布在CI里把代码打成tar包或wheel包传到服务器新目录再切换软链并重启服务。这样部署更接近发布新版本而不是更新工作副本。如果你在维护重要服务强烈建议往这个方向演进。4.3 方案BDocker镜像构建与推送如果服务已经容器化部署就变成两件事把代码构建成镜像并推送到仓库然后让服务器拉取新镜像并重启容器。好处是服务器上不需要装Python、不需要有虚拟环境所有依赖都锁在镜像里。先写一个适合部署的Dockerfile我用的是python:slim镜像而不是full镜像能减掉大量体积FROM python:3.11-slim WORKDIR /app ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 \ PIP_NO_CACHE_DIR1 COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]注意还要写.dockerignore它的重要性不亚于.gitignore.venv __pycache__ *.pyc .git .env tests docs构建和推送可以在GitHub Actions里完成name: Build Image on: push: branches: [main] tags: [v*] jobs: docker: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: docker/setup-buildx-actionv3 - name: 登录容器镜像仓库 uses: docker/login-actionv3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: 构建并推送镜像 uses: docker/build-push-actionv5 with: context: . push: true tags: | ghcr.io/yourname/myapp:${{ github.sha }} ghcr.io/yourname/myapp:latest推送之后服务器上的发布动作由容器编排工具执行。用docker compose的话可以在CI里SSH到服务器执行docker compose pull docker compose up -d。关键点是给镜像打上不可变的tag最推荐用git commit SHA作为镜像tag能精确定位到线上跑的是哪个提交出问题可以直接回滚到上一个SHA对应的镜像。4.4 密钥管理比流水线本身更值得花时间的一环CD流水线掌握了代码仓库和服务器的高权限密钥泄露比部署失败严重得多。我的几个硬性习惯任何密钥、密码、token都放到CI平台的Secrets/变量体系里禁止明文出现在YAML或代码仓库。为部署场景单独创建SSH密钥不要用日常开发者的个人密钥。CI的部署密钥加到服务器authorized_keys里但只给它专用账号或限制命令范围。使用environment级别的密钥隔离。GitHub Actions里先配置environment: production再把密钥挂到environment secrets下只有这个环境的job能读取比放在repository secrets更安全尤其适合生产部署权限收口的场景。部署账号做最小权限只需要执行git pull、systemctl restart myapp或docker compose up就够了没必要给整个root shell。虽然有人图省事直接给root但出事之后后悔的成本远远大于前期配置成本。5. Python项目CI/CD的经典坑位与一次真实排错5.1 CI环境是全新建的别指望它继承任何本机状态新手写CI时最容易犯的错是我本地能装CI肯定也能装。本地环境经过长期使用里面已经躺着几十个Python包有些碰巧成了隐式依赖CI每次从零开始缺什么都不会自动补。典型表现是本地import某个库没问题CI却报ModuleNotFoundError。原因常常是本地能装成功但requirements里根本没写这个库或者某个库的版本范围不对。解决思路只有一个做到依赖清单完整、版本明确而不是靠本地环境的巧合。5.2 requirements.txt锁了不等于锁对了很多人跑pip freeze requirements.txt然后提交上去就以为万事大吉了。pip freeze会把你环境里所有包都锁定包括大量间接依赖文件又长又脆换个环境安装时极易冲突。更优雅的做法是用pip-tools管理requirements.in里只写直接依赖然后pip-compile生成带完整传递依赖的requirements.txt锁得准、更新也方便。另一种情况是requirements.txt里写的是范围约束比如fastapi0.100没有锁精确版本。这在CI里跑没问题但数月后部署到服务器时解析出的fastapi版本可能和当时测试完全不同行为也跟着变。对生产项目要么用锁文件工具链pip-tools、poetry、pipenv要么在发布流水线里把依赖解析结果记录下来。5.3 测试依赖外部服务流水线会时好时坏如果测试用例连接了本地PostgreSQL、Redis或其他外部服务CI全绿与否完全取决于服务在不在、数据是否就绪。这种时好时坏的流水线比直接红还让人头疼因为它会让人慢慢对流水线的失败信号麻木。解决办法是让测试环境在流水线内自包含。GitHub Actions支持services配置在job里直接起一个配套容器jobs: test: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: POSTGRES_USER: app POSTGRES_PASSWORD: app POSTGRES_DB: app_test ports: - 5432:5432 options: - --health-cmd pg_isready -U app --health-interval 10s --health-timeout 5s --health-retries 5services里的容器和job在同一个网络测试代码通过localhost和映射端口访问即可。用health-cmd等服务真正就绪再跑测试就不会出现连不上数据库的偶发失败。GitLab CI的services关键字思路类似。如果项目简单到不需要数据库让测试代码使用临时文件或内存数据库也行但对多数涉及数据库的项目来说把数据库放进services里更贴近生产环境。5.4 真实排错记录本地全绿CI为什么红了分享一个我帮朋友项目排的真实案例现象很典型push之后GitHub Actions的pytest红了报错ModuleNotFoundError: No module named pkg_resources朋友本地跑同样的测试全绿他百思不得其解。排查过程分三步走第一步点开CI日志确认失败发生在test这一步报错发生在导入某个依赖库时。第二步对比他本地和CI的Python版本本地3.10CI的matrix里有3.12。第三步查Python 3.12的变更——从3.12开始默认安装的setuptools行为发生了变化很多旧库的代码会直接import pkg_resources而在干净环境里没有setuptools自然就找不到这个模块。为什么本地全绿因为本地的Python 3.10环境在几年前装过setuptools包一直存在掩盖了依赖缺失。修复很简单在requirements.in或requirements.txt里显式声明setuptools或者把那个依赖库升级到支持新Python版本的版本。这个案例给我留下很深印象本地能跑很多时候只是幸存者偏差环境里多出来的每一个包都可能掩盖一个真实缺陷。6. 用了一年CI/CD后我给Python团队的实用建议6.1 流水线不是建完就完要当产品来维护流水线建好之后不是一劳永逸的。依赖会变、Python版本会变、服务端行为也会变几个月不看的流水线很容易出现昨天还绿今天突然红了的场面。我给自己定的规矩是每周至少看一眼流水线健康状态GitHub仓库的Actions页面能直接看到最近几条workflow的运行成功率如果连续一周没有新的流水线运行记录我会怀疑是不是触发条件出问题了。依赖方面也要定时更新。每月用pip-review这类工具过一遍直接依赖看有没有安全更新更新后用流水线自动跑全量测试。更新依赖不是想一出是一出而是把流水线当作改变的缓冲——哪怕升级某个库后确实引入问题最坏也是流水线变红不会直接打崩生产环境。6.2 提交粒度小一点CI反馈才快把很长一段时间的工作攒成一次大push是流水线最难受的使用方式。改动范围大、涉及模块多一旦测试失败你得在一堆diff里猜是哪里引起的。相反每次提交小一些、范围单一一些流水线失败后能很快定位到是哪个commit引入的。我并不是说每次提交都要碎成芝麻那么大而是让每次push形成一个逻辑上完整的变更单元一个新功能、一次重构、一个bugfix。配合分支保护规则让主干永远保持绿灯。6.3 部署失败一定要有后路CD越强大失败时的破坏面也越大。一次自动部署把生产环境打挂如果没有任何回滚机制CI/CD就会从提效工具变成背锅神器。最简单可行的回滚策略是保留最近N个镜像tag出问题后重新部署上一个tag。如果用SSH直接部署且没有镜像那就在服务器上保留上一个发布目录的备份切换软链就能回滚。这些策略不复杂关键是提前想好并把命令写进部署文档不要等事故发生后再翻历史命令。6.4 不要拿一套模板套所有项目网上有很多现成的CI/CD模板我也参考过不少。模板最大的问题是替你做了太多假设假设你用pytest、假设你只有一个服务、假设部署方式一样。实际项目里有人用poetry、有人用pipenv、有人用conda有人部署Docker、有人部署systemd任何一个假设不成立模板就需要大改。我现在的做法是以基础模板为起点为每一类项目Web服务、数据脚本、CLI工具维护一套精简的流水线骨架再按项目需求增删步骤。骨架里的每个步骤我都要求自己清楚知道它的作用和存在的理由而不是单纯大家都在这么写所以我也写上。说实话CI/CD这套东西前期投入的时间不算少但收益是持续累积的。它不会让每个commit都变绿但会让每个问题都提前暴露在它该出现的地方。对我个人来说最大的变化反而不是部署更快了而是发布这件事不再依赖某个人的记忆和状态——这比任何事情都值。