Nginx 部署 Next.js 指南：利用 health_check 监控 SSR 服务状态-Nginx-PHP中文网

Next.js SSR应用需自建/api/health端点，NGINX Plus可配置主动健康检查，开源Nginx则依赖被动检查+外部探活工具，部署时须确保服务就绪后再接入流量并做好限流与缓存隔离。

nginx 部署 next.js 指南：利用 health_check 监控 ssr 服务状态

Next.js 应用在 SSR（服务端渲染）模式下通常依赖 Node.js 服务（如 next start）提供动态页面和 API 路由。Nginx 作为反向代理，本身不直接感知后端健康状态；要实现真正的服务可用性监控，需配合自定义健康检查端点与 Nginx 的 health_check 指令（需启用 ngx_http_upstream_health_check_module，即商业版 NGINX Plus，或使用开源替代方案）。以下指南聚焦实用、可落地的部署与监控策略，兼顾开源 Nginx 用户。

1. 在 Next.js 中暴露健康检查端点

Next.js 默认不提供健康接口，需手动添加。推荐使用 pages/api/health.ts（或 .js）创建轻量级、无副作用的检查逻辑：

返回 200 OK，响应体可为 {"status": "healthy", "timestamp": "..."}
可选校验关键依赖（如数据库连接池、Redis 连通性），但避免耗时操作或写入行为
不验证会话、Token 或权限——健康检查应绕过业务中间件

示例代码：

export default function handler(req, res) {
  res.status(200).json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    version: process.env.NEXT_PUBLIC_APP_VERSION || 'dev'
  });
}

2. 配置 Nginx upstream 与主动健康检查（NGINX Plus）

若使用 NGINX Plus（支持原生 health_check），可在 upstream 块中启用主动探测：

指定 health_check 参数，设置路径、间隔、失败阈值等
确保 SSR 服务监听地址（如 localhost:3000）已加入 upstream

示例配置：

upstream nextjs_backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    health_check interval=5s uri="/api/health" fails=2 passes=2;
}

注意：该功能 仅限 NGINX Plus，开源 Nginx 不支持原生主动健康检查

3. 开源 Nginx 的替代方案：被动健康检查 + 自定义探活

对于标准开源 Nginx，虽无主动探测，但可通过组合方式实现有效监控：

启用 max_fails 和 fail_timeout 实现被动健康判断（基于请求失败统计）
搭配外部工具（如 curl + systemd 定时任务或 consul-template）定期调用 /api/health，失败时触发 reload 或告警
在 Nginx 日志中记录健康端点访问（location /api/health { access_log /var/log/nginx/health.log; }），便于审计与排查
将健康检查路径排除在缓存规则之外（避免被 proxy_cache 缓存）