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

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

如何使用 Traefik 错误页中间件

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

labels:
  - "traefik.http.middlewares.test-errorpage.errors.status=500-599"
  - "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
  - "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"

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

labels:
  - "traefik.enable=true"
  - "traefik.docker.network=traefik"

  # 定义中间件
  - "traefik.http.middlewares.error-pages-middleware.errors.status=400-599"
  - "traefik.http.middlewares.error-pages-middleware.errors.service=error-pages-service"
  - "traefik.http.middlewares.error-pages-middleware.errors.query=/{status}.html"

  # 使用中间件
  - "traefik.http.routers.error-pages-router.middlewares=error-pages-middleware@docker"
  - "traefik.http.routers.errorpage.entrypoints=https"
  - "traefik.http.routers.errorpage.tls=true"
  - "traefik.http.routers.errorpage.rule=HostRegexp(`{host:.+}`)"
  - "traefik.http.routers.errorpage.priority=1"
  - "traefik.http.services.error-pages-service.loadbalancer.server.port=80"

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

labels:
  - "traefik.http.routers.errorpage.priority=1"

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

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

labels:
  - "traefik.http.middlewares.error-pages-middleware.errors.query=/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.conf 和 docker-entrypoint.sh 文件。

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

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

编写模版页面

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

<html lang="en-US">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>${DEFAULT_CODE} ${DEFAULT_TITLE}</title>
</head>
<body>
  <h1>${DEFAULT_TITLE}</h1>
  <p>${DEFAULT_DESC}</p>
</body>
</html>

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

准备错误码列表数据

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

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

400;Bad Request;The server did not understand the request
401;Unauthorized;The requested page needs a username and a password
403;Forbidden;Access is forbidden to the requested page
404;Not Found;The server can not find the requested page
405;Method Not Allowed;The method specified in the request is not allowed
407;Proxy Authentication Required;You must authenticate with a proxy server before this request can be served
408;Request Timeout;The request took longer than the server was prepared to wait
409;Conflict;The request could not be completed because of a conflict
410;Gone;The requested page is no longer available
411;Length Required;The "Content-Length" is not defined. The server will not accept the request without it
412;Precondition Failed;The pre condition given in the request evaluated to false by the server
413;Payload Too Large;The server will not accept the request, because the request entity is too large
416;Requested Range Not Satisfiable;The requested byte range is not available and is out of bounds
418;I'm a teapot;Attempt to brew coffee with a teapot is not supported
429;Too Many Requests;Too many requests in a given amount of time
500;Internal Server Error;The server met an unexpected condition
502;Bad Gateway;The server received an invalid response from the upstream server
503;Service Unavailable;The server is temporarily overloading or down
504;Gateway Timeout;The gateway has timed out
505;HTTP Version Not Supported;The server does not support the "http protocol" version

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

编写解析脚本

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

cat "pages.csv" | grep ";" | while read line; do
    CODE=$(echo "$line" | cut -d";" -f1)
    TITLE=$(echo "$line" | cut -d";" -f2)
    DESC=$(echo "$line" | cut -d";" -f3)

    echo $CODE;
    echo $TITLE;
    echo $DESC;
done

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

400
Bad Request
The server did not understand the request
401
Unauthorized
The requested page needs a username and a password
403
Forbidden
Access is forbidden to the requested page
...

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

编写模版生成脚本

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

#!/bin/sh

set -e

ME=$(basename $0)

auto_envsubst() {
  local template_dir="${NGINX_ENVSUBST_TEMPLATE_DIR:-/etc/nginx/templates}"
  local suffix="${NGINX_ENVSUBST_TEMPLATE_SUFFIX:-.template}"
  local output_dir="${NGINX_ENVSUBST_OUTPUT_DIR:-/etc/nginx/conf.d}"

  local template defined_envs relative_path output_path subdir
  defined_envs=$(printf '${%s} ' $(env | cut -d= -f1))
  [ -d "$template_dir" ] || return 0
  if [ ! -w "$output_dir" ]; then
    echo >&3 "$ME: ERROR: $template_dir exists, but $output_dir is not writable"
    return 0
  fi
  find "$template_dir" -follow -type f -name "*$suffix" -print | while read -r template; do
    relative_path="${template#$template_dir/}"
    output_path="$output_dir/${relative_path%$suffix}"
    subdir=$(dirname "$relative_path")
    # create a subdirectory where the template file exists
    mkdir -p "$output_dir/$subdir"
    echo >&3 "$ME: Running envsubst on $template to $output_path"
    envsubst "$defined_envs" < "$template" > "$output_path"
  done
}

