网站升级时显示维护页:保留503状态并验证恢复

适用场景

适用于已经通过Nginx提供服务的网站,在升级、迁移或修复时暂时停止用户访问。示例按Ubuntu 24.04的Nginx配置方式说明,只修改一个网站的HTTPS虚拟主机。面板安装的Nginx要使用面板实际加载的配置和检测命令,不能另装一套Nginx。

维护页只能挡住经过这个入口的新请求,不能停止队列、计划任务、支付回调的其他入口或已经开始的请求。需要暂停写入时,应另行停用本项目的后台写入任务,并安排补单或回调重试;不能把显示维护页当成数据库已经静止。

一、备份配置并准备维护开关

用nginx -T确认域名对应的server块,保存其配置副本到非网站目录。检查是否有负载均衡、CDN或其他直连端口,否则用户可能绕过这个入口。下面的site-example.flag只代表本网站,不要与其他站点共用。

sudo install -d -o root -g root -m 0755 /var/lib/site-maintenance

把以下配置合并到目标HTTPS的server块。开关判断应放在该块原有的return或rewrite规则之前;保留原有证书、域名和正常业务location。命名location用不同名称,避免与现有配置重名。

error_page 503 @site_maintenance;

if (-f /var/lib/site-maintenance/site-example.flag) {
    return 503;
}

location @site_maintenance {
    default_type text/html;
    charset utf-8;
    add_header Retry-After 600 always;
    add_header Cache-Control "no-store" always;
    return 503 '<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>网站维护中</title><h2>网站正在维护</h2><p>请稍后重新访问。</p></html>';
}

这里使用独立的命名location直接返回页面,避免维护页再次进入相同跳转规则。响应保持503,不改成200。Retry-After 600表示建议十分钟后重试,不代表业务一定能在十分钟内恢复,应按维护安排调整。不要在页面写未经确认的完成时间。

二、检测通过后开启

sudo nginx -t
sudo systemctl reload nginx
sudo touch /var/lib/site-maintenance/site-example.flag
curl -sS -D - -o /dev/null https://www.example.com/

只有配置检测成功才执行重载。把域名换成自己的,确认响应为503,并出现Retry-After和no-store。再用浏览器检查中文维护文字,同时测试首页、文章内页、一个静态资源和登录入口。若仍有正常页面,检查缓存、实际入口和是否改错虚拟主机。

可用curl的--resolve www.example.com:443:服务器IP直接检查源站,但仍应使用正式域名验证证书。不要加-k掩盖证书问题,也不要为了测试而关闭整个防火墙。经过CDN的站点还要核对边缘是否缓存了旧页面或维护响应。

三、恢复访问并做真实验收

sudo rm -- /var/lib/site-maintenance/site-example.flag
curl -sS -D - -o /dev/null https://www.example.com/

只删除本次创建的开关文件。此开关本身不要求再次重载Nginx。恢复后验证首页、登录、一次测试提交及需要恢复的队列和计划任务,并检查错误日志。涉及付费业务时使用既定测试方式,不能重复真实扣款。

如果新增配置引起异常,恢复该站点的配置副本,检测通过后重载;若应用升级本身失败,按应用备份方案回退。维护页已经关闭不等于应用恢复成功,外部入口和关键业务都通过才结束维护。

维护期间浏览器可能保留用户正在填写的表单。恢复后应先提示用户刷新状态再重试,避免把旧页面的重复提交当成新的业务请求。带支付或库存变更的操作,需要按应用的重复提交保护规则核对最终结果。