BIGboss248/nextjs-wordpress

Next.js 健康检查与可观测性技能 (nextjs-healthcheck)

一个模块化、生产就绪的工作流，用于在 Next.js App Router 应用中创建和维护健康检查端点（/api/health）、零依赖的 Docker Compose 健康探针以及 Node.js 运行时指标。

---

工作流概述

flowchart TD
    A["1. 扫描项目<br/>(数据库和 Docker Compose)"] --> B["2. 生成 /api/health<br/>(包含指标的模板)"]
    B --> C["3. 注入 Docker 探针<br/>(docker-compose.yml)"]
    C --> D["4. 验证与测试<br/>(curl 和 docker compose ps)"]

---

逐步执行手册

请按以下清单顺序执行，以实现和验证应用健康监控：

1. 项目发现与依赖检查

• 定位路由处理器路径：确定项目使用 app/ 还是 src/app/（目标路径：app/api/health/route.ts 或 src/app/api/health/route.ts）。
• 检测数据库/外部存储：扫描 package.json 查找 ORM 和客户端（Prisma、Drizzle、Supabase、Mongoose、PostgreSQL、Redis）。请参考 database-probes.md。
• 定位 Docker Compose 文件：发现 docker-compose.yml、docker-compose.prod.yml 或其他编排文件。请参考 docker-compose-probes.md。

2. 实现健康检查路由处理器

• 选择路由模板：
  • 如果 无数据库：部署 route-no-db.ts.template。
  • 如果 存在数据库：部署 route-with-db.ts.template，并接入项目特定的数据库客户端，设置严格的 2 秒超时。
• 强制动态执行：确保包含 export const dynamic = "force-dynamic"; 以及 Cache-Control: no-store, no-cache, must-revalidate 头部。
• 配置非阻塞指标：收集 V8 堆饱和度、事件循环延迟（通过 perf_hooks 计算的 p99 延迟）和进程运行时间。请参考 status-and-metrics.md。
• 强制 HTTP 状态码规范：对于 healthy/degraded 状态返回 200 OK，对于 unhealthy 状态返回 503 Service Unavailable。

3. 配置 Docker Compose 健康探针

• 识别 Next.js 服务：检查已发现的编排文件中的 Next.js 服务块（nextjs-app、web、app）。
• 注入健康检查块：从 docker-compose.healthcheck.template.yml 添加零依赖的 Node.js fetch 健康探针。

4. 验证与测试

• 本地 API 测试：

  curl -i http://localhost:3000/api/health
  

  验证 HTTP 200 响应，并包含有效的 JSON 负载（status、timestamp、uptimeSeconds、checks）。
• Compose 健康状态检查：

  docker compose ps
  

  验证服务状态在初始启动期后转变为 (healthy)。

---

边缘情况与已知 AI 陷阱

[!WARNING]

• 缺少 force-dynamic：如果省略 export const dynamic = "force-dynamic"，Next.js App Router 可能会静态评估或缓存路由响应，导致时间戳过时和运行时间指标冻结。
• 挂起的数据库连接：切勿在没有竞态超时（最长 2000ms）的情况下查询外部数据库。未处理的网络延迟将导致请求池耗尽。
• 容器中的外部工具依赖：不要在 Docker 健康检查中依赖 curl 或 wget；生产环境的最小化镜像（例如 node:alpine 或 distroless）通常缺少这些工具。请使用 Node.js 原生 fetch 通过 node -e 执行。
• 密钥泄露：切勿在公开的 /api/health 响应负载中打印数据库连接 URL、密码或内部原始错误跟踪信息。

---

输出摘要模式

完成健康检查设置后，提供简洁的摘要报告：

### 健康监控配置完成

- **路由处理器**：`[app/api/health/route.ts](file:///...)`
- **数据库探针**：[已配置：Prisma / Drizzle / 无] (超时：2000ms)
- **运行时指标**：V8 堆饱和度和事件循环延迟 (p99)
- **更新的 Docker Compose 堆栈**：`docker-compose.yml`、`docker-compose.prod.yml`
- **验证状态**：通过 (HTTP 200 / 容器健康)

---

参考指南与模板

• 状态码与指标参考 — 架构状态矩阵、内存计算公式和延迟阈值。
• 数据库探针参考 — 检测清单、超时包装和 ORM 探针模式。
• Docker Compose 探针参考 — 服务匹配规则和零依赖 fetch 定义。
• 路由模板 (无数据库) — 适用于无状态应用的完整路由处理器。
• 路由模板 (有数据库) — 包含依赖探针的完整路由处理器。
• Docker Compose 健康检查模板 — 可复用的编排代码片段。