@maiyunnet/kebab 9.13.8 → 9.14.1

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.13.8";
+export declare const VER = "9.14.1";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

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

package/lib/core.js

@@ -307,10 +307,11 @@ export function muid(ctr, opt = {}) {
 export function ip(ctr, req) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     if (typeof headers['cf-connecting-ip'] === 'string') {
-        return headers['cf-connecting-ip'];
+        return normalizeIP(headers['cf-connecting-ip']);
     }
     else if (typeof headers['x-forwarded-for'] === 'string') {
-        return headers['x-forwarded-for'];
+        // --- X-Forwarded-For 可能为逗号分隔的多个 IP，取第一个即客户端 IP ---
+        return normalizeIP(headers['x-forwarded-for'].split(',')[0].trim());
     }
     else {
         if (!req) {
@@ -321,21 +322,37 @@ export function ip(ctr, req) {
                 return '';
             }
         }
-        return req.socket.remoteAddress ?? '';
+        return normalizeIP(req.socket.remoteAddress ?? '');
     }
 }
 /** --- 获取 CF 和 X 的 IP --- */
 export function ips(ctr) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     return {
-        'cf': typeof headers['cf-connecting-ip'] === 'string' ? headers['cf-connecting-ip'] : '',
-        'x': typeof headers['x-forwarded-for'] === 'string' ? headers['x-forwarded-for'] : ''
+        'cf': typeof headers['cf-connecting-ip'] === 'string' ? normalizeIP(headers['cf-connecting-ip']) : '',
+        'x': typeof headers['x-forwarded-for'] === 'string' ? normalizeIP(headers['x-forwarded-for'].split(',')[0].trim()) : ''
     };
 }
 /** --- 使用 X-Forwarded-For 的 CDN 厂商 --- */
 export const REAL_IP_X = 'x-forwarded-for';
 /** --- 使用的是 Cloudflare --- */
 export const REAL_IP_CF = 'cf-connecting-ip';
+/**
+ * --- 规范化 IP 地址 ---
+ * --- 将 IPv4-mapped IPv6（如 ::ffff:127.0.0.1）转换为纯 IPv4，原生 IPv6 保持不变 ---
+ * @param ip 原始 IP 地址
+ */
+function normalizeIP(ip) {
+    if (!ip) {
+        return '';
+    }
+    const value = ip.trim();
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(value);
+    if (mapped) {
+        return mapped[1];
+    }
+    return value;
+}
 /**
  * --- 获取直连 IP（安全 IP） ---
  * @param ctr
@@ -346,11 +363,11 @@ export function realIP(ctr, name = '') {
     if (name !== '') {
         const value = headers[name];
         if (typeof value === 'string') {
-            return value;
+            return normalizeIP(value);
         }
     }
     const req = ctr.getPrototype('_req');
-    return req.socket.remoteAddress ?? '';
+    return normalizeIP(req.socket.remoteAddress ?? '');
 }
 /**
  * --- 间隔一段时间 ---

package/lib/crypto.d.ts

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-4-2 14:01:06
- * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47, 2026-07-29 11:51
  */
 import * as crypto from 'crypto';
 /**
@@ -31,8 +31,8 @@ export declare function generateKeyPair(type: string, options?: {
  * @param format 输出格式
  * @param algorithm 哈希方式
  */
-export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format: 'hex' | 'base64' | 'binary', algorithm?: string): string;
-export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format?: 'buffer', algorithm?: string): Buffer;
+export declare function sign(data: string | NodeJS.ArrayBufferView, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format: 'hex' | 'base64' | 'binary', algorithm?: string): string;
+export declare function sign(data: string | NodeJS.ArrayBufferView, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format?: 'buffer', algorithm?: string): Buffer;
 /**
  * --- 非对称验签 ---
  * @param data 数据
@@ -40,31 +40,31 @@ export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike
  * @param signature 签名
  * @param algorithm 哈希方式
  */
-export declare function verify(data: crypto.BinaryLike, object: crypto.KeyLike | crypto.VerifyKeyObjectInput | crypto.VerifyPublicKeyInput | crypto.VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, algorithm?: string): boolean;
+export declare function verify(data: string | NodeJS.ArrayBufferView, object: crypto.KeyLike | crypto.VerifyKeyObjectInput | crypto.VerifyPublicKeyInput | crypto.VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, algorithm?: string): boolean;
 /**
  * --- 非对称公钥加密 ---
  * @param key 公钥
  * @param buffer 数据
  */
