Iris 框架无内置维护模式，需手动实现：在 app.UseGlobal() 中注册高优先级中间件，检查配置或文件开关，命中则返回 503、设置 Retry-After 头并调用 ctx.StopExecution()；不可依赖路由覆盖，须注意缓存、健康端点白名单及文件读取异常处理。
维护模式在Iris中不存在内置机制
Iris 框架本身不提供类似 Laravel 的 php artisan down 维护模式，也没有自动检查 storage/framework/down 文件、返回 503 响应的默认中间件。所谓“维护模式下的全局拦截路由”，必须由开发者手动实现——本质是注册一个高优先级中间件，在所有业务路由前统一判断是否启用维护，并提前终止请求。
如何用中间件模拟全站 503 拦截
核心思路：在 app.UseGlobal() 中插入一个闭包中间件，检查某个开关（如环境变量、配置项或文件存在性），匹配成功则直接写响应并调用 ctx.StopExecution()。
- 推荐开关方式：读取配置项
app.Configuration().IsMaintenance（需提前在iris.Configuration中设置）或检查本地文件是否存在（如./maintenance.flag） - 必须调用
ctx.StatusCode(503)+ctx.Writef(...)或ctx.JSON(...)，否则浏览器收不到标准维护响应 - 务必紧接其后调用
ctx.StopExecution()，否则后续中间件和路由仍会执行 - 静态资源（
public/下文件）不受影响——Iris 默认不走中间件链，除非你显式用app.StaticWeb()并挂了该中间件
示例代码片段：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
app.UseGlobal(func(ctx iris.Context) {
if isMaintenanceMode() { // 自定义函数，比如 return fileExists("./maintenance.flag")
ctx.StatusCode(503)
ctx.ContentType("text/plain; charset=utf-8")
ctx.WriteString("Service temporarily unavailable")
ctx.StopExecution()
return
}
ctx.Next()
})
为什么不能靠路由注册来实现“拦截”
试图用 app.Any("/", maintenanceHandler) 或 app.Get("/*any", ...) 覆盖全部路径，是无效且危险的：
-
app.Any()只捕获未被更精确路由匹配的请求，一旦有app.Get("/health")存在，它就永远收不到请求 -
/*any通配符路由优先级低于静态路径和参数路由，无法保证“全局”生效 - 它不阻止中间件执行，日志、鉴权等仍会跑一遍，违背“快速拦截”初衷
- 无法控制响应头（如
Retry-After），而 503 场景下这个头对爬虫和前端重试逻辑很关键
容易被忽略的细节
维护模式不是开个开关就完事。真正上线时，这几个点常被跳过导致故障：
- 没清理缓存：CDN、浏览器缓存、甚至 Go 的
http.Transport连接池都可能复用旧响应，建议配合设置Cache-Control: no-cache, no-store - 健康检查端点被拦：运维脚本访问
/health也返回 503，导致误判宕机。应在中间件里加白名单 IP 或路径放行 - 文件读取权限问题：若用 flag 文件方式，
os.Stat()失败会静默跳过维护逻辑，建议加日志或 panic 提醒 - 没有设置
Retry-After响应头：浏览器和监控系统依赖它做退避重试，补上ctx.Header("Retry-After", "60")
