chanjs 2.8.2 → 2.8.4

package/core/Container.js

@@ -1,8 +1,8 @@
 import fs from "fs";
 import path from "path";
-import { pathToFileURL } from "url";
 import { Paths } from "../utils/paths.js";
 import { BaseComponent } from "./BaseComponent.js";
+import { importFile } from "./loader.js";
 import logger from "../utils/logger.js";
 
 const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
@@ -67,6 +67,11 @@ export class Container extends BaseComponent {
 
   /**
    * 物理加载文件、导入模块、安全校验
+   *
+   * 职责分层（组件加载唯一核心）：
+   * 1. 本方法只做「用户输入校验」（模块/文件名白名单 + 路径越界）与「存在性探测」
+   * 2. 文件导入统一委托 loader.importFile（access + pathToFileURL + default 提取 + IO 错误日志），
+   *    与 loadController/loadConfig 共享同一原语，避免两套导入实现行为漂移
    * @private
    */
   async _loadFile(moduleName, fileName, type = this._type) {
@@ -80,15 +85,17 @@ export class Container extends BaseComponent {
       throw new Error(`路径越界: ${filePath}`);
     }
 
+    // 存在性是预期内路径（按需探测），静默返回 null 交给 get 打 info 日志
     try {
       await fs.promises.access(filePath, fs.constants.R_OK);
     } catch {
       return null;
     }
 
-    // 统一 pathToFileURL（与 loader.js 一致，Windows/跨盘安全）
-    const mod = await import(pathToFileURL(filePath).href);
-    return mod.default;
+    // 项目约定组件必须是实例对象（export default new XxxService()）；
+    // 只导出类/函数的文件视为无效组件，不缓存不报错（与 loadController 的过滤口径一致）
+    const mod = await importFile(filePath);
+    return mod && typeof mod === "object" ? mod : null;
   }
 }
 

package/core/Repository.js

@@ -130,6 +130,19 @@ class Repository extends BaseComponent {
     if (!this.db) throw new Error("Database connection not available");
   }
 
