使用 GitLab CI 与 dokku/ci-docker-image 自动化部署 Dokku 应用【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku本文是一份面向 GitLab 用户的 Dokku 部署实战指南讲解如何利用官方提供的dokku/ci-docker-image容器镜像在 GitLab CI 流水线中实现「代码推送即自动部署」的完整流程。阅读本文后你将掌握最简 GitLab CI 配置的每一个字段含义、dokku-deploy/dokku-unlock的执行机制、SSH 远程与密钥的配置要点并能将其扩展为多分支、多环境的生产级流水线。为什么用 GitLab CI 部署 DokkuDokku 是一个基于 Docker 的 PaaS应用的传统部署方式是本地执行git push dokku main见 application-deployment.md。当团队使用 GitLab 托管代码并希望实现持续部署时可以在 GitLab CI 的 runner 中模拟这一 git push 行为——但前提是 runner 环境里必须有可用的 git、ssh 客户端并正确配置远程地址与密钥。Dokku 项目为此提供了官方 CI 容器镜像dokku/ci-docker-image它内置了部署所需的一切工具与脚本。镜像内的dokku-deploy脚本会自动完成「读取环境变量 → SSH 连接 Dokku 服务器 → 推送代码触发部署」的完整链路使用户无需在 .gitlab-ci.yml 里手工编写 ssh 与 git 命令。GitLab CI 是该镜像明确支持自动检测的环境变量来源之一详见 generic.md。最简配置一份可直接落地的 .gitlab-ci.yml原文档给出的最简示例完整如下--- image: dokku/ci-docker-image stages: - deploy variables: GIT_DEPTH: 0 deploy: stage: deploy only: - master variables: GIT_REMOTE_URL: ssh://dokkudokku.me:22/appname script: - dokku-deploy after_script: - dokku-unlock这份配置只有 20 余行但每一行都对应一个关键行为下面逐项拆解。image: dokku/ci-docker-image指定所有 job 的运行镜像为官方 CI 镜像。该镜像内置了dokku-deploy、dokku-unlock等部署脚本以及必要的 ssh/git 工具链。它与其它 CI 平台GitHub Actions、Woodpecker CI 等复用同一镜像用法保持一致便于在多 CI 平台间迁移可参考 github-actions.md 与 woodpecker-ci.md。GIT_DEPTH: 0这是本配置中最重要的一个全局变量。GitLab CI 默认采用浅克隆shallow clone拉取代码而 Dokku 的 git 部署不支持浅克隆——git.md 明确警告浅克隆推送可能导致未定义行为部署前应确保本地仓库为完整克隆。设置GIT_DEPTH: 0即要求 GitLab 执行完整克隆保证dokku-deploy推送时携带完整提交历史。Woodpecker CI 文档中也采用了完全相同的处理用depth: 0替代默认浅克隆。stages与only: masterstages: - deploy定义流水线阶段。最简场景只有一个deploy阶段实际项目中可以在前面追加test、build等阶段仅让部署 job 属于deploy阶段。only: master仅在master分支的推送事件上触发部署。这与 Dokku 的默认部署分支一致——Dokku 默认部署推送到master分支的代码。若项目主分支为main或需支持其它分支见下文「非 master 分支的部署」。GIT_REMOTE_URL在 job 级variables中指定部署目标远程地址GIT_REMOTE_URL: ssh://dokkudokku.me:22/appname其格式为ssh://dokkuHOSTNAME.TLD:HOST_PORT/APP_NAME。结合 remote-commands.md 可知Dokku 支持的远程格式共有三种格式示例说明dokkuHOST:APP_NAMEdokkudokku.me:appname短格式使用默认 SSH 端口ssh://dokkuHOST/APP_NAMEssh://dokkudokku.me/appname显式 scheme默认端口ssh://dokkuHOST:PORT/APP_NAMEssh://dokkudokku.me:22/appname显式 scheme 与端口三个要点用户名必须是dokku。Dokku 通过系统用户dokku的 SSH 通道接收推送使用其它用户名会导致推送失败见 application-deployment.md。:22是默认 SSH 端口若 Dokku 服务器修改了 SSH 端口需在此同步修改。appname即 Dokku 应用名推送时若应用尚不存在Dokku 会自动按该名称创建应用。script: dokku-deploydokku-deploy是镜像内核心脚本它读取GIT_REMOTE_URL与 SSH 私钥等环境变量通过 SSH 将当前 CI 工作目录的代码推送到 Dokku 服务器等效于本地执行git push部署。该命令同时会在 Dokku 端获取部署锁防止并发部署相互干扰。after_script: dokku-unlockdokku-unlock与dokku-deploy成对出现。由于after_script无论 job 成功与否都会执行将它放在这里可以确保即使部署失败Dokku 端的部署锁也能被释放避免后续流水线被卡死。因此不建议省略此步骤。运行机制部署锁与 SSH 链路从镜像的工作方式可以推断其部署链路大致为GitLab runner 以完整克隆拉取代码GIT_DEPTH: 0保证runner 以dokku/ci-docker-image启动容器注入GIT_REMOTE_URL、SSH_PRIVATE_KEY等环境变量dokku-deploy校验配置、尝试获取 Dokku 端部署锁随后通过 SSH 建立到dokkudokku.me的连接将仓库代码推送到目标应用仓库触发 Dokku 的pre-receive钩子与构建部署流程job 结束无论成败由after_script中的dokku-unlock释放部署锁。这一「远程命令 git push」模型与 Dokku 的 SSH 命令体系完全同构。若需要在流水线中额外执行 Dokku 管理命令可参照 remote-commands.md 的方式ssh -t dokkudokku.me command传递参数时使用--分隔例如ssh -t dokkudokku.me -- apps:list。部署前的准备工作服务器端确认用户与 SSH 权限确保 Dokku 服务器已配置至少一个可通过 SSH 登录的用户。部署推送使用的dokku用户需要持有你的公钥——application-deployment.md 与 user-management.md 介绍了用户管理与密钥导入方式。本地推送遇到permission denied时可用ssh-add -k ~/your private key注册私钥。GitLab 端注入 SSH 私钥dokku-deploy需要 SSH 私钥才能免密登录 Dokku 服务器。虽然最简示例未展示但结合 generic.md 可知镜像约定的部署环境变量为GIT_REMOTE_URL与SSH_PRIVATE_KEY。在 GitLab 项目设置 → CI/CD → Variables 中创建SSH_PRIVATE_KEY类型选 File 或 Variable 均可值为与服务器公钥配对的私钥内容并勾选「保护变量 / Masked」以限制其仅在受保护分支的受保护 job 中可用避免私钥泄露。进阶用法非 master 分支的部署Dokku 默认仅部署master分支的推送。若 GitLab 项目主分支是main有两种处理方式保持only: [main]触发同时在 Dokku 服务器上调整应用的部署分支# 在 Dokku 主机上为单个应用指定部署分支 dokku git:set appname deploy-branch main # 或全局生效 dokku git:set --global deploy-branch main若只想临时部署某个本地分支可在本地等价地执行git push dokku SOME_BRANCH_NAME:master完成分支映射详见 git.md 的「Changing the deploy branch」。多环境流水线可以基于 GitLab 的rules或only关键字为 production / staging 各定义一个 deploy job每个 job 使用不同的GIT_REMOTE_URL指向不同的 Dokku 应用deploy:staging: stage: deploy only: - develop variables: GIT_REMOTE_URL: ssh://dokkudokku.me:22/appname-staging script: - dokku-deploy after_script: - dokku-unlock deploy:production: stage: deploy only: - master variables: GIT_REMOTE_URL: ssh://dokkudokku.me:22/appname script: - dokku-deploy after_script: - dokku-unlock若担心并发部署锁冲突可配合 GitLab 的resource_group让同一应用的部署 job 串行执行。结合其它 CI 平台同一套dokku/ci-docker-image也可用于 GitHub Actionsdokku/github-action见 github-actions.md与 Woodpecker CIwoodpecker-ci.md三者的核心输入一致完整的代码克隆 GIT_REMOTE_URL SSH 私钥。当 CI 平台未被内置支持时generic.md 还提供了通用的 Docker 运行方式# 其中 .env 文件包含 GIT_REMOTE_URL 与 SSH_PRIVATE_KEY docker run --rm -v$PWD:/app --env-file.env dokku/ci-docker-image dokku-deploy常见问题与注意事项浅克隆报错忘记设置GIT_DEPTH: 0是 GitLab CI 部署失败的最常见原因Dokku 不支持浅克隆推送务必保持该变量为0。用户名不是 dokkuGIT_REMOTE_URL中用户名必须为dokku否则 SSH 认证会失败。私钥未注入确保SSH_PRIVATE_KEY变量存在且与服务器端公钥配对受保护分支需要受保护的变量才能读取。部署锁残留任何时候都保留after_script: dokku-unlock防止失败 job 遗留部署锁阻塞后续部署。域名替换示例中的dokku.me是文档约定占位域名实际使用时应替换为 Dokku 服务器的真实域名或 IPVagrant 虚拟机场景下dokku.me才指向虚拟机。总结将 GitLab CI 与 Dokku 结合部署核心只有四件事使用官方镜像dokku/ci-docker-image、设置GIT_DEPTH: 0保证完整克隆、配置GIT_REMOTE_URL指向 Dokku 应用、注入 SSH 私钥并成对使用dokku-deploy/dokku-unlock。在此基础上借助 Dokku 的git:set deploy-branch与 GitLab 的 job 规则即可轻松扩展出多分支、多环境的持续部署流水线。更深入的服务端行为可继续阅读 git.md部署分支、仓库同步、remote-commands.mdSSH 命令与官方客户端与 application-deployment.md完整部署教程。【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考