auto_envsubst

exit 0

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

#!/bin/sh

set -e

ME=$(basename $0)

auto_envsubst() {

  local template_dir="${ERRORPAGE_ENVSUBST_TEMPLATE_DIR:-/pages}"
  local suffix="${ERRORPAGE_ENVSUBST_TEMPLATE_SUFFIX:-.html}"
  local output_dir="${ERRORPAGE_ENVSUBST_OUTPUT_DIR:-/usr/share/nginx/html}"

  local template defined_envs relative_path output_path subdir
  defined_envs=$(printf '${%s} ' $(env | cut -d= -f1))
  [ -d "$template_dir" ] || return 0
  if [ ! -w "$output_dir" ]; then
    echo >&3 "$ME: ERROR: $template_dir exists, but $output_dir is not writable"
    return 0
  fi

  find "$template_dir" -follow -type f -name "*$suffix" -print | while read -r template; do
    relative_path="${template#$template_dir/}"
    output_path="$output_dir/${relative_path%$suffix}$suffix"
    subdir=$(dirname "$relative_path")
    # create a subdirectory where the template file exists
    mkdir -p "$output_dir/$subdir"
    echo >&3 "$ME: Running envsubst on $template to $output_path"
    envsubst "$defined_envs" < "$template" > "$output_path"

    sed -i "s/^[[:space:]\t\n]*//g" "$output_path"

    cat "${template_dir}/pages.csv" | grep ";" | while read line; do
        CODE=$(echo "$line" | cut -d";" -f1)
        TITLE=$(echo "$line" | cut -d";" -f2)
        DESC=$(echo "$line" | cut -d";" -f3)

        export DEFAULT_CODE=$CODE
        export DEFAULT_TITLE=$TITLE
        export DEFAULT_DESC=$DESC
        export output_path="$output_dir/$CODE$suffix"

        envsubst "$defined_envs" < "$template" > "$output_path"
    done

  done
}

auto_envsubst

exit 0

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

编写 Nginx 配置

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

server {
    listen        ${NGINX_PORT};
    server_name   ${NGINX_HOST};

    charset       utf-8;
    gzip on;

    access_log    off;
    log_not_found off;
    server_tokens off;

    location / {
        root   /usr/share/nginx/html;
        index  index.html;
    }

    error_page 400 /400.html;
    error_page 401 /401.html;
    error_page 403 /403.html;
    error_page 404 /404.html;
    error_page 405 /405.html;
    error_page 407 /407.html;
    error_page 408 /408.html;
    error_page 409 /409.html;
    error_page 410 /410.html;
    error_page 411 /411.html;
    error_page 412 /412.html;
    error_page 413 /413.html;
    error_page 416 /416.html;
    error_page 418 /418.html;
    error_page 429 /429.html;
    error_page 500 /500.html;
    error_page 502 /502.html;
    error_page 503 /503.html;
    error_page 504 /504.html;
    error_page 505 /505.html;

    location = /favicon.ico {
        add_header 'Content-Type' 'image/x-icon';
        return 200 "";
    }

    location = /robots.txt {
        return 200 "User-agent: *\nDisallow: /";
    }
}

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

编写服务容器配置

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

version: '3'

services:

  errorpage-nginx:
    image: nginx:1.19.4-alpine
    volumes:
       - ./templates:/etc/nginx/templates:ro
       - ./docker-entrypoint.d/30-envsubst-on-pages.sh:/docker-entrypoint.d/30-envsubst-on-pages.sh:ro
       - ./pages:/pages:ro
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80
      - DEFAULT_CODE=404
      - DEFAULT_TITLE=The page you're looking for is now beyond our reach. Let's get you..
      - DEFAULT_DESC=Page not found
    networks:
      - traefik
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik"

      - "traefik.http.routers.errorpage.entrypoints=https"
      - "traefik.http.routers.errorpage.tls=true"
      - "traefik.http.routers.errorpage.rule=HostRegexp(`{host:.+}`)"
      - "traefik.http.routers.errorpage.priority=1"
      - "traefik.http.services.error-pages-service.loadbalancer.server.port=80"

      - "traefik.http.routers.error-pages-router.middlewares=error-pages-middleware@docker"
      - "traefik.http.middlewares.error-pages-middleware.errors.status=400-599"
      - "traefik.http.middlewares.error-pages-middleware.errors.service=error-pages-service"
      - "traefik.http.middlewares.error-pages-middleware.errors.query=/{status}.html"

networks:
  traefik:
    external: true

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

最后

我使用的错误页面模版

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

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

–EOF