本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。概述本文档记录了使用Jenkins Pipeline配合Docker实现自动化 CI/CD 的完整过程。目标是从 Git 仓库Gitee拉取代码 → 构建 Docker 镜像 → 部署运行容器全程自动化。项目架构语言Python FastAPI包管理uv基于 pyproject.toml构建Docker 多阶段构建部署Docker 容器运行CI/CDJenkins PipelineDeclarative Pipeline前置条件组件说明Jenkins 服务已安装并正常运行本文使用 docker-compose 部署 Jenkins代码仓库Gitee或其他 Git 仓库仓库内已有 Dockerfile 和 JenkinsfileDocker 环境Jenkins 所在节点能执行 docker 命令一、创建管道流水线Jenkins 首页 →New Item→ 输入任务名称如fastapi-demo → 选择Pipeline→ OK二、各配置选项详解1. Discard old builds丢弃旧构建作用自动清理旧的构建记录防止磁盘被撑爆。推荐配置Strategy:Log RotationDays to keep builds:7保留最近 7 天的构建Max # of builds to keep:20最多保留 20 次构建记录2. GitHub project项目链接作用在 Jenkins 任务页面显示一个跳转到仓库的快捷链接方便快速查看源码。Project url:填你的仓库地址如https://gitee.com/peng-chao2005/test此字段非必填纯辅助功能。3. Triggers构建触发器触发器决定什么时候自动开始构建有几种方式3.1 Build periodically定时构建不管代码有没有变化到点就执行一次。Schedule 语法Cron 表达式H 2 * * * # 分段分钟 小时 日期 月份 星期 # H 是 Jenkins 的哈希分散机制防止所有任务同时触发常用示例表达式含义H/5 * * * *每 5 分钟构建一次H * * * *每小时构建一次H 2 * * *每天凌晨 2 点构建一次H 9 * * 1-5工作日周一至周五早上 9 点daily每天一次3.2 Poll SCM轮询代码仓库每隔一段时间自动检查 Git 仓库有没有新提交有则触发构建。H/5 * * * * # 每 5 分钟检查一次仓库变更3.3 GitHub hook trigger / GitLab webhookWebhook 触发代码 push 时由仓库主动通知 Jenkins立即触发构建实时性最高。需要配合在仓库 Settings → Webhooks 中配置 Jenkins 地址GitHub:http://Jenkins-IP:8080/github-webhook/Gitee: 在仓库 → 管理 → WebHooks 中添加本文使用 Build periodically适合学习和测试场景。生产环境推荐 Webhook 方式。三、Pipeline 部分配置Pipeline 区域是整个任务的核心定义了 Jenkins要去哪里拿代码以及按什么脚本执行。Definition定义方式有两种选择方式说明适用场景Pipeline script直接在 Jenkins 网页里写构建脚本临时测试、快速验证Pipeline script from SCM推荐 ✅从 Git 仓库读取 Jenkinsfile版本化管理、团队协作本文使用 Pipeline script from SCM。关键字段说明Repository URL仓库地址填你的 Git 仓库地址https://gitee.com/你的用户名/你的仓库.gitCredentials凭据公开仓库可以不填凭据私有仓库需要添加登录凭据本文拉取的是Gitee私有仓库添加凭据步骤点击Add→Jenkins填写字段内容KindUsername with passwordUsernameGitee 用户名PasswordGitee 登录密码IDgitee-creds自定义标识注意Gitee 的默认分支是master不是main所以 Branches to build 要填*/master。Branch Specifier分支指定*/master如果不填默认使用仓库的 HEAD 分支。也可以指定为*/develop、*/feature/*等。Script Path脚本路径Jenkinsfile 在仓库中的路径在根目录填Jenkinsfile⚠️ 这是最容易出错的地方必须和仓库里的实际路径完全一致包括大小写。本文的 Jenkinsfile 在仓库根目录所以填Jenkinsfile。Lightweight checkout轻量级检出勾选后Jenkins 先只下载 Jenkinsfile 本身来解析流水线结构解析完成后再全量拉取代码。建议勾选可以节省一次不必要的全量下载。四、安装 Docker Pipeline 插件Jenkins 默认不认识docker.build()等命令需要安装插件。操作步骤Jenkins 首页 →Manage Jenkins→Plugins切换到Available plugins选项卡搜索Docker Pipeline勾选 → 点击Install without restart安装完成后如有提示则重启 Jenkins如果不安装此插件会报如下错误groovy.lang.MissingPropertyException: No such property: docker for class: groovy.lang.Binding五、Docker 环境配置问题docker: not found如果 Jenkins 是以容器方式运行的容器内部默认没有 docker 命令执行docker build会报错/var/jenkins_home/workspace/xxx: docker: not found解决方法在 Jenkins 容器的docker-compose.yml中挂载宿主机 Dockername:Jenkinsservices:jenkins:image:jenkins/jenkins:ltscontainer_name:jenkinsuser:rootports:-34560:8080-34561:50000volumes:-/volume/Jenkins/jenkins_home:/var/jenkins_home-/var/run/docker.sock:/var/run/docker.sock-/usr/bin/docker:/usr/bin/docker三行 volumes 的作用挂载项作用/var/run/docker.sock让容器内的 Docker CLI 连接宿主机的 Docker 守护进程/usr/bin/docker把宿主机上的 docker 二进制文件共享到容器内/volume/Jenkins/jenkins_home持久化 Jenkins 配置和数据重启不丢失注意修改 docker-compose.yml 后不能只用restart必须docker-compose down docker-compose up -d重新创建容器volumes 配置才会生效。Jenkins 的配置数据会保留因为挂载了持久化目录。六、完整的 Jenkinsfilepipeline { // 在哪台机器上跑 agent any // 环境变量 environment { // 按你的项目修改 IMAGE_NAME fastapi-demo IMAGE_TAG ${BUILD_NUMBER} CONTAINER_NAME fastapi-demo HOST_PORT 8858 CONTAINER_PORT 8000 // } // 流水线阶段 stages { stage(拉取代码) { steps { checkout scm } // 从配置的 Git 仓库拉取最新代码 } stage(构建 Docker 镜像) { steps { script { docker.build(${IMAGE_NAME}:${IMAGE_TAG}) // 也打 latest 标签方便回滚时指定 sh docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:latest } } // 等价于: docker build -t fastapi-demo:3 . docker tag fastapi-demo:3 fastapi-demo:latest } stage(停止并删除旧容器) { steps { script { sh docker stop ${CONTAINER_NAME} || true docker rm ${CONTAINER_NAME} || true } } // || true 确保第一次部署没有旧容器时也不会报错终止 } stage(启动新容器) { steps { script { sh docker run -d \\ --name ${CONTAINER_NAME} \\ --restart unless-stopped \\ -p ${HOST_PORT}:${CONTAINER_PORT} \\ ${IMAGE_NAME}:${IMAGE_TAG} } } // 等价于: docker run -d --name fastapi-demo --restart unless-stopped -p 8858:8000 fastapi-demo:3 } stage(清理旧镜像保留最近 5 个) { steps { script { sh docker image prune -f --filter until24h || true } } // 删除 24 小时前的不再使用的镜像节省磁盘空间 } } // 构建完成后的操作 post { success { echo ✅ 部署成功访问 http://服务器IP:${HOST_PORT} sh docker ps --filter name${CONTAINER_NAME} --format 容器状态: {{.Status}} } failure { echo ❌ 部署失败请查看构建日志 } } }完整执行流程代码 Push 到 Gitee │ ▼ Jenkins 触发构建 │ ├── [1] checkout scm 从 Gitee 拉取最新代码 ├── [2] docker build 构建镜像 fastapi-demo:3 │ (多阶段构建用 uv 安装依赖) ├── [3] docker stop 停止旧容器首次无则跳过 ├── [4] docker rm 删除旧容器首次无则跳过 ├── [5] docker run 启动新容器映射 8858:8000 ├── [6] docker prune 清理 24 小时前的旧镜像 └── [7] post 输出 ✅ 或 ❌ 结果七、流水线常用命令解析checkout scm作用从任务配置的 Git 仓库拉取代码说明Jenkins 自动生成等价于git clone 切换到指定分支无需手动写参数仓库地址、凭据、分支都在配置界面填好了docker.build()作用构建 Docker 镜像等价于docker build -t name .来源Docker Pipeline 插件提供的 Groovy 方法注意不装插件会报No such property: dockersh ...作用在 Jenkins 节点上执行 Shell 命令三引号Groovy 的多行字符串可以换行写命令${变量}引用在 environment 中定义的变量docker run -d参数作用-d后台运行--name指定容器名方便后续管理--restart unless-stopped自动重启策略除非手动 stop-p 宿主机端口:容器端口端口映射|| true作用命令执行失败时忽略错误流水线继续执行场景docker stop时容器不存在会报错加上|| true让流水线不被中断post作用所有 stage 执行完毕后执行success全部成功时触发failure任意 stage 失败时触发可以扩展发送钉钉通知、邮件通知等八、构建结果验证构建成功后查看控制台输出点构建记录 →Console Output确认各 stage 都是绿色通过检查容器状态在服务器上执行docker ps查看容器是否运行访问接口验证浏览器打开http://服务器IP:8858/docs结果截图FastAPI 项目接口一览接口URL说明根路径http://IP:8858/返回基础信息健康检查http://IP:8858/health{status: ok}接口信息http://IP:8858/api/info服务版本和时间戳API 文档http://IP:8858/docsSwagger 交互式文档回声测试POST http://IP:8858/api/echo传入{message: hello}返回回声九、常见问题排查报错原因解决No such property: docker for class: groovy.lang.Binding未安装 Docker Pipeline 插件Manage Jenkins → Plugins → 安装 Docker Pipelinedocker: not foundJenkins 容器内没有 docker 命令在 docker-compose.yml 挂载/usr/bin/dockerpermission denied连接 Docker socketJenkins 用户无权限使用user: root或在宿主机将 Jenkins 用户加入 docker 组Script not found: xxx/JenkinsfileScript Path 路径错误检查 Jenkinsfile 在仓库中的实际路径port is already allocated端口被占用修改HOST_PORT或先docker stop占用端口的容器Could not find credentialsGit 凭据无效重新添加凭据检查 Token 是否过期十、总结通过 Jenkins Pipeline Docker实现了代码推送 → 自动构建 → 自动部署 → 服务可用 全程不需要手动登录服务器执行命令核心知识点Jenkins Pipeline使用 Declarative Groovy 语法stage/steps 结构化编排任务Docker Pipeline 插件提供了docker.build()等便捷方法容器化 Jenkins需要挂载宿主机 Docker socket 和 docker 二进制文件才能执行 docker 命令Jenkinsfile 与代码同仓库管理方便版本控制和团队协作Discard old builds和docker image prune都是必要的运维策略防止磁盘占满