Traefik V3如何临时禁用HTTP/TCP路由并返回503维护状态

核心思路 #

通过配置ErrorPages中间件关联维护页面服务，同时将目标服务标记为不可用，触发Traefik返回503状态码并展示维护提示。

步骤1：部署维护页面服务 #

用Nginx快速搭建静态维护页面服务（也可替换为其他静态服务），示例Docker Compose配置：

services:
  maintenance:
    image: nginx:alpine
    volumes:
      - ./maintenance.html:/usr/share/nginx/html/index.html
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.maintenance.loadbalancer.server.port=80"
      # 仅内部调用，无需暴露外部路由

创建maintenance.html自定义维护提示：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>服务维护中</title>
</head>
<body>
    <h1>503 服务维护中</h1>
    <p>我们正在进行系统升级，预计XX时间恢复服务，感谢您的理解。</p>
</body>
</html>

步骤2：配置ErrorPages中间件 #

方式A：动态配置文件（推荐） #

在Traefik动态配置文件（如dynamic.yml）中定义维护中间件：

http:
  middlewares:
    maintenance-mode:
      errorPages:
        status:
          - "503"
        service: maintenance
        query: "/index.html"

确保Traefik主配置traefik.yml已加载File Provider：

providers:
  file:
    filename: ./dynamic.yml
    watch: true

方式B：Docker注解直接配置 #

直接在目标服务的Docker Labels中定义中间件：

labels:
  - "traefik.http.middlewares.maintenance.errorpages.status=503"
  - "traefik.http.middlewares.maintenance.errorpages.service=maintenance"
  - "traefik.http.middlewares.maintenance.errorpages.query=/index.html"

步骤3：启用维护模式 #

给需要维护的目标服务添加中间件关联，并标记服务不可用：

# 目标服务的Docker Labels
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.my-service.middlewares=maintenance-mode@file" # 对应方式A的中间件
  # 若用方式B，替换为 maintenance@docker
  - "traefik.http.services.my-service.loadbalancer.server.port=8080"
  # 设置权重为0，让Traefik判定服务不可用，触发503
  - "traefik.http.services.my-service.loadbalancer.weight=0"

排查要点 #

• 检查Traefik日志，确认中间件和服务是否被正确加载
• 启用Traefik API（api: { insecure: true }），访问http://traefik-ip:8080/dashboard/查看路由与中间件的关联状态
• 确认维护服务正常运行，Traefik能通过服务发现找到它

内容的提问来源于stack exchange，提问作者Arun Kumar V