Nginx反向代理前置是Docker升级维护期间实现503维护页的核心方案：通过location /{return 503; error_page 503 /maintenance.html;}配合root和add_header Retry-After等指令，实现流量接管与标准响应。
升级维护期间，Docker 服务本身不直接提供“维护页面”功能，关键在于把外部流量（HTTP/HTTPS 请求）临时导向一个静态提示页，而不是让请求失败或打到正在停机的容器上。核心思路是：**在应用容器下线前，用反向代理层接管入口流量，并返回 503 状态码 + 自定义 HTML 页面**。
用 Nginx 反向代理前置做维护开关
这是最常用、最可控的方式。Nginx 部署在 Docker 宿主机或独立容器中，作为所有外部请求的第一入口：
- 准备一个简单的维护页 HTML 文件（如
maintenance.html），含文案、样式和可选倒计时 - 在 Nginx 配置中添加一个
location /块，匹配所有路径，并返回该页面：
location / {<br> return 503;<br> error_page 503 /maintenance.html;<br> root /usr/share/nginx/html;<br>} - 配合
add_header设置标准维护头：
add_header Retry-After "3600";<br>add_header Cache-Control "no-store, no-cache, must-revalidate, max-age=0";
- 维护开始前 reload Nginx 配置；维护结束后删掉该 location 或注释掉，再 reload 即可恢复原路由
用 Docker Compose 编排快速切换
若你已用 Compose 管理服务，可提前定义两个 service：主应用 + 维护页容器。通过修改 docker-compose.yml 实现秒级切换：
- 维护页容器用轻量镜像（如
nginx:alpine），挂载本地maintenance.html到/usr/share/nginx/html/ - 将 Nginx 的 upstream 指向一个统一的服务名（如
backend），然后用docker service update或docker-compose up -d切换 backend 指向维护页容器 - 优势是无需改 Nginx 配置，靠服务发现自动重路由，适合 Swarm 或 Compose V2+ 场景
结合云厂商负载均衡器（如 ALB/NLB）
如果你的流量经过云平台 LB（如阿里云 SLB、AWS ALB、华为云 ELB），可跳过容器层，在基础设施层控制：
- 提前配置一个指向静态 OSS/S3 存储桶的备用目标组（bucket 中放 maintenance.html）
- 维护开始时，将监听器规则临时重定向到该目标组，或修改默认动作返回固定响应（ALB 支持直接配置 HTTP 503 响应体）
- 这种方式完全绕过后端容器，零延迟生效，且不影响 Docker 宿主机状态
注意事项与验证点
别只改配置就上线，务必检查这几项：
- HTTP 状态码必须是 503 Service Unavailable，不是 200 或 404，搜索引擎和客户端会据此暂停重试
- 确认
Retry-After头正确设置，告知客户端何时重试（单位为秒或 HTTP-date 格式） - 测试从公网 curl 访问，看是否返回预期 HTML 和状态码：
curl -I https://your-domain.com - 检查浏览器访问是否加载了页面、无 JS/CSS 报错（确保静态资源路径相对或正确）
- 维护结束后，清除浏览器缓存或加版本号参数（如
?v=20260720）避免旧页被强缓存
