chanjs 2.8.0 → 2.8.2

package/README.md

@@ -29,7 +29,8 @@
 ### 基础设施
 
 - **高性能日志**：Pino 结构化日志输出
-- **全链路请求追踪**：pino‑http，自动注入唯一 `requestId`
+- **全链路请求追踪**：自动注入唯一 `requestId`（`X-Request-Id` 响应头 + `req.id` + `req.log`）
+- **访问日志按人归因**：一行纯文本，身份列 `ip + (uid|fp|sid)`，可追踪单个用户/访客的完整访问路径
 - **国际化多语言**：i18next，内存高速语言查找
 - **全局事件总线**：轻量封装 Node.js EventEmitter，解耦业务事件
 - **定时任务调度**：node‑cron，自带异常捕获、停机安全回收
@@ -109,21 +110,59 @@ chan.run((port) => {       // 启动 HTTP 服务
 
 ### 1. 日志系统（Pino）
 
-开发环境彩色控制台输出；生产环境输出 JSON 结构化日志，适配 PM2 采集。API 向下完全兼容。
+pino 单实例 + pino-pretty（以 stream 方式跑主进程），**唯一开关 `LOG_LEVEL`**（默认 `info`），不读 `NODE_ENV`。输出格式固定：
 
 ```
-import logger, { createLogger } from "chanjs";
+2026-09-04 23:01:16.811 [Chan] HTTP服务启动，监听端口：3000
+2026-09-04 23:01:16.811 ip=127.0.0.1 uid=2 GET /base/menu/list 200 6ms
+```
+
+时间是本地时区 `yyyy-MM-dd HH:mm:ss.SSS`，后面直接接正文——没有 `level/pid/hostname/module` 固定头，也没有 pino-pretty 默认的方括号和冒号。输出一律 stdout：本地开发直接看控制台，线上由 pm2 收集（框架不写日志文件、不接自定义管道）。
+
+```
+import { logger } from "chanjs";
 
-// 全局日志实例
+// 全局日志实例（logger 是具名导出，默认导出是 Chan 主类）
 logger.info("启动完成");
 logger.error("查询失败", err);   // 自动识别 Error 对象
 
-// 创建带业务标签的子日志
-const dbLog = createLogger("DB");
-dbLog.warn("慢查询");
+// 携带上下文用 pino 原生 child（如请求链路 req.log）
+const reqLog = logger.child({ userId: 1 });
+reqLog.warn("慢查询");
+```
+
+访问日志由 **pino-http** 官方中间件接管（`middleware/log.js` 内 `app.use(pinoHttp({ logger: root }))`），自动记录 `req/res/status/duration`，并挂载 `req.log` 供业务打点：
+
+```js
+import pinoHttp from "pino-http";
+import { root } from "../utils/logger.js";
+
+app.use(pinoHttp({ logger: root }));
+```
+
+`middleware/log.js` 只额外补两件 pino-http 不管的事：① 匿名访客自动种 `_sid`（30 天 httpOnly cookie，按浏览器归人）；② 用 `customSuccessMessage` 把访问行拼成 morgan 一行，身份列 = 来源IP + 用户标识（登录打 `uid`，未登录有设备指纹打 `fp`，再否则打 `sid`），用于按人追踪访问路径：
+
 ```
+# 游客首访（自动种 _sid）
+2026-09-04 22:59:36.768 ip=127.0.0.1 sid=2aad120e7b1c85b9 GET /news/index.html 200 23ms
+# 同一浏览器后续请求 → 同一 sid，可串出完整访问序列
+2026-09-04 22:59:36.868 ip=127.0.0.1 sid=2aad120e7b1c85b9 GET /news/hydraulic/index.html 200 23ms
+# 未登录但有设备指纹 → fp
+2026-09-04 22:59:36.903 ip=127.0.0.1 fp=fp_dev_hash_9x GET /news/hydraulic/article-58.html 200 23ms
+# 登录用户 → uid 优先
+2026-09-04 22:59:37.161 ip=127.0.0.1 uid=2 GET /base/menu/list 200 7ms
+```
+
+四列身份的取值优先级（`middleware/log.js` 内 `who()`）：
+
+| 列 | 来源 | 说明 |
+|---|---|---|
+| `ip` | `getIp(req)`（取 `X-Forwarded-For` / `X-Real-IP`） | 常驻，每行必有 |
+| `uid` | `req.user.uid` | 登录用户（后台 auth、前台会员 `optionalAuth`），优先级最高 |
+| `fp` | cookie `_f` | 设备指纹，未登录但有指纹时打 |
+| `sid` | cookie `_sid` | 匿名访客，首访由服务端生成并种 30 天 httpOnly cookie |
 
-请求日志由 `pino‑http` 自动接管，每个请求分配唯一 `requestId`，Controller 内可直接携带链路日志：
+每个请求注入唯一 `requestId`（响应头 `X-Request-Id` + `req.id` + `req.log`），Controller 内可直接携带链路日志：
 
 ```
 // 在 Controller 中
@@ -253,7 +292,7 @@ HTTP 服务 → 定时任务 → 缓存存储 → 数据库连接 → 事件总
 | `NODE_ENV` | 运行环境标识(dev/prd) | dev |
 | `PORT` | HTTP 监听端口 | 3000 |
 | `LOCALE` | 默认语言 | zh‑CN |
-| `LOG_LEVEL` | 日志输出级别 | dev:debug / prd:info |
+| `LOG_LEVEL` | 日志输出级别（trace/debug/info/warn/error/fatal） | info |
 | `TRUSTED_PROXIES` | 信任反向代理网段 | loopback |
 | `SHUTDOWN_TIMEOUT` | 优雅停机超时时间(ms) | 5000 |
 | `REDIS_ENABLED` | 是否开启 Redis | false |

package/core/App.js

@@ -10,6 +10,7 @@ import { register as registerShutdown, shutdown as runShutdown } from "../utils/
 import { registerCoreMiddleware } from "./bootstrap/middleware.js";
 import { loadModuleRouter, loadCommonRouter } from "./bootstrap/router-loader.js";
 import { registerErrorHandler } from "./bootstrap/error-handler.js";
+import { log } from "../middleware/log.js";
 import { runHooks } from "./bootstrap/hook-runner.js";
 import { loadDotEnv } from "../config/index.js";
 import { event } from "./EventBus.js";
@@ -71,6 +72,7 @@ export default class Chan {
     logger.info("[Chan] 核心中间件注册完成");
 
     this.#setupApp();
+    log(this.app);   // 访问日志中间件：框架内置，业务侧无感（早于 #mountRouter 以正确计时整请求）
     await this.#loadRoutes();
     this.#mountRouter();
     logger.info("[Chan] 路由加载挂载完成");

package/core/bootstrap/error-handler.js

@@ -68,7 +68,10 @@ export function registerErrorHandler(chan) {
     const userId = req.user?.id ?? "-";
 
     // 日志分级：业务错误 4xx → warn，系统错误 5xx → error（唯一打印点，杜绝重复刷屏）
-    const logFn = httpStatus < 500 ? logger.warn : logger.error;
+    // ⚠️ pino 的日志方法依赖 this，不能解引用后裸调（logFn = logger.warn; logFn(...) 会在
+    // pino/lib/tools.js 抛 TypeError: Cannot read properties of undefined (reading 'Symbol(pino.msgPrefix)')，
+    // 把真实的业务错误整个掩盖成 500），必须用箭头函数包一层保住 this
+    const logFn = httpStatus < 500 ? (msg) => logger.warn(msg) : (msg) => logger.error(msg);
     logFn(JSON.stringify({
       type: err.name || "UnknownError",
       message: describeError(err), // 递归解析 cause 根因，支持 AggregateError

package/doc/00-README.md

@@ -52,7 +52,7 @@ graph TD
     Err["错误 AppError 族<br/>(core/errors.js)"]
     Sec["安全 jwt / filterXSS /<br/>checkKeywords / rate-limit / sign"]
     Sto["存储 store / cache"]
-    Log["日志 logger / createLogger"]
+    Log["日志 logger"]
     Val["校验 validate / validateAll"]
     Path["路径 utils.paths / file"]
   end
@@ -191,7 +191,7 @@ export class DemoController extends Controller {
 | [02-响应与错误.md](./02-响应与错误.md) | `success` / `fail` / `AppError` 族 / `CODE` 错误码 | 写接口必看 |
 | [03-安全模块.md](./03-安全模块.md) | JWT 登录态、XSS 过滤、关键词校验、限流、加解密 | 做登录/评论/表单必看 |
 | [04-存储与缓存.md](./04-存储与缓存.md) | `store`（Redis/内存）、`cache`（内存缓存） | 做缓存/限流/黑名单必看 |
-| [05-工具与校验.md](./05-工具与校验.md) | `logger` / `createLogger`、`Paths`、`safePath`、`validate` / `validateAll` | 日常工具 |
+| [05-工具与校验.md](./05-工具与校验.md) | `logger`、`Paths`、`safePath`、`validate` / `validateAll` | 日常工具 |
 | [06-应用生命周期.md](./06-应用生命周期.md) | `Chan` 类、`beforeStart`、`loader`、`registry` | 想理解启动流程/写启动钩子 |
 | [07-事件系统EventBus.md](./07-事件系统EventBus.md) | `EventBus` / `event` 事件总线 | 做模块解耦 / 异步通知 |
 | [08-定时任务Task.md](./08-定时任务Task.md) | `Task` 定时任务（cron） | 做定时清理 / 同步 / 报表 |

package/doc/05-/345/267/245/345/205/267/344/270/216/346/240/241/351/252/214.md

@@ -1,20 +1,22 @@
-# 05 · 工具与校验：logger / createLogger / Paths / 文件安全 / validate / utils 工具集
+# 05 · 工具与校验：logger / Paths / 文件安全 / validate / utils 工具集
 
 日常开发最常用的小工具。导出方式分两类：
-- **根包直接导出**：`logger`（默认导出）、`createLogger`、`Paths`、`validate`、`validateAll`。
+- **根包直接导出**：`logger`、`Paths`、`validate`、`validateAll`。
 - **`utils` 命名空间导出**：`import { getIp, request, tree, ... } from "chanjs/utils/index.js"`，
   或集中用 `import { utils } from "chanjs"` 后 `utils.getIp(...)`。
 
 ---
 
-## 一、日志 `logger` / `createLogger`
+## 一、日志 `logger`
 
-文件：`utils/logger.js`。统一日志，**dev 彩色控制台、prd JSON 单行**（方便日志采集）。
+文件：`utils/logger.js`。基于 pino 单实例（`logger` 即 `root`），**dev/prd 均走 pino-pretty 人读输出**，
+`base:null` + `ignore` 去掉 `pid/hostname/module/level` 固定头，时间只留 `HH:mm:ss`。例：
+`[14:09:33]: GET /cms/field/findByMid?mid=11 200 3ms`
 
 ### 1.1 默认实例 `logger`
 
 ```js
-import logger from "chanjs";   // 注意是默认导出
+import { logger } from "chanjs";   // logger 是具名导出（默认导出是 Chan 主类）
 
 logger.info("服务启动");
 logger.warn("缓存未命中");
@@ -28,25 +30,25 @@ logger.debug("调试信息", { userId: 1 });
 | `debug` | 1 | 调试（dev 默认开启）|
 | `info` | 2 | 常规信息（prd 默认开启）|
 | `warn` | 3 | 警告 |
-| `error` | 4 | 错误（自动走 stderr）|
+| `error` | 4 | 错误 |
 | `fatal` | 5 | 致命 |
 
-**级别控制**：环境变量 `LOG_LEVEL`（dev 默认 `debug`，prd 默认 `info`）。低于该级别的日志不输出。
-**输出目标**：基于 pino，dev 走 pino-pretty 彩色控制台；prd 输出纯 JSON 到 stdout，由 pm2 统一捕获落盘（框架不直接写日志文件）。
+**级别控制**：唯一环境变量 `LOG_LEVEL`（默认 `info`），低于该级别的日志不输出——不读 `NODE_ENV`，级别只看这一个变量。
+**输出目标**：pino + pino-pretty，统一 stdout。本地开发直接看控制台；线上由 pm2 捕获 stdout 落盘（框架不写日志文件、不接自定义管道）。格式固定为「时间戳 + 正文」，`pid/hostname/module/level` 固定头已忽略。
 
-### 1.2 自定义标签实例 `createLogger(name)`
+### 1.2 子日志 / 链路日志
 
-框架内部统一用默认 `logger`（标签 `Chan`）。**业务代码建议用 `createLogger` 自建带标签实例**，方便区分来源：
+需要区分来源或携带上下文时，用 pino 原生 `child`（不要再造 logger 实例）：
 
 ```js
-import { createLogger } from "chanjs";
+import { logger } from "chanjs";
 
-const log = createLogger("Member");   // 标签 Member
-log.info("用户登录", { userId: 1 });
-// 输出（pino-pretty 彩色）：[2026-08-01 12:00:00.123 INFO]: 用户登录 {"userId":1}
+const reqLog = logger.child({ userId: 1 });   // 绑定字段，每行自动附带
+reqLog.info("用户登录");
+// [14:09:33]: 用户登录 {"userId":1}
 ```
 
-> 📌 约定：框架内部统一 `import logger`，业务侧用 `createLogger("模块名")` 区分来源。dev 环境下 `module` 字段已被 pino-pretty 隐藏以精简输出（prod 仍保留便于聚合）。
+请求链路：`middleware/log.js` 已为每个请求注入 `req.log`（`logger.child({ requestId })`）与 `req.id`，Controller 内直接用。
 
 ### 1.3 传 Error 自动解析
 
@@ -283,8 +285,7 @@ const html = `<ul>${pages(page, total, 10, "/news/", "")}</ul>`;
 
 | 导出 | 类型 | 一句话用途 |
 |---|---|---|
-| `logger`(默认) | 实例 | 框架级日志（标签 Chan）|
-| `createLogger(name)` | 函数 | 业务自建带标签日志 |
+| `logger` | 实例 | 框架级日志（具名导出，pino 单实例）|
 | `Paths` | 对象 | 项目目录常量（root/app/config/public/modules/common/helper/extend）|
 | `safePath` | 函数 | 防路径穿越（深导入 `utils/file.js`）|
 | `validate` | 函数 | 单来源 zod 校验中间件 |
@@ -301,7 +302,7 @@ const html = `<ul>${pages(page, total, 10, "/news/", "")}</ul>`;
 
 ## 七、常见坑
 
-1. **`logger` 是默认导出**：`import logger from "chanjs"`（无花括号）；`createLogger` 才是具名导出。
+1. **`logger` 是具名导出**：`import { logger } from "chanjs"`（花括号）；`chanjs` 的默认导出是 `Chan` 主类，别混。
 2. **忘了 `await store` 但 `cache` 同步**：`store` 异步要 `await`，`cache` 同步不要 `await`。
 3. **校验后读 `req.body` 而非 `req.validated`**：Express 5 下 `req.query` 只读，框架已用 `req.validated` 统一承载，优先用它。
 4. **zod 数字不 coerce**：表单传来的是字符串，`z.number()` 会失败，记得 `z.coerce.number()`。

package/index.js

@@ -69,7 +69,7 @@ export { createRateLimitMiddleware } from "./security/rate-limit.js";
 export { filterXSS, checkKeywords } from "./security/index.js";
 
 // ===================== 统一日志 =====================
-export { default as logger, createLogger } from "./utils/logger.js";
+export { default as logger } from "./utils/logger.js";
 
 // ===================== 校验中间件 =====================
 export { validate, validateAll } from "./middleware/validate.js";

package/middleware/log.js

@@ -1,52 +1,47 @@
-import { randomUUID } from "crypto";
+import { randomBytes } from "crypto";
 import pinoHttp from "pino-http";
-import { getIp } from "../utils/ip.js";
 import { root } from "../utils/logger.js";
+import { getIp } from "../utils/ip.js";
+
+// 静态资源：不记日志、不种 cookie
+const STATIC = /\.(ico|png|jpe?g|gif|svg|css|js|mjs|woff2?|ttf|eot|map|webp|avif)([?#].*)?$/;
+
+// 一行访问日志：ip=1.2.3.4 sid=xx GET /url 200 13ms
+// 框架保持通用：只记框架自己能产生的身份（ip + sid），业务身份（uid 等）与框架无关
+const line = (req, res, ms) =>
+  [
+    `ip=${getIp(req)}`,
+    req.sid && `sid=${req.sid}`,
+    req.method,
+    req.originalUrl || req.url,
+    res.statusCode,
+    `${ms ?? 0}ms`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+// 访问日志：pino-http 官方中间件接管（监听 finish、算耗时、挂 req.log）
+// 额外只做 pino-http 不管的一件事：匿名访客 _sid（首访种 30 天 httpOnly cookie，之后按浏览器归人）
+export function log(app) {
+  app.use((req, res, next) => {
+    req.skipLog = STATIC.test(req.originalUrl || req.url);
+    if (!req.skipLog) {
+      const hasSid = Boolean(req.cookies?._sid);
+      req.sid = hasSid ? req.cookies._sid : randomBytes(8).toString("hex");
+      // 仅首访无 _sid 时种 cookie（避免每个响应都带 Set-Cookie 头）
+      if (!hasSid) {
+        res.cookie("_sid", req.sid, { maxAge: 30 * 24 * 3600 * 1000, httpOnly: true, sameSite: "lax" });
+      }
+    }
+    next();
+  });
 
-/**
- * 请求日志中间件（pino-http）
- *
- * 自动为每个请求生成 requestId，挂载 req.log（带 requestId 的子 logger）。
- * 业务 Controller 中可通过 req.log.info("xxx") 输出带 requestId 的日志。
- *
- * @param {object} app - Express 实例
- * @param {object} [config={}] - 配置对象
- */
-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 }),
-    },
-  }));
+  app.use(
+    pinoHttp({
+      logger: root,
+      autoLogging: { ignore: (req) => req.skipLog },
+      customSuccessMessage: line,
+      customErrorMessage: (req, res, err, ms) => `${line(req, res, ms)} ${err?.message || ""}`.trim(),
+    }),
+  );
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "chanjs基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。",
   "main": "index.js",
   "module": "index.js",

