dokku 0.30.0 迁移指南：破坏性变更清单与升级到 0.30.0 的完整操作手册

本文以 dokku 官方 0.30.0 迁移指南 为主体骨架，系统梳理该版本引入的废弃项（Deprecations）、行为变更（Changes）与移除项（Removals）。你将了解 DOKKU_SCALE 移除后的 formation 配置替代方案、app.json 提取时机的变化、logs:failed 的新调用约束，以及一批被清理的旧版 shell 函数、CLI 标志与命令的替代方式，并掌握如何在升级前检查并调整自己的应用与插件，避免升级后容器因缺少 scale 配置而全部停止。

[!IMPORTANT] 由于 DOKKU_SCALE 支持被移除，版本低于 0.25.x 的用户被强烈建议先升级到 0.29.x，再升级到 0.30.x。如果不这样做，由于没有任何 scale 设置，所有应用容器都会在重建时停止。

升级前必读：版本跳级警告

0.30.0 迁移指南在开头给出了一个醒目的警告：DOKKU_SCALE 文件的支持已被移除。该特性自 0.25.0 起被标记为废弃（参见 0.25.0 迁移指南 中的 "The DOKKU_SCALE file is deprecated" 条目），到 0.30.0 正式删除。

如果你当前运行的版本低于 0.25.x，升级路径必须经过 0.29.x：

1. 先升级到 0.29.x，并在此期间把应用的 scale 配置迁移到 app.json 的 formation 键；
2. 确认所有应用的 scale 设置都已迁移完成；
3. 再升级到 0.30.x。

如果跳过 0.29.x 直接升级到 0.30.x，且应用仍依赖 DOKKU_SCALE 文件，那么升级后所有应用容器都会因没有 scale 设置而在重建时停止——这正是迁移指南强调"强烈建议（heavily encouraged）"的原因。

废弃项（Deprecations）

0.30.0 仅新增了一项正式废弃声明：

• Ubuntu 18.04 支持被废弃：官方于 2023 年 4 月停止对该系统的支持（End of Life）。请在此日期之前升级宿主机操作系统。

这意味着 dokku 官方对 Ubuntu 18.04 的测试与问题修复将停止，继续运行将得不到官方保障。

行为变更（Changes）

0.30.0 对 app.json 的处理时机做了一处关键调整：

• app.json 文件现在从源码中提取，而非从构建后的镜像中提取。唯一的例外是 git:from-image 方式的部署——这种场景下没有源码树，文件仍从构建后的镜像中提取。

从源码结构看，app.json 的解析与触发逻辑集中在 plugins/app-json/src/triggers/triggers.go，其中 core-post-extract 触发点接收 sourceWorkDir（源码工作目录）参数，正是这一变更的实现载体。app.json 中的 formation、scripts 等配置在部署早期（源码提取阶段）即可被读取，这也让下述 formation 键取代 DOKKU_SCALE 成为可能。

对使用 git push、git:from-archive、git:sync 等方式部署的应用，请确保 app.json 位于源码根目录（或通过 deployment tasks 文档 中说明的 app.json 位置配置进行指定）；对 git:from-image 部署，则需确保 app.json 已包含在镜像内。

移除项（Removals）

1. SPDY 协议支持移除

• SPDY（HTTP/2 的前身协议）支持已被移除。截至 2021 年，已没有主流浏览器支持该协议。
• 自定义 nginx.conf.sigil 模板中若引用了 spdy 相关变量，在 1.0.0 版本发布前仍可继续构建，但请尽快清理这些模板引用。

2. DOKKU_SCALE 文件移除，改用 formation

DOKKU_SCALE 文件（0.25.0 起废弃）被正式移除，替代方案是 app.json 文件中的 formation 键。详细用法参见 process management 文档。

formation 键的配置方式

在应用的 app.json 中按如下格式声明各进程类型的数量：

{
  "formation": {
    "web": {
      "quantity": 1
    },
    "worker": {
      "quantity": 4
    }
  }
}

