维护模式中间件必须全局注册于所有路由前并直接返回503,禁用后续处理;推荐用atomic.Bool控制开关,放行OPTIONS与健康检查,响应纯文本且跳过日志。

维护模式中间件必须拦截所有请求并返回统一响应
直接返回 503 Service Unavailable 是最稳妥的做法,而不是重定向或跳转。Iris 不会自动跳过已注册的路由或中间件,所以维护模式必须在所有业务逻辑之前生效,且不能依赖 ctx.Next()——一旦调用,后续 handler 就会执行,失去“维护中”的语义。
- 维护中间件应注册为全局
app.Use(),放在所有路由注册之前 - 响应体建议用纯文本(如
"Site is under maintenance")或简单 HTML,避免模板渲染引入额外依赖和失败风险 - 不要在维护模式下尝试读取 session、数据库或调用外部服务,否则可能因依赖不可用导致 panic 或超时
- 若需保留健康检查端点(如
/healthz),得在中间件里显式放行:if ctx.Path() == "/healthz" { ctx.Next(); return }
如何安全地开关维护模式而不重启服务
硬编码布尔变量(如 var maintenance = true)无法热更新;用原子操作或互斥锁保护的指针更合适。生产环境推荐通过环境变量或配置文件控制,启动时加载,运行中不修改——真要动态开关,得配合信号(如 SIGHUP)或管理接口(如 POST /admin/maintenance)来更新状态。
- 推荐用
atomic.Bool:声明var maintenanceMode atomic.Bool,用maintenanceMode.Store(true)和maintenanceMode.Load()安全读写 - 避免用
sync.RWMutex包裹普通 bool —— 过重,且容易漏掉锁 - 如果用了
iris.Configuration{DisableStartupLog: true}等配置,维护模式响应也应跳过日志中间件,否则日志刷屏 - 前端可通过响应头加
X-Maintenance: true方便调试或监控识别
常见错误:维护模式没生效或部分路由绕过
根本原因几乎全是注册顺序或路径匹配问题。Iris 的 app.Use() 中间件只对匹配到的路由生效;如果某条路由是用 app.Any() 或通配符 app.Get("/*path") 注册的,而维护中间件又没覆盖它,就可能漏掉。
- 确保
app.Use(maintenanceMiddleware)在app.Get()、app.Party()等任何路由注册之前调用 - 不要把维护中间件放在
app.Done()里——那是响应后执行的,完全无效 - 检查是否误用了分组路由(
app.Party("/api"))但没对根路径app.Use(),导致/路径不受控 - 若启用了静态文件服务(
app.HandleDir()),它默认不走中间件链,需手动包裹或改用app.StaticWeb()并确认其兼容性
一个可直接复用的维护中间件实现
以下代码满足最小可用原则:无依赖、可热更新、兼容 v12.2.0+,且明确处理了 OPTIONS 预检(避免 CORS 失败干扰维护提示)。
func MaintenanceMode(enabled *atomic.Bool) iris.Handler {
return func(ctx iris.Context) {
if !enabled.Load() {
ctx.Next()
return
}
// 放行 OPTIONS,避免预检失败掩盖维护状态
if ctx.Method() == "OPTIONS" {
ctx.StatusCode(204)
return
}
ctx.StatusCode(503)
ctx.Header("Retry-After", "3600")
ctx.WriteString("Site is under maintenance.")
}
}
// 使用示例:
var maintenance atomic.Bool
maintenance.Store(false) // 启动时关闭
app.Use(MaintenanceMode(&maintenance))
// 动态开启(例如从管理接口调用):
// maintenance.Store(true)
注意:这个中间件不处理 favicon.ico、robots.txt 等隐式请求,如需统一响应,得在 app.Use() 前加一条 app.Handle("GET", "/favicon.ico", ...) 显式拦截——Iris 不会自动为你补全这类细节。











