使用 Traefik 比较久的读者应该会发现,在服务重启的时候,原来的网站会展示 404 not found 的空白页面,虽然多数情况下服务恢复很快,但是这个恢复时间取决于部署启动的应用和监控检查配置策略,如果没有配置流量切换规则,那么有的时候,会看到很久的空白页面,这样的体验显然不好。

为了提升体验,我们可以使用 Traefik 提供的错误页面中间件来解决这个问题,优化访问体验。本篇思路同样可以处理通用 Nginx 错误页面的创建。

如何使用 Traefik 错误页中间件

虽然官方文档中有明确记录“错误页面”中间件的使用方法:

但是这只描述了如何使用中间件,我们还需要实际的“应用服务”来支持在错误发生的时候,能够有对应的错误页面展示给用户,所以处理这段逻辑对应的配置如下:

在进行配置的时候,还需要注意一个细节:

我们务必降低这个服务的优先级,避免影响业务正常运行。这样才能保证在其他业务中断的时候,展示这个页面,而非遇到一些极端情况下的时候,我们看到的不是预期中的内容。

另外,如果不希望准备多个错误页面的话,可以考虑将 {status}.html 改为指定的固定页面 index.html

寻找HTTP错误码页面相关的开源项目

在配置书写完毕之后,我们需要准备对应的错误页面,我们都知道常用的 HTTP 错误码有至少20个,所以如果依赖人工来处理,非常不利于维护。

考虑到现在 traefik 用户量不少了,应该有人有类似需求,经过搜索果然找到了国外小哥编写的项目:https://github.com/tarampampam/error-pages

简单使用这个开源项目,感觉还好,但是如果你想定制页面的话,需要准备的内容稍微有一些多:

  • 依赖一个页面生成工具,构建 Node 构建镜像。
  • 依赖自定义的 Nginx docker-entrypoint.sh,并需要构建 Nginx 运行镜像,以及需要修改默认的 Nginx.conf

追求简洁高效是工程师的基础素养,所以我们能否有更简单的方案呢?

使用官方 Nginx 镜像进行定制

我们知道 Nginx 在 1.18 之后提供了一个特殊功能,允许用户自定义及额外的扩展 docker-entrypoint.d 脚本,以及支持使用基于 envsubst 的自定义 Nginx 配置文件而不需要修改官方镜像中的 nginx.confdocker-entrypoint.sh 文件。

稍微扩展一些思路,不难想到可以使用 envsubst 以及 扩展的 docker-entrypoint.d 来进行自定义页面的预处理。

出于分发性能考虑,我们使用 alpine 版本的 Nginx Docker 容器镜像。

编写模版页面

出于演示,这里简化我们的模版结构,仅演示如何使用 envsubst 来完成需求:

在页面中定义需要使用的数据变量后,便可以着手准备页面内的数据了。

准备错误码列表数据

准备数据的时候,考虑计划使用 shell 来进行处理,shell 默认对 JSON 处理支持能力不佳,所以这里需要将错误码进行整理,最好整理为一行几列的模式,方便程序读取和解析。

因为描述文本在后续调整更新过程中,潜在会引入逗号,所以这里使用分号作为分隔符,避免潜在问题:

将上面的内容保存为 pages.csv 后,继续编写数据解析脚本。

编写解析脚本

因为我们预期使用 alpine 版本的镜像,镜像内默认只有 sh,所以这里编写功能的时候,不能使用 array 拆分的方式,需要进行变通:

执行脚本进行验证,可以看到解析结果是符合预期的:

核心功能编写完毕,接下来是站在“巨人的肩膀”上,参考官方镜像的脚本,实现“自动读取数据生成各种错误码页面”。

编写模版生成脚本

官方容器中用于生成 nginx 配置的 “docker-entrypoint.d/20-envsubst-on-templates.sh” 脚本是这样编写的:

可以看到思路还是比较清晰的,我们将前文中的解析脚本和这段脚本适当合并,来完成我们的需求。

将内容保存为 30-envsubst-on-pages.sh,稍后使用。

编写 Nginx 配置

因为官方镜像支持扩展配置,所以我们无需修改主 Nginx.conf ,只需要根据需求书写新的配置即可:

将上面的内容保存为 default.conf.template,接下来完成容器配置,就可以使用这个服务啦。

编写服务容器配置

我们的容器配置文件其实很简单:

你或许会疑问,为什么还有三个默认环境变量 DEFAULT_CODEDEFAULT_TITLEDEFAULT_DESC,这些变量是用于处理服务站点首页 index.html 文件,如果你愿意的话,可以自由发挥整点不一样的内容。

最后

我使用的错误页面模版

想要查看在线例子,可以访问:https://error.soulteary.com/,例子模版编写参考了 https://www.mantralabsglobal.com/404 的设计创意,感谢 Mantra Labs 的分享。

不得不说,新版本的 Nginx 容器镜像相当强大,从历史文章中也应该看的出我对它的喜欢:小巧、简洁、高性能、接口丰富。如果你还在使用老版本的 Nginx ,不妨考虑升级到最新版本。

–EOF