chanjs 2.8.4 → 2.8.6

package/doc/06-/345/272/224/347/224/250/347/224/237/345/221/275/345/221/250/346/234/237.md

@@ -174,6 +174,7 @@ const otherDb = app.dbManager.get("logs");
 | `LOCALE` | i18n 默认语言（默认 `zh-CN`）|
 | `LIMIT_MAX` | Repository 单页上限（默认 300）；`all()`/`find()` 显式 limit 亦被钳制到该值 |
 | `middleware` | 宿主全局中间件插槽：数组，元素为 express 中间件或中间件工厂 `(chan) => mw`，注册于核心链早期（健康检查后、静态资源前），对所有响应生效 |
+| `health` | 内置健康检查端点：`{ enabled: true, path: '/health' }`（默认值）。健全部署返回 HTTP **200**、degraded（含内部异常）返回 HTTP **503**，便于探针/负载均衡摘除实例。浅模式零 IO——只读进程内 DB 健康缓存，不实时 ping。`enabled: false` 可整体关闭，`path` 可改路径 |
 | `SLOW_THRESHOLD` | 数据库慢查询阈值（ms，默认 200），超过记 warn 日志 |
 | `SHUTDOWN_TIMEOUT` | 优雅停机强制退出超时（ms，默认 5000）|
 | `BODY_LIMIT` | 请求体上限（默认 `10mb`）|

package/middleware/health.js

@@ -9,7 +9,11 @@ import { store } from "../storage/index.js";
  * DB 健康缓存由 error-handler 在真实查询成功/失败时维护（markUp/markDown）。
  *
  * 配置（config/index.js）：
- *   health: { enabled: true, path: '/health' }   // 默认值，可整体关闭或改路径
+ *   health: { enabled: true, path: '/health' }   // 默认值；enabled:false 可整体关闭，path 可改路径
+ *
+ * HTTP 状态码：健康 → 200；degraded（含内部异常）→ 503。
+ *   —— 探针/负载均衡据此摘除故障实例，故 degraded 必须体现为 503。
+ *   —— enabled:false 时注册的是透传中间件（不是不注册），保证 app.use() 始终拿到函数。
  *
  * 响应示例：
  *   { "success":true, "code":0, "msg":"ok", "data":{
@@ -18,12 +22,17 @@ import { store } from "../storage/index.js";
  *       "db":[{ "name":"default", "healthy":true }],
  *       "store":{ "mode":"memory", ... }
  *   } }
