Dokku 0.9.0 迁移指南：Golang 重写计划下的插件架构与兼容性承诺

Dokku 0.9.0 是一个具有分水岭意义的版本：Dokku 团队正式启动了将核心代码从 Bash 向 Golang 重写的长期工程，并以 repo 插件为第一个试点。本文以官方 0.9.0 迁移指南为主体，结合当前仓库源码，梳理这次架构演进的现状、四条不变的设计承诺，以及它们对插件作者与运维者的实际影响。读完本文，你将理解 Dokku 插件系统为何能长期保持"任意语言可写插件、核心插件可开关、plugn 触发、Bash 包装器"这一稳定形态，并能基于当前仓库源码追踪 Go 化插件的实现路径。

迁移背景：一场"超出本文范围"的架构重写

docs/appendices/0.9.0-migration-guide.md 开篇即点明：Dokku 正在进行一项把自身从 Bash 重写为 Golang 的持续迁移。指南明确表示，重写的动机细节不属于该文档的讨论范围（"The reasons are beyond the scope of this document"），但它立刻给出一个对所有人都有实际影响的提示：任何为 Dokku 维护的补丁（patches）都可能受到这次重写的波及。

换言之，这篇指南的读者对象不是"为什么"，而是"这会如何影响你，以及哪些底线不会变"。这也是 Dokku 版本化迁移指南（docs/appendices 目录下从 0.5.0 到 0.38.0 的一系列文档）的惯例：每个版本记录该版本对用户与插件生态带来的结构性变化。

0.9.0 的现状：repo 插件成为首个 Go 化插件

指南给出了一个精确的时间点事实：截至 0.9.0，只有 repo 插件是使用 Golang 编写的。

这一论断在当前仓库中可以得到完整印证。repo 插件的插件清单文件 plugins/repo/plugin.toml 声明了 dokku core repo plugin 的定位，而其核心逻辑全部位于 Go 源码中：

• plugins/repo/repo.go 实现了两个核心函数：
  • PurgeCache(appName)：通过 Docker label com.dokku.app-name 与 com.dokku.image-stage=build 过滤出构建阶段的容器并移除，随后调用 docker volume rm -f cache-<app> 删除构建缓存卷；失败时会返回带自定义退出码的 PurgeCacheFailed 错误类型。
  • RepoGc(appName)：先备份应用仓库 refs/heads 下的所有 head 文件内容，再以 GIT_DIR 指向应用仓库的方式执行 git gc --aggressive，最后在 defer 中恢复 head 文件——避免 GC 过程影响正在使用的引用。
• plugins/repo/subcommands.go 暴露 CommandGc 与 CommandPurgeCache 两个命令入口。
• plugins/repo/src/subcommands/subcommands.go 是子命令主程序，根据 os.Args[0] 的 basename 分发到 gc 或 purge-cache，错误统一走 common.LogFailWithError。
• plugins/repo/Makefile 展示了 Go 化插件的构建形态：SUBCOMMANDS = subcommands/gc subcommands/purge-cache、TRIGGERS = triggers/post-stack-set triggers/post-delete，通过 include ../../common.mk 复用统一的构建规则。

从源码结构可以推断，Go 化插件的标准形态是：Go 包提供核心函数 → 独立的 main 程序承载子命令与触发器 → Makefile 统一构建出可执行文件，并接入 Dokku 的全局构建体系（common.mk）。

四条不变承诺：无论重写进行到哪一步

这是迁移指南中分量最重的部分。指南明确声明，无论重写状态如何，以下四条承诺始终保持成立：

1. 用户可以用任何语言编写自定义插件 —— 插件机制与实现语言解耦，Go 重写只影响核心代码，不设门槛要求第三方插件跟随迁移。
2. 用户能够启用或禁用核心插件 —— 核心插件本身也是可插拔的，用户拥有对核心功能的开关权。
3. plugn 将继续用于执行插件触发器（trigger） —— 触发器调度机制保持稳定，这是整个插件生态的调用协议。
4. 项目会提供可 source 的 Bash 包装器，用于执行用 Golang 实现的核心功能 —— 已 Go 化的功能仍以 Bash 可调用的方式暴露给既有脚本与插件。

这四条承诺共同勾勒出 Dokku 插件架构的稳定边界：语言在变，接口协议不变。下文结合当前仓库逐一印证它们的实现形态。

承诺一与四：任意语言写插件 + Bash 包装器

两条承诺在仓库中是互相咬合的。虽然核心逻辑在 Go 化，但 Dokku 仍然保留了大量的 Bash 接口层供插件调用。

repo 插件的 Go 子命令会通过 dokku 主脚本以插件命令的形式暴露（参考 plugins/repo/Makefile 中 commands 的构建），而 Bash 侧则通过"可 source 的包装器"获得等价能力。最典型的例子是 common 插件：它既包含 Go 实现（如 plugins/common/src/common/common.go），也保留了 plugins/common/functions、plugins/common/deploy、plugins/common/archive-functions、plugins/common/property-functions、plugins/common/release-and-deploy 等一批纯 Bash 的共享函数文件。任何插件都可以通过 source 这些文件来复用 Dokku 的核心能力，而不必关心底层是否已经 Go 化。