从 plugins/app-json/appjson.go 的源码结构看，formation 是一个以进程类型为键的映射，每个条目包含 quantity（进程数量）、max_quantity、min_quantity、autoscaling 等可选字段；plugins/app-json/functions.go 会将 quantity 非空的进程类型转换为 proctype=count 形式的 scale 参数，这印证了 formation 与内部 scale 机制的直接关联。

使用要点与注意事项

• 只要 app.json 中存在 formation 键且任一进程指定了 quantity，ps:scale 命令对该应用的缩放能力即被禁用；app.json 中未列出的进程类型，其进程数会被置为 0。
• 从仓库中移除 formation 键或删除整个 app.json 文件后，dokku 将恢复对 ps:scale 命令的尊重；此前通过 app.json 设置的 scale 值仍会保留生效。
• web 是唯一会在首次部署时自动缩放为 1 的进程类型，详见 process management 文档。

迁移检查清单

升级到 0.30.0 前，请对每个应用执行：

1. 确认应用仓库中不存在 DOKKU_SCALE 文件，或已将其内容转换为 app.json 的 formation 键；
2. 用 dokku ps:scale <app> 检查当前各进程类型数量，作为迁移后的对照基准；
3. 用 dokku ps:report <app> 确认应用的 scale/formation 状态。

3. dokku run 的 --detach 全局标志移除

废弃的 --detach 全局标志被移除。如需运行分离（后台）容器，请使用 run:detached 命令，详见 one-off tasks 文档。

# 旧方式（已移除）
dokku run --detach node-js-app ls -lah

# 新方式
dokku run:detached node-js-app ls -lah

run:detached 会立即返回容器名（使用 k3s 调度器时返回 pod 名），分离容器默认无 TTY、进程结束后自动移除；如需 TTY 可加 --force-tty 标志。需要说明的是，run:detached 自 0.25.0 引入，而 --detach 在 0.25.0 中即被标记废弃，0.30.0 正式删除，属于标准的两步废弃流程。

4. 三个 post-release-* 触发器合并为 post-release-builder

以下废弃触发器被移除，统一由 post-release-builder 触发器取代：

• post-release-buildpack
• post-release-dockerfile
• post-release-pack

各 builder 插件（如 plugins/builder-dockerfile/builder-release、plugins/builder-herokuish/builder-release、plugins/builder-pack/builder-release 等）的构建脚本均在构建末尾调用 plugn trigger post-release-builder "$BUILDER_TYPE" "$APP" "$IMAGE"，传入 builder 类型、应用名与镜像三个参数。在 plugins/app-json/src/triggers/triggers.go 中可以看到该触发点将这三个参数依次解析为 builderType、appName、image。作为插件作者，如果自定义插件监听了旧的三个 post-release-* 触发器，请迁移为监听 post-release-builder，并自行按需筛选 BUILDER_TYPE。

5. logs:failed 必须指定应用或 --all

调用 logs:failed 而不指定应用、也不加 --all 标志的行为已被移除（该限制自 0.22.0 起废弃）。详见 logs 文档。

# 合法用法
dokku logs:failed node-js-app
dokku logs:failed --all

# 非法用法（已移除，不再默认覆盖所有应用）
dokku logs:failed

从源码结构看，plugins/logs/src/subcommands/subcommands.go 中 logs:failed 子命令解析 --all 标志与可选的应用名参数，无应用名时由 plugins/logs/subcommands.go 通过 RunCommandAgainstAllAppsSerially 对全部应用执行——因此迁移指南的措辞实际上意味着：不带应用名时必须显式使用 --all 才能获得全量行为。

6. apps# 系列 shell 函数移除，改用 plugin trigger

以下自 0.20.0 起废弃的 apps 插件 shell 函数被移除，改由对应的 plugin trigger 承担。今后 source app/functions 文件将直接失败：

已移除函数	替代方式
apps#apps_create()	plugn trigger app-create
apps#apps_destroy()	plugn trigger app-destroy
apps#apps_exists()	plugn trigger app-exists
apps#apps_maybe_create()	plugn trigger app-maybe-create

应用生命周期管理一律通过 plugn trigger 触发对应 trigger 完成，插件代码中不应再直接调用上述 shell 函数。

