chanjs 2.7.12 → 2.7.15

package/README.md

@@ -1,84 +1,102 @@
 # ChanJS
 
-基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。模块自治 + 跨模块双通道协作，约定优于配置，开箱即用。
+基于 Node.js + Express 5 构建的**标准 HMVC（NHMVC）后端框架**，原生 ESM 纯 JavaScript 开发。
+以**模块自治 + 双通道跨模块协作**为核心，约定优于配置，开箱即用，拒绝冗余复杂。
+
+## 设计哲学
+
+> 
+> **大道至简。**
+> 优秀的开发工具，应当化繁为简。ChanJS 摒弃过度设计与沉重抽象，回归纯粹 JavaScript，用最少的心智负担交付稳定高效的业务能力。
+
+## 核心亮点
+
+- 🛡️ **安全可控**：内置多层防护能力，降低业务安全开发成本
+- ⚡ **高性能**：高性能日志、按需组件加载、慢查询监控
+- 🪶 **轻量精简**：无多余抽象、低侵入、上手门槛低
+- ✅ **务实好用**：聚焦后端业务高频场景，配套完整基础设施
 
 ## 特性
 
 ### 核心架构
-- Express 5+ 原生
-- Node.js 22.18+
-- ES Modules（import / export）
-- 标准 HMVC 架构（模块自治 + 跨模块双通道协作）
-- 约定优于配置
+
+- 原生基于 Express 5+
+- 最低运行环境 Node.js 22.18+
+- 全量 ES Modules（import / export）
+- **标准 HMVC 架构：模块自治 + 双通道跨模块协作**
+- 约定优于配置，减少样板配置代码
 
 ### 基础设施
