用官方 ci-docker-image 打通 Dokku 通用 CI/CD 集成环境变量自动检测与多平台部署实战【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku本文围绕 Dokku 官方提供的dokku/ci-docker-image镜像讲解在缺乏现成插件或官方集成时如何通过“Docker 任务 环境变量注入”的方式将任意 CI/CD 系统接入 Dokku 应用部署流程。读完本文你将掌握该镜像的最简用法、各主流 CI 平台GitHub Actions、GitLab CI、Woodpecker CI 等的等效配置写法以及部署前必须准备好的应用、SSH 密钥与仓库克隆条件。为什么需要通用 CI/CD 集成方案Dokku 的部署模型建立在 Git 之上开发者将代码git push到 Dokku 服务器服务器上的pre-receive钩子触发完整的构建与发布流程见 Git 部署文档 与 receive-app 触发器。这一模型天然适合 CI/CD 自动化——因为对 Dokku 而言由 CI 触发部署与由本地开发者推送在本质上没有区别。但当某个 CI 系统没有现成的 Dokku 插件、Action 或文档化集成时就需要一种通用的接入方式。Dokku 项目的答案是官方 Docker 镜像dokku/ci-docker-image其仓库与 README 可在项目官方组织下找到它把推送到 Dokku这一动作封装成一个可独立运行的容器任务任何能以Docker 任务形式运行、并支持注入环境变量的 CI 系统都可以使用它镜像内部自动识别来自常见 CI 平台的环境变量无需针对每家平台写特判逻辑唯一需要你提供的两个关键信息是目标 Dokku 仓库地址GIT_REMOTE_URL和用于认证的 SSH 私钥SSH_PRIVATE_KEY。自动检测的 CI 平台只要 CI 任务运行在 Docker 容器中且支持环境变量注入以下平台的构建环境变量就会被镜像自动检测并用于部署无需额外配置CircleCICloudBeesDroneGitHub ActionsGitLab CISemaphoreCITravis CIWoodpecker CI对于这些平台镜像内部会读取各自约定的环境变量如构建号、仓库地址、分支名等来自动组装部署参数对于其他未列出的平台也仍然可以通过显式设置GIT_REMOTE_URL等变量完成部署——这正是通用二字的含义。最简用法一条 docker run 命令dokku/ci-docker-image的最简用法是在项目根目录下执行# 其中 .env 文件包含 GIT_REMOTE_URL 与 SSH_PRIVATE_KEY 两个变量 docker run --rm -v$PWD:/app --env-file.env dokku/ci-docker-image dokku-deploy逐项拆解这条命令参数作用--rm容器执行完毕后自动删除避免 CI 机器上残留容器-v$PWD:/app将当前项目目录挂载到容器内的/app使镜像能读取你的仓库代码--env-file.env从.env文件批量注入环境变量避免在命令行暴露密钥dokku/ci-docker-image官方 CI 部署镜像dokku-deploy镜像内的部署入口命令读取环境变量并执行 git push.env文件中至少需要两个变量GIT_REMOTE_URLssh://dokkudokku.me:22/appname SSH_PRIVATE_KEY-----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----GIT_REMOTE_URLDokku 应用仓库的 SSH 地址格式为ssh://dokku服务器地址:端口/应用名。注意用户名必须是dokku否则推送会被拒绝见 应用部署文档。SSH_PRIVATE_KEYCI 机器上用于认证的 SSH 私钥内容。私钥对应的公钥必须先添加到 Dokku 服务器见下文部署前置条件。更多配置示例与进阶用法如指定分支、超时、额外参数等参见ci-docker-image仓库自身 README官方文档 generic.md 也明确指引读者前往该处获取完整说明。部署前置条件在 Dokku 侧做好准备通用镜像只是执行推送的客户端真正接收部署的是 Dokku 服务器。在接入任何 CI 之前请确认以下条件已满足1. 应用必须已存在Dokku 可以通过git push自动按 remote 名称创建应用但显式创建更可控# 在 Dokku 主机上 dokku apps:create appname2. 添加 CI 的 SSH 公钥Dokku 通过dokku/.ssh/authorized_keys管理用户授权SSH 密钥是推送部署的首选认证方式详见 用户管理文档。将 CI 生成的公钥添加到 Dokku# 在 Dokku 主机上KEY_NAME 为该密钥的标识名 dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub也可以从 CI 机器远程添加cat ~/.ssh/id_rsa.pub | ssh rootdokku.me dokku ssh-keys:add KEY_NAME提示KEY_NAME必须唯一重复使用同名会报错名称中包含admin的密钥拥有额外添加密钥的远程权限。3. 服务器指纹确认首次连接时 SSH 会询问known_hosts指纹确认这在无人值守的 CI 环境中会导致推送卡住。你可以在 Dokku 主机上预先把服务器指纹加入 CI 环境的 known_hosts或使用git:allow-host在 Dokku 侧管理主机信任见 Git 部署文档。4. 避免浅克隆shallow cloneDokku 的 Git 部署流程不支持浅克隆若 CI 在检出代码时使用了--depth 1之类的参数推送会失败或行为异常见 Git 部署文档 中的明确警告。因此 CI 配置中必须做完整克隆这一点在各平台示例里都有对应处理见下文。各 CI 平台配置速览ci-docker-image的通用用法在各平台上有几乎一一对应的写法。以下三份示例分别来自仓库内同目录的 github-actions.md、gitlab-ci.md 与 woodpecker-ci.md可作为参照模板。GitHub ActionsGitHub 生态有官方 Actiondokku/github-action不属于通用镜像路线但同为官方推荐方案--- name: deploy on: push: branches: - master jobs: deploy: runs-on: ubuntu-24.04 steps: - name: Cloning repo uses: actions/checkoutv4 with: fetch-depth: 0 # 完整克隆避免浅克隆被 Dokku 拒绝 - name: Push to dokku uses: dokku/github-actionmaster with: git_remote_url: ssh://dokkudokku.me:22/appname ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}注意fetch-depth: 0正是为了规避上文提到的浅克隆限制。GitLab CIGitLab CI 直接使用dokku/ci-docker-image是通用镜像路线的典型范例--- 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-unlockdokku-unlock用于在部署结束后释放锁防止并发部署互相阻塞。Woodpecker CIwhen: - event: push branch: main clone: git: image: woodpeckerci/plugin-git settings: partial: false # 完整克隆 depth: 0 steps: - name: deploy image: dokku/ci-docker-image environment: GIT_REMOTE_URL: ssh://dokkudokku.me:22/appname SSH_PRIVATE_KEY: from_secret: DOKKU_ME_SSH_DEPLOY_KEY commands: - dokku-deployWoodpecker 示例的两个要点与通用镜像的要求完全对应用完整克隆替换默认浅克隆partial: falsedepth: 0否则 Dokku 会拒绝推送只需GIT_REMOTE_URL与SSH_PRIVATE_KEY通过from_secret引用密钥即可完成部署。三份配置放在一起可以清晰看到无论平台如何变化完整克隆 GIT_REMOTE_URLSSH_PRIVATE_KEYdokku-deploy就是ci-docker-image的最小公约数。使用要点与排错建议端口与地址格式GIT_REMOTE_URL中ssh://dokkudokku.me:22/appname的:22是 Dokku 的 SSH 端口若你的 Dokku 使用了非标准端口请相应调整。部分 Git 客户端不支持短上游语法统一使用ssh://前缀的完整格式更稳妥。私钥格式确保SSH_PRIVATE_KEY中的换行在注入后仍然保留在 GitHub Secrets 中粘贴多行值即可在.env文件中则用引号包裹。环境变量自动检测在已支持列表内的平台镜像会自动读取平台环境变量你只需显式提供GIT_REMOTE_URL与SSH_PRIVATE_KEY未列出的平台同样可用只要保证变量注入即可。部署分支默认推送master分支触发部署如需其他分支可通过 Dokku 的git:set app deploy-branch branch调整见 Git 部署文档或在 CI 侧做分支映射。进一步查阅通用镜像的完整配置选项与高级示例以ci-docker-image仓库 README 为准Dokku 侧的 Git 部署能力git:sync、git:auth、git:allow-host等命令详见 Git 部署文档。【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考