chanjs 2.7.7 → 2.7.10

package/doc/09-/345/233/275/351/231/205/345/214/226Lang.md

@@ -0,0 +1,220 @@
+# 国际化 i18n（Lang）
+
+> 基于 `i18next` 的多语言支持，启动时扫描 `lang/` 目录加载全部 JSON 语言包，运行时 O(1) 查词。
+> 对外通过 `import { initLang } from "chanjs"` 或 `this.app.lang`（Chan 应用实例已内置）使用。
+
+---
+
+## 一、设计理念
+
+| 决策 | 说明 |
+|------|------|
+| 成熟库 | 采用 `i18next`，复用其插值、复数、命名空间等成熟能力，不重复造轮子 |
+| 启动加载 | 启动时扫描 `lang/` 目录，把全部语言包读进内存，运行时零 I/O |
+| 全局单例 | `initLang` 返回的就是 i18next 单例，`this.app.lang` 指向同一实例 |
+| 后端不转义 | `interpolation.escapeValue: false`，JSON 输出 / 邮件等后端场景不自动转义 |
+
+---
+
+## 二、语言包目录结构
+
+在项目**根目录**下建 `lang/`，每个语言一个子目录，每个命名空间一个 JSON 文件：
+
+```
+lang/
+├── zh-CN/
+│   ├── common.json      # 默认命名空间
+│   └── user.json        # 也可按模块拆命名空间
+├── en/
+│   ├── common.json
+│   └── user.json
+└── ja/
+    └── common.json
+```
+
+`lang/zh-CN/common.json` 示例：
+
+```json
+{
+  "user": {
+    "welcome": "欢迎，{{name}}",
+    "login": "登录",
+    "logout": "退出"
+  },
+  "order": {
+    "created": "订单创建成功，编号 {{id}}"
+  }
+}
+```
+
+> 语言目录名需匹配 `^[a-zA-Z_-]+$`（如 `zh-CN`、`en`、`ja`）。命名空间 = JSON 文件名（如 `common`）。
+
+---
+
+## 三、初始化 initLang
+
+### 应用实例内置（推荐）
+
+`Chan` 应用启动时会自动调用 `initLang`，并把结果挂到 `this.app.lang`：
+
+```javascript
+// app/app.js
+import Chan from "chanjs";
+
+const chan = new Chan();
+await chan.start();   // 内部已初始化 i18n，默认语言来自 config
+```
+
+启动后业务代码直接用 `this.app.lang`：
+
+```javascript
+const msg = this.app.lang.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+```
+
+### 手动初始化（中间件 / 独立脚本）
+
+```javascript
+import { initLang } from "chanjs";
+
+const i18n = await initLang("zh-CN");   // 返回 i18next 实例
+i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `locale` | `string` | 默认语言，默认 `"zh-CN"` |
+| **返回** | `Promise<i18next>` | i18next 实例 |
+
+---
+
+## 四、翻译 `t(key, opts?)`
+
+### 4.1 基础查词
+
+```javascript
+this.app.lang.t("user.login");   // → "登录"
+```
+
+### 4.2 插值（`{{变量}}`）
+
+```javascript
+this.app.lang.t("user.welcome", { name: "张三" });   // → "欢迎，张三"
+```
+
+### 4.3 复数（i18next 原生支持）
+
+语言包：
+
+```json
+{ "item": {
+  "one": "有 {{count}} 个商品",
+  "other": "有 {{count}} 个商品"
+} }
+```
+
+```javascript
+this.app.lang.t("item", { count: 1 });   // → "有 1 个商品"
+this.app.lang.t("item", { count: 5 });   // → "有 5 个商品"
+```
+
+### 4.4 指定命名空间
+
+语言包拆了多个命名空间时，用 `ns` 指定：
+
+```javascript
+// lang/user.json: { "title": "用户中心" }
+this.app.lang.t("title", { ns: "user" });   // → "用户中心"
+```
+
+> 未指定 `ns` 时默认用 `common` 命名空间。
+
+---
+
+## 五、动态切换语言 changeLanguage
+
+业务运行时（登录后 / 用户偏好 / 请求头）可随时切换：
+
+```javascript
+// 切换语言并等待资源生效
+await this.app.lang.changeLanguage("en");
+
+// 切换后立即按新语言取词
+const msg = this.app.lang.t("user.welcome", { name: "Zhang San" });  // 英文包
+```
+
+### 按请求动态切换（多语言站点）
+
+```javascript
+// app/middleware/i18n.js  —— 每个请求按 Accept-Language 切换
+import { event } from "chanjs";
+
+export function i18nMw(app) {
+  app.use(async (req, res, next) => {
+    const lang = req.headers["accept-language"]?.split(",")[0] || "zh-CN";
+    await app.lang.changeLanguage(lang);
+    next();
+  });
+}
+```
+
+> 注意：`changeLanguage` 是异步的，切换后记得 `await` 再取词。
+
+---
+
+## 六、使用场景
+
+### 场景一：接口返回多语言文案
+
+```javascript
+// Controller 里
+async greet(req, res) {
+  const name = req.query.name || "朋友";
+  return this.success({
+    data: {
+      msg: this.app.lang.t("user.welcome", { name }),
+    },
+  });
+}
+```
+
+### 场景二：邮件 / 短信模板
+
+```javascript
+const subject = this.app.lang.t("email.subject", { ns: "mail" });
+const body = this.app.lang.t("email.reset_body", { name: user.name, link });
+await sendMail(user.email, subject, body);
+```
+
+### 场景三：错误提示本地化
+
+```javascript
+const KeyedError = new AppError(this.app.lang.t("error.order_not_found"));
+throw KeyedError;   // → 按当前语言给出错误提示
+```
+
+---
+
+## 七、注意事项
+
+### 1. 语言包必须存在，否则回退 zh-CN
+
+`fallbackLng` 固定为 `zh-CN`。某语言缺词时自动回退到中文包，不会报错。
+
+### 2. `escapeValue: false`（后端不转义）
+
+这是后端场景特意关闭的。若用于**前端渲染用户输入**，请自行 `XSS` 过滤（见 `filterXSS`），不要直接拼接。
+
+### 3. 单文件解析失败不阻断
+
+某个语言包的 JSON 解析失败会被跳过，不影响其它语言和应用启动。
+
+### 4. 与 `changeLanguage` 配合 requestId
+
+`changeLanguage` 是异步切换，多语言站点建议在请求期间保持语言一致，避免并发切换串语言。
+
+### 5. 新增语言步骤
+
+1. 在 `lang/` 下建语言目录（如 `lang/fr/`）
+2. 放入 `common.json`（及需要的命名空间文件）
+3. 重启应用（启动时扫描加载）
+4. 用 `changeLanguage("fr")` 切换后按 `fr` 渲染

package/index.js

@@ -10,6 +10,7 @@
  *   import { Controller, Repository, Service, cache, Paths, loader, utils, getApp } from "chanjs";
  *   import { validate, validateAll } from "chanjs";  // zod 校验中间件
  *   import { AppError, NotFoundError, ValidationError } from "chanjs";  // 错误类
+ *   import { event, EventBus, Task, initLang } from "chanjs";  // 基础设施
  *
  * 多实例：
  *   每个 Chan 实例持有独立 config/db/paths/dbManager（注册表管理），
@@ -22,6 +23,11 @@ export { default as Controller } from "./core/Controller.js";
 export { default as Repository } from "./core/Repository.js";
 export { Service } from "./core/Service.js";
 
+// ===================== 基础设施（事件总线 / 定时任务 / i18n）=====================
+export { EventBus, event } from "./core/EventBus.js";
+export { default as Task } from "./core/Task.js";
+export { initLang } from "./core/Lang.js";
+
 // ===================== 错误体系 =====================
 export {
   AppError, AuthError, TokenExpiredError, ForbiddenError,
@@ -33,8 +39,31 @@ export {
 // ===================== 统一响应工具（纯函数，可复用于接口 / 定时任务 / RPC）=====================
 export { success, fail, routeNotFound, serializeError, buildErrorHtml, respondError } from "./response/index.js";
 
+// ===================== 业务状态码 =====================
+export {
+  CODE,
+  getCodeMsg,
+  CODE_OK,
+  CODE_AUTH_FAILED,
+  CODE_TOKEN_EXPIRED,
+  CODE_FORBIDDEN,
+  CODE_NOT_FOUND,
+  CODE_CONFLICT,
+  CODE_PARAM_INVALID,
+  CODE_PARAM_MISSING,
+  CODE_BUSINESS_FAIL,
+  CODE_RATE_LIMIT,
+  CODE_DEVICE_ERROR,
+  CODE_BLOCKED,
+  CODE_SYSTEM_ERROR,
+  CODE_SERVICE_BUSY,
+  CODE_DB_CONNECTION_ERROR,
+  CODE_DB_ACCESS_DENIED,
+  CODE_DB_OPERATION_TIMEOUT,
+} from "./response/code.js";
+
 // ===================== 安全工具 =====================
-export { setToken, getToken, verifyToken } from "./security/jwt.js";
+export { setToken, getToken, verifyToken, revokeToken } from "./security/jwt.js";
 export { aesEncrypt, aesDecrypt } from "./security/sign.js";
 export { createRateLimitMiddleware } from "./security/rate-limit.js";
 export { filterXSS, checkKeywords } from "./security/index.js";
@@ -58,4 +87,4 @@ export { Paths } from "./utils/paths.js";
 
 // ===================== 默认导出应用主类 =====================
 import Chan from "./core/App.js";
-export default Chan;
+export default Chan;

package/middleware/log.js

@@ -1,35 +1,52 @@
-import morgan from "morgan";
+import { randomUUID } from "crypto";
+import pinoHttp from "pino-http";
 import { getIp } from "../utils/ip.js";
-
-// 日志格式白名单，防止非法格式注入
-const ALLOWED_FORMATS = new Set(["chancms", "combined", "common", "dev", "short", "tiny"]);
-
-// 自定义token
-morgan.token("ip", req => getIp(req));
-morgan.token("user", req => req.user ? `${req.user.uid}:${req.user.username}` : "-");
-morgan.token("datetime", () => new Date().toISOString());
-
-// 自定义ChanCMS日志输出模板
-morgan.format("chancms", (tokens, req, res) => [
-  tokens.datetime(req, res),
-  tokens.ip(req, res),
-  tokens.user(req, res),
-  tokens.method(req, res),
-  tokens.url(req, res),
-  tokens.status(req, res),
-  tokens.res(req, res, "content-length") || "-",
-  "-",
-  tokens["response-time"](req, res),
-  "ms"
-].join(" "));
+import { root } from "../utils/logger.js";
 
 /**
- * 请求日志中间件(morgan)，内置格式白名单防注入
- * @param {express.Application} app Express实例
- * @param {{level?: string}} [logger={}] 日志配置
+ * 请求日志中间件（pino-http）
+ *
+ * 自动为每个请求生成 requestId，挂载 req.log（带 requestId 的子 logger）。
+ * 业务 Controller 中可通过 req.log.info("xxx") 输出带 requestId 的日志。
+ *
+ * @param {object} app - Express 实例
+ * @param {object} [config={}] - 配置对象
  */
-export const log = (app, logger = {}) => {
-  const level = logger.level;
-  const format = ALLOWED_FORMATS.has(level) ? level : "chancms";
-  app.use(morgan(format));
-};
+export function log(app, config = {}) {
+  app.use(pinoHttp({
+    logger: root,
+    // 自动记录请求日志（静态资源跳过）
+    autoLogging: {
+      ignore: (req) => {
+        const url = req.url || "";
+        return /\.(ico|png|jpg|jpeg|gif|svg|css|js|woff|woff2)$/.test(url);
+      },
+    },
+    // requestId 生成：优先复用上游 X-Request-Id
+    genReqId: (req, res) => {
+      const id = req.headers["x-request-id"] || randomUUID();
+      res.setHeader("X-Request-Id", id);
+      return id;
+    },
+    // 日志级别按状态码区分
+    customLogLevel: (req, res, err) => {
+      if (err || res.statusCode >= 500) return "error";
+      if (res.statusCode >= 400) return "warn";
+      return "info";
+    },
+    customSuccessMessage: (req, res) => {
+      return `${req.method} ${req.originalUrl || req.url} ${res.statusCode}`;
+    },
+    customErrorMessage: (req, res, err) => {
+      return `${req.method} ${req.originalUrl || req.url} ${res.statusCode} ${err.message}`;
+    },
+    serializers: {
+      req: (req) => ({
+        method: req.method,
+        url: req.originalUrl || req.url,
+        ip: getIp(req),
+      }),
+      res: (res) => ({ statusCode: res.statusCode }),
+    },
+  }));
+}

package/middleware/waf.js

@@ -29,17 +29,13 @@ const DEFAULT_BLOCK = {
 };
 
 /**
- * 判断内网/回环可信IP
+ * 判断本机回环可信IP：仅 127.0.0.1 / ::1 无条件放行 WAF。
+ * 不再放行整个内网段（如 10.x、192.168.x、172.16-31.x），
+ * 否则当 Nginx 部署在另一台内网机、Express 未解析 XFF 时，全站 WAF 会静默失效。
  */
 const isTrustedIp = ip => {
   if (!ip) return false;
-  if (TRUSTED_IPS.has(ip)) return true;
-  if (ip.startsWith("10.") || ip.startsWith("192.168.")) return true;
-  if (ip.startsWith("172.")) {
-    const seg = Number(ip.split(".")[1]);
-    return seg >= 16 && seg <= 31;
-  }
-  return false;
+  return TRUSTED_IPS.has(ip);
 };
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.7",
+  "version": "2.7.10",
   "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
   "main": "index.js",
   "module": "index.js",
@@ -18,6 +18,18 @@
   },
   "author": "明空",
   "license": "ISC",
+  "files": [
+    "index.js",
+    "app/",
+    "config/",
+    "core/",
+    "middleware/",
+    "response/",
+    "security/",
+    "storage/",
+    "utils/",
+    "doc/"
+  ],
   "dependencies": {
     "art-template": "^4.13.4",
     "cookie-parser": "^1.4.7",
@@ -26,17 +38,23 @@
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "express-art-template": "^1.0.1",
+    "i18next": "^24.2.0",
     "jsonwebtoken": "^9.0.3",
     "knex": "^3.2.10",
     "marked": "^18.0.3",
-    "morgan": "^1.10.1",
     "mysql2": "^3.22.3",
+    "node-cron": "^3.0.3",
+    "pino": "^9.5.0",
+    "pino-http": "^10.3.0",
     "serve-favicon": "^2.5.1",
     "xss": "^1.0.15",
     "ioredis": "^5.4.6"
   },
+  "devDependencies": {
+    "pino-pretty": "^11.3.0"
+  },
   "peerDependencies": {
-    "zod": "^3.0.0"
+    "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
     "zod": {

package/response/code.js

@@ -52,18 +52,6 @@ export const CODE_DB_CONNECTION_ERROR = 6001;
 export const CODE_DB_ACCESS_DENIED = 6002;
 export const CODE_DB_OPERATION_TIMEOUT = 6007;
 
-// 数据库原生错误标识 → 业务码映射
-export const DB_ERROR = Object.freeze({
-  ECONNREFUSED: 6001,
-  ER_ACCESS_DENIED_ERROR: 6002,
-  ER_ROW_IS_REFERENCED_2: 6003,
-  ER_BAD_FIELD_ERROR: 6004,
-  ER_DUP_ENTRY: 6005,
-  ER_NO_SUCH_TABLE: 6006,
-  ETIMEDOUT: 6007,
-  ER_TABLE_EXISTS_ERROR: 1005,
-});
-
 /**
  * 根据业务码获取默认提示文案
  * @param {number} code 业务状态码

package/response/response.js

@@ -31,7 +31,12 @@ export function serializeError(err, exposeDetail = false) {
   if (isAppError(err)) {
     const result = { success: false, code: err.code, msg: err.message };
     const extra = {};
+    // 框架内部字段永远不外泄；stack/cause(可能含SQL) 仅 dev(exposeDetail=true) 时附带
+    const NEVER_EXPOSE = new Set(["code", "message", "name", "meta", "httpStatus"]);
+    const SENSITIVE = new Set(["stack", "cause"]);
     for (const key of Object.getOwnPropertyNames(err)) {
+      if (NEVER_EXPOSE.has(key)) continue;
+      if (SENSITIVE.has(key) && !exposeDetail) continue; // 生产环境不泄露堆栈/根因(SQL)
       const val = err[key];
       if (val === undefined || val === null) continue;
       if (typeof val === "function" || typeof val === "symbol") continue;
@@ -42,11 +47,12 @@ export function serializeError(err, exposeDetail = false) {
     return result;
   }
 
-  // 原生未知系统错误：生产环境强制脱敏，不泄露 SQL / 堆栈
+  // 原生未知系统错误：生产环境强制脱敏，不泄露 SQL / 堆栈 / 根因
   return {
     success: false,
     code: CODE_SYSTEM_ERROR,
-    msg: err?.message || "系统内部错误",
+    // 生产环境不暴露原始 message（可能含 SQL 片段），仅 dev 透出
+    msg: exposeDetail ? (err?.message || "系统内部错误") : "系统内部错误",
     ...(exposeDetail && err?.stack ? { data: { stack: err.stack } } : {}),
   };
 }

package/security/keywords.js

@@ -22,11 +22,10 @@ const KEYWORD_RULES = Object.freeze({
   commandInjection: [
     "cmd=", "system(", "exec(", "shell_exec(", "passthru(",
     "eval(", "assert(", "preg_replace", "bash -i", "rm -rf",
-    "wget ", "curl ", "base64_decode", "phpinfo()",
+    "wget ", "base64_decode", "phpinfo()",
     "killall", "shutdown", "fdisk", "mkfs", "dd ",
     "scp ", "rsync", "nc ", "netcat", "nmap", "iptables",
-    "systemctl", "service", "crontab", "sudo", "useradd",
-    "userdel", "usermod", "groupadd", "groupdel", "passwd", "chpasswd"
+    "systemctl"
   ],
   pathTraversal: [
     "../", "..\\", "/etc/passwd", "/etc/shadow", "/etc/hosts",

package/utils/logger.js

@@ -1,117 +1,86 @@
-/**
- * 统一日志工具
- * 1. 本地dev：彩色友好打印
- * 2. 线上prd：JSON单行字符串输出，供日志采集器解析
- * 3. 日志分级控制 LOG_LEVEL，线上关闭调试日志减少磁盘占用
- * 4. error/fatal 自动走 stderr
- * 5. 支持自定义模块标签、本地文件落盘、错误堆栈结构化解析
- */
-import fs from "fs";
-import path from "path";
-import { parseStack } from "../core/errors.js";
-
-const LOG_LEVELS = Object.freeze({
-  trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 99,
-});
-
-const COLORS = Object.freeze({
-  trace: "\x1b[90m",
-  debug: "\x1b[34m",
-  info: "\x1b[32m",
-  warn: "\x1b[33m",
-  error: "\x1b[31m",
-  fatal: "\x1b[41m\x1b[37m",
-  reset: "\x1b[0m",
-});
-
-const ERROR_LEVELS = new Set(["error", "fatal"]);
+import pino from "pino";
 
 const NODE_ENV = (process.env.NODE_ENV || "dev").toLowerCase();
 const IS_PROD = ["prd", "prod", "production"].includes(NODE_ENV);
-const DEFAULT_LOG_LEVEL = IS_PROD ? "info" : "debug";
-const CURRENT_LEVEL = LOG_LEVELS[(process.env.LOG_LEVEL || DEFAULT_LOG_LEVEL).toLowerCase()] ?? LOG_LEVELS.info;
+const LOG_LEVEL = process.env.LOG_LEVEL || (IS_PROD ? "info" : "debug");
 
-const LOG_FILE = process.env.LOG_FILE || "";
-let writeStream = null;
-
-/** 判断当前级别是否允许输出 */
-const isLevelEnable = level => (LOG_LEVELS[level] ?? 99) >= CURRENT_LEVEL;
+/**
+ * pino 基础配置
+ * - dev：pino-pretty 彩色输出，单行易读
+ * - prod：纯 JSON，pm2 捕获 stdout
+ */
+const baseOptions = {
+  level: LOG_LEVEL,
+  timestamp: pino.stdTimeFunctions.isoTime,
+};
 
-/** 格式化毫秒级时间戳 YYYY-MM-DD HH:mm:ss.SSS */
-function getTime() {
-  const now = new Date();
-  const pad = (n, len = 2) => String(n).padStart(len, "0");
-  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
+if (!IS_PROD) {
+  baseOptions.transport = {
+    target: "pino-pretty",
+    options: {
+      colorize: true,
+      translateTime: "yyyy-mm-dd HH:mm:ss.l",
+      // dev 终端只做单进程开发，module 恒为 "Chan" 无区分意义，隐藏以精简输出
+      // （prod 仍保留 module 字段，便于日志聚合时按模块过滤）
+      ignore: "pid,hostname,module",
+    },
+  };
 }
 
-/** 本地日志文件写入（仅开发环境） */
-function writeFile(line) {
-  if (!LOG_FILE.trim() || IS_PROD) return;
-  try {
-    if (!writeStream) {
-      const dir = path.dirname(LOG_FILE);
-      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-      writeStream = fs.createWriteStream(LOG_FILE, { flags: "a" });
-      writeStream.on("error", () => {}); // 静默吞掉流异常，不阻塞业务
-      process.once("exit", () => writeStream?.end());
-    }
-    writeStream.write(`${line}\n`);
-  } catch { /* 写入失败静默 */ }
-}
+/** pino 根实例 */
+export const root = pino(baseOptions);
+
+/**
+ * 将多参数调用适配为 pino 格式
+ * 兼容现有用法：logger.info("msg")、logger.error("msg", err)、logger.warn("msg", obj)
+ *
+ * @param {string} level - 日志级别
+ * @param {import("pino").Logger} instance - pino 实例
+ * @param {...any} args - 业务传入的参数
+ */
+function emit(level, instance, ...args) {
+  const msgParts = [];
+  const mergeObj = {};
 
-/** 解析日志入参，分离普通文本与错误堆栈 */
-function parseArgs(args) {
-  let stackInfo = null;
-  const parts = [];
   for (const arg of args) {
     if (arg instanceof Error) {
-      const stackData = parseStack(arg.stack);
-      stackInfo = { ...stackData, raw: arg.stack };
-      parts.push(arg.message);
+      // Error 对象转为 pino 的 err 字段（自动序列化 stack）
+      mergeObj.err = arg;
+      msgParts.push(arg.message);
     } else if (arg !== null && typeof arg === "object") {
-      try { parts.push(JSON.stringify(arg)); }
-      catch { parts.push(String(arg)); }
+      Object.assign(mergeObj, arg);
     } else {
-      parts.push(arg);
+      msgParts.push(String(arg));
     }
   }
-  return { message: parts.join(" "), stackInfo };
-}
 
-/** 日志核心输出 */
-function emit(level, label, args) {
-  if (!isLevelEnable(level)) return;
+  const msg = msgParts.join(" ");
+  const hasMerge = Object.keys(mergeObj).length > 0;
 
-  const { message, stackInfo } = parseArgs(args);
-  const time = getTime();
-  const isErrLog = ERROR_LEVELS.has(level);
-  const printFn = isErrLog ? console.error : console.log;
-
-  if (IS_PROD) {
-    const logLine = JSON.stringify({ time, env: NODE_ENV, level, label, message, stack: stackInfo, pid: process.pid });
-    printFn(logLine);
-    return;
+  if (hasMerge) {
+    instance[level](mergeObj, msg);
+  } else {
+    instance[level](msg);
   }
-
-  const color = COLORS[level] ?? "";
-  printFn(`${color}[${time}] [${level.toUpperCase()}] [${label}]${COLORS.reset}`, ...args);
-  if (stackInfo) console.error(`${color}>>>> 错误堆栈详情:${COLORS.reset}`, stackInfo);
-  writeFile(`[${time}] [${level.toUpperCase()}] [${label}] ${message}`);
 }
 
-/** 创建带固定业务标签的日志实例 */
+/**
+ * 创建带固定标签的日志实例
+ * @param {string} [label="Chan"] - 模块标签
+ * @returns {{trace: Function, debug: Function, info: Function, warn: Function, error: Function, fatal: Function}}
+ */
 export function createLogger(label = "Chan") {
-  const safeLabel = String(label).trim() || "Chan";
-  const make = level => (...args) => emit(level, safeLabel, args);
+  const instance = root.child({ module: label });
   return {
-    trace: make("trace"),
-    debug: make("debug"),
-    info: make("info"),
-    warn: make("warn"),
-    error: make("error"),
-    fatal: make("fatal"),
+    trace: (...args) => emit("trace", instance, ...args),
+    debug: (...args) => emit("debug", instance, ...args),
+    info:  (...args) => emit("info", instance, ...args),
+    warn:  (...args) => emit("warn", instance, ...args),
+    error: (...args) => emit("error", instance, ...args),
+    fatal: (...args) => emit("fatal", instance, ...args),
   };
 }
 
+/** 默认导出：全局 logger 实例（标签 "Chan"） */
 const logger = createLogger("Chan");
 export default logger;