-export declare function publicEncrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function publicEncrypt(key: crypto.KeyLike | crypto.PublicKeyInput | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称私钥加密 ---
  * @param key 私钥
  * @param buffer 数据
  */
-export declare function privateEncrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function privateEncrypt(key: crypto.KeyLike | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称公钥解密 ---
  * @param key 公钥
  * @param buffer 数据
  */
-export declare function publicDecrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function publicDecrypt(key: crypto.KeyLike | crypto.PublicKeyInput | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称私钥解密 ---
  * @param key 私钥
  * @param buffer 数据
  */
-export declare function privateDecrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function privateDecrypt(key: crypto.KeyLike | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /** --- 勿使用，无 iv 默认，但勿使用 --- */
 export declare const AES_256_ECB = "aes-256-ecb";
 /** --- 一般不用，兼容性场景下用 --- */
@@ -86,7 +86,7 @@ export declare const SM4_CFB = "sm4-cfb";
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function cipherEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64' | 'buffer'): string | Buffer | false;
+export declare function cipherEncrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64' | 'buffer'): string | Buffer | false;
 /**
  * --- AES 加密 ---
  * @param original 原始字符串
@@ -95,16 +95,16 @@ export declare function cipherEncrypt(original: string | Buffer, key: crypto.Cip
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+export declare function aesEncrypt(original: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function aesEncrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64'): string | false;
 /**
  * --- AES GCM 托管加密 ---
  * @param original 原始字符串
  * @param key 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
  * @param output 输出类型
  */
-export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
-export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output?: 'base64'): string | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.KeyLike, output: 'buffer'): Buffer | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.KeyLike, output?: 'base64'): string | false;
 /**
  * --- SM4 加密 ---
  * @param original 原始字符串
@@ -112,8 +112,8 @@ export declare function gcmEncrypt(original: string | Buffer, key: crypto.Cipher
  * @param iv 向量 16 个英文字母和数字
  * @param method 加密方法
  */
-export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+export declare function sm4Encrypt(original: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function sm4Encrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64'): string | false;
 /**
  * --- cipher 解密 ---
  * @param encrypt 需解密的字符串
@@ -122,7 +122,7 @@ export declare function sm4Encrypt(original: string | Buffer, key: crypto.Cipher
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary' | 'buffer'): string | Buffer | false;
+export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary' | 'buffer'): string | Buffer | false;
 /**
  * --- AES 解密 ---
  * @param encrypt 需解密的字符串
@@ -130,16 +130,16 @@ export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.Ciph
  * @param iv 向量 16(CTR) 或 12(GCM) 个英文字母和数字
  * @param method 加密方法
  */
-export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
+export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary'): string | false;
 /**
  * --- AES 解密 ---
  * @param encrypt 需解密的字符串
  * @param key 密钥 32 个英文字母和数字
  * @param output 输出类型
  */
-export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
-export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output?: 'binary'): string | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, output: 'buffer'): Buffer | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, output?: 'binary'): string | false;
 /**
  * --- SM4 解密 ---
  * @param encrypt 需解密的字符串
@@ -147,24 +147,24 @@ export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherK
  * @param iv 向量 16 个英文字母和数字
  * @param method 加密方法
  */
-export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
+export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary'): string | false;
 /**
  * --- hash 或 hmac 加密 ---
  * @param algorithm 哈希方式
  * @param data 源数据
  * @param key 设置则采用 hmac 加密
  */
-export declare function hashHmac(algorithm: string, data: Buffer | string, key?: crypto.CipherKey, format?: 'hex' | 'base64'): string;
-export declare function hashHmac(algorithm: string, data: Buffer | string, key: crypto.CipherKey | undefined, format: 'buffer'): Buffer;
+export declare function hashHmac(algorithm: string, data: Buffer | string, key?: crypto.KeyLike, format?: 'hex' | 'base64'): string;
+export declare function hashHmac(algorithm: string, data: Buffer | string, key: crypto.KeyLike | undefined, format: 'buffer'): Buffer;
 /**
  * --- hash 或 hmac 加密文件 ---
  * @param algorithm 加密方式，如 md5、sha256、sm3 等
  * @param path 文件路径
  * @param key 设置则采用 hmac 加密
  */
