Errors

errors 中间件根据配置的 HTTP 状态码范围返回自定义页面，替代默认页面。

配置示例¶

结构化 (YAML)

# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
http:
  middlewares:
    test-errors:
      errors:
        status:
          - "500"
          - "501"
          - "503"
          - "505-599"
        statusRewrites:
          "418": 404
          "502-504": 500
        service: error-handler-service
        query: "/{status}.html"

  services:
    # ... definition of the error-handler-service

结构化 (TOML)

# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
[http.middlewares]
  [http.middlewares.test-errors.errors]
    status = ["500","501","503","505-599"]
    service = "error-handler-service"
    query = "/{status}.html"

    [http.middlewares.test-errors.errors.statusRewrites]
      "418" = 404
      "502-504" = 500

[http.services]
  # ... definition of the error-handler-service

容器标签

# Dynamic Custom Error Page for 5XX Status Code
labels:
  - "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
  - "traefik.http.middlewares.test-errors.errors.statusRewrites.418=404"
  - "traefik.http.middlewares.test-errors.errors.statusRewrites.502-504=500"
  - "traefik.http.middlewares.test-errors.errors.service=error-handler-service"
  - "traefik.http.middlewares.test-errors.errors.query=/{status}.html"

服务标签

// Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
{
  // ...
  "Tags": [
    "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599",
    "traefik.http.middlewares.test-errors.errors.statusRewrites.418=404",
    "traefik.http.middlewares.test-errors.errors.statusRewrites.502-504=500",
    "traefik.http.middlewares.test-errors.errors.service=error-handler-service",
    "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
  ]

}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-errors
spec:
  errors:
    status:
      - "500"
      - "501"
      - "503"
      - "505-599"
    statusRewrites:
      "418": 404
      "502-504": 500
    query: /{status}.html
    service:
      name: error-handler-service
      port: 80

配置选项¶

字段	说明	默认值	必填
`status`	定义哪些状态码或状态码范围应触发错误页面。状态码范围包含两端（`505-599` 会在 `505` 至 `599` 的每个状态码触发，包括 `505` 和 `599`）。可以定义单个数字状态码（`500`）、多个逗号分隔的数字（`500,502`）、使用连字符分隔两个状态码定义的范围（`505-599`），或两者的组合（`404,418,505-599`）。	[]	否
`statusRewrites`	可选的状态码重写映射。更多信息见此处。	[]	否
`service`	提供新请求的错误页面的服务。更多信息见此处。	""	是
`query`	错误页面的 URL（由 `service` 托管）。更多信息见此处。	""	否
`errorRequestHeaders`	定义转发给错误页面服务的原始请求头列表。更多信息见此处。	[]	否

service 与 HostHeader¶

默认情况下，会将客户端的 Host 头值转发给配置的错误服务。要转发与配置的错误服务 URL 对应的 Host 值，必须将 passHostHeader 选项设置为 false。

Kubernetes

在 Kubernetes 中指定服务（例如在 IngressRoute 中）时，需要引用 Kubernetes Service 资源的 name、namespace 和 port。例如，my-service.my-namespace@kubernetescrd（或 my-service.my-namespace@kubernetescrd:80）可确保请求发送到正确的服务和端口。

ServersTransport（Kubernetes）

要自定义 Traefik 如何连接错误页面服务（例如配置到后端的 TLS），请在中间件的 service 上设置 serversTransport。此处不会应用 Kubernetes Service 上的 traefik.ingress.kubernetes.io/service.serverstransport 注解：它仅影响作为 Ingress 后端使用的 Service，不影响由中间件引用的 Service。

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-errors
spec:
  errors:
    status:
      - "500"
      - "501"
    service:
      name: error-handler-service
      port: 80
      serversTransport: mytransport

statusRewrites 状态码重写¶

statusRewrites 是可选的状态码重写映射。

例如，服务返回 418 时，你可能希望将其重写为 404。可以将单个状态码或整个范围映射为另一个状态码。

范围的语法与 status 选项遵循相同规则。

query 查询¶

可在 query 选项中放置多个变量，向 URL 插入相应的值。

下表列出所有可用变量及对应的值。

变量	值
`{status}`	响应状态码。
`{originalStatus}`	如果响应状态码被 `statusRewrites` 选项修改，则此值为原始响应状态码。
`{url}`	经过转义的请求 URL。

`errorRequestHeaders` 错误请求头¶

定义转发给错误页面服务的原始请求头列表。

默认情况下（未设置 errorRequestHeaders），所有请求头都会转发，包括 Authorization 和 Cookie 等认证信息。如果错误页面服务位于不同的信任域，请使用此选项限制跨越服务边界的请求头。

设置为显式列表时，只转发这些请求头；设置为空列表（errorRequestHeaders: []）时，不转发任何请求头。