使用Docker标签配置Traefik自定义错误页面

我之前也踩过这个坑，官方文档里的<name>确实没说太清楚，其实它指的是Traefik内部用来识别错误页面服务的完整服务标识符，结合Docker后端的场景，给你一步步拆解正确配置：

1. 先部署你的错误页面服务 #

首先需要一个提供自定义错误页面的后端服务（比如用nginx、apache，或者专门的错误页面镜像），给它加上Traefik的标签让Traefik发现它：

version: '3.8'
services:
  # 自定义错误页面服务
  error-page-service:
    image: nginx:alpine
    volumes:
      - ./custom-error-pages:/usr/share/nginx/html  # 挂载你的自定义错误页面文件
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.error-page-service.loadbalancer.server.port=80"
      # 这里的服务名（error-page-service）就是后面要用到的核心部分

2. 给业务服务配置错误页面中间件 #

接下来在你的业务应用服务的Traefik标签里，配置errorpages中间件，这里的<name>要替换成错误页面服务的标识符——格式是[服务名]@docker，也就是上面的error-page-service@docker：

# 你的业务应用服务
  my-business-app:
    image: your-app-image:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-business-app.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.my-business-app.entrypoints=websecure"
      - "traefik.http.routers.my-business-app.tls.certresolver=letsencrypt"
      
      # 1. 给路由绑定错误页面中间件
      - "traefik.http.routers.my-business-app.middlewares=custom-error-pages@docker"
      
      # 2. 定义custom-error-pages中间件
      - "traefik.http.middlewares.custom-error-pages.errorpages.status=502,503,504"  # 触发错误页面的状态码
      - "traefik.http.middlewares.custom-error-pages.errorpages.service=error-page-service@docker"  # 这里的<name>就是这个服务标识符
      - "traefik.http.middlewares.custom-error-pages.errorpages.retryoriginal=false"  # 可选：保持原错误状态码返回

关键解释：到底是什么？ #

官方文档里的<name>其实是Traefik的服务唯一标识，每个通过Docker后端注册的服务，Traefik都会自动生成一个格式为[docker-compose里的服务名]@docker的标识符。你只需要把错误页面服务的名称（比如上面的error-page-service）加上@docker后缀，替换掉文档里的<name>就行。

额外注意事项 #

• 确保错误页面服务的traefik.enable=true标签存在，否则Traefik无法发现这个服务，中间件会失效
• 如果你的错误页面服务不需要对外暴露，不需要给它配置路由规则，只要让Traefik识别为内部服务即可
• Traefik v2和v3的配置逻辑基本一致，标签前缀没有变化，放心套用

内容的提问来源于stack exchange，提问作者shankie_san