维护模式的价值
维护模式是把「计划内不可用」和「意外故障」区分开的机制：升级引擎、切换模型、迁移机房时，由网关主动返回 503 并附带建议重试时间，客户端可以据此给出明确提示或自动重试。相比之下，直接停进程会让客户端读到连接超时或连接被拒绝，用户与监控都无法判断这是计划行为还是事故。
基本信息
| 适用层 | 网关或负载均衡层（Nginx、Ingress、企业负载设备） |
|---|---|
| 核心返回 | HTTP 503 Service Unavailable + Retry-After |
| 触发方式 | 发布脚本或运维开关切换，而非手工改运行中的配置 |
| 静态页位置 | 独立站点目录，与业务发布产物分开存放 |
| 记录要求 | 进入与退出维护都要留下时间、操作人、原因 |
典型使用场景
- 引擎大版本升级：需要停止服务数分钟到数十分钟，提前告知比突然断流体验好得多
- 数据库或存储迁移：后端整体不可用期间给出一致的提示页
- 配额与模型切换：切换默认模型时先进入短时维护，避免新老版本混跑产生不一致结果
- 压测前置：为压测单独打开维护开关，把真实用户挡在外面
- 故障降级：后端大面积不可用时主动降级为维护页，避免请求堆积拖垮整个链路
网关维护开关
网关维护开关
location / {
return 503;
# 或指向静态维护页：
# root /var/www/maintenance; try_files /index.html =503;
}
# 在 server 或 location 层补充重试建议
add_header Retry-After 600 always; # 建议客户端 600 秒后重试
add_header X-Maintenance planned always; # 便于监控区分计划内维护返回码与提示对照
| 场景 | 建议返回 | 客户端感知 |
|---|---|---|
| 计划内维护 | 503 + Retry-After | 明确的等待时间，可给用户倒计时提示 |
| 后端短暂不可用 | 502 或 503 | 网关层错误，与维护需通过在监控上打标签区分 |
| 已下线接口 | 410 或 404 | 接口永久移除，不应被重试 |
| 限流触发 | 429 + Retry-After | 请求被拒但服务正常，应退避重试 |
| 正常运行 | 200 | 无需特殊处理 |
维护标志由发布脚本统一控制，避免手工改动引发不一致：进入维护、执行变更、退出维护三步都要有时间戳与操作人记录，事后能对上变更窗口。
维护页应写清恢复时间预期与状态页入口；若无法给出确定时间，至少说明正在处理并给出下次更新时间。