如何在开发环境测试 Coolify 的自托管升级流程【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 提供了自托管实例的自动升级能力界面里的Check for Updates从 CDN 的versions.json拉取最新版本点击Upgrade后会下载upgrade.sh并在实例本机执行升级。如果你改动了升级链路相关的代码需要在升级真正推给生产环境之前先在一台一次性自托管测试实例上把「安装旧版本 → 检查更新 → 执行升级」完整走一遍。仓库的 AGENTS.md 给出了官方的四步测试工作流本文按该工作流展开并核对每一步在源码里的实际行为。需要先明确一个边界这套流程不能跑在docker compose -f docker-compose.yml -f docker-compose.dev.yml up启动的本地 dev 栈上。升级动作的入口 UpdateCoolify 和检查更新的 CheckForUpdatesJob 开头都有if (isDev()) { return; }判断而isDev()的定义是config(app.env) local见 shared.php。也就是说APP_ENVlocal的 dev 栈既不会检查更新点 Upgrade 也只会被静默跳过。所以下文所说的「开发环境」指开发者自建的一台自托管测试服务器目录布局与生产一致/data/coolify而不是仓库里的 compose dev 栈。准备条件脚本 scripts/upgrade.sh 硬编码了自托管布局下的路径测试机必须满足已有自托管 Coolify 实例环境变量文件位于/data/coolify/source/.env脚本用它做 compose 解析和变量合并容器名为coolify、coolify-db、coolify-redis、coolify-realtime升级时这四个容器会被停止、删除并重建机器上有 Docker 和 Docker Compose可以访问 CDN 和镜像仓库。升级动作最终执行在哪台机器上由 sentinel 规则决定AGENTS.md 的 sentinel 表说明Server::find(0)是「运行 Coolify 的这台机器Upgrades、instance backups 和 docker inspect 都指向它」UpdateCoolify也是对Server::find(0)发起remote_process。因此无需在 Coolify 里额外配置服务器本机自托管实例天然满足条件。第一步用升级脚本安装指定 source 版本在测试服务器上执行命令来自 AGENTS.md 的 Testing the Self-Hosted Upgrade Processbash upgrade.sh sha-6492d081362c009519481ac70e50873e39ba1861在自托管实例上该脚本位于/data/coolify/source/upgrade.shUpdateCoolify升级前会重新curl下载覆盖它仓库中的对应副本是 scripts/upgrade.sh。这个 sha 标签是文档给定的示例 source 版本RELEASE.md 的 Image tags 表说明sha-commit表示「Exact commit build」如果你要测自己分支上的改动可以用对应的sha-commit标签替换它。执行前要知道这个脚本的副作用它会从配置的 CDN 下载docker-compose.yml、docker-compose.prod.yml、.env.production、upgrade-postgres.sh到/data/coolify/source/修改/data/coolify/source/.env默认先备份为.env-时间戳再把.env.production中缺失的键合并进来并更新REGISTRY_URL等变量传第 4 个参数true可跳过备份拉取 helper 镜像和 compose 文件里的全部镜像停止并删除coolify、coolify-db、coolify-redis、coolify-realtime四个容器再通过 helper 镜像执行docker compose up -d --remove-orphans --wait重建期间服务不可用。脚本接收四个参数默认值来自脚本头部参数含义默认值$1目标 Coolify 镜像标签latest$2helper 镜像版本latest$3镜像仓库地址不传时从.env的REGISTRY_URL读取docker.io$4是否跳过.env备份true跳过falseAGENTS.md 的命令只传了第一个参数其余按默认值处理。第二步把当前版本标记为 4.3.0docker exec -e COOLIFY_VERSION4.3.0 coolify php artisan config:cacheCoolify 报告「当前版本」的来源是 config/constants.php 中的version env(COOLIFY_VERSION) ?: 4.3.18。这条命令把COOLIFY_VERSION4.3.0只注入到 artisan 进程里再用config:cache把它固化进缓存配置——之后常驻运行的实例会一直报告自己是 4.3.0。目的是制造一个「当前版本落后于目标版本」的状态让第三步的更新检查有升级可报。第三步在 UI 检查更新并执行升级登录 Coolify 界面在 Updates 设置页对应 app/Livewire/Settings/Updates.php点击Check for Updates确认可用升级后点击Upgrade。按 AGENTS.md 的说法验证点就是「Confirm that an upgrade is available, then click Upgrade」。点击后UpdateCoolify的实际动作从 CDN 的versions.json取coolify.v4.versionCDN 不可达时回退到本地versions.json缓存但缓存版本若低于当前版本会被判定为损坏并抛错随后禁止降级——目标版本低于当前版本会抛出Cannot downgrade ... please do so manually via Docker commands。检查侧同样只在目标版本严格大于当前版本时把new_version_available置为true见 CheckForUpdatesJob所以第二步把当前版本压到 4.3.0 是这里能提示升级的前提。确认后它在 server 0 上执行curl -fsSL upgrade_script_url -o /data/coolify/source/upgrade.sh bash /data/coolify/source/upgrade.sh latestVersion helperVersion registryUrl即又走一遍第一步描述的完整升级过程目标版本来自更新检查刚取到的最新版本。验证升级完成AGENTS.md 的收尾要求是「verify that the upgrade completes successfully」脚本自身提供了可核对的凭据升级日志/data/coolify/source/upgrade-YYYY-mm-dd-H-M-S.log时间戳取脚本启动时刻按 6 个阶段记录下载配置文件 → 合并环境配置 → 拉镜像 → 停容器 → 启动新容器 →Upgrade complete成功时末尾会写入Coolify upgrade completed successfully和目标版本。状态文件/data/coolify/source/.upgrade-status格式为步骤|信息|ISO 时间戳供前端轮询脚本完成后写入6|Upgrade complete约 10 秒后被删除。失败信号compose 配置解析不出镜像、helper 镜像拉取失败、任意镜像拉取失败时脚本都会打印Aborting upgrade.并以exit 1退出日志里有对应ERROR行。升级成功后脚本会把.env中的LATEST_IMAGE和COOLIFY_VERSION更新为新版本实例随后按新版本运行。限制与已知行为本地 dev 栈APP_ENVlocal和 Cloud 实例isCloud()都会跳过检查与升级逻辑测试必须走非 local 的自托管布局。升级路径不支持降级目标版本必须不低于当前报告版本需要降级时文档要求手动通过 Docker 命令操作。四个容器会被停止重建升级期间实例不可用测试机不要用生产数据。检查更新依赖 CDN 可达或有效的本地缓存CheckForUpdatesJob的异常被静默捕获如果点Check for Updates后没有任何提示优先确认实例能否访问 CDN 的versions.json。完成以上四步、日志出现Upgrade complete且状态文件正常收尾即说明自托管升级流程在该版本下工作正常测试结束后该实例可整体废弃无需回滚。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考