Dokku 0.31.0 版本迁移指南：关键变更与升级注意事项

前言

Dokku 作为轻量级 PaaS 解决方案，其 0.31.0 版本带来了一系列重要的架构改进和功能调整。本文将详细解析这些变更，帮助开发者顺利完成版本迁移。我们将从构建缓存、容器集成、端口映射等多个维度，深入剖析每个变更的技术细节和实际影响。

核心变更解析

1. 构建缓存机制升级

变更内容：Herokuish 构建缓存现在使用 Docker 卷（如 cache-node-js-app）替代原有的本地文件系统存储。

技术影响：

• 升级到 0.29.0 以上版本时，所有现有应用缓存将被清除
• Docker 卷提供更好的跨主机移植性和管理便利性
• 缓存生命周期与容器生命周期解耦，提高构建稳定性

操作建议：首次升级后需要重新构建应用以建立新的缓存卷。

2. 容器集成优化

Vector 日志收集组件

• 配置挂载路径从 /etc/vector/vector.json 改为 /etc/vector
• 现在支持通过额外配置文件扩展 Vector Sinks 功能

操作步骤：

dokku logs:vector-stop
dokku logs:vector-start

Traefik 反向代理

• 配置挂载路径从 /acme.json 改为 /data
• 解决了特定架构下的权限问题

操作步骤：

dokku traefik:stop
dokku traefik:start

3. 部署流程改进

镜像部署优化：

• 不再需要手动清除 source-image git 属性
• 支持从镜像部署（git:from-image/git:load-image）无缝切换到其他部署方式

CHECKS 文件处理：

• 镜像部署：从镜像的 WORKDIR 提取 CHECKS
• 其他部署（git push/from-archive/sync）：直接从源代码提取
• 文件名固定为 CHECKS，不可修改

4. 端口映射自动化

重大改进：

• 构建过程中自动检测端口映射
• 默认映射：http:80:5000（当未指定时）
• 可通过 ports 插件覆盖自动检测结果

技术意义：

• 简化应用部署配置
• 减少因端口配置错误导致的部署失败
• 保持与 Dockerfile EXPOSE 指令的兼容性

构建器镜像更新

Herokuish Buildpack

• 默认镜像升级为 gliderlabs/herokuish:latest-22
• 基于 heroku-22 栈和 Ubuntu 22.04
• 兼容选项：gliderlabs/herokuish:latest-20（基于 heroku-20/Ubuntu 20.04）

Cloud Native Buildpack

• 默认镜像升级为 heroku/builder:22
• 同样基于 heroku-22 栈和 Ubuntu 22.04
• 兼容选项：heroku/buildpacks:20

升级建议：

• 测试新镜像的兼容性后再全面升级
• 关注应用依赖库与新系统版本的兼容性
• 考虑在过渡期显式指定旧版构建器

废弃功能与替代方案

1. 端口管理重构

• proxy:ports* 命令组被新的 ports 插件取代
• 过渡期保留一个次版本周期的兼容性

2. 函数废弃

• common#get_available_port() → 使用 ports-get-available 插件触发器
• common#get_dockerfile_exposed_ports() → 无替代（仅内部使用）
• common#get_exposed_ports_from_image() → 无替代（仅构建过程使用）

3. 健康检查演进

• CHECKS 文件模式废弃，推荐使用 app.json
• 迁移工具：docker-container-healthchecker
• 新格式支持更丰富的健康检查配置

4. 架构支持调整

• ARM 架构进入废弃周期，下个次版本移除
• ARM64 继续支持
• Raspberry PI 用户应规划迁移到 ARM64

配置变量变更

已移除的配置

• RAW_TCP_PORTS（不再用于 nginx 模板）
• DOKKU_DOCKERFILE_PORTS → 使用 ports 插件
• DOKKU_PROXY_PORT_MAP → 迁移到属性系统

最佳升级实践

1. 预升级检查：

   • 备份重要应用和数据
   • 检查所有自定义插件与核心功能的兼容性
   • 特别关注端口映射和健康检查配置

2. 分阶段升级：

   # 1. 升级Dokku核心
   sudo apt-get update
   sudo apt-get install dokku
   
   # 2. 逐个应用测试
   dokku ps:rebuild <app-name>
   
   # 3. 处理废弃功能
   dokku ports:set <app-name> <port-map>
   

3. 健康检查迁移：

   • 使用工具转换现有 CHECKS 文件
   • 验证新健康检查配置的有效性
   • 逐步过渡到 app.json 格式

4. 构建器测试：

   • 为关键应用显式指定构建器版本
   • 监控构建日志中的系统依赖警告
   • 准备回滚方案

结语

Dokku 0.31.0 通过标准化端口管理、优化容器集成、升级基础镜像等改进，为应用部署提供了更稳定和现代化的平台。开发者应重点关注端口映射、健康检查和工作负载构建三个方面的变更，按照本文指南制定合理的升级策略，确保平稳过渡到新版本。