承诺二：核心插件可启用 / 可禁用

Dokku 主入口脚本 dokku 第 46-48 行定义了插件系统的三条路径：

export PLUGIN_PATH=${PLUGIN_PATH:="$DOKKU_LIB_ROOT/plugins"}
export PLUGIN_AVAILABLE_PATH=${PLUGIN_AVAILABLE_PATH:="$PLUGIN_PATH/available"}
export PLUGIN_ENABLED_PATH=${PLUGIN_ENABLED_PATH:="$PLUGIN_PATH/enabled"}

available 目录存放全部已安装插件，enabled 目录存放实际生效的插件，二者分离即为"启用/禁用"提供了物理基础。主脚本在第 232 行通过扫描 $PLUGIN_PATH/enabled 下的 commands 文件收集可用命令，plugins/00_dokku-standard/subcommands/report 中也会执行 plugn list 来展示插件清单。用户可以随时在 enabled/available 之间增删插件入口，从而开关任意核心插件——这条承诺至今依然成立。

承诺三：plugn 触发器机制

plugn 是 Dokku 插件触发器的执行器，这条承诺在当前仓库中证据最为充分。

在 Go 侧，plugins/common/plugn.go 提供了 CallPlugnTrigger / CallPlugnTriggerWithContext，其实现核心就是拼装 plugn trigger <Trigger> [Args...] 命令并通过 CallExecCommand 执行；当设置了 DOKKU_TRACE=1 时，还会把触发器的 stdout/stderr 逐行输出为调试日志。这说明即使是 Go 化的核心代码，跨插件协作仍然统一走 plugn 触发协议。

在 Bash 侧，plugins/common/functions 中遍布 plugn 调用，例如：

• plugn trigger app-list（第 29 行）—— 枚举应用；
• plugn trigger deployed-app-image-tag / deployed-app-repository / deployed-app-image-repo（第 311、321-322、352-353、393 行）—— 获取已部署应用镜像与仓库信息；
• plugn trigger builder-build / builder-release / scheduler-deploy / builds-record-finalize（第 628、652、661、707 行）—— 贯穿构建与调度主链路；
• plugn trigger user-auth（第 757 行）—— SSH 用户鉴权。

而 plugins/00_dokku-standard/subcommands/urls 中的 plugn trigger domains-urls 与 plugins/00_dokku-standard/subcommands/report 中的 plugn trigger report "$APP" 则是核心命令向各插件分发职责的标准姿势。可以这样理解：Dokku 的主流程是一系列 plugn 触发器按序执行的编排，Go 重写改变的是单个触发器内部的实现，而不是触发器的调度方式——这正是迁移期间新旧插件能够共存互操作的根本原因。

对插件作者与运维者的实操影响

综合指南与仓库现状，可以给出以下可落地的判断与操作建议：

• 补丁需跟随插件形态演进：如果你的补丁直接修改了 Bash 实现（例如 plugins/repo 这类已 Go 化的插件），在 0.9.0 之后需要改为面向 Go 源码或 Bash 包装器层进行适配；对尚未 Go 化的插件，原 Bash 补丁仍可继续工作。
• 插件触发协议是长期稳定契约：无论插件用 Bash、Go 还是其他语言编写，对外协作一律通过 plugn trigger <trigger-name>。新插件应优先以"实现触发器 + 注册命令"的方式接入，参考 plugins/repo/Makefile 中 TRIGGERS 的声明模式。
• 核心插件开关仍有效：借助 available / enabled 两套目录结构，任何插件（包括核心插件）都可以被启用或禁用；报告命令 dokku report 会通过 plugn 汇总各插件状态（见 plugins/00_dokku-standard/subcommands/report）。
• 关注 Bash 包装器层：Go 化功能会持续以可 source 的 Bash 文件（如 common 插件中的 functions 系列）暴露，既有脚本与第三方插件应优先通过这些包装器调用核心能力，而非直接执行 Go 二进制。

小结

0.9.0 迁移指南篇幅不长，却划定了 Dokku 一次深远架构演进的稳定边界：以 repo 插件为起点的 Golang 重写，只改变核心功能的实现语言，不改变"任意语言插件、可开关核心插件、plugn 触发器、Bash 包装器"这四条接口层承诺。结合当前仓库源码可以看到，这一设计至今仍在生效——Go 代码通过 plugins/common/plugn.go 调用与 Bash 脚本同样的触发协议，available/enabled 目录结构依然支撑着插件的启停，common 插件的 Bash 函数文件继续充当 Go 化功能与外部世界之间的桥梁。对于 Dokku 的插件作者与平台运维者来说，这套架构保证了：无论核心重写推进到哪一步，你的插件接入方式都不会因语言变迁而失效。