+  /**
+   * 写操作 WHERE 防御（fail-closed）：条件字段全部非法时拒绝执行。
+   * 被丢弃的条件会让 del/update 退化为无 WHERE 的全表操作，统一在此拦截。
+   * @param {object} query WHERE 条件
+   * @returns {{success:false,code:number,msg:string,data:{}}|null} 非法返回错误体（调用方应 return），合法返回 null
+   */
+  #assertValidWhere(query) {
+    if (!Object.keys(query).some(f => SORT_FIELD_REGEX.test(f))) {
+      return { success: false, code: CODE_PARAM_INVALID, msg: "操作条件非法", data: {} };
+    }
+    return null;
+  }
+
   /** 当前连接的数据库客户端类型（knex client：mysql2 / pg / better-sqlite3 ...） */
   get _clientType() {
     return this.db?.client?.config?.client || "";
@@ -175,21 +188,26 @@ class Repository extends BaseComponent {
     return row;
   }
 
-  /** 查询全部，默认上限1000条 */
-  async all({ query={}, sort={}, fields=[], limit=1000 }={}) {
+  /**
+   * 查询全部。上限口径统一收口到 config.LIMIT_MAX（this.limit）：
+   * 未传 limit 时默认取 this.limit；显式传入的 limit 也会被钳制到 [1, this.limit]，
+   * 避免"all 默认 1000 / 分页上限 300"两套口径并存。
+   */
+  async all({ query={}, sort={}, fields=[], limit }={}) {
     const err = this._guard({ query });
     if (err) return err;
-    const list = await this._buildBaseQuery({query,sort,fields}).limit(limit);
+    const size = Math.min(Math.max(Number(limit) || this.limit, 1), this.limit);
+    const list = await this._buildBaseQuery({query,sort,fields}).limit(size);
     return { success:true, code:CODE_OK, msg:"查询成功", data: list };
   }
 
-  /** 分页偏移查询 */
+  /** 分页偏移查询（limit 同 all() 口径，钳制到 config.LIMIT_MAX） */
   async find({ query={}, sort={}, fields=[], limit, offset }={}) {
     const err = this._guard({ query });
     if (err) return err;
     let q = this._buildBaseQuery({query,sort,fields});
     typeof offset === 'number' && (q = q.offset(offset));
-    typeof limit === 'number' && (q = q.limit(limit));
+    typeof limit === 'number' && (q = q.limit(Math.min(Math.max(limit, 1), this.limit)));
     return { success:true, code:CODE_OK, msg:"查询成功", data: await q };
   }
 
@@ -234,11 +252,10 @@ class Repository extends BaseComponent {
   async del(query={}) {
     this._checkDB();
     if (!Object.keys(query).length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
-    // 防御纵深：若传入的查询条件字段全部非法（被 applyQuery 静默丢弃），
-    // 会生成不带 WHERE 的全表删除，这里 fail-closed 拒绝执行。
-    if (!Object.keys(query).some(f => SORT_FIELD_REGEX.test(f))) {
-      return { success:false, code:CODE_PARAM_INVALID, msg:"删除条件非法", data:{} };
-    }
+    // 防御纵深：条件字段全部非法（会被 applyQuery 静默丢弃）时，
+    // 会生成不带 WHERE 的全表删除，fail-closed 拒绝执行。
+    const invalid = this.#assertValidWhere(query);
+    if (invalid) return invalid;
     const rows = await applyQuery(this.db(this.tableName), query).del();
     return { success:true, code:CODE_OK, msg:"删除成功", data:{ affectedRows:rows } };
   }
@@ -269,9 +286,8 @@ class Repository extends BaseComponent {
       return { success:false, code:CODE_PARAM_INVALID, msg:"参数无效", data:{} };
     }
     // 防御纵深：与 del 同理，条件字段全部非法时会生成无 WHERE 的全表更新，fail-closed 拒绝。
-    if (!Object.keys(query).some(f => SORT_FIELD_REGEX.test(f))) {
-      return { success:false, code:CODE_PARAM_INVALID, msg:"更新条件非法", data:{} };
-    }
+    const invalid = this.#assertValidWhere(query);
+    if (invalid) return invalid;
     const rows = await applyQuery(this.db(this.tableName), query).update(this.#formatDate(data));
     return { success:true, code:CODE_OK, msg:"更新成功", data:{ affectedRows:rows } };
   }
@@ -299,18 +315,18 @@ class Repository extends BaseComponent {
       if (!item.query || !Object.keys(item.query).length) {
         return { success:false, code:CODE_PARAM_INVALID, msg:"批量更新条件不能为空", data:{} };
       }
-      // 防御纵深：与 update 同口径，条件字段全部非法时 fail-closed 拒绝，
+      // 防御纵深：与 del/update 同口径，条件字段全部非法时 fail-closed 拒绝，
       // 避免生成无 WHERE 的全表更新
-      if (!Object.keys(item.query).some(f => SORT_FIELD_REGEX.test(f))) {
-        return { success:false, code:CODE_PARAM_INVALID, msg:"批量更新条件非法", data:{} };
-      }
+      const invalid = this.#assertValidWhere(item.query);
+      if (invalid) return invalid;
     }
     const trx = await this.db.transaction();
     let total = 0;
     try {
+      // 与单条 update 同口径：条件统一过 applyQuery（操作符解析 + 非法字段过滤），不再裸用 knex where
       for (const { query, data } of updates) {
-        const row = await trx(this.tableName).where(query).update(this.#formatDate(data));
-        row === 0 && logger.info("[Repository] updateMany无匹配行", query);
+        const row = await applyQuery(trx(this.tableName), query).update(this.#formatDate(data));
+        row === 0 && logger.info(`[Repository] updateMany无匹配行 ${JSON.stringify(query)}`);
         total += row;
       }
       await trx.commit();

package/core/bootstrap/middleware.js

@@ -4,10 +4,11 @@ import {
 } from "../../middleware/index.js";
 import { health } from "../../middleware/health.js";
 import { BODY_LIMIT } from "../../config/index.js";
+import logger from "../../utils/logger.js";
 
 /**
  * 注册核心中间件（顺序固化：不可随意调整）
- * WAF 前置 → Favicon → 静态 → Cookie → Body 解析 → WAF Body 检查 → CORS → 日志 → 模板 → 响应头
+ * WAF 前置 → 健康检查 → Favicon → 静态 → CORS → Cookie → Body 解析 → WAF Body 检查 → 日志 → 模板 → 响应头
  * @param {object} chan 框架实例
  */
 export async function registerCoreMiddleware(chan) {
@@ -17,22 +18,36 @@ export async function registerCoreMiddleware(chan) {
   await waf(app, cfg.waf ?? { enabled: false });
   // 1.5 健康检查端点（默认开启，config.health = {enabled,path} 可调；浅模式零 IO）
   app.use(health(chan, cfg.health ?? {}));
+  // 1.6 宿主全局中间件插槽：config.middleware 数组，按声明顺序注册。
+  //     元素支持两种形态：express 中间件本身 (req,res,next)；或工厂 () => express 中间件（需闭包 chan/config 时用）。
+  //     注册位置在核心链早期、模块路由之前，保证对所有响应（含静态资源）生效。
+  //     注意：app/router.js（loadCommonRouter）的执行时机在模块路由之后，app.use 在那里
+  //     只罩得住 404 兜底请求，安全响应头等全局策略应经本插槽注册而非写在 router.js。
+  for (const mw of cfg.middleware ?? []) {
+    const fn = typeof mw === "function" && mw.length <= 1 ? mw(chan) : mw;
+    if (typeof fn !== "function") {
+      logger.warn(`[Chan] config.middleware 含非法项（须为中间件或中间件工厂），已跳过: ${String(mw)}`);
+      continue;
+    }
+    app.use(fn);
+  }
   // 2. Favicon
   favicon(app);
   // 3. 静态资源
   staticMw(app, cfg.statics ?? []);
+  // 3.5 CORS（前移到 body 之前：OPTIONS 预检无需等待 body 解析即返回；
+  //      WAF 拦截预检时响应也能携带 CORS 头，浏览器报错不再误导排障）
+  Cors(app, cfg.cors ?? {});
   // 4. Cookie
   cookie(app, cfg.cookieKey);
   // 5. 请求体解析
   body(app, cfg.BODY_LIMIT ?? BODY_LIMIT);
   // 5.1 WAF Body 检查（须在 body 解析之后）
   wafBody(app, cfg.waf ?? { enabled: false });
-  // 6. CORS
-  Cors(app, cfg.cors ?? {});
   // 7. 请求日志
   log(app, cfg.logger ?? {});
-  // 8. 模板渲染
-  template(app, { views: cfg.views ?? [], NODE_ENV: cfg.NODE_ENV ?? "dev" });
+  // 8. 模板渲染（NODE_ENV 兜底 production：与「默认生产口径」约束一致，生产默认开启模板缓存）
+  template(app, { views: cfg.views ?? [], NODE_ENV: cfg.NODE_ENV ?? "production" });
   // 9. 响应头
   header(app, { APP_NAME: cfg.APP_NAME ?? "ChanCMS", APP_VERSION: cfg.APP_VERSION ?? "1.0.0" });
 }

package/core/bootstrap/router-loader.js

@@ -19,7 +19,8 @@ async function registerRouterFile(filePath, app, router, config) {
       await register(app, router, config);
     }
   } catch (err) {
-    logger.error(`[RouterLoader] 路由文件加载失败: ${filePath}`, err);
+    // 详情必须拼进 msg 本身：logger 的 messageFormat 仅输出 msg 字段，第二参数会被 pino-pretty 忽略导致错误原因丢失
+    logger.error(`[RouterLoader] 路由文件加载失败: ${filePath}\n${err?.stack || err}`);
   }
 }
 

package/core/loader.js

@@ -23,9 +23,10 @@ export async function importFile(filepath) {
     const mod = await import(pathToFileURL(filepath).href);
     return mod.default ?? mod;
   } catch (err) {
+    // 详情必须拼进 msg 本身：logger 的 messageFormat 仅输出 msg 字段，第二参数会被 pino-pretty 忽略导致错误原因丢失
     if (err.code === "ENOENT") logger.error(`[Loader] 文件不存在: ${filepath}`);
     else if (err.code === "EACCES") logger.error(`[Loader] 无访问权限: ${filepath}`);
-    else logger.error(`[Loader] 导入失败 ${filepath}:`, err.message);
+    else logger.error(`[Loader] 导入失败 ${filepath}: ${err?.message || err}`);
     return null;
   }
 }

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

@@ -172,7 +172,8 @@ const otherDb = app.dbManager.get("logs");
 | `REDIS_ENABLED` / `REDIS` | Redis 配置 |
 | `JWT_SECRET` | JWT 签名密钥 |
 | `LOCALE` | i18n 默认语言（默认 `zh-CN`）|
-| `LIMIT_MAX` | Repository 单页上限（默认 300）|
+| `LIMIT_MAX` | Repository 单页上限（默认 300）；`all()`/`find()` 显式 limit 亦被钳制到该值 |
+| `middleware` | 宿主全局中间件插槽：数组，元素为 express 中间件或中间件工厂 `(chan) => mw`，注册于核心链早期（健康检查后、静态资源前），对所有响应生效 |
 | `SLOW_THRESHOLD` | 数据库慢查询阈值（ms，默认 200），超过记 warn 日志 |
 | `SHUTDOWN_TIMEOUT` | 优雅停机强制退出超时（ms，默认 5000）|
 | `BODY_LIMIT` | 请求体上限（默认 `10mb`）|

package/middleware/cookie.js

@@ -3,6 +3,11 @@ import logger from "../utils/logger.js";
 
 /**
  * Cookie解析中间件，支持签名校验
+ *
+ * 职责边界：本中间件只负责「解析」（含签名校验）；「写入侧」的安全属性
+ * （httpOnly / sameSite / secure / maxAge）由业务写入时的 res.cookie(name, value, opts)
+ * 决定，框架不越俎代庖。业务侧统一在 app/common/auth-cookie.js 收口：
+ * sameSite=prd:strict / dev:lax，secure 可配，httpOnly=false 为统一登录态方案的已确认权衡。
  * @param {express.Application} app Express实例
  * @param {string} [cookieKey] Cookie签名密钥
  */

package/middleware/header.js

@@ -1,20 +1,22 @@
 /**
- * 自定义响应头中间件，隐藏原生Express标识，统一输出ChanCMS
- * @param {express.Application} app Express实例
- * @param {{APP_NAME?: string, APP_VERSION?: string}} [opts] 配置选项
+ * 品牌响应头中间件：隐藏原生 Express 标识，统一输出 ChanCMS。
+ *
+ * 注：安全响应头（X-Content-Type-Options / HSTS / Referrer-Policy /
+ * Permissions-Policy / CSP 等）属于宿主业务策略，不在框架层默认设置——
+ * 由各项目的 security-headers 中间件统一收敛（本项目见 app/middleware/security-headers.js）。
+ * 尤其 CSP frame-ancestors 一旦在框架写死 'self'，会与需要被第三方
+ * iframe 嵌入的宿主业务直接冲突，故不在此声明。
  */
 export const header = (app, opts = {}) => {
   const appName = opts.APP_NAME || "ChanCMS";
   const appVer = opts.APP_VERSION || "";
   const poweredBy = appVer ? `${appName}/${appVer}` : appName;
+  // 静态资源在核心链第 3 步即被接住、到不了本中间件，Express 会默认补
+  // X-Powered-By: Express 泄露技术栈——先禁用默认注入，品牌头只由下方显式设置
+  app.disable("x-powered-by");
 
   app.use((_, res, next) => {
     res.setHeader("X-Powered-By", poweredBy);
-    // 常驻安全响应头：无论 WAF 是否启用都生效
-    // 禁止 MIME 嗅探（防 XSS 利用 Content-Type 歧义）
-    res.setHeader("X-Content-Type-Options", "nosniff");
-    // 防点击劫持：仅允许同源 iframe 嵌套（如需被第三方嵌入请按需放宽）
-    res.setHeader("Content-Security-Policy", "frame-ancestors 'self'");
     next();
   });
-};
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.8.2",
+  "version": "2.8.4",
   "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",

package/utils/logger.js

@@ -11,7 +11,7 @@ const timestamp = () => {
 
 // 输出格式：时间 + 空格 + 正文（pino-pretty 默认模板是 [time]: msg，方括号和冒号去不掉，
 // 故忽略 time 字段、改由 messageFormat 把时间拼在行首）
-export const root = pino(
+const root = pino(
   { level: (process.env.LOG_LEVEL || "info").trim(), base: null, timestamp },
   pretty({
     colorize: false,
@@ -19,4 +19,51 @@ export const root = pino(
     messageFormat: "{time} {msg}",
   }),
 );
-export default root;
+
+/**
+ * 附加参数序列化：error/warn 的第二参（Error/对象）拼进消息本身。
+ *
+ * 背景：pino-pretty 的 messageFormat 字符串模板只渲染 msg 字段，
+ * 「logger.error(msg, err)」的 err 会被整体丢弃（连堆栈都不输出），
+ * 曾导致 Gather.js 加载失败只剩「导入失败 xxx.js:」空冒号、无法定位根因。
+ * 在封装层统一序列化，保证文档承诺的「第二参数自动解析堆栈」真实生效。
+ * @param {unknown[]} args error/warn 的除消息外全部参数
+ * @returns {string} 可读文本（Error 优先 stack，对象 JSON，其余 String）
+ */
+function serializeExtra(args) {
+  return args
+    .map(v => {
+      if (v == null) return "";
+      if (v instanceof Error) return v.stack || `${v.name}: ${v.message}`;
+      if (typeof v === "object") {
+        try { return JSON.stringify(v); } catch { return String(v); }
+      }
+      return String(v);
+    })
+    .filter(Boolean)
+    .join(" ");
+}
+
+/**
+ * 统一日志门面：与文档用法对齐（logger.error("xx", err) 自动带出堆栈）
+ * 全部级别统一将附加参数序列化进 msg（pino-pretty messageFormat 只渲染 msg 字段，
+ * 任何直接透传的第二参都会被丢弃），保证 info("xx", obj) 与 error 行为一致
+ */
+const logger = {
+  info(msg, ...extra) {
+    extra.length ? root.info(`${msg} ${serializeExtra(extra)}`) : root.info(msg);
+  },
+  debug: root.debug.bind(root),
+  trace: root.trace.bind(root),
+  fatal: root.fatal.bind(root),
+  child: root.child.bind(root),
+  warn(msg, ...extra) {
+    extra.length ? root.warn(`${msg} ${serializeExtra(extra)}`) : root.warn(msg);
+  },
+  error(msg, ...extra) {
+    extra.length ? root.error(`${msg} ${serializeExtra(extra)}`) : root.error(msg);
+  },
+};
+
+export { root };
+export default logger;

package/utils/signal.js

@@ -23,6 +23,8 @@ async function doShutdown(chan) {
 
   if (server) {
     try {
+      // 先断开空闲 keep-alive 连接，避免 server.close 等待存量长连接拖满停机超时
+      typeof server.closeIdleConnections === "function" && server.closeIdleConnections();
       await new Promise((resolve, reject) => server.close(err => (err ? reject(err) : resolve())));
       logger.info("[Chan] HTTP服务已停止接受新连接");
     } catch (e) {