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或其他 compose 堆疊。請參考 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 狀態碼規範：健康/降級狀態回傳
200 OK，不健康狀態回傳503 Service Unavailable。
3. 設定 Docker Compose 健康探測
- 識別 Next.js 服務：檢查偵測到的 compose 檔案中是否有 Next.js 服務區塊（
nextjs-app、web、app）。 - 注入健康檢查區塊：從 docker-compose.healthcheck.template.yml 加入零依賴的 Node.js fetch 健康探測。
4. 驗證與測試
- 本機 API 測試：
驗證回傳 HTTP 200 以及有效的 JSON 負載（curl -i http://localhost:3000/api/healthstatus、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 健康檢查範本 — 可重複使用的 compose 片段。