-export declare function hashHmacFile(algorithm: string, path: string, key?: crypto.CipherKey, encoding?: 'hex' | 'base64' | 'base64url'): Promise<string | false>;
-export declare function hashHmacFile(algorithm: string, path: string, key: crypto.CipherKey, encoding: 'buffer'): Promise<Buffer | false>;
+export declare function hashHmacFile(algorithm: string, path: string, key?: crypto.KeyLike, encoding?: 'hex' | 'base64' | 'base64url'): Promise<string | false>;
+export declare function hashHmacFile(algorithm: string, path: string, key: crypto.KeyLike, encoding: 'buffer'): Promise<Buffer | false>;
 /**
  * --- base64 编码 ---
  * @param data 字符串或 Buffer

package/lib/crypto.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-4-2 14:01:06
- * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47, 2026-07-29 11:51
  */
 import * as crypto from 'crypto';
 // --- 库和定义 ---

package/lib/sql.d.ts

@@ -42,6 +42,8 @@ export declare class Sql {
     private _placeholderCounter;
     /** --- 是否忽略错误 --- */
     private _ignore;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    private _hint;
     constructor(opt: {
         'service': ESERVICE;
         'ctr'?: ctr.Ctr;
@@ -51,6 +53,30 @@ export declare class Sql {
         'sql'?: string[];
         'alias'?: string[];
     });
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)
+     *
+     * // --- 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html ---
+     */
+    hint(h: string): this;
     /**
      * --- 插入数据前导 ---
      * @param table 表名
@@ -303,4 +329,4 @@ export declare function value(val: kebab.DbValue): {
  * --- 将对象转换为 JSON 字符串并避开类型检查，用于适配 PostgreSQL 的 jsonb 字段 ---
  * @param obj 要转换的 JSON 对象
  */
-export declare function json(obj: kebab.Json): any;
+export declare function json<T>(obj: T): T;

package/lib/sql.js

@@ -45,6 +45,8 @@ export class Sql {
     _placeholderCounter = 1;
     /** --- 是否忽略错误 --- */
     _ignore = false;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    _hint = '';
     // --- 实例化 ---
     constructor(opt) {
         this._ctr = opt.ctr;
@@ -60,6 +62,33 @@ export class Sql {
             this._alias = opt.alias;
         }
     }
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)
+     *
+     * // --- 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html ---
+     */
+    hint(h) {
+        this._hint = h;
+        return this;
+    }
     // --- 前导 ---
     /**
      * --- 插入数据前导 ---
@@ -880,7 +909,7 @@ export class Sql {
             'data': data,
             'sql': sql,
             'alias': lCore.clone(this._alias),
-        });
+        }).hint(this._hint);
     }
     // --- 操作 ---
     /**
@@ -888,6 +917,10 @@ export class Sql {
      */
     getSql() {
         let sql = this._sql.join('');
+        // --- 注入优化器 Hint 到 SELECT 关键字后 ---
+        if (this._hint && !sql.includes('/*+')) {
+            sql = sql.replace(/^SELECT /i, `SELECT /*+ ${this._hint} */ `);
+        }
         if (this._pre) {
             return this._alias.reduce((result, item) => {
                 if (this._service === ESERVICE.MYSQL) {

package/lib/undici/response.d.ts

@@ -31,7 +31,7 @@ export declare class Response {
     /**
      * --- 获取响应读取流对象 ---
      */
-    getStream(): zlib.BrotliDecompress | zlib.Gunzip | zlib.Inflate | (import("undici/types/readable").default & undici.Dispatcher.BodyMixin) | null;
+    getStream(): (import("undici/types/readable").default & undici.Dispatcher.BodyMixin) | zlib.Gunzip | zlib.Inflate | zlib.BrotliDecompress | null;
     /**
      * --- 获取原生响应读取流对象 ---
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.13.8",
+  "version": "9.14.1",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [
@@ -22,47 +22,47 @@
     "#kebab/*": "./*"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1047.0",
-    "@aws-sdk/lib-storage": "^3.1047.0",
+    "@aws-sdk/client-s3": "^3.1096.0",
+    "@aws-sdk/lib-storage": "^3.1096.0",
     "@litert/http-client": "^1.1.2",
     "@litert/mime": "^0.1.3",
     "@litert/redis": "^3.2.1",
     "@litert/websocket": "^0.2.8",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@tailwindcss/cli": "^4.3.0",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-label": "^2.1.15",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@radix-ui/react-switch": "^1.3.7",
+    "@tailwindcss/cli": "^4.3.3",
     "@types/ssh2": "^1.15.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "ejs": "^5.0.2",
-    "esbuild": "^0.28.0",
+    "ejs": "^6.0.1",
+    "esbuild": "^0.28.1",
     "jszip": "^3.10.1",
-    "mysql2": "^3.22.3",
-    "node-cron": "^4.2.1",
-    "openai": "^6.37.0",
-    "pg": "^8.20.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-router-dom": "^7.15.1",
+    "mysql2": "^3.23.2",
+    "node-cron": "^4.6.0",
+    "openai": "^7.0.0",
+    "pg": "^8.22.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router-dom": "^7.18.1",
     "ssh2": "^1.17.0",
     "svg-captcha": "^1.4.0",
     "tailwind-merge": "^3.6.0",
-    "tencentcloud-sdk-nodejs": "^4.1.232",
-    "undici": "^8.3.0"
+    "tencentcloud-sdk-nodejs": "^4.1.277",
+    "undici": "^8.9.0"
   },
   "devDependencies": {
     "@litert/eslint-plugin-rules": "^0.3.1",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^25.8.0",
+    "@types/node": "^26.1.2",
     "@types/pg": "^8.20.0",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "typedoc": "^0.28.19",
-    "typedoc-plugin-markdown": "^4.11.0",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^6.0.3"
   }
 }

package/sys/child.js

@@ -47,6 +47,8 @@ let http2Server;
 const linkCount = {};
 /** --- 是否正在停止，停止时对 HTTP/1.1 响应追加 Connection: close，避免请求完成后连接回到保活池 --- */
 let stopping = false;
+/** --- 当前活跃的 HTTP/2 会话集合，用于 graceful shutdown 时发送 GOAWAY 帧 --- */
+const http2Sessions = new Set();
 /**
  * --- 包装请求处理函数，统一管理 linkCount 计数和错误处理 ---
  * @param key 连接标识
@@ -144,6 +146,12 @@ async function run() {
         }
         wrapWithLinkCount(host + (req.url ?? ''), () => upgradeHandler(req, socket, true, head), '[CHILD][http2][upgrade]', 'UPGRADE');
     }).listen(lCore.globalConfig.httpsPort);
+    // --- 追踪 HTTP/2 会话，用于 graceful shutdown 时发送 GOAWAY 帧通知 CDN 切换连接 ---
+    http2Server.on('session', (session) => {
+        http2Sessions.add(session);
+        session.on('close', () => { http2Sessions.delete(session); });
+        session.on('error', () => { http2Sessions.delete(session); });
+    });
     // --- 增大 HTTP/2 超时，防止 CDN 预建连接被 Node.js 过早关闭 ---
     http2Server.setTimeout(120_000);
     httpServer = http.createServer(function (req, res) {
@@ -562,6 +570,13 @@ process.on('message', function (msg) {
             case 'stop': {
                 // --- 需要停止监听，等待已有连接全部断开，然后关闭线程 ---
                 stopping = true;
+                // --- 向所有 HTTP/2 会话发送 GOAWAY 帧，通知 CDN 客户端停止在该连接上发送新请求并切换到新连接 ---
+                for (const session of http2Sessions) {
+                    try {
+                        session.goaway(http2.constants.NGHTTP2_NO_ERROR);
+                    }
+                    catch { }
+                }
                 httpServer?.close();
                 http2Server?.close();
                 // --- 立即关闭空闲保活连接（无活跃请求的 keep-alive socket），避免进程长时间等待 ---

package/sys/ctr.d.ts

@@ -342,5 +342,9 @@ export declare class Ctr {
         'maxFileSize'?: number;
         /** --- 允许的文件扩展名（含点号），如 ['.jpg', '.png', '.pdf'] --- */
         'allowedExts'?: string[];
+        /** --- 单个字段（非文件）最大字节数，默认 1 MB --- */
+        'maxFieldSize'?: number;
+        /** --- 整体请求超时时间（毫秒），默认 5 分钟，设为 0 禁用超时 --- */
+        'timeout'?: number;
     }): Promise<boolean>;
 }

package/sys/master.js

@@ -18,6 +18,29 @@ import * as lTime from '#kebab/lib/time.js';
 import * as lZip from '#kebab/lib/zip.js';
 /** --- 当前运行中的子进程列表 --- */
 const workerList = {};
+/**
+ * --- 等待指定 worker 开始监听端口就绪 ---
+ * @param worker 要等待的 worker 对象
+ * @param timeout 超时时间（毫秒），默认 30 秒
+ */
+function waitForWorkerListening(worker, timeout = 30_000) {
+    return new Promise((resolve) => {
+        let timer;
+        const onListening = (w) => {
+            if (w.id === worker.id) {
+                clearTimeout(timer);
+                cluster.removeListener('listening', onListening);
+                resolve();
+            }
+        };
+        timer = setTimeout(() => {
+            lCore.display(`[master] Worker ${worker.process.pid ?? 'undefined'} timed out waiting for listening, proceeding anyway.`);
+            cluster.removeListener('listening', onListening);
+            resolve();
+        }, timeout);
+        cluster.on('listening', onListening);
+    });
+}
 /**
  * --- 最终调用执行的函数块 ---
  */
@@ -124,16 +147,7 @@ function createRpcListener() {
                     break;
                 }
                 case 'restart': {
-                    // --- 为所有子线程发送 stop 信息 ---
-                    for (const pid in workerList) {
-                        workerList[pid].worker.send({
-                            'action': 'stop'
-                        });
-                        // --- 开启新线程 ---
-                        await createChildProcess(workerList[pid].cpu);
-                        // --- 删除记录 ---
-                        delete workerList[pid];
-                    }
+                    await restartWorkers();
                     break;
                 }
                 case 'global': {
@@ -768,6 +782,34 @@ function createRpcListener() {
         });
     }).listen(lCore.globalConfig.rpcPort);
 }
+/**
+ * --- 零宕机重启所有 worker 进程：先创建新进程并等待监听就绪，再停止旧进程 ---
+ */
+async function restartWorkers() {
+    // --- 收集旧进程信息（先快照，避免迭代过程中修改 workerList） ---
+    const oldEntries = [];
+    for (const pid in workerList) {
+        oldEntries.push({
+            'pid': pid,
+            'cpu': workerList[pid].cpu,
+            'worker': workerList[pid].worker
+        });
+    }
+    // --- 阶段 1：创建新进程并等待其监听端口就绪 ---
+    for (const entry of oldEntries) {
+        const newWorker = await createChildProcess(entry.cpu);
+        if (newWorker) {
+            await waitForWorkerListening(newWorker);
+        }
+    }
+    // --- 阶段 2：停止旧进程 ---
+    for (const entry of oldEntries) {
+        entry.worker.send({
+            'action': 'stop'
+        });
+        delete workerList[entry.pid];
+    }
+}
 /**
  * --- 检测是否有死掉丢失的子进程，复活之 ---
  */
@@ -795,7 +837,7 @@ async function checkWorkerLost() {
 async function createChildProcess(cpu) {
     const worker = cluster.fork();
     if (!worker.process.pid) {
-        return;
+        return null;
     }
     workerList[worker.process.pid] = {
         'worker': worker,
@@ -823,16 +865,7 @@ async function createChildProcess(cpu) {
                     break;
                 }
                 case 'restart': {
-                    // --- 为所有子进程发送 restart 信息 ---
-                    for (const pid in workerList) {
-                        workerList[pid].worker.send({
-                            'action': 'stop'
-                        });
-                        // --- 开启新线程 ---
-                        await createChildProcess(workerList[pid].cpu);
-                        // --- 删除记录 ---
-                        delete workerList[pid];
-                    }
+                    await restartWorkers();
                     break;
                 }
                 case 'global': {
@@ -889,6 +922,7 @@ async function createChildProcess(cpu) {
             'data': lCore.global
         });
     }
+    return worker;
 }
 /**
  * --- 开发模式下的文件监听自动重载（HMR），仅在 debug: true 时启用 ---
@@ -919,18 +953,10 @@ function startFileWatcher() {
             }
             restarting = true;
             lCore.display(`[HMR] File changed: ${formatName}, reloading workers...`);
-            (async () => {
-                // --- 为所有子进程发送 stop 信息并重启 ---
-                for (const pid in workerList) {
-                    workerList[pid].worker.send({
-                        'action': 'stop'
-                    });
-                    await createChildProcess(workerList[pid].cpu);
-                    delete workerList[pid];
-                }
+            restartWorkers().then(() => {
                 restarting = false;
                 lCore.display('[HMR] All workers reloaded.');
-            })().catch((e) => {
+            }).catch((e) => {
                 restarting = false;
                 lCore.display('[HMR] Reload error:', e);
             });