7. common# 通用 shell 函数移除

以下通用 shell 函数被移除，并给出替代：

已移除函数	废弃起始	替代方式
common#is_container_running()	0.12.6	common#is_container_status()
common#is_app_running()	0.22.0	ps#fn-ps-is-app-running()

容器与应用运行状态判断分别收敛到 common 插件的 is_container_status 与 ps 插件的 fn-ps-is-app-running。

8. 全局 --rm-container 与 --rm 标志移除

自 0.25.0 起废弃的全局 --rm-container 与 --rm 标志被移除。dokku run 的一次性容器在进程退出后总是被移除（自 0.25.0 起），这两个标志已无实际作用。需要持久容器的场景，官方建议在 Procfile 中定义一个 console 进程类型并适当缩放，而非依赖一次性运行容器。

9. git# shell 函数移除

以下 git 插件 shell 函数被移除：

已移除函数	废弃起始	替代方式
git#use_git_worktree()	0.23.7	无替代——该函数已内部化（internal）
git#git_deploy_branch()	0.21.0	plugn trigger git-deploy-branch

use_git_worktree 没有对外替代品，插件代码不得再依赖它；部署分支获取请改用 plugn trigger git-deploy-branch。

10. nginx 命令重命名

以下自 0.20.0/0.21.0 起废弃的 nginx 命令被移除，统一改用新命令：

已移除命令	替代命令
nginx:show-conf	nginx:show-config
nginx:validate	nginx:validate-config
nginx:build-config（0.21.0 起废弃）	proxy:build-config

nginx:show-config 的实现在 plugins/nginx-vhosts/command-functions：它会校验应用、查询 proxy 类型，并直接输出 $DOKKU_ROOT/$APP/nginx.conf 的内容；nginx:validate-config 则用于校验配置合法性。注意 show-config 仅对 proxy 类型为 nginx 的应用可用，其他 proxy（caddy、haproxy 等）各自提供 caddy:show-config、haproxy:show-config 等价命令。

11. proxy# shell 函数移除，改用 plugin trigger

以下自 0.20.0 起废弃的 proxy 插件 shell 函数被移除，改由对应 plugin trigger 承担。今后 source proxy/functions 文件将直接失败：

已移除函数	替代方式
proxy#is_app_proxy_enabled()	plugn trigger proxy-is-enabled
proxy#get_app_proxy_type()	plugn trigger proxy-type

代理状态判断与代理类型查询统一通过 plugin trigger 完成，插件代码中不应再直接调用上述 shell 函数。

升级 0.30.0 操作清单

综合以上变更，升级到 0.30.0 的推荐流程如下：

1. 宿主机检查：确认 Ubuntu 版本为 18.04 以上受支持版本（18.04 已废弃）；
2. 应用仓库检查：确认无 DOKKU_SCALE 文件，scale 配置已迁移到 app.json 的 formation 键；确认 app.json 位于源码根目录（git:from-image 部署则确认其位于镜像内）；
3. 命令脚本检查：查找并替换 nginx:show-conf、nginx:validate、nginx:build-config、dokku run --detach、logs:failed（无参调用）等旧用法；
4. 插件代码检查：如维护自定义插件，替换 apps#、common#、git#、proxy# 系列 shell 函数为 plugin trigger 调用，并将 post-release-buildpack/dockerfile/pack 监听迁移到 post-release-builder；
5. 清理模板：移除 nginx.conf.sigil 中的 spdy 相关变量引用；
6. 验证：升级后使用 dokku ps:scale <app> 与 dokku ps:report <app> 核对各应用进程数量，确认容器正常重建与启动。

延伸阅读

• 0.25.0 迁移指南：DOKKU_SCALE、post-release-*、--rm/--rm-container、--detach 等废弃项的原始出处
• 进程管理文档：formation 键用法、ps:scale/ps:report/ps:set 完整说明
• 一次性任务文档：run:detached 等一次性容器命令用法
• 日志管理文档：logs:failed 与失败部署日志说明
• 插件触发器文档：post-release-builder、proxy-is-enabled、proxy-type 等触发器签名