+ *   degraded 时：HTTP 503 + { "success":false, "code":5001, "msg":"degraded", ... }
  */
 
 const DEFAULT_PATH = "/health";
 
 export const health = (chan, opts = {}) => {
-  if (opts.enabled === false) return;
+  // 关闭时必须返回「合法中间件」，不能 return undefined：
+  // 调用方 core/bootstrap/middleware.js 是无条件 app.use(health(chan, cfg.health ?? {}))，
+  // 返回 undefined 会让 Express 抛 `TypeError: app.use() requires a middleware function`，
+  // 且发生在启动阶段 → 进程直接退出（配置项反而变成崩溃开关）。
+  if (opts.enabled === false) return (req, res, next) => next();
   const path = opts.path || DEFAULT_PATH;
   const startedAt = Date.now();
 
@@ -32,9 +41,11 @@ export const health = (chan, opts = {}) => {
     try {
       const db = chan.dbManager?.healthSnapshot?.() ?? [];
       const degraded = db.some(d => !d.healthy);
-      res.status(200).json({
-        success: true,
-        code: 0,
+      // 状态码必须反映真实健康度：degraded → 503。
+      // 旧实现恒 200，探针/负载均衡无法据此摘除故障实例（degraded 形同无效）。
+      res.status(degraded ? 503 : 200).json({
+        success: !degraded,
+        code: degraded ? 5001 : 0,
         msg: degraded ? "degraded" : "ok",
         data: {
           status: degraded ? "degraded" : "ok",
@@ -45,9 +56,10 @@ export const health = (chan, opts = {}) => {
       });
     } catch (err) {
       logger.error(`[Health] 健康检查异常：${err.message}`);
-      res.status(200).json({
-        success: true,
-        code: 0,
+      // 内部异常同样按「不可用」上报，不再伪装成 200
+      res.status(503).json({
+        success: false,
+        code: 5001,
         msg: "degraded",
         data: { status: "degraded", uptime: Math.floor((Date.now() - startedAt) / 1000), db: [], store: null },
       });

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",
@@ -51,11 +51,11 @@
     "pg": "^8.23.0",
     "pino": "^9.5.0",
     "pino-http": "^10.3.0",
+    "pino-pretty": "^13.1.3",
     "serve-favicon": "^2.5.1",
     "xss": "^1.0.15"
   },
   "devDependencies": {
-    "pino-pretty": "^11.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/utils/request.js

@@ -5,6 +5,8 @@ import { promisify } from "util";
 const dnsLookup = promisify(dns.lookup);
 const DEFAULT_TIMEOUT = 10000;
 const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** 重定向跳数上限（逐跳重新过 SSRF 校验） */
+const MAX_REDIRECTS = 5;
 
 /** IPv4 私网/回环段 */
 const IPV4_PRIVATE = /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|0\.0\.0\.0$)/;
@@ -38,6 +40,11 @@ async function isPrivateUrl(urlStr) {
 /**
  * HTTP 请求封装：超时/重试/SSRF 防护/大小限制
  * 支持 JSON 和原始数据（Buffer/文本）两种模式
+ *
+ * SSRF 防护是「逐跳」的：redirect 固定为 "manual"，重定向不自动跟随，
+ * 每一跳（含 302/301/307/308 的目标）都重新做协议白名单 + DNS 解析后 IP 校验，
+ * 跳数上限 MAX_REDIRECTS。调用方无法通过 options 覆盖 redirect。
+ *
  * @param {string} url - 请求地址
  * @param {Object} [options={}] - 请求配置
  * @param {number} [options.timeout=10000] - 超时时间(ms)
@@ -60,7 +67,7 @@ export async function request(url, options = {}) {
     ...rest
   } = options;
 
-  // SSRF 防护
+  // SSRF 防护（首跳；重定向目标在下方请求循环内逐跳校验）
   if (await isPrivateUrl(rawUrl)) {
     return { success: false, error: `SSRF防护拦截：${rawUrl}` };
   }
@@ -87,7 +94,43 @@ export async function request(url, options = {}) {
     const timer = timeout > 0 ? setTimeout(() => controller.abort(), timeout) : null;
 
     try {
-      const res = await fetch(rawUrl, { ...fetchOpts, signal: controller.signal });
+      // 重定向逐跳处理：redirect:"manual" 让 fetch 不自动跟随，由本循环接管，
+      // 并对「每一跳」重新做 SSRF 校验。
+      // 旧实现未设 redirect（默认 "follow"）且只校验了首个 URL ——
+      // 公网地址返回 302 指向 127.0.0.1 / 169.254.169.254 即可绕过防护。
+      // 注意：redirect 放在 ...fetchOpts 之后，调用方无法覆盖该安全约束。
+      let currentUrl = rawUrl;
+      let res;
+      for (let hop = 0; ; hop++) {
+        if (hop > MAX_REDIRECTS) {
+          if (timer) clearTimeout(timer);
+          return { success: false, error: `重定向次数超过上限(${MAX_REDIRECTS})：${rawUrl}` };
+        }
+        res = await fetch(currentUrl, { ...fetchOpts, redirect: "manual", signal: controller.signal });
+        // 非 3xx 即最终响应
+        if (!(res.status >= 300 && res.status < 400)) break;
+
+        const loc = res.headers.get("location");
+        // 释放重定向响应体，避免 socket 泄漏
+        try { await res.body?.cancel(); } catch { /* 已关闭则忽略 */ }
+        if (!loc) {
+          if (timer) clearTimeout(timer);
+          return { success: false, error: `HTTP ${res.status} 重定向缺少 Location 头` };
+        }
+        let next;
+        try {
+          next = new URL(loc, currentUrl).href; // 相对路径按当前 URL 补全
+        } catch {
+          if (timer) clearTimeout(timer);
+          return { success: false, error: `重定向地址非法：${loc}` };
+        }
+        // 关键：重定向目标必须重新过一遍 SSRF 校验（协议白名单 + DNS 解析后 IP 判定）
+        if (await isPrivateUrl(next)) {
+          if (timer) clearTimeout(timer);
+          return { success: false, error: `SSRF防护拦截（重定向目标）：${next}` };
+        }
+        currentUrl = next;
+      }
       if (timer) clearTimeout(timer);
 
       if (!res.ok) {