-- **日志**：[pino](https://github.com/pinojs/pino) 高性能结构化日志
-- **请求日志**：pino-http，自动生成 requestId 贯穿全链路
-- **国际化**：[i18next](https://www.i18next.com/) 多语言支持
-- **事件总线**：EventBus，基于 Node 内置 EventEmitter
-- **定时任务**：Task，基于 [node-cron](https://github.com/node-cron/node-cron)
-- **数据库**：[Knex](https://knexjs.org/) 查询构建器，慢查询监控
-- **组件容器**：按需动态加载 controller/service，成功永久缓存、缺失不缓存
-- **优雅停机**：统一信号处理，资源按序释放
-
-### 安全能力
-- WAF 防火墙
-- XSS 防护
-- 关键词过滤
-- 请求限流
-- 路由白名单
-- Cookie 安全
-
-### 中间件生态
-- CORS
-- 请求解析（body / cookie）
-- 静态资源
-- favicon
-- 请求头注入
-- Art-template 模板引擎
-
-### 开发体验
-- 多环境配置（.env.dev / .env.prd）
-- 统一响应（success / fail）
+
+- **高性能日志**：Pino 结构化日志输出
+- **全链路请求追踪**：pino‑http，自动注入唯一 `requestId`
+- **国际化多语言**：i18next，内存高速语言查找
+- **全局事件总线**：轻量封装 Node.js EventEmitter，解耦业务事件
+- **定时任务调度**：node‑cron，自带异常捕获、停机安全回收
+- **数据库层**：Knex 查询构建器，内置慢查询监控告警
+- **按需组件容器**：Controller/Service 动态懒加载，成功实例永久缓存；缺失模块不缓存，修改文件即时生效
+- **优雅停机**：统一信号监听，资源有序释放，超时强制退出
+
+### 内置安全能力
+
+- WAF 基础防火墙
+- XSS 请求防护
+- 敏感关键词过滤
+- 接口请求限流
+- 路由访问白名单
+- Cookie 安全加固
+
+### 开箱即用中间件生态
+
+- CORS 跨域处理
+- Body / Cookie 请求解析
+- 静态资源托管
+- favicon 快捷支持
+- 自定义响应头注入
+- Art‑template 模板引擎渲染
+
+### 优秀开发体验
+
+- 多环境配置隔离（`.env.dev` / `.env.prd`）
+- 标准化统一返回体（success / fail）
 - Zod 参数校验中间件
-- 全局异常处理
-- 工具函数库
+- 全局异常捕获兜底
+- 内置通用工具函数库
 
 ## 目录结构
 
 ```
 |- app/
-|   |- common/            # 公共路由
-|   |- helper/            # 辅助函数
-|   |- middleware/        # 应用中间件
-|   |- modules/           # 业务模块
-|   |   |- <module>/
+|   |- common/            # 公共业务路由
+|   |- helper/            # 全局辅助工具函数
+|   |- middleware/        # 应用级中间件
+|   |- modules/           # 业务模块根目录
+|   |   |- <module>/      # 单个业务模块
 |   |       |- controller/
 |   |       |- service/
 |   |       |- middleware/
 |   |       |- router.js
-|   |- router.js
-|- config/                # 框架常量与环境加载
-|- data/                  # 运行数据
-|- doc/                   # 文档
-|- lang/                  # i18n 资源（zh-CN/en-US/...）
-|- public/                # 静态资源
-|- view/                  # 模板视图
-|- app.js                 # 业务入口
-|- .env.dev / .env.prd    # 环境变量
-|- pm2.json               # 进程管理
+|   |- router.js          # 根路由聚合
+|- config/                # 框架配置、环境变量加载
+|- data/                  # 运行时持久化数据目录
+|- doc/                   # 项目文档
+|- lang/                  # i18n 语言资源(zh‑CN/en‑US/...)
+|- public/                # 前端静态资源
+|- view/                  # 视图模板文件
+|- app.js                 # 项目业务入口
+|- .env.dev / .env.prd    # 环境配置文件
+|- pm2.json               # PM2 进程部署配置
 ```
 
 ## 快速开始
 
-```javascript
+```
 import Chan from "chanjs";
 
 const chan = new Chan();
 
-// 注册启动前置钩子
+// 注册启动前置钩子（事件、定时任务等初始化）
 chan.beforeStart(() => {
-  // 此处可注册事件监听、定时任务等
 });
 
 await chan.start();        // 加载配置、i18n、数据库、中间件、路由
@@ -87,65 +105,65 @@ chan.run((port) => {       // 启动 HTTP 服务
 });
 ```
 
-## 核心能力
+## 核心能力详解
 
-### 1. 日志系统（pino）
+### 1. 日志系统（Pino）
 
-dev 环境彩色输出，prod 环境输出 JSON（pm2 捕获 stdout）。API 完全兼容旧用法。
+开发环境彩色控制台输出；生产环境输出 JSON 结构化日志，适配 PM2 采集。API 向下完全兼容。
 
-```javascript
+```
 import logger, { createLogger } from "chanjs";
 
-// 全局日志
+// 全局日志实例
 logger.info("启动完成");
-logger.error("查询失败", err);   // 自动分离 Error 对象
+logger.error("查询失败", err);   // 自动识别 Error 对象
 
-// 带模块标签的子日志
+// 创建带业务标签的子日志
 const dbLog = createLogger("DB");
 dbLog.warn("慢查询");
 ```
 
-请求日志由 pino-http 自动处理，每个请求生成唯一 `requestId`，业务中通过 `req.log` 输出带 requestId 的日志：
+请求日志由 `pino‑http` 自动接管，每个请求分配唯一 `requestId`，Controller 内可直接携带链路日志：
 
-```javascript
+```
 // 在 Controller 中
 async getUser(req, res) {
-  req.log.info("查询用户详情");  // 自动携带 requestId
-  // ...
+  req.log.info("查询用户详情");  // 日志自动附带 requestId
 }
 ```
 
 ### 2. 事件总线（EventBus）
 
-基于 Node 内置 EventEmitter 的轻量封装，全局单例。
+基于 Node.js 原生 EventEmitter 封装的全局单例事件中心，用于业务解耦。
 
-```javascript
+```
 import { event, EventBus } from "chanjs";
 
-// 全局实例
+// 使用全局事件实例
 const off = event.on("user.login", (uid) => {
   logger.info(`用户 ${uid} 登录`);
 });
 event.emit("user.login", 1001);
-off();  // 取消监听
+off();  // 解绑监听
 
-// 独立实例（隔离场景）
+// 创建独立隔离的事件实例
 const localBus = new EventBus();
 ```
 
-> 详见 [doc/07-事件系统EventBus.md](./doc/07-事件系统EventBus.md)
+> 
+> 详细文档：[doc/07‑事件系统EventBus.md](./doc/07%E2%80%91%E4%BA%8B%E4%BB%B6%E7%B3%BB%E7%BB%9FEventBus.md)
 
 ### 3. 定时任务（Task）
 
-基于 node-cron 封装，支持 cron 表达式校验、异常自动捕获、优雅停机。
+基于 node‑cron 封装，内置 cron 表达式校验、任务异常捕获、优雅停机回收。
 
-```javascript
+```
 import Chan from "chanjs";
 
 const chan = new Chan();
 
 chan.beforeStart(() => {
-  // 注册定时任务（启动时自动开始）
+  // 注册定时任务，框架启动后自动运行
   chan.task.add("clear-log", "0 3 * * *", async () => {
     await chan.db.raw("DELETE FROM logs WHERE created_at < NOW() - INTERVAL 7 DAY");
   });
@@ -157,7 +175,7 @@ chan.run();
 
 ### 4. 国际化（i18next）
 
-启动时扫描 `lang/` 目录加载全部语言资源到内存，运行时 O(1) 查找。
+服务启动时一次性扫描加载 `lang/` 全部语言资源至内存，运行时 O(1) 快速读取翻译文本。
 
 ```
 lang/
@@ -167,7 +185,7 @@ lang/
     common.json    # { "user.welcome": "Welcome, {{name}}" }
 ```
 
-```javascript
+```
 import { initLang } from "chanjs";
 
 const i18n = await initLang("zh-CN");
@@ -176,86 +194,107 @@ i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
 
 ### 5. 数据库（Knex + 慢查询监控）
 
-多连接管理，自动慢查询与错误监控。
+支持多数据库连接管理，自动开启慢查询与 SQL 异常监控。
 
-```javascript
-// 框架启动时根据 config.db 自动注册连接
-// 业务中通过 this.db 或 getApp().db 访问默认连接
+```
+// 框架启动自动读取 config.db 注册数据库连接
+// 业务代码内可通过 this.db / getApp().db 获取默认连接
 
-// 运行时调整慢查询阈值
-chan.dbManager.setSlowThreshold(500);  // 500ms
+// 运行时动态调整慢查询告警阈值（毫秒）
+chan.dbManager.setSlowThreshold(500);
 ```
 
-### 6. 组件容器（跨模块按需获取）
+### 6. 组件容器 · 双通道跨模块调用
 
-Controller / Service 都继承 `Container`，自带 `this.get()`，按「模块名 + 文件名」动态加载组件。
-成功永久缓存；缺失不缓存（文件新增后立即感知）。
+Controller / Service 继承容器基类，内置 `this.get()` 方法，通过「模块名 + 组件名」动态加载跨模块业务组件。
 
-```javascript
-// 同模块获取 Service（Service 容器默认 type=service）
+> 
+> 加载成功后实例永久缓存；组件文件缺失不缓存，新增文件无需重启即可识别。
+
+```
+// 同模块调用 Service
 const cat = await this.get("book", "BookCategory");
 
-// 跨模块获取其他模块的 Service（Controller 容器默认 type=controller，取 service 需传第三参）
+// 跨模块调用 Service（推荐，HMVC 双通道‑服务通道）
 const book = await this.get("book", "Book", "service");
 const special = await this.get("cms", "Special", "service");
 ```
 
-- 存在返回实例并永久缓存；缺失返回 `null`，下次实时感知。
-- 自带非法名称 / 路径越界安全校验。
-- 异步方法，需 `await`。
-- 跨模块协作优先用 `get`，避免手写 `../../` 相对路径 import。
+- 返回实例或 null，异步调用必须 await
+- 内置名称校验、路径越界安全防护
+- 跨模块业务复用优先使用容器调用，摒弃超长相对路径 import
 
-### HMVC 定位（标准实现）
+#### HMVC 标准实现说明
 
-教科书把「Controller 嵌套调用 Controller + 运行时子请求」当作 HMVC 的标准，其实是把**实现手段**当成了标准，是片面的。
-HMVC 的本质是**分层 + 模块自治 + 跨模块复用**。Chanjs 抓住本质，支持**双通道跨模块协作**：
+传统教程常将「控制器嵌套发起子 HTTP 请求」当作 HMVC 的标准，该方式混淆了**实现手段**和架构本质。
 
-- `await this.get("模块", "Controller")` —— 获取其他模块的 Controller（默认本容器类型）
-- `await this.get("模块", "Service", "service")` —— 获取其他模块的 Service（推荐路径）
+> 
+> HMVC 的核心 = 分层解耦 + 模块自治 + 跨模块业务复用。
 
-因此 Chanjs 是更贴合 HMVC 本质的**标准 HMVC 实现**，教科书把手段当标准才是过时的变体。
+ChanJS 提供双通道协作模式，回归 HMVC 本质：
+
+1. 控制器通道：`await this.get("模块", "Controller")`
+2. 服务通道（推荐）：`await this.get("模块", "Service", "service")`
 
 ### 7. 优雅停机
 
-统一处理 SIGTERM / SIGINT / SIGQUIT，按序释放资源：
+统一监听 `SIGTERM / SIGINT / SIGQUIT` 退出信号，按顺序逐级释放资源：
 
 ```
 HTTP 服务 → 定时任务 → 缓存存储 → 数据库连接 → 事件总线
 ```
 
-单个资源关闭失败不阻断其他资源，超时强制退出。
+单个资源关闭失败不会阻断其余回收流程，超时后进程强制退出。
+
+## 环境变量配置
 
-## 环境变量
+| 变量 | 说明 | 默认值 |
+| --- | --- | --- |
+| `NODE_ENV` | 运行环境标识(dev/prd) | dev |
+| `PORT` | HTTP 监听端口 | 3000 |
+| `LOCALE` | 默认语言 | zh‑CN |
+| `LOG_LEVEL` | 日志输出级别 | dev:debug / prd:info |
+| `TRUSTED_PROXIES` | 信任反向代理网段 | loopback |
+| `SHUTDOWN_TIMEOUT` | 优雅停机超时时间(ms) | 5000 |
+| `REDIS_ENABLED` | 是否开启 Redis | false |
 
-| 变量 | 说明 | 默认 |
-|------|------|------|
-| `NODE_ENV` | 环境（dev/prd） | dev |
-| `PORT` | HTTP 端口 | 3000 |
-| `LOCALE` | 默认语言 | zh-CN |
-| `LOG_LEVEL` | 日志级别 | dev:debug / prd:info |
-| `TRUSTED_PROXIES` | 信任代理 | loopback |
-| `SHUTDOWN_TIMEOUT` | 停机超时(ms) | 5000 |
-| `REDIS_ENABLED` | 启用 Redis | false |
+## 项目依赖清单
 
-## 依赖
+### 运行依赖
 
-### 运行时依赖
 - express ^5.2.1
 - knex ^3.2.10
 - pino ^9.5.0
-- pino-http ^10.3.0
+- pino‑http ^10.3.0
 - i18next ^24.2.0
-- node-cron ^3.0.3
-- art-template ^4.13.4
+- node‑cron ^3.0.3
+- art‑template ^4.13.4
 - mysql2 ^3.22.3
 - ioredis ^5.4.6
 
 ### 开发依赖
-- pino-pretty ^11.3.0
+
+- pino‑pretty ^11.3.0
 
 ### 可选 Peer 依赖
-- zod ^4.4.3（参数校验）
 
-## License
+- zod ^4.4.3（接口参数校验）
+
+## Hono 高性能版本
+
+[chanjs‑hono](https://www.npmjs.com/package/chanjs%E2%80%91hono) 为 ChanJS 衍生高性能分支，基于 Hono，API 保持一致，性能更强。
+
+```
+npm install chanjs-hono
+```
+
+## 文档 & 生态资源
+
+- ChanJS官网文档：[ChanJS](https://chancms.top/)
+- ChanJS-Hono官网文档：[ChanJS-Hono](https://chancms.top/)
+- ChanJS-cli官方脚手架：[ChanJS-cli](https://chancms.top/)
+- ChanCMS官方开源 CMS：[ChanCMS](https://chancms.top/)
+
+## 开源协议
 
 ISC

package/core/Database.js

@@ -50,22 +50,25 @@ class DatabaseManager {
 
   /**
    * 挂载 knex 事件监控
-   * - query: 记录 SQL 执行起点
+   * - query: 记录 SQL 执行起点（键用 __knexQueryUid 查询唯一 ID，避免同连接串行查询互相覆盖）
    * - query-response: 计算耗时，超阈值记慢查询日志
    * - query-error: 记录失败 SQL 与错误信息
    * @private
    */
   _attachMonitoring(name, conn) {
     const startTimes = new Map();
+    // 容量保护：异常路径下残留的计时起点累积到上限即清空，防 Map 无界增长
+    const MAX_PENDING = 5000;
 
     conn.on("query", (data) => {
-      startTimes.set(data.__knexUid, Date.now());
+      if (startTimes.size >= MAX_PENDING) startTimes.clear();
+      startTimes.set(data.__knexQueryUid, Date.now());
     });
 
     conn.on("query-response", (_response, data) => {
-      const startedAt = startTimes.get(data.__knexUid);
+      const startedAt = startTimes.get(data.__knexQueryUid);
       if (!startedAt) return;
-      startTimes.delete(data.__knexUid);
+      startTimes.delete(data.__knexQueryUid);
 
       const elapsed = Date.now() - startedAt;
       if (elapsed >= this._slowThreshold) {
@@ -74,7 +77,7 @@ class DatabaseManager {
     });
 
     conn.on("query-error", (err, data) => {
-      startTimes.delete(data?.__knexUid);
+      startTimes.delete(data?.__knexQueryUid);
       logger.error(`[Database] 查询失败 ${name}: ${data?.sql || ""}`, err);
     });
   }
@@ -138,6 +141,17 @@ class DatabaseManager {
   markUp(name = this._defaultName) {
     this._health.set(name, true);
   }
+
+  /**
+   * 健康快照（/health 端点用）：读缓存状态，不做实时 IO
+   * @returns {{name:string, healthy:boolean}[]}
+   */
+  healthSnapshot() {
+    return [...this._connections.keys()].map(name => ({
+      name,
+      healthy: this._health.get(name) ?? false,
+    }));
+  }
 }
 
 export default DatabaseManager;

package/core/EventBus.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from "events";
+import logger from "../utils/logger.js";
 
 /**
  * 事件总线：基于 Node 内置 EventEmitter 的轻量封装。
@@ -40,12 +41,21 @@ export class EventBus {
   }
 
   /**
-   * 触发事件（同步执行全部监听器）
+   * 触发事件（同步逐个执行监听器，单个异常被隔离记录，不中断后续监听器）
    * @param {string} event - 事件名
    * @param {...any} args - 传递给监听器的参数
+   * @returns {boolean} 是否存在监听器
    */
   emit(event, ...args) {
-    this._emitter.emit(event, ...args);
+    const listeners = this._emitter.listeners(event);
+    for (const fn of listeners) {
+      try {
+        fn(...args);
+      } catch (err) {
+        logger.error(`[EventBus] 监听器执行异常 event:${event}: ${err.message}`, err);
+      }
+    }
+    return listeners.length > 0;
   }
 
   /**

package/core/Repository.js

@@ -97,6 +97,8 @@ function applySelectAndSort(q, fields, sort) {
 /**
  * 数据访问基类，封装通用CRUD操作
  * 继承 BaseComponent 获得 app/config/db 快捷访问，不绑定组件加载职责
+ * 防御设计：所有入口统一经 _guard 校验「数据库可用性 + 查询条件合法性」，
+ * 再进入 SQL 构造层，避免各方法重复书写 `_checkDB + guardInvalidQuery` 样板。
  */
 class Repository extends BaseComponent {
   constructor(table=null, dbName=null, opts={}) {
@@ -105,6 +107,9 @@ class Repository extends BaseComponent {
     this._dbName = dbName;
     this._customDb = null;
     this._dateFields = Array.isArray(opts.dateFields) ? opts.dateFields : [];
+    // join() 联表白名单：声明后 joinTable 必须在列，防未来某处把用户输入透传成任意表读取；
+    // 未声明保持原行为（仅正则格式校验），存量业务零破坏
+    this._allowJoinTables = Array.isArray(opts.allowJoinTables) ? opts.allowJoinTables : null;
     typeof this.on === 'function' && this.on();
   }
 
@@ -125,6 +130,30 @@ class Repository extends BaseComponent {
     if (!this.db) throw new Error("Database connection not available");
   }
 
+  /** 当前连接的数据库客户端类型（knex client：mysql2 / pg / better-sqlite3 ...） */
+  get _clientType() {
+    return this.db?.client?.config?.client || "";
+  }
+
+  /** PostgreSQL 的 INSERT 默认不回传自增主键，必须显式 RETURNING 才能拿到 insertId */
+  get _needReturning() {
+    const c = this._clientType;
+    return c === "pg" || c === "postgres" || c === "pg-query-stream";
+  }
+
+  /**
+   * 统一防御守卫：数据库可用性 + 查询条件合法性（fail-closed）。
+   * 查询/统计/存在性等方法的入口统一先过此守卫，替代各方法开头的 `_checkDB()+guardInvalidQuery()` 重复样板。
+   * 空 query（如 {}）合法放行；仅 db 不可用时直接抛异常，保证后端配置错误尽早暴露。
+   * @param {object} [opts={}]
+   * @param {object} [opts.query={}] 查询条件；为空对象或缺省时仅校验数据库连接
+   * @returns {null | {success:false,code:number,msg:string,data:object}} 校验通过返回 null，否则返回错误体（调用方应 return 该值）
+   */
+  _guard({ query = {} } = {}) {
+    this._checkDB();
+    return guardInvalidQuery(query);
+  }
+
   /** 统一构建查询实例（子类可重写以扩展过滤逻辑） */
   _buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) {
     this._checkDB();
@@ -148,16 +177,16 @@ class Repository extends BaseComponent {
 
   /** 查询全部，默认上限1000条 */
   async all({ query={}, sort={}, fields=[], limit=1000 }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const list = await this._buildBaseQuery({query,sort,fields}).limit(limit);
     return { success:true, code:CODE_OK, msg:"查询成功", data: list };
   }
 
   /** 分页偏移查询 */
   async find({ query={}, sort={}, fields=[], limit, offset }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    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));
@@ -166,8 +195,8 @@ class Repository extends BaseComponent {
 
   /** 查询单条记录 */
   async findOne({ query={}, fields=[] }={}) {
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const row = await this._buildBaseQuery({query,fields}).first();
     if (!row) return { success:false, code:CODE_NOT_FOUND, msg:"记录不存在", data:null };
     return { success:true, code:CODE_OK, msg:"查询成功", data: row };
@@ -182,8 +211,11 @@ class Repository extends BaseComponent {
   async insert(data={}) {
     this._checkDB();
     if (!Object.keys(data).length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
-    const res = await this.db(this.tableName).insert(this.#formatDate(data));
-    return { success:true, code:CODE_OK, msg:"插入成功", data:{ insertId:res[0], affectedRows:1 } };
+    const query = this.db(this.tableName).insert(this.#formatDate(data));
+    if (this._needReturning) query.returning("id"); // pg 需 RETURNING 才有 insertId；mysql/sqlite 的 res[0] 天然是自增 id
+    const raw = await query;
+    const insertId = this._needReturning ? (raw[0]?.id ?? raw[0]) : raw[0]; // pg returning 返回 [{id:N}]
+    return { success:true, code:CODE_OK, msg:"插入成功", data:{ insertId, affectedRows:1 } };
   }
 
   /** 批量插入 */
@@ -191,8 +223,11 @@ class Repository extends BaseComponent {
     this._checkDB();
     if (!records.length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
     const list = records.map(r => this.#formatDate(r));
-    const res = await this.db(this.tableName).insert(list);
-    return { success:true, code:CODE_OK, msg:"批量插入成功", data:{ insertId:res[0], affectedRows:records.length } };
+    const query = this.db(this.tableName).insert(list);
+    if (this._needReturning) query.returning("id");
+    const raw = await query;
+    const insertId = this._needReturning ? (raw[0]?.id ?? raw[0]) : raw[0];
+    return { success:true, code:CODE_OK, msg:"批量插入成功", data:{ insertId, affectedRows:records.length } };
   }
 
   /** 条件删除 */
@@ -235,11 +270,10 @@ class Repository extends BaseComponent {
     return { success:true, code:CODE_OK, msg:"更新成功", data:{ affectedRows:rows } };
   }
 
-  /** 根据ID更新，返回更新后完整数据 */
+  /** 根据ID更新，返回更新后完整数据（复用 update 走统一 applyQuery 校验） */
   async updateById(id, data={}) {
-    this._checkDB();
     if (!id || !Object.keys(data).length) return { success:false, code:CODE_PARAM_INVALID, msg:"参数无效", data:{} };
-    await this.db(this.tableName).where({id}).update(this.#formatDate(data));
+    await this.update({ query: { id }, data });
     return this.findById(id);
   }
 
@@ -253,6 +287,11 @@ class Repository extends BaseComponent {
       if (!item.query || !Object.keys(item.query).length) {
         return { success:false, code:CODE_PARAM_INVALID, msg:"批量更新条件不能为空", data:{} };
       }
+      // 防御纵深：与 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 trx = await this.db.transaction();
     let total = 0;
@@ -278,9 +317,8 @@ class Repository extends BaseComponent {
    * @returns {Promise<{success:boolean,code:number,msg:string,data:object}>}
    */
   async _doPaginate({ current=1, pageSize=10, query={}, sort={}, field=[] }={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     // 页码边界保护：current<=0 会生成负 offset 让 MySQL 直接语法报错
     const currentPage = Math.max(1, Math.floor(Number(current) || 1));
     const size = Math.min(Math.max(pageSize, 1), this.limit);
@@ -310,20 +348,68 @@ class Repository extends BaseComponent {
     return this._doPaginate(params);
   }
 
+  /**
+   * 基于游标的深分页查询（keyset pagination），替代 offset 深分页。
+   *
+   * 适用场景：大表（数万行+）且需翻到很后面的分页。
+   * offset 深分页痛点：`LIMIT 100000, 20` 需先扫描并丢弃前 10 万行，越深越慢；
+   * keyset 直接用 `WHERE id > 上一页最后一条的 id ORDER BY id LIMIT 20` 精准定位，与页码无关，常数级耗时。
+   *
+   * 返回体不依赖 offset/totalPages，浏览器端用「加载更多」或「下一页」+ nextCursor 驱动。
+   *
+   * @param {object} [params]
+   * @param {object} [params.query={}] 过滤条件（同 query()）
+   * @param {number} [params.pageSize=20] 每页条数（受 this.limit 上限约束）
+   * @param {string} [params.cursorField='id'] 游标字段，须为稳定唯一且可排序的列（默认主键 id；也支持 created_at 等，但注意并列值会导致漏数据）
+   * @param {string|number|null} [params.cursorValue=null] 上一页最后一条的 cursorField 值；null 表示首页
+   * @param {'asc'|'desc'} [params.direction='desc'] 排序方向（取新纪录通常 desc）
+   * @param {string[]} [params.fields=[]] 白名单字段
+   * @returns {Promise<{success:boolean,code:number,msg:string,data:{list:Array,nextCursor:number|string|null,hasMore:boolean,cursorField:string}}>}
+   *
+   * @example
+   * // 首页（取最新 20 条）
+   * const p1 = await repo.cursorPage({ query:{cid:5}, pageSize:20, direction:'desc' });
+   * const nextCursor = p1.data.nextCursor;
+   * // 下一页（携带上一页末尾游标，常数级耗时，即使翻到第 1 万页也一样快）
+   * const p2 = await repo.cursorPage({ query:{cid:5}, pageSize:20, direction:'desc', cursorValue:nextCursor });
+   */
+  async cursorPage({ query={}, pageSize=20, cursorField='id', cursorValue=null, direction='desc', fields=[] }={}) {
+    const err = this._guard({ query });
+    if (err) return err;
+    // 游标字段与方向必须白名单校验，防 SQL 注入（排序字段会被直接拼进 ORDER BY）
+    if (!SORT_FIELD_REGEX.test(cursorField)) {
+      logger.warn(`[Repository] 非法游标字段：${cursorField}`);
+      return { success:false, code:CODE_PARAM_INVALID, msg:"非法排序字段", data:null };
+    }
+    const dir = String(direction).toLowerCase() === 'asc' ? 'asc' : 'desc';
+    const size = Math.min(Math.max(Number(pageSize) || 1, 1), this.limit);
+
+    let q = this._buildBaseQuery({ query, sort: { [cursorField]: dir }, fields });
+    // 游标定位：大于/小于上一页末尾的游标值，天然避免重复与跳跃
+    if (cursorValue !== null && cursorValue !== undefined && cursorValue !== "") {
+      q = dir === 'asc' ? q.where(cursorField, '>', cursorValue) : q.where(cursorField, '<', cursorValue);
+    }
+    const list = await q.limit(size);
+
+    const last = list.length ? list[list.length - 1] : null;
+    const nextCursor = last ? last[cursorField] : null;
+    // 恰好取满 size 条时无法确定是否还有更多（边界处需多取一条判断更严谨，这里退化为 hasMore=满页）
+    const hasMore = list.length === size;
+    return { success:true, code:CODE_OK, msg:"查询成功", data:{ list, nextCursor, hasMore, cursorField } };
+  }
+
   /** 统计符合条件记录行数 */
   async count(query={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const res = await applyQuery(this.db(this.tableName), query).count("* as total").first();
     return { success:true, code:CODE_OK, msg:"统计成功", data:{ count: Number(res?.total ?? 0) } };
   }
 
   /** 判断查询条件下记录是否存在 */
   async exists(query={}) {
-    this._checkDB();
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    const err = this._guard({ query });
+    if (err) return err;
     const row = await applyQuery(this.db(this.tableName), query).first();
     return { success:true, code:CODE_OK, msg:"检查成功", data:{ exists: !!row } };
   }
@@ -335,8 +421,13 @@ class Repository extends BaseComponent {
       logger.warn(`[Repository] 非法联表/字段：${joinTable}/${localField}/${foreignField}`);
       return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表或字段", data: null };
     }
-    const guard = guardInvalidQuery(query);
-    if (guard) return guard;
+    // 表白名单校验（构造时声明 allowJoinTables 才启用）
+    if (this._allowJoinTables && !this._allowJoinTables.includes(joinTable)) {
+      logger.warn(`[Repository] 联表不在白名单：${joinTable}`);
+      return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表", data: null };
+    }
+    const err = this._guard({ query });
+    if (err) return err;
     const select = fields.length
       ? fields.filter(f => SORT_FIELD_REGEX.test(f) || f === '*')
       : [`${this.tableName}.*`];
@@ -348,26 +439,32 @@ class Repository extends BaseComponent {
     return { success:true, code:CODE_OK, msg:"查询成功", data: await q };
   }
 
-  /** 统计表总数量 + 今日新增数量 */
+  /** 统计表总数量 + 今日新增数量（今日列探测失败降级为 0，不阻断总数统计） */
   async stats() {
     this._checkDB();
     const createKey = this._dateFields.find(f => /created_at|createdAt/.test(f)) || "created_at";
-    const today = new Date();
-    today.setHours(0,0,0,0);
-    const [totalRes, todayRes] = await Promise.all([
-      this.db(this.tableName).count('* as count').first(),
-      this.db(this.tableName).where(createKey, '>=', today).count('* as count').first()
-    ]);
+    const totalRes = await this.db(this.tableName).count('* as count').first();
+    let today = 0;
+    try {
+      const todayStart = new Date();
+      todayStart.setHours(0,0,0,0);
+      const todayRes = await this.db(this.tableName)
+        .where(createKey, '>=', todayStart).count('* as count').first();
+      today = Number(todayRes?.count || 0);
+    } catch (err) {
+      // 表无 created_at 列等情况：跳过今日统计而非整体报错
+      logger.warn(`[Repository] stats 今日统计失败（表 ${this.tableName} 列 ${createKey}?）：${err.message}`);
+    }
     return {
       success:true,
       code:CODE_OK,
       msg:"统计成功",
       data: {
         total: Number(totalRes?.count || 0),
-        today: Number(todayRes?.count || 0)
+        today
       }
     };
   }
 }
 
-export default Repository;
+export default Repository;

package/core/bootstrap/error-handler.js

@@ -49,12 +49,11 @@ export function registerErrorHandler(chan) {
     if (!isAppError(err)) err = wrapDbError(err);
 
     // 连接类故障实时标记：后续未登录请求可直接返回「数据库未连接」，
-    // 而非伪装成 token 缺失（详见 auth 中间件 isDown 短路）
-    const isDbConnection = isAppError(err) && (
-      err.code >= 6000 ||
-      /数据库连接|数据库访问被拒绝|ECONNREFUSED|ETIMEDOUT|连接中断/.test(err.message || "")
-    );
-    if (isDbConnection) {
+    // 而非伪装成 token 缺失（详见 auth 中间件 isDown 短路）。
+    // 仅认结构化信号：wrapDbError 已把连接拒绝/超时/中断等统一归类为 6xxx AppError，
+    // 不再做错误消息正则匹配，避免文案改动导致健康状态失真。
+    const isDbDown = isAppError(err) && err.code >= 6000;
+    if (isDbDown) {
       chan.dbManager?.markDown?.();
     } else if (isAppError(err) && DB_RECOVERY_CODES.has(err.code)) {
       // 仅明确经过 DB 查询的业务错误（查无记录/唯一冲突/业务失败）才推断 DB 已恢复，

package/core/bootstrap/middleware.js

@@ -2,6 +2,7 @@ import {
   Cors, body, cookie, favicon, header,
   staticMw, template, waf, wafBody, log,
 } from "../../middleware/index.js";
+import { health } from "../../middleware/health.js";
 import { BODY_LIMIT } from "../../config/index.js";
 
 /**
@@ -14,6 +15,8 @@ export async function registerCoreMiddleware(chan) {
 
   // 1. WAF 前置（IP/封禁/限流/路径与 query 检查，不依赖请求体）
   await waf(app, cfg.waf ?? { enabled: false });
+  // 1.5 健康检查端点（默认开启，config.health = {enabled,path} 可调；浅模式零 IO）
+  app.use(health(chan, cfg.health ?? {}));
   // 2. Favicon
   favicon(app);
   // 3. 静态资源

package/core/bootstrap/router-loader.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { Router } from "express";
-import { loaderSort, importFile } from "../loader.js";
+import { importFile } from "../loader.js";
 import logger from "../../utils/logger.js";
 
 /**
@@ -23,8 +23,22 @@ async function registerRouterFile(filePath, app, router, config) {
   }
 }
 
+/**
+ * 统计 Express 全局路由栈层数（用于检测模块是否真的挂载了路由）
+ * Express 5 的 app.router 为 Router 实例，stack 可访问；异常环境返回 null 跳过检测
+ */
+function countAppLayers(app) {
+  try {
+    return app?.router?.stack?.length ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 加载 modules 业务模块路由，按配置顺序挂载
+ * 顺序完全遵循 config.modules 声明顺序（框架不再隐式重排），
+ * 含动态兜底路由的模块（如 web）应自行在配置中放在末位。
  * @param {object} chan 框架实例
  */
 export async function loadModuleRouter(chan) {
@@ -32,13 +46,20 @@ export async function loadModuleRouter(chan) {
   const modulesDir = paths.modulesPath;
   if (!fs.existsSync(modulesDir)) return;
 
-  const moduleNames = loaderSort(config.modules ?? []);
+  const moduleNames = config.modules ?? [];
   for (const name of moduleNames) {
     const routeFile = path.join(modulesDir, name, "router.js");
     // 每个模块使用独立的子 Router 实例，防止模块内 router.use(auth()) 等无路径前缀
     // 的中间件污染全局，导致未匹配路径（如 404）被提前拦截成鉴权错误。
     const subRouter = Router();
+    const layersBefore = countAppLayers(app);
     await registerRouterFile(routeFile, app, subRouter, config);
+    // 挂载责任在模块作者（app.use(prefix, router)），但静默失效代价太高：
+    // 注册前后全局路由栈无增长即视为忘挂载，启动期直接告警。
+    const layersAfter = countAppLayers(app);
+    if (layersBefore !== null && layersAfter !== null && layersAfter === layersBefore) {
+      logger.warn(`[RouterLoader] 模块 "${name}" 未向 app 注册任何路由（缺少 app.use(prefix, router)?），该模块路由未生效`);
+    }
   }
 }
 

package/core/loader.js

@@ -30,17 +30,6 @@ export async function importFile(filepath) {
   }
 }
 
-/**
- * 模块排序：web模块强制后置
- * @param {string[]} modules
- * @returns {string[]}
- */
-export function loaderSort(modules = []) {
-  const webIdx = modules.indexOf("web");
-  if (webIdx > -1) modules.push(modules.splice(webIdx, 1)[0]);
-  return modules;
-}
-
 /**
  * 加载根配置 index.js
  */

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

@@ -111,7 +111,6 @@ const config = await loader.loadConfig();   // 读取 config/index.js 合并成
 | `loadController(name)` | 加载某模块全部 Controller（自动 bind 实例方法防 this 丢失），返回 `{ 控制器名: 实例 }` |
 | `loadConfig()` | 加载合并配置（读 `config/index.js`）|
 | `importFile(filepath)` | 动态导入单个文件（成功返回模块 default 或模块本身，失败/IO 异常返回 `null`）|
-| `loaderSort(modules)` | 模块排序（`web` 强制后置）|
 
 > 多数业务场景你直接 `new MyService()` / `new MyController()` 即可，不必走 loader。
 > loader 主要在框架自动装配或插件化场景使用。

package/middleware/health.js

@@ -0,0 +1,56 @@
+import logger from "../utils/logger.js";
+import { store } from "../storage/index.js";
+
+/**
+ * 内置健康检查端点（默认开启）
+ *
+ * 设计：浅模式零 IO —— 只读进程内已有状态（运行时长 / DB 健康缓存 / 存储层诊断），
+ * 不做实时 ping，可被监控系统高频探活而不打数据库。
+ * DB 健康缓存由 error-handler 在真实查询成功/失败时维护（markUp/markDown）。
+ *
+ * 配置（config/index.js）：
+ *   health: { enabled: true, path: '/health' }   // 默认值，可整体关闭或改路径
+ *
+ * 响应示例：
+ *   { "success":true, "code":0, "msg":"ok", "data":{
+ *       "status":"ok",            // ok=全部连接健康；degraded=有连接标记为不可用
+ *       "uptime":12345,
+ *       "db":[{ "name":"default", "healthy":true }],
+ *       "store":{ "mode":"memory", ... }
+ *   } }
+ */
+
+const DEFAULT_PATH = "/health";
+
+export const health = (chan, opts = {}) => {
+  if (opts.enabled === false) return;
+  const path = opts.path || DEFAULT_PATH;
+  const startedAt = Date.now();
+
+  return (req, res, next) => {
+    if (req.path !== path) return next();
+    try {
+      const db = chan.dbManager?.healthSnapshot?.() ?? [];
+      const degraded = db.some(d => !d.healthy);
+      res.status(200).json({
+        success: true,
+        code: 0,
+        msg: degraded ? "degraded" : "ok",
+        data: {
+          status: degraded ? "degraded" : "ok",
+          uptime: Math.floor((Date.now() - startedAt) / 1000),
+          db,
+          store: store.getInfo?.() ?? null,
+        },
+      });
+    } catch (err) {
+      logger.error(`[Health] 健康检查异常：${err.message}`);
+      res.status(200).json({
+        success: true,
+        code: 0,
+        msg: "degraded",
+        data: { status: "degraded", uptime: Math.floor((Date.now() - startedAt) / 1000), db: [], store: null },
+      });
+    }
+  };
+};

package/middleware/index.js

@@ -13,3 +13,4 @@ export { staticMw } from "./static.js";
 export { template } from "./template.js";
 export { waf, wafBody } from "./waf.js";
 export { log } from "./log.js";
+export { health } from "./health.js";

package/middleware/static.js

@@ -5,15 +5,20 @@ import logger from "../utils/logger.js";
 /**
  * 批量挂载静态资源中间件，内置目录安全校验
  * @param {express.Application} app Express实例
- * @param {Array<{prefix:string;dir:string;maxAge?:number}>} statics 静态目录配置数组
+ * @param {Array<{prefix:string;dir:string;maxAge?:number;immutable?:boolean}>} statics 静态目录配置数组
+ *        immutable:true 输出 Cache-Control: max-age=..., immutable —— 仅用于构建期带内容 hash 的产物目录
  */
 export const staticMw = async (app, statics) => {
   if (!Array.isArray(statics) || !statics.length) return;
-  statics.forEach(({ prefix, dir, maxAge }) => {
+  statics.forEach(({ prefix, dir, maxAge, immutable }) => {
     if (!safePath(dir)) {
       logger.error(`[Static] 不安全目录拦截：${dir}`);
       return;
     }
-    app.use(prefix, express.static(dir, { maxAge: maxAge ?? 0, dotfiles: "deny" }));
+    app.use(prefix, express.static(dir, {
+      maxAge: maxAge ?? 0,
+      dotfiles: "deny",
+      ...(immutable ? { immutable: true } : {}),
+    }));
   });
 };

package/middleware/waf.js

@@ -1,5 +1,5 @@
 import { getIp } from "../utils/ip.js";
-import { checkKeywords } from "../security/checker.js";
+import { checkKeywords, isIgnored } from "../security/checker.js";
 import { filterXSS } from "../security/xss-filter.js";
 import { createRateLimitMiddleware } from "../security/rate-limit.js";
 import { CODE_BLOCKED } from "../response/code.js";
@@ -14,6 +14,9 @@ const WAF_PATH_WHITELIST = [
   "/sitemap.xml",
 ];
 
+// waf 配置合法键集合：启动期校验，未知键打 warn，防配置漂移静默失效
+const WAF_KNOWN_KEYS = new Set(["enabled", "rateLimit", "ignorePaths"]);
+
 const TRUSTED_IPS = new Set(["127.0.0.1", "::1"]);
 
 // URL/query 关键词检测保留的分类——只保留真正危险、几乎不会在正常 URL 中出现的攻击特征。
@@ -64,7 +67,17 @@ const runRateLimit = (rateLimit, req, res) =>
  * 前置WAF中间件（body前）
  */
 const createWafMiddleware = wafConfig => {
-  const rateLimit = createRateLimitMiddleware(wafConfig.rateLimit);
+  // ignorePaths 统一读 waf 层级（限流跳过 + 关键词检测跳过共用一份），
+  // 不再从 rateLimit 子对象读取，避免两级同名配置断链静默失效
+  const ignorePaths = Array.isArray(wafConfig.ignorePaths) ? wafConfig.ignorePaths : [];
+  const rateLimit = createRateLimitMiddleware({ ...(wafConfig.rateLimit ?? {}), ignorePaths });
+
+  // 启动期配置自检：未知键提示，防「配置写了但框架不认」的漂移
+  for (const key of Object.keys(wafConfig ?? {})) {
+    if (!WAF_KNOWN_KEYS.has(key)) {
+      logger.warn(`[waf] 未识别的配置项 "${key}"，已忽略（合法键：${[...WAF_KNOWN_KEYS].join("/")}）`);
+    }
+  }
 
   return async (req, res, next) => {
     try {
@@ -72,7 +85,7 @@ const createWafMiddleware = wafConfig => {
 
       const clientIp = getIp(req);
       const path = req.path || "";
-      const whitePath = isWhitelistedPath(path);
+      const whitePath = isWhitelistedPath(path) || isIgnored(path, ignorePaths);
 
       // 可信IP直接放行，仅做query XSS过滤
       if (isTrustedIp(clientIp)) {
@@ -122,11 +135,12 @@ const createWafMiddleware = wafConfig => {
  * Body层WAF中间件（body解析后）
  */
 const createWafBodyMiddleware = wafConfig => {
+  const ignorePaths = Array.isArray(wafConfig.ignorePaths) ? wafConfig.ignorePaths : [];
   return async (req, res, next) => {
     try {
       if (!wafConfig.enabled) return next();
       const path = req.path || "";
-      if (isWhitelistedPath(path)) return next();
+      if (isWhitelistedPath(path) || isIgnored(path, ignorePaths)) return next();
 
       const clientIp = getIp(req);
       const contentType = req.headers["content-type"]?.toLowerCase() || "";

package/package.json

@@ -1,8 +1,8 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.12",
-  "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
+  "version": "2.7.15",
+  "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",
   "keywords": [
@@ -16,6 +16,9 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "author": "明空",
   "license": "ISC",
   "files": [
@@ -39,19 +42,21 @@
     "express": "^5.2.1",
     "express-art-template": "^1.0.1",
     "i18next": "^24.2.0",
+    "ioredis": "^5.4.6",
     "jsonwebtoken": "^9.0.3",
     "knex": "^3.2.10",
     "marked": "^18.0.3",
     "mysql2": "^3.22.3",
     "node-cron": "^3.0.3",
+    "pg": "^8.23.0",
     "pino": "^9.5.0",
     "pino-http": "^10.3.0",
     "serve-favicon": "^2.5.1",
-    "xss": "^1.0.15",
-    "ioredis": "^5.4.6"
+    "xss": "^1.0.15"
   },
   "devDependencies": {
-    "pino-pretty": "^11.3.0"
+    "pino-pretty": "^11.3.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "zod": "^4.4.3"

package/security/rate-limit.js

@@ -40,13 +40,11 @@ export const createRateLimitMiddleware = cfg => {
       const ip = getIp(req) || "unknown";
       const uid = req.user?.uid;
       const ipKey = `${KEY_PREFIX}ip:${ip}`;
-      const uidKey = uid ? `${KEY_PREFIX}uid:${uid}` : null;
+      // 空字符串为占位 key（批量接口跳过），Redis 模式下单条 Lua 完成双维度计数，一次往返
+      const uidKey = uid ? `${KEY_PREFIX}uid:${uid}` : "";
 
-      // 计数自增（一次操作完成限流判定，存储异常 fail-close 拦截）
-      const [ipCount, uidCount] = await Promise.all([
-        store.incrAndExpire(ipKey, windowMs),
-        uidKey ? store.incrAndExpire(uidKey, windowMs) : 0,
-      ]);
+      // 计数自增（批量原子完成限流判定，存储异常 fail-close 拦截）
+      const [ipCount, uidCount] = await store.incrAndExpireBatch([ipKey, uidKey], windowMs);
 
       if (ipCount > max || uidCount > max) {
         const dim = ipCount > max ? "IP" : "UID";

package/storage/cache.js

@@ -72,6 +72,17 @@ class Cache {
     return this._incrInternal(key, ttlMs, true);
   }
 
+  /**
+   * 批量限流自增，与 Redis 后端 incrAndExpireBatch 接口对齐
+   * 内存操作无网络往返，顺序执行即可；空字符串 key 跳过返回 0
+   * @param {string[]} keys 计数key数组
+   * @param {number} ttlMs 窗口过期时间
+   * @returns {number[]} 与 keys 顺序对应的计数值数组
+   */
+  incrAndExpireBatch(keys, ttlMs) {
+    return keys.map(k => (k === "" ? 0 : this.incrAndExpire(k, ttlMs)));
+  }
+
   _incrInternal(key, ttlMs, refreshTTL) {
     const now = Date.now();
     const item = this.map.get(key);

package/storage/redis.js

@@ -156,6 +156,32 @@ class RedisBackend {
     );
   }
 
+  /**
+   * 批量限流自增（IP+UID 双维度一次往返）
+   * 单条 Lua 脚本内完成全部 key 的 INCR+PEXPIRE，原子且省 RTT；
+   * 空字符串 key 跳过（占位用），返回数组与传入 keys 一一对应
+   * @param {string[]} keys 计数key数组
+   * @param {number} ttlMs 窗口过期时间
+   * @returns {Promise<number[]>} 与 keys 顺序对应的计数值数组
+   */
+  async incrAndExpireBatch(keys, ttlMs) {
+    const cli = await this._getClient();
+    const script = `
+      local r = {}
+      for i, k in ipairs(KEYS) do
+        if k ~= '' then
+          local c = redis.call('INCR', k)
+          if c == 1 then redis.call('PEXPIRE', k, ARGV[1]) end
+          r[i] = c
+        else
+          r[i] = 0
+        end
+      end
+      return r
+    `;
+    return cli.eval(script, keys.length, ...keys, ttlMs);
+  }
+
   /**
    * 判断key是否存在
    * @param {string} key 键名

package/storage/store.js

@@ -44,6 +44,14 @@ class MemoryAdapter {
    */
   incrAndExpire(key, ttlMs) { return this._cache.incrAndExpire(key, ttlMs); }
 
+  /**
+   * 批量限流自增（IP+UID 双维度一次完成），与 Redis 后端接口对齐
+   * @param {string[]} keys 键数组
+   * @param {number} ttlMs 过期时间（毫秒）
+   * @returns {number[]} 与 keys 顺序对应的计数值
+   */
+  incrAndExpireBatch(keys, ttlMs) { return this._cache.incrAndExpireBatch(keys, ttlMs); }
+
   /** 判断 key 是否存在 */
   exists(key) { return this._cache.has(key); }
 
@@ -197,6 +205,15 @@ class Store {
    */
   incrAndExpire(key, ttlMs) { return this._safeExec("incrAndExpire", [key, ttlMs], 0); }
 
+  /**
+   * 批量限流自增：Redis 模式下单条 Lua 完成全部 key（一次往返、原子），
+   * 内存模式顺序执行。keys 中空字符串为占位跳过，返回 0。
+   * @param {string[]} keys 计数键数组
+   * @param {number} ttlMs 窗口过期毫秒
+   * @returns {Promise<number[]>}
+   */
+  incrAndExpireBatch(keys, ttlMs) { return this._safeExec("incrAndExpireBatch", [keys, ttlMs], keys.map(() => 0)); }
+
   /** 判断 key 是否存在；异常返回 false */
   exists(key) { return this._safeExec("exists", [key], false); }