@maiyunnet/kebab 8.6.5 → 9.0.0

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "8.6.5";
+export declare const VER = "9.0.0";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */
@@ -124,14 +124,6 @@ export interface IConfigDb {
     'user': string;
     'pwd': string;
 }
-/** --- Jwt 信息 --- */
-export interface IConfigJwt {
-    'name': string;
-    'ttl': number;
-    'ssl': boolean;
-    'secret': string;
-    'auth': boolean;
-}
 /** --- DNS --- */
 export interface IConfigDns {
     'sid': string;

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '8.6.5';
+export const VER = '9.0.0';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/core.d.ts

@@ -15,6 +15,8 @@ export declare const globalConfig: kebab.IConfig & {
     'max': number;
     'hosts': string[];
     'ind': string[];
+    /** --- 日志格式，csv 或 jsonl，默认 jsonl --- */
+    'logFormat': 'csv' | 'jsonl';
 };
 /** --- Cookie 设置的选项 --- */
 export interface ICookieOptions {
@@ -294,3 +296,13 @@ export declare function writeEventStreamHead(res: http2.Http2ServerResponse | ht
  * @param data 数据
  */
 export declare function write(res: http2.Http2ServerResponse | http.ServerResponse | net.Socket, data: string | Buffer): void;
+/**
+ * --- 加载 .env 文件到 process.env，若文件不存在则跳过 ---
+ * @param dir .env 文件所在目录路径（以 / 结尾）
+ */
+export declare function loadEnv(dir: string): Promise<void>;
+/**
+ * --- 将配置对象中的 ${ENV_VAR} 占位符替换为 process.env 的值 ---
+ * @param obj 配置对象
+ */
+export declare function resolveEnvVars(obj: Record<string, any>): void;

package/lib/core.js

@@ -738,31 +738,57 @@ export function log(opt, msg, fend = '') {
         if (!rtn) {
             return;
         }
-        path += h + '.csv';
-        if (!await lFs.isFile(path)) {
-            if (!await lFs.putContent(path, 'TIME,UNIX,URL,COOKIE,SESSION,USER_AGENT,REALIP,CLIENTIP,OS,PROCESS,MESSAGE\n', {
+        const format = globalConfig.logFormat ?? 'jsonl';
+        if (format === 'jsonl') {
+            // --- JSON Lines 格式 ---
+            path += h + '.jsonl';
+            const entry = lText.stringifyJson({
+                'time': lTime.format(null, 'H:i:s'),
+                'unix': lTime.stamp(),
+                'url': urlFull + wpath + (Object.keys(get).length ? '?' + lText.queryStringify(get) : ''),
+                'cookie': cookie,
+                'session': session,
+                'userAgent': headers['user-agent'] ?? '',
+                'realIp': realIp,
+                'clientIp': clientIp,
+                'osMem': lText.sizeFormat(os.totalmem() - os.freemem(), ''),
+                'procMem': lText.sizeFormat(process.memoryUsage().rss, ''),
+                'message': msg,
+            }) + '\n';
+            await lFs.putContent(path, entry, {
                 'encoding': 'utf8',
-                'mode': 0o777
-            })) {
-                return;
+                'mode': 0o777,
+                'flag': 'a'
+            });
+        }
+        else {
+            // --- CSV 格式（默认） ---
+            path += h + '.csv';
+            if (!await lFs.isFile(path)) {
+                if (!await lFs.putContent(path, 'TIME,UNIX,URL,COOKIE,SESSION,USER_AGENT,REALIP,CLIENTIP,OS,PROCESS,MESSAGE\n', {
+                    'encoding': 'utf8',
+                    'mode': 0o777
+                })) {
+                    return;
+                }
             }
+            await lFs.putContent(path, '"' +
+                lTime.format(null, 'H:i:s') + '","' +
+                lTime.stamp().toString() + '","' +
+                urlFull + wpath + (Object.keys(get).length ? '?' + lText.queryStringify(get).replace(/"/g, '""') : '') + '","' +
+                lText.queryStringify(cookie).replace(/"/g, '""') + '","' +
+                lText.stringifyJson(session).replace(/"/g, '""') + '","' +
+                (headers['user-agent']?.replace(/"/g, '""') ?? 'No HTTP_USER_AGENT') + '","' +
+                realIp.replace(/"/g, '""') + '","' +
+                clientIp.replace(/"/g, '""') + '","' +
+                lText.sizeFormat(os.totalmem() - os.freemem(), '') + '","' +
+                lText.sizeFormat(process.memoryUsage().rss, '') + '","' +
+                JSON.stringify(msg).slice(1, -1).replace(/"/g, '""') + '"\n', {
+                'encoding': 'utf8',
+                'mode': 0o777,
+                'flag': 'a'
+            });
         }
-        await lFs.putContent(path, '"' +
-            lTime.format(null, 'H:i:s') + '","' +
-            lTime.stamp().toString() + '","' +
-            urlFull + wpath + (Object.keys(get).length ? '?' + lText.queryStringify(get).replace(/"/g, '""') : '') + '","' +
-            lText.queryStringify(cookie).replace(/"/g, '""') + '","' +
-            lText.stringifyJson(session).replace(/"/g, '""') + '","' +
-            (headers['user-agent']?.replace(/"/g, '""') ?? 'No HTTP_USER_AGENT') + '","' +
-            realIp.replace(/"/g, '""') + '","' +
-            clientIp.replace(/"/g, '""') + '","' +
-            lText.sizeFormat(os.totalmem() - os.freemem(), '') + '","' +
-            lText.sizeFormat(process.memoryUsage().rss, '') + '","' +
-            JSON.stringify(msg).slice(1, -1).replace(/"/g, '""') + '"\n', {
-            'encoding': 'utf8',
-            'mode': 0o777,
-            'flag': 'a'
-        });
     })().catch((e) => {
         display('[CORE] [log]', e);
     });
@@ -919,3 +945,48 @@ export function write(res, data) {
         res.write(data);
     }
 }
+/**
+ * --- 加载 .env 文件到 process.env，若文件不存在则跳过 ---
+ * @param dir .env 文件所在目录路径（以 / 结尾）
+ */
+export async function loadEnv(dir) {
+    const content = await lFs.getContent(dir + '.env', 'utf8');
+    if (!content) {
+        return;
+    }
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // --- 空行或注释行跳过 ---
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eqIndex).trim();
+        let val = trimmed.slice(eqIndex + 1).trim();
+        // --- 去掉首尾引号 ---
+        if ((val.startsWith('\'') && val.endsWith('\'')) || (val.startsWith('"') && val.endsWith('"'))) {
+            val = val.slice(1, -1);
+        }
+        process.env[key] = val;
+    }
+}
+/**
+ * --- 将配置对象中的 ${ENV_VAR} 占位符替换为 process.env 的值 ---
+ * @param obj 配置对象
+ */
+export function resolveEnvVars(obj) {
+    for (const key in obj) {
+        if (typeof obj[key] === 'string') {
+            obj[key] = obj[key].replace(/\$\{([^}]+)\}/g, (_, envKey) => {
+                return process.env[envKey] ?? '';
+            });
+        }
+        else if (typeof obj[key] === 'object' && obj[key] !== null) {
+            resolveEnvVars(obj[key]);
+        }
+    }
+}

package/lib/cron.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2025-9-20 19:46:30
- * Last: 2025-9-20 19:46:32
+ * Last: 2025-9-20 19:46:32, 2026-3-22 00:00:00
  */
 import * as kebab from '#kebab/index.js';
 import * as nodeCron from 'node-cron';
@@ -9,6 +9,7 @@ import * as lFs from '#kebab/lib/fs.js';
 import * as lCore from '#kebab/lib/core.js';
 import * as lText from '#kebab/lib/text.js';
 import * as lTime from '#kebab/lib/time.js';
+import * as lKv from '#kebab/lib/kv.js';
 /** --- 定时任务列表 --- */
 const regulars = [];
 /** --- 获取定时任务列表 --- */
@@ -28,13 +29,14 @@ export async function regular(task, immediate = '') {
         // --- 当前进程已经注册过了，不能再注册了 ---
         return false;
     }
-    // --- 检查是否存在相同名称的计划任务 ---
-    if (!await lFs.isDir(kebab.LOG_CWD + `cron/`)) {
-        await lFs.mkdir(kebab.LOG_CWD + `cron/`);
-        await lFs.putContent(kebab.LOG_CWD + `cron/lock.txt`, 'Kebab');
+    // --- 检查 cron 数据目录是否存在 ---
+    const cronDataDir = kebab.LOG_CWD + 'cron/';
+    if (!await lFs.isDir(cronDataDir)) {
+        await lFs.mkdir(cronDataDir);
+        await lFs.putContent(cronDataDir + 'lock.txt', 'Kebab');
     }
-    // --- 保存计划任务 ---
-    const content = await lFs.getContent(kebab.LOG_CWD + `cron/${task.name}.json`, 'utf8');
+    // --- 加载已有的持久化数据 ---
+    const content = await lFs.getContent(cronDataDir + `${task.name}.json`, 'utf8');
     /** --- 任务对象 --- */
     const obj = {
         ...task,
@@ -43,41 +45,90 @@ export async function regular(task, immediate = '') {
         'rcount': 0,
     };
     if (content) {
-        const json = JSON.parse(content);
-        obj.last = json.last;
-        obj.count = json.count;
+        const json = lText.parseJson(content);
+        if (json) {
+            obj.last = json.last ?? '';
+            obj.count = json.count ?? 0;
+        }
     }
-    await lFs.putContent(kebab.LOG_CWD + `cron/${obj.name}.json`, JSON.stringify(obj));
-    // --- 好，先注册 ---
+    await saveCronData(obj);
+    // --- 注册定时任务 ---
     nodeCron.schedule(task.rule, () => {
-        /** --- 当前日期字符串 --- */
-        const date = lTime.format(null, 'YmdHi');
-        obj.callback(date, false);
-        // --- 设置执行后的数据 ---
-        obj.last = date;
-        ++obj.count;
-        ++obj.rcount;
-        lFs.putContent(kebab.LOG_CWD + `cron/${obj.name}.json`, JSON.stringify(obj)).catch(() => { });
+        executeWithLock(obj, false).catch((e) => {
+            const msg = `[CRON][${obj.name}] ${lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""')}`;
+            lCore.debug(msg);
+            lCore.log({}, msg, '-error');
+        });
     });
     // --- 检查是否需要立即执行 ---
     /** --- 当前日期字符串 --- */
     const date = lTime.format(null, 'YmdHi');
     if ((immediate && (immediate <= date) && (obj.last < immediate))) {
-        // --- 理应执行的时间早于当前，或要执行的时间就是现在 ---
+        await executeWithLock(obj, true);
+    }
+    regulars.push(obj);
+    return true;
+}
+/**
+ * --- 带分布式锁执行定时任务（多进程/多机下只有一个 worker 会执行） ---
+ * @param obj 任务数据对象
+ * @param immediate 是否为立即执行模式
+ */
+async function executeWithLock(obj, immediate) {
+    const date = lTime.format(null, 'YmdHi');
+    const lockKey = `cron_lock:${obj.name}:${date}`;
+    // --- 尝试通过 KV 获取分布式锁 ---
+    if (lCore.globalConfig.kv?.host) {
         try {
-            obj.callback(date, true);
+            const kv = get();
+            // --- 锁的 TTL 为 120 秒，防止任务异常退出后锁永远不释放 ---
+            const acquired = await kv.add(lockKey, process.pid?.toString() ?? '1', 120);
+            if (!acquired) {
+                // --- 其他进程已经在执行此任务了 ---
+                return;
+            }
         }
-        catch (e) {
-            const msg = `[CRON][${obj.name}] ${lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""')}`;
-            lCore.debug(msg);
-            lCore.log({}, msg, '-error');
+        catch {
+            // --- KV 不可用时降级为本地执行（不做锁控制） ---
+            lCore.debug(`[CRON][${obj.name}] KV lock unavailable, fallback to local execution`);
         }
-        // --- 设置执行后的数据 ---
-        obj.last = date;
-        ++obj.count;
-        ++obj.rcount;
-        await lFs.putContent(kebab.LOG_CWD + `cron/${obj.name}.json`, JSON.stringify(obj));
     }
-    regulars.push(obj);
-    return true;
+    // --- 执行任务 ---
+    try {
+        await obj.callback(date, immediate);
+    }
+    catch (e) {
+        const msg = `[CRON][${obj.name}] ${lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""')}`;
+        lCore.debug(msg);
+        lCore.log({}, msg, '-error');
+    }
+    // --- 更新执行数据 ---
+    obj.last = date;
+    ++obj.count;
+    ++obj.rcount;
+    await saveCronData(obj);
+}
+/**
+ * --- 保存定时任务持久化数据 ---
+ * @param obj 任务数据对象
+ */
+async function saveCronData(obj) {
+    await lFs.putContent(kebab.LOG_CWD + `cron/${obj.name}.json`, lText.stringifyJson({
+        'name': obj.name,
+        'last': obj.last,
+        'count': obj.count,
+    })).catch(() => { });
+}
+/**
+ * --- 获取 Kv 实例（内部使用，用于分布式锁） ---
+ */
+function get() {
+    return lKv.get({
+        'host': lCore.globalConfig.kv.host,
+        'port': lCore.globalConfig.kv.port,
+        'index': lCore.globalConfig.kv.index,
+        'pre': lCore.globalConfig.kv.pre,
+        'user': lCore.globalConfig.kv.user,
+        'pwd': lCore.globalConfig.kv.pwd,
+    });
 }

package/lib/db.d.ts

@@ -60,5 +60,7 @@ export interface IPacket {
 export declare function get(ctrEtc: sCtr.Ctr | kebab.IConfigDb, opt?: {
     /** --- 服务商，默认 PGSQL --- */
     'service'?: ESERVICE;
+    /** --- 是否使用只读库，默认 false --- */
+    'read'?: boolean;
 }): Pool;
 export { Connection, Pool, IConnectionInfo, getConnectionList, Transaction };

package/lib/db.js

@@ -24,7 +24,9 @@ export function get(ctrEtc, opt = {}) {
         // --- 从 ctr 中读取连接信息 ---
         const config = ctrEtc.getPrototype('_config');
         const service = opt.service ? ESERVICE[opt.service] : config.db.default;
-        return new Pool(config.db[service].default, {
+        /** --- 读写分离：若 read 为 true 且存在 read 配置且 read 配置的 host 不为空，则使用 read 库 --- */
+        const dbKey = (opt.read && config.db[service].read?.host) ? 'read' : 'default';
+        return new Pool(config.db[service][dbKey], {
             'service': service === 'MYSQL' ? ESERVICE.MYSQL : ESERVICE.PGSQL,
         });
     }

package/lib/ratelimit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Project: Kebab
+ * Date: 2026-3-22 00:00:00
+ * --- Rate Limiting 限速库，支持令牌桶和滑动窗口两种策略 ---
+ * --- 基于 KV（Redis）实现，天然支持多进程和多机部署 ---
+ */
+import * as lKv from '#kebab/lib/kv.js';
+/**
+ * --- 检查指定 key 是否超速，使用多段近似滑动窗口算法 ---
+ * @param kv KV 实例
+ * @param key 限速标识（如 IP、用户 UID 等）
+ * @param opt 限速选项
+ * @returns 返回结果对象
+ */
+export declare function check(kv: lKv.Kv, key: string, opt?: {
+    /** --- 窗口时间（秒），默认 60 --- */
+    'window'?: number;
+    /** --- 窗口内最大请求数，默认 60 --- */
+    'max'?: number;
+    /** --- key 前缀，默认 rl: --- */
+    'pre'?: string;
+}): Promise<ICheckResult>;
+/**
+ * --- 简易固定窗口限速检查（性能更高，精度较低） ---
+ * @param kv KV 实例
+ * @param key 限速标识
+ * @param opt 限速选项
+ */
+export declare function checkFixed(kv: lKv.Kv, key: string, opt?: {
+    /** --- 窗口时间（秒），默认 60 --- */
+    'window'?: number;
+    /** --- 窗口内最大请求数，默认 60 --- */
+    'max'?: number;
+    /** --- key 前缀，默认 rl: --- */
+    'pre'?: string;
+}): Promise<ICheckResult>;
+/** --- 限速检查结果 --- */
+export interface ICheckResult {
+    /** --- 是否允许通过 --- */
+    'allowed': boolean;
+    /** --- 剩余可用次数 --- */
+    'remaining': number;
+    /** --- 总限额 --- */
+    'limit': number;
+    /** --- 窗口重置时间（Unix 时间戳秒） --- */
+    'reset': number;
+}

package/lib/ratelimit.js

@@ -0,0 +1,88 @@
+import * as lTime from '#kebab/lib/time.js';
+import * as lCore from '#kebab/lib/core.js';
+/**
+ * --- 检查指定 key 是否超速，使用多段近似滑动窗口算法 ---
+ * @param kv KV 实例
+ * @param key 限速标识（如 IP、用户 UID 等）
+ * @param opt 限速选项
+ * @returns 返回结果对象
+ */
+export async function check(kv, key, opt = {}) {
+    const window = opt.window ?? 60;
+    const max = opt.max ?? 60;
+    const pre = opt.pre ?? 'rl:';
+    const now = lTime.stamp();
+    /** --- 将窗口分为 6 个子段 --- */
+    const segSize = Math.max(Math.floor(window / 6), 1);
+    /** --- 当前段标识 --- */
+    const segId = Math.floor(now / segSize);
+    /** --- 需要统计的段数 --- */
+    const segCount = Math.ceil(window / segSize);
+    /** --- 统计各段请求数总和 --- */
+    let total = 0;
+    for (let i = 0; i < segCount; ++i) {
+        const segKey = `${pre}${key}:${segId - i}`;
+        const val = await kv.get(segKey);
+        if (val) {
+            total += parseInt(val) || 0;
+        }
+    }
+    // --- 当前段 +1 ---
+    const currentSegKey = `${pre}${key}:${segId}`;
+    const count = await kv.incr(currentSegKey);
+    if (count === false) {
+        // --- KV 连接失败，放行 ---
+        lCore.debug('[RATELIMIT] KV incr failed, allow by default');
+        return {
+            'allowed': true,
+            'remaining': max,
+            'limit': max,
+            'reset': now + window,
+        };
+    }
+    if (count === 1) {
+        await kv.expire(currentSegKey, window + segSize);
+    }
+    total += 1;
+    const allowed = total <= max;
+    return {
+        'allowed': allowed,
+        'remaining': allowed ? max - total : 0,
+        'limit': max,
+        'reset': (segId + 1) * segSize,
+    };
+}
+/**
+ * --- 简易固定窗口限速检查（性能更高，精度较低） ---
+ * @param kv KV 实例
+ * @param key 限速标识
+ * @param opt 限速选项
+ */
+export async function checkFixed(kv, key, opt = {}) {
+    const window = opt.window ?? 60;
+    const max = opt.max ?? 60;
+    const pre = opt.pre ?? 'rl:';
+    const now = lTime.stamp();
+    const rkey = pre + key;
+    const count = await kv.incr(rkey);
+    if (count === false) {
+        // --- KV 连接失败，放行 ---
+        return {
+            'allowed': true,
+            'remaining': max,
+            'limit': max,
+            'reset': now + window,
+        };
+    }
+    if (count === 1) {
+        // --- 首次请求，设置过期时间 ---
+        await kv.expire(rkey, window);
+    }
+    const allowed = count <= max;
+    return {
+        'allowed': allowed,
+        'remaining': allowed ? max - count : 0,
+        'limit': max,
+        'reset': now + window,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "8.6.5",
+  "version": "9.0.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [
@@ -22,33 +22,40 @@
     "#kebab/*": "./*"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.993.0",
-    "@aws-sdk/lib-storage": "^3.993.0",
+    "@aws-sdk/client-s3": "^3.1014.0",
+    "@aws-sdk/lib-storage": "^3.1014.0",
     "@litert/http-client": "^1.1.2",
     "@litert/mime": "^0.1.3",
-    "@litert/redis": "^3.1.0",
+    "@litert/redis": "^3.2.0",
     "@litert/websocket": "^0.2.8",
     "@types/ssh2": "^1.15.5",
-    "@zilliz/milvus2-sdk-node": "^2.6.10",
+    "@zilliz/milvus2-sdk-node": "^2.6.11",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
-    "ejs": "^4.0.1",
+    "ejs": "^5.0.1",
+    "@tailwindcss/cli": "^4.2.2",
+    "esbuild": "^0.27.4",
     "jszip": "^3.10.1",
-    "mysql2": "^3.17.2",
+    "mysql2": "^3.20.0",
     "node-cron": "^4.2.1",
-    "openai": "^6.22.0",
-    "pg": "^8.18.0",
+    "openai": "^6.32.0",
+    "pg": "^8.20.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.13.1",
     "ssh2": "^1.17.0",
     "svg-captcha": "^1.4.0",
-    "tencentcloud-sdk-nodejs": "^4.1.186"
+    "tencentcloud-sdk-nodejs": "^4.1.199"
   },
   "devDependencies": {
     "@litert/eslint-plugin-rules": "^0.3.1",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^25.3.0",
-    "@types/pg": "^8.16.0",
+    "@types/node": "^25.5.0",
+    "@types/pg": "^8.20.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "typedoc": "^0.28.17",
-    "typedoc-plugin-markdown": "^4.10.0",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.9.3"
   }
 }

package/sys/child.js

@@ -448,11 +448,13 @@ async function upgradeHandler(req, socket, https, head) {
  */
 async function reload() {
     // --- 清除全局 config，并重新加载全局信息 ---
+    await lCore.loadEnv(kebab.ROOT_CWD);
     const configContent = await lFs.getContent(kebab.CONF_CWD + 'config.json', 'utf8');
     if (!configContent) {
         throw `File '${kebab.CONF_CWD}config.json' not found.`;
     }
     const config = lText.parseJson(configContent);
+    lCore.resolveEnvVars(config);
     for (const key in lCore.globalConfig) {
         delete lCore.globalConfig[key];
     }