尧图网站建设 
Dokku 0.5.0 迁移指南nginx-vhosts 模板化、certs 证书体系与 Dockerfile 端口暴露【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku本文以 Dokku 0.5.0 官方迁移指南docs/appendices/0.5.0-migration-guide.md为骨架结合当前仓库中nginx-vhosts、certs、domains、checks、proxy、builder-dockerfile等插件的源码与文档系统梳理从 0.4.x 升级到 0.5.0 时必须注意的破坏性变更并给出可复制的迁移操作与后续演进路径。读者可据此完成 nginx 自定义模板迁移、SSL 证书接入方式切换、VHOST 开关语义升级、零停机控制简化以及 Dockerfile 应用端口策略调整。一、迁移背景与影响面概览0.5.0 是 Dokku 在代理层与部署层上的一次重要版本迭代。此次迁移的核心变化集中在两条主线nginx-vhosts插件重构模板语言切换为 sigil模板文件改名、换路径SSL 证书处理从服务器级SSL环境变量转向certs插件的应用级证书管理并用domains:enable/disable取代了 magic 的NO_VHOST环境变量用checks:enable/disable简化零停机部署控制Dockerfile 应用端口策略调整Dockerfile 中的EXPOSE指令现在会默认让 Dokku 代理全部tcp端口。如果您的应用在 0.5.0 之前使用过以下任何能力本次升级就需要逐项核对自定义的 nginx 模板旧路径/home/dokku/app下的自定义模板通过NO_VHOST环境变量控制虚拟主机开关服务器级server-wideSSL 证书依赖 DockerfileEXPOSE但未显式声明端口映射的应用。二、nginx-vhosts 插件模板语言切换到 sigil2.1 不再需要转义$0.5.0 之前nginx 模板本质上是一份经过 shell 处理的文本模板中所有字面量$例如 nginx 变量$host、$request_uri都需要转义成\$这类 bash-isms。0.5.0 起模板渲染引擎切换为 sigil$不再具有 shell 特殊含义无需再对字面量$字符或其他 bash 语法做转义模板变量统一表示为{{ .VARIABLE_NAME }}。这一点在当前仓库的默认模板 plugins/nginx-vhosts/templates/nginx.conf.sigil 中可以直接看到模板大量使用{{ $.APP }}、{{ $.DOKKU_ROOT }}这类变量同时裸写proxy_pass http://{{ $.APP }}-{{ $upstream_port }};、return 301 https://$host:{{ $.PROXY_SSL_PORT }}$request_uri;其中$host、$request_uri都是 nginx 原生变量不再需要任何转义。2.2 模板变量清单迁移后可以使用的完整模板变量如下也可参考 Nginx Proxy 文档{{ .APP }} Application name {{ .APP_SSL_PATH }} Path to SSL certificate and key {{ .DOKKU_ROOT }} Global Dokku root directory (ex: app dir would be {{ .DOKKU_ROOT }}/{{ .APP }}) {{ .PROXY_PORT }} Non-SSL nginx listener port (same as the proxy-port property) {{ .PROXY_SSL_PORT }} SSL nginx listener port (same as the proxy-ssl-port property) {{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS {{ .PROXY_PORT_MAP }} List of port mappings (same as the map ports property) {{ .PROXY_UPSTREAM_PORTS }} List of configured upstream ports (derived from the map ports property) {{ .SSL_INUSE }} Boolean set when an app is SSL-enabled {{ .SSL_SERVER_NAME }} List of SSL VHOSTS此外每个进程类型都暴露了对应的网络监听器变量.DOKKU_APP_${PROCESS_TYPE}_LISTENERSPROCESS_TYPE大写、连字符转下划线它是一组IP:PORT对用于在模板中把非web进程也暴露到 nginx 代理之下。应用环境变量也可在模板中通过{{ var FOO }}形式访问。2.3 自定义模板改名并换路径迁移要点中最容易踩坑的是自定义模板的文件名与存放位置自定义 nginx 模板必须命名为nginx.conf.sigil模板默认路径是应用仓库根目录容器内即/app若为 Dockerfile 应用则是其WORKDIRDokku 不再到 Dokku 服务器上的/home/dokku/node-js-app目录查找该文件。换言之0.4.x 时代在服务器上直接改/home/dokku/app/下模板的做法被废弃模板需要随代码仓库一起提交。官方示例模板的讲解见 Nginx Proxy 文档。作为对比当前版本的默认模板位于 plugins/nginx-vhosts/templates/nginx.conf.sigil渲染逻辑大致是遍历PROXY_PORT_MAP的每一条scheme:listen_port:upstream_port映射对http/https映射生成server块含 HTTP→HTTPS 301 跳转分支、SSL 证书指令、gzip、proxy_pass到对应 upstream 等对grpc/grpcs映射生成使用grpc_pass的server块最后为每个 upstream 端口生成upstream {{ .APP }}-{{ $upstream_port }} { ... }块其成员来自DOKKU_APP_WEB_LISTENERS中的容器监听地址。如果迁移后需要调整模板查找路径例如 monorepo 场景后续版本也提供了nginx:set app nginx-conf-sigil-path path与全局nginx:set --global nginx-conf-sigil-path的扩展能力详见 Nginx Proxy 文档。2.4 SSL 重定向行为默认开启0.5.0 起所有 SSL 应用的域名默认会被重定向到 https对于启用 SSL 的应用非 SSL 的listen端口如 80上的请求默认return 301到 HTTPS 对应端口该行为可通过自定义模板覆盖即上文nginx.conf.sigil中{{ if $is_redirect }} ... {{ end }}分支的控制逻辑当SSL_INUSE且监听端口为 80 时执行 301 跳转若您不希望重定向可在自定义模板中改写该分支。三、SSL从服务器级证书切换到 certs 插件3.1 放弃 server-wide SSL 证书0.5.0 起不再支持服务器级server-wideSSL 证书统一改用certs插件做应用级证书管理。证书由 nginx 在应用容器之外管理因此可以即时更新、无需重建容器。迁移操作为通过 tarball 导入证书dokku certs:add node-js-app certs.tar更完整的流程是先把.crt与.key打包再导入tar cvf cert-key.tar server.crt server.key dokku certs:add node-js-app cert-key.tar注意如果.crt文件附带.ca-bundle需要先拼接成单个.crt再打包cat yourdomain_com.crt yourdomain_com.ca-bundle server.crt。certs插件还提供证书生成自签名仅建议开发/预发环境使用、移除、查看与报告能力dokku certs:generate node-js-app node-js-app.dokku.me # 生成 key、csr 与自签名证书 dokku certs:remove node-js-app # 移除应用证书并重建、重载 nginx 配置 dokku certs:show node-js-app crt server.crt # 导出证书例如导出 Lets Encrypt 证书 dokku certs:show node-js-app key server.key dokku certs:report node-js-app # 查看证书有效期、指纹、签发者等报告与 SSL 相关的其余细节HSTS 默认开启、HTTP/2 版本要求、SSL 端口暴露规则等可参考 SSL Configuration 文档。四、VHOST 控制用 domains:enable/disable 取代 NO_VHOST4.1 magic 环境变量的退役0.5.0 之前开发者通过设置应用环境变量NO_VHOST1来关闭某个应用的虚拟主机vhost。这属于一种魔法约定从 plugins/domains/functions 中仍能看到其遗留痕迹——旧逻辑通过config_set $APP NO_VHOST1写入、通过config_get $APP NO_VHOST读取该变量并在其为1时跳过 vhost 生成第 304–307 行附近。0.5.0 起该机制被正式废弃改由 domains 插件的显式子命令控制dokku domains:disable node-js-app # 关闭 vhost dokku domains:enable node-js-app # 重新开启 vhost也可以一次性对所有应用生效dokku domains:disable --all dokku domains:enable --all关闭 vhost 后后续部署将不再生成 nginx 虚拟主机nginx 仍会把应用代理到某个随机高位端口便于内部服务在多次部署间保持稳定端口该端口可分别通过dokku proxy:set app proxy-port value与dokku proxy:set app proxy-ssl-port value定制。域的增删改查、全局域名、报告等更多用法见 Domain Configuration 文档。4.2 代理与端口的进一步解耦与 VHOST 重构相伴的是代理能力的抽象0.5.0 中端口代理从nginx-vhosts插件中解耦出来成为独立的 proxy 插件0.6.0 起支持宿主机端口到容器端口的映射从而允许使用 HAProxy、Caddy 等替代 nginx。常用命令dokku proxy:build-config node-js-app # 重新构建应用的代理配置 dokku proxy:disable node-js-app # 禁用代理不再生成代理配置、不再路由流量 dokku proxy:enable node-js-app # 重新启用代理 dokku proxy:report node-js-app # 查看代理类型与启用状态详见 Proxy Management 文档。五、零停机部署用 checks:enable/disable 简化控制0.5.0 将零停机部署的控制方式简化为 checks 插件的checks:enable与checks:disabledokku checks:enable node-js-app # 启用零停机部署检查 dokku checks:disable node-js-app # 关闭零停机部署部署期间将有停机风险两点务必注意checks:disable会产生停机关闭后部署时会先停止旧容器再启动新容器如果应用启动失败可能导致连接中断详见 Zero-downtime Deploys 文档 中的警告该文档同时指出自 0.6.0 起checks:disable才真正导致停机此前其行为等同于现在的checks:skip粒度更细两个命令都可接收逗号分隔的进程类型列表例如dokku checks:disable node-js-app worker,web且还有checks:skip用于完全跳过等待与健康检查。六、Dockerfile 应用的端口暴露策略6.1 EXPOSE 的 tcp 端口默认全部代理0.5.0 起Dockerfile 应用中凡是写了EXPOSE的tcp端口都会默认被全部代理详见 Dockerfile 构建文档nginx 会以相同的端口号对外监听即对外监听端口与容器暴露端口一致例如EXPOSE 3000则 nginx 会在宿主机 3000 端口上监听并代理到容器 3000 端口。如果希望修改对外端口可结合 端口管理文档 使用dokku ports:add/set/remove/clear调整映射。另外若应用此前是 buildpack 部署且自定义过端口切换到 Dockerfile 前建议先清空端口映射以确保 Dockerfile 的端口声明被尊重dokku ports:clear node-js-app6.2 UDP 端口需要关闭代理nginx 只能代理 TCP/HTTP 类流量UDP 端口无法由 nginx 代理。如果 Dockerfile 暴露了 UDP 端口需要为该应用关闭 nginx 代理dokku proxy:disable node-js-app关闭后 Dokku 不再为应用生成代理配置流量也就不再经过 nginx 路由UDP 端口将由容器直接对外提供服务具体取决于您的网络配置。七、迁移检查清单变更项0.4.x 旧做法0.5.0 新做法nginx 模板语言手工转义$的 shell 模板sigil 模板变量写作{{ .VAR }}$无需转义自定义模板文件名任意命名必须为nginx.conf.sigil自定义模板位置/home/dokku/app服务器端应用仓库根目录/app或 DockerfileWORKDIRSSL 证书服务器级证书dokku certs:add app certs.tar应用级SSL 重定向视配置而定SSL 应用域名默认全部重定向到 https可用自定义模板覆盖VHOST 开关环境变量NO_VHOSTdokku domains:enable/disable零停机控制旧式开关dokku checks:enable/disableDockerfile 端口依赖手动映射EXPOSE的 tcp 端口默认全部由 nginx 以相同端口号代理Dockerfile UDP 端口—通过dokku proxy:disable关闭代理后暴露八、进一步阅读迁移完成后nginx 代理的全部能力模板变量、属性表、HSTS、X-Forwarded-*、错误页等见 Nginx Proxy 文档nginx.conf.sigil模板的部署前校验与 HTTP/2 语法演进见 nginx-conf-sigil 文件格式说明代理类型切换与端口映射管理见 Proxy Management 文档Dockerfile 构建器细节见 Dockerfile Deployment 文档。【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dokku 0.5.0 迁移指南：nginx-vhosts 模板化、certs 证书体系与 Dockerfile 端口暴露
Dokku 0.5.0 迁移指南nginx-vhosts 模板化、certs 证书体系与 Dockerfile 端口暴露【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku本文以 Dokku 0.5.0 官方迁移指南docs/appendices/0.5.0-migration-guide.md为骨架结合当前仓库中nginx-vhosts、certs、domains、checks、proxy、builder-dockerfile等插件的源码与文档系统梳理从 0.4.x 升级到 0.5.0 时必须注意的破坏性变更并给出可复制的迁移操作与后续演进路径。读者可据此完成 nginx 自定义模板迁移、SSL 证书接入方式切换、VHOST 开关语义升级、零停机控制简化以及 Dockerfile 应用端口策略调整。一、迁移背景与影响面概览0.5.0 是 Dokku 在代理层与部署层上的一次重要版本迭代。此次迁移的核心变化集中在两条主线nginx-vhosts插件重构模板语言切换为 sigil模板文件改名、换路径SSL 证书处理从服务器级SSL环境变量转向certs插件的应用级证书管理并用domains:enable/disable取代了 magic 的NO_VHOST环境变量用checks:enable/disable简化零停机部署控制Dockerfile 应用端口策略调整Dockerfile 中的EXPOSE指令现在会默认让 Dokku 代理全部tcp端口。如果您的应用在 0.5.0 之前使用过以下任何能力本次升级就需要逐项核对自定义的 nginx 模板旧路径/home/dokku/app下的自定义模板通过NO_VHOST环境变量控制虚拟主机开关服务器级server-wideSSL 证书依赖 DockerfileEXPOSE但未显式声明端口映射的应用。二、nginx-vhosts 插件模板语言切换到 sigil2.1 不再需要转义$0.5.0 之前nginx 模板本质上是一份经过 shell 处理的文本模板中所有字面量$例如 nginx 变量$host、$request_uri都需要转义成\$这类 bash-isms。0.5.0 起模板渲染引擎切换为 sigil$不再具有 shell 特殊含义无需再对字面量$字符或其他 bash 语法做转义模板变量统一表示为{{ .VARIABLE_NAME }}。这一点在当前仓库的默认模板 plugins/nginx-vhosts/templates/nginx.conf.sigil 中可以直接看到模板大量使用{{ $.APP }}、{{ $.DOKKU_ROOT }}这类变量同时裸写proxy_pass http://{{ $.APP }}-{{ $upstream_port }};、return 301 https://$host:{{ $.PROXY_SSL_PORT }}$request_uri;其中$host、$request_uri都是 nginx 原生变量不再需要任何转义。2.2 模板变量清单迁移后可以使用的完整模板变量如下也可参考 Nginx Proxy 文档{{ .APP }} Application name {{ .APP_SSL_PATH }} Path to SSL certificate and key {{ .DOKKU_ROOT }} Global Dokku root directory (ex: app dir would be {{ .DOKKU_ROOT }}/{{ .APP }}) {{ .PROXY_PORT }} Non-SSL nginx listener port (same as the proxy-port property) {{ .PROXY_SSL_PORT }} SSL nginx listener port (same as the proxy-ssl-port property) {{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS {{ .PROXY_PORT_MAP }} List of port mappings (same as the map ports property) {{ .PROXY_UPSTREAM_PORTS }} List of configured upstream ports (derived from the map ports property) {{ .SSL_INUSE }} Boolean set when an app is SSL-enabled {{ .SSL_SERVER_NAME }} List of SSL VHOSTS此外每个进程类型都暴露了对应的网络监听器变量.DOKKU_APP_${PROCESS_TYPE}_LISTENERSPROCESS_TYPE大写、连字符转下划线它是一组IP:PORT对用于在模板中把非web进程也暴露到 nginx 代理之下。应用环境变量也可在模板中通过{{ var FOO }}形式访问。2.3 自定义模板改名并换路径迁移要点中最容易踩坑的是自定义模板的文件名与存放位置自定义 nginx 模板必须命名为nginx.conf.sigil模板默认路径是应用仓库根目录容器内即/app若为 Dockerfile 应用则是其WORKDIRDokku 不再到 Dokku 服务器上的/home/dokku/node-js-app目录查找该文件。换言之0.4.x 时代在服务器上直接改/home/dokku/app/下模板的做法被废弃模板需要随代码仓库一起提交。官方示例模板的讲解见 Nginx Proxy 文档。作为对比当前版本的默认模板位于 plugins/nginx-vhosts/templates/nginx.conf.sigil渲染逻辑大致是遍历PROXY_PORT_MAP的每一条scheme:listen_port:upstream_port映射对http/https映射生成server块含 HTTP→HTTPS 301 跳转分支、SSL 证书指令、gzip、proxy_pass到对应 upstream 等对grpc/grpcs映射生成使用grpc_pass的server块最后为每个 upstream 端口生成upstream {{ .APP }}-{{ $upstream_port }} { ... }块其成员来自DOKKU_APP_WEB_LISTENERS中的容器监听地址。如果迁移后需要调整模板查找路径例如 monorepo 场景后续版本也提供了nginx:set app nginx-conf-sigil-path path与全局nginx:set --global nginx-conf-sigil-path的扩展能力详见 Nginx Proxy 文档。2.4 SSL 重定向行为默认开启0.5.0 起所有 SSL 应用的域名默认会被重定向到 https对于启用 SSL 的应用非 SSL 的listen端口如 80上的请求默认return 301到 HTTPS 对应端口该行为可通过自定义模板覆盖即上文nginx.conf.sigil中{{ if $is_redirect }} ... {{ end }}分支的控制逻辑当SSL_INUSE且监听端口为 80 时执行 301 跳转若您不希望重定向可在自定义模板中改写该分支。三、SSL从服务器级证书切换到 certs 插件3.1 放弃 server-wide SSL 证书0.5.0 起不再支持服务器级server-wideSSL 证书统一改用certs插件做应用级证书管理。证书由 nginx 在应用容器之外管理因此可以即时更新、无需重建容器。迁移操作为通过 tarball 导入证书dokku certs:add node-js-app certs.tar更完整的流程是先把.crt与.key打包再导入tar cvf cert-key.tar server.crt server.key dokku certs:add node-js-app cert-key.tar注意如果.crt文件附带.ca-bundle需要先拼接成单个.crt再打包cat yourdomain_com.crt yourdomain_com.ca-bundle server.crt。certs插件还提供证书生成自签名仅建议开发/预发环境使用、移除、查看与报告能力dokku certs:generate node-js-app node-js-app.dokku.me # 生成 key、csr 与自签名证书 dokku certs:remove node-js-app # 移除应用证书并重建、重载 nginx 配置 dokku certs:show node-js-app crt server.crt # 导出证书例如导出 Lets Encrypt 证书 dokku certs:show node-js-app key server.key dokku certs:report node-js-app # 查看证书有效期、指纹、签发者等报告与 SSL 相关的其余细节HSTS 默认开启、HTTP/2 版本要求、SSL 端口暴露规则等可参考 SSL Configuration 文档。四、VHOST 控制用 domains:enable/disable 取代 NO_VHOST4.1 magic 环境变量的退役0.5.0 之前开发者通过设置应用环境变量NO_VHOST1来关闭某个应用的虚拟主机vhost。这属于一种魔法约定从 plugins/domains/functions 中仍能看到其遗留痕迹——旧逻辑通过config_set $APP NO_VHOST1写入、通过config_get $APP NO_VHOST读取该变量并在其为1时跳过 vhost 生成第 304–307 行附近。0.5.0 起该机制被正式废弃改由 domains 插件的显式子命令控制dokku domains:disable node-js-app # 关闭 vhost dokku domains:enable node-js-app # 重新开启 vhost也可以一次性对所有应用生效dokku domains:disable --all dokku domains:enable --all关闭 vhost 后后续部署将不再生成 nginx 虚拟主机nginx 仍会把应用代理到某个随机高位端口便于内部服务在多次部署间保持稳定端口该端口可分别通过dokku proxy:set app proxy-port value与dokku proxy:set app proxy-ssl-port value定制。域的增删改查、全局域名、报告等更多用法见 Domain Configuration 文档。4.2 代理与端口的进一步解耦与 VHOST 重构相伴的是代理能力的抽象0.5.0 中端口代理从nginx-vhosts插件中解耦出来成为独立的 proxy 插件0.6.0 起支持宿主机端口到容器端口的映射从而允许使用 HAProxy、Caddy 等替代 nginx。常用命令dokku proxy:build-config node-js-app # 重新构建应用的代理配置 dokku proxy:disable node-js-app # 禁用代理不再生成代理配置、不再路由流量 dokku proxy:enable node-js-app # 重新启用代理 dokku proxy:report node-js-app # 查看代理类型与启用状态详见 Proxy Management 文档。五、零停机部署用 checks:enable/disable 简化控制0.5.0 将零停机部署的控制方式简化为 checks 插件的checks:enable与checks:disabledokku checks:enable node-js-app # 启用零停机部署检查 dokku checks:disable node-js-app # 关闭零停机部署部署期间将有停机风险两点务必注意checks:disable会产生停机关闭后部署时会先停止旧容器再启动新容器如果应用启动失败可能导致连接中断详见 Zero-downtime Deploys 文档 中的警告该文档同时指出自 0.6.0 起checks:disable才真正导致停机此前其行为等同于现在的checks:skip粒度更细两个命令都可接收逗号分隔的进程类型列表例如dokku checks:disable node-js-app worker,web且还有checks:skip用于完全跳过等待与健康检查。六、Dockerfile 应用的端口暴露策略6.1 EXPOSE 的 tcp 端口默认全部代理0.5.0 起Dockerfile 应用中凡是写了EXPOSE的tcp端口都会默认被全部代理详见 Dockerfile 构建文档nginx 会以相同的端口号对外监听即对外监听端口与容器暴露端口一致例如EXPOSE 3000则 nginx 会在宿主机 3000 端口上监听并代理到容器 3000 端口。如果希望修改对外端口可结合 端口管理文档 使用dokku ports:add/set/remove/clear调整映射。另外若应用此前是 buildpack 部署且自定义过端口切换到 Dockerfile 前建议先清空端口映射以确保 Dockerfile 的端口声明被尊重dokku ports:clear node-js-app6.2 UDP 端口需要关闭代理nginx 只能代理 TCP/HTTP 类流量UDP 端口无法由 nginx 代理。如果 Dockerfile 暴露了 UDP 端口需要为该应用关闭 nginx 代理dokku proxy:disable node-js-app关闭后 Dokku 不再为应用生成代理配置流量也就不再经过 nginx 路由UDP 端口将由容器直接对外提供服务具体取决于您的网络配置。七、迁移检查清单变更项0.4.x 旧做法0.5.0 新做法nginx 模板语言手工转义$的 shell 模板sigil 模板变量写作{{ .VAR }}$无需转义自定义模板文件名任意命名必须为nginx.conf.sigil自定义模板位置/home/dokku/app服务器端应用仓库根目录/app或 DockerfileWORKDIRSSL 证书服务器级证书dokku certs:add app certs.tar应用级SSL 重定向视配置而定SSL 应用域名默认全部重定向到 https可用自定义模板覆盖VHOST 开关环境变量NO_VHOSTdokku domains:enable/disable零停机控制旧式开关dokku checks:enable/disableDockerfile 端口依赖手动映射EXPOSE的 tcp 端口默认全部由 nginx 以相同端口号代理Dockerfile UDP 端口—通过dokku proxy:disable关闭代理后暴露八、进一步阅读迁移完成后nginx 代理的全部能力模板变量、属性表、HSTS、X-Forwarded-*、错误页等见 Nginx Proxy 文档nginx.conf.sigil模板的部署前校验与 HTTP/2 语法演进见 nginx-conf-sigil 文件格式说明代理类型切换与端口映射管理见 Proxy Management 文档Dockerfile 构建器细节见 Dockerfile Deployment 文档。【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考