package/utils/logger.js

@@ -1,86 +1,22 @@
 import pino from "pino";
-
-const NODE_ENV = (process.env.NODE_ENV || "dev").toLowerCase();
-const IS_PROD = ["prd", "prod", "production"].includes(NODE_ENV);
-const LOG_LEVEL = process.env.LOG_LEVEL || (IS_PROD ? "info" : "debug");
-
-/**
- * pino 基础配置
- * - dev：pino-pretty 彩色输出，单行易读
- * - prod：纯 JSON，pm2 捕获 stdout
- */
-const baseOptions = {
-  level: LOG_LEVEL,
-  timestamp: pino.stdTimeFunctions.isoTime,
+import pretty from "pino-pretty";
+
+// 本地时间 yyyy-mm-dd HH:mm:ss.l（pino 默认给 UTC 的 ISO 串，带 T/Z 不好读，这里直接格式化好）
+const p = (n, w = 2) => String(n).padStart(w, "0");
+const timestamp = () => {
+  const d = new Date();
+  const t = `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+  return `,"time":"${t}"`;
 };
 
-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",
-    },
-  };
-}
-
-/** 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 = {};
-
-  for (const arg of args) {
-    if (arg instanceof Error) {
-      // Error 对象转为 pino 的 err 字段（自动序列化 stack）
-      mergeObj.err = arg;
-      msgParts.push(arg.message);
-    } else if (arg !== null && typeof arg === "object") {
-      Object.assign(mergeObj, arg);
-    } else {
-      msgParts.push(String(arg));
-    }
-  }
-
-  const msg = msgParts.join(" ");
-  const hasMerge = Object.keys(mergeObj).length > 0;
-
-  if (hasMerge) {
-    instance[level](mergeObj, msg);
-  } else {
-    instance[level](msg);
-  }
-}
-
-/**
- * 创建带固定标签的日志实例
- * @param {string} [label="Chan"] - 模块标签
- * @returns {{trace: Function, debug: Function, info: Function, warn: Function, error: Function, fatal: Function}}
- */
-export function createLogger(label = "Chan") {
-  const instance = root.child({ module: label });
-  return {
-    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;
+// 输出格式：时间 + 空格 + 正文（pino-pretty 默认模板是 [time]: msg，方括号和冒号去不掉，
+// 故忽略 time 字段、改由 messageFormat 把时间拼在行首）
+export const root = pino(
+  { level: (process.env.LOG_LEVEL || "info").trim(), base: null, timestamp },
+  pretty({
+    colorize: false,
+    ignore: "pid,hostname,level,time,req,res,responseTime,reqId",
+    messageFormat: "{time} {msg}",
+  }),
+);
+export default root;