chanjs 2.7.13 → 2.7.15

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

@@ -107,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();
   }
 
@@ -127,6 +130,17 @@ 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()` 重复样板。
@@ -197,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 } };
   }
 
   /** 批量插入 */
@@ -206,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 } };
   }
 
   /** 条件删除 */
@@ -267,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;
@@ -396,6 +421,11 @@ class Repository extends BaseComponent {
       logger.warn(`[Repository] 非法联表/字段：${joinTable}/${localField}/${foreignField}`);
       return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表或字段", data: null };
     }
+    // 表白名单校验（构造时声明 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
@@ -409,23 +439,29 @@ 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
       }
     };
   }

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,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.13",
+  "version": "2.7.15",
   "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",
@@ -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); }