backend / 日志模块 - WlAdmin 文档

WlAdmin

1. 概述

本文档详细说明了后端服务实现的日志管理模块，涵盖日志级别、模块级别控制、结构化输出、敏感信息脱敏、自动轮转、请求追踪等核心功能，以及日志使用、最佳实践、常见问题等内容，确保系统的可观测性和可维护性。

1.1 什么是日志模块

日志管理模块是后端服务的核心组件，提供了统一的日志记录功能，支持：

✅ 多级别日志：DEBUG、INFO、WARN、ERROR 四个级别
✅ 模块级别控制：不同模块可以设置不同的日志级别
✅ 结构化输出：JSON 格式，便于日志分析和检索
✅ 敏感信息脱敏：自动脱敏密码、邮箱、手机号等敏感信息
✅ 自动轮转：按文件大小自动轮转，防止日志文件过大
✅ 请求追踪：支持 correlation_id，便于跨服务追踪

核心特性

✅ 精细化管理：支持全局和模块级别的日志级别控制
✅ 安全可靠：自动脱敏敏感信息，保护用户隐私
✅ 易于分析：结构化 JSON 格式，便于日志检索和分析
✅ 自动维护：自动轮转和清理，防止日志文件过大
✅ 追踪能力：支持 correlation_id，实现跨服务请求追踪

1.2 为什么需要日志

日志是系统运维和问题排查的重要工具：

🔍 问题排查：快速定位错误和异常
📊 性能监控：监控请求响应时间和系统性能
🔐 安全审计：记录用户操作和系统行为
📈 数据分析：分析用户行为和系统使用情况

1.3 5分钟上手

步骤 1：导入 Logger

const { getLogger } = require("../logger");
const logger = getLogger("controllers.userController");

步骤 2：记录日志

// 业务操作成功
logger.info("用户创建成功", { userId: 123 });

// 错误异常
logger.error("用户创建失败", { error: err, payload: req.body });

// 调试信息
logger.debug("获取用户列表", { page, limit, filters });

// 警告信息
logger.warn("访问次数超过限制", { userIp, accessCount });

步骤 3：使用中间件（可选）

const { createRequestLogger, createErrorLogger } = require("../logger");
const requestIdMiddleware = require("../middlewares/requestIdMiddleware");

// 请求 ID 中间件（必须最先使用）
app.use(requestIdMiddleware);

// 请求日志中间件
app.use(createRequestLogger({ moduleName: "http", logBody: true }));

// 错误日志中间件（放在路由之后）
app.use(createErrorLogger("error"));

恭喜！ 你已经掌握了日志的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 日志级别

日志模块支持四个日志级别，按优先级从高到低：

级别	优先级	使用场景	示例
ERROR	3	错误异常，需要立即处理	系统错误、数据库查询失败
WARN	2	警告信息，需要关注但不影响主流程	权限不足、访问限制、慢请求
INFO	1	业务操作成功和关键流程节点	用户创建成功、登录成功
DEBUG	0	调试信息、缓存操作、查询操作	缓存命中、查询参数、内部状态

级别选择指南

DEBUG - 调试信息、缓存操作、查询操作

// ✅ 正确使用
logger.debug("缓存命中", { cacheKey });
logger.debug("从缓存获取用户列表", { page, limit });
logger.debug("获取用户列表参数", { page, limit, filters });

// ❌ 错误使用
logger.info("缓存命中", { cacheKey }); // 应该用 debug
logger.debug("用户创建成功", { userId }); // 应该用 info

INFO - 业务操作成功、关键流程节点

// ✅ 正确使用
logger.info("用户创建成功", { userId: 123 });
logger.info("用户更新成功", { userId: 123 });
logger.info("文件上传成功", { userId, filename });
logger.info("SSE连接已建立", { userId });

// ❌ 错误使用
logger.debug("用户创建成功", { userId }); // 应该用 info
logger.info("获取用户列表", { list }); // 查询操作应该用 debug，且不要记录完整列表

WARN - 警告信息，不影响主流程

// ✅ 正确使用
logger.warn("访问次数超过限制", { userIp, accessCount });
logger.warn("权限不足", { currentUserId, targetUserId });
logger.warn("请求慢响应", { duration: 1500, url: "/api/users" });

// ❌ 错误使用
logger.error("访问次数超过限制", { userIp }); // 应该用 warn
logger.info("权限不足", { userId }); // 应该用 warn

ERROR - 错误异常，需要立即处理

// ✅ 正确使用
logger.error("获取用户列表失败", { error: err });
logger.error("用户创建失败", { error: err, payload: req.body });
logger.error("数据库查询失败", { error: err, sql });

// ❌ 错误使用
logger.warn("用户创建失败", { error: err }); // 应该用 error
logger.error("访问次数超过限制", { userIp }); // 应该用 warn

2.2 模块级别控制

模块级别控制允许为不同的模块设置不同的日志级别，实现精细化的日志管理。

工作原理

全局日志级别（上限）
    ↓
模块日志级别（可以更严格，但不能更宽松）
    ↓
最终有效级别 = max(全局级别, 模块级别)

配置示例

// config/base/logger.js
const MODULE_LOG_LEVELS = {
  default: "info", // 默认级别
  database: "warn", // 数据库模块：只记录警告和错误
  api: "info", // API模块：记录信息、警告和错误
  auth: "debug", // 认证模块：记录所有日志（但受全局限制）
  cache: "warn", // 缓存模块：只记录警告和错误
};

模块名称映射规则

系统会自动将模块名称映射到配置键：

精确匹配（最高优先级）：
- infra.dbClient → database
- controllers.authController → auth
- cache.redisCache → cache
前缀匹配：
- models.* → database
- controllers.* → api
- routes.* → api
- middlewares.* → api
默认匹配：
- 未匹配到的模块使用 default 配置

实际效果示例

全局级别	模块级别	有效级别	说明
`info`	`debug`	`info`	模块不能比全局更宽松
`info`	`warn`	`warn`	模块可以更严格
`warn`	`debug`	`warn`	模块不能比全局更宽松
`warn`	`error`	`error`	模块可以更严格
`debug`	`warn`	`warn`	模块可以更严格

2.3 结构化日志

日志以 JSON 格式输出，包含以下字段：

{
  "timestamp": "2025-12-10T10:00:00.000Z",
  "level": "info",
  "message": "用户创建成功",
  "app_id": "node-express-mysql",
  "service_name": "api-service",
  "environment": "production",
  "correlation_id": "uuid-v4-string",
  "module": "controllers.userController",
  "file": "userController.js",
  "line": 123,
  "function": "createUser",
  "meta": {
    "userId": 123,
    "username": "testuser"
  }
}

关键字段说明

timestamp：ISO 格式的时间戳
level：日志级别（debug/info/warn/error）
message：日志描述信息
correlation_id：关联 ID，用于跨请求/服务追踪
module：模块名称
file/line/function：调用位置信息
meta：附加元数据

2.4 敏感信息脱敏

日志模块自动对敏感信息进行脱敏处理，保护用户隐私。

脱敏规则

字段类型	脱敏方式	示例
password	完全脱敏	`password123` → `***`
token	完全脱敏	`abc123` → `***`
email	邮箱脱敏	`user@example.com` → `us***@example.com`
phone	中间脱敏	`13812345678` → `138****5678`
idCard	中间脱敏	`110101199001011234` → `110101********1234`
bankCard	中间脱敏	`6222021234567890` → `6222********7890`

自动脱敏

所有通过 logger 记录的日志都会自动脱敏：

logger.info("用户登录", {
  username: "testuser",
  password: "secret123", // 自动脱敏为 ***
  email: "user@example.com", // 自动脱敏为 us***@example.com
  phone: "13812345678", // 自动脱敏为 138****5678
});

3. 基础使用

3.1 获取 Logger 实例

基本用法

const { getLogger } = require("../logger");

// 为当前模块创建 logger 实例
const logger = getLogger("controllers.userController");

模块命名规范

为了确保模块级别日志配置生效，请遵循以下命名规范：

Controllers: controllers.{ControllerName}
Models: models.{ModelName}
Routes: routes.{RouteName}
Middlewares: middlewares.{MiddlewareName}
Services: services.{ServiceName}
Infrastructure: infra.{ClientName}
Cache: cache.{CacheName}

3.2 记录日志

DEBUG 级别

// 缓存操作
logger.debug("缓存命中", { cacheKey: "user:123" });
logger.debug("缓存未命中", { cacheKey: "user:123" });

// 查询操作
logger.debug("获取用户列表", { page: 1, limit: 10, filters: { username: "test" } });

// 内部状态
logger.debug("初始化缓存服务", { provider: "RedisCache" });

INFO 级别

// 业务操作成功
logger.info("用户创建成功", { userId: 123, username: "testuser" });
logger.info("用户更新成功", { userId: 123 });
logger.info("用户删除成功", { userId: 123 });

// 关键流程节点
logger.info("用户登录成功", { userId: 123 });
logger.info("文件上传成功", { userId: 123, filename: "avatar.jpg" });
logger.info("SSE连接已建立", { userId: 123 });

WARN 级别

// 警告信息
logger.warn("访问次数超过限制", { userIp: "192.168.1.1", accessCount: 100 });
logger.warn("权限不足", { currentUserId: 123, targetUserId: 456 });
logger.warn("请求慢响应", { duration: 1500, url: "/api/users" });

ERROR 级别

// 错误异常
logger.error("获取用户列表失败", { error: err });
logger.error("用户创建失败", { error: err, payload: req.body });
logger.error("数据库查询失败", { error: err, sql: "SELECT * FROM users" });

3.3 日志级别选择

选择指南

何时使用 DEBUG：

缓存操作（命中/未命中/设置）
数据库查询操作
内部状态变化
详细的调试信息

何时使用 INFO：

业务操作成功（创建/更新/删除）
关键流程节点（登录/登出/上传）
重要状态变化（定时任务完成）

何时使用 WARN：

权限不足、访问限制
降级处理、非关键操作失败
慢请求（响应时间 > 1秒）
配置问题、参数验证警告

何时使用 ERROR：

系统错误、异常
操作失败（数据库查询失败、服务调用失败）
关键业务逻辑错误

避免记录大量数据

// ❌ 错误：记录完整列表数据
logger.debug("获取用户列表", { list: users }); // 列表可能很大

// ✅ 正确：只记录关键信息
logger.debug("获取用户列表", { page: 1, limit: 10, total: 100 });

// ❌ 错误：记录完整缓存数据
logger.debug("缓存命中", { cacheData: largeObject });

// ✅ 正确：只记录缓存键
logger.debug("缓存命中", { cacheKey: "user:123" });

4. 进阶使用

4.1 请求日志中间件

请求日志中间件自动记录所有 HTTP 请求的详细信息。

基本用法

const { createRequestLogger } = require("../logger");

// 创建请求日志中间件
app.use(
  createRequestLogger({
    moduleName: "http",
    logBody: true, // 是否记录请求体（默认 true）
    logHeaders: false, // 是否记录请求头（默认 false）
  })
);

配置选项

moduleName：模块名称（默认 "http"）
logBody：是否记录请求体（默认 true，GET 请求不记录）
logHeaders：是否记录请求头（默认 false）

自动日志级别

中间件会根据响应状态码和响应时间自动选择日志级别：

状态码 >= 500：ERROR 级别
状态码 >= 400：WARN 级别
响应时间 > 1秒：WARN 级别（慢请求）
其他：DEBUG 级别

日志内容

{
  "level": "debug",
  "message": "请求完成",
  "method": "POST",
  "url": "/api/users",
  "status_code": 200,
  "duration_ms": 150,
  "response_size": 1024,
  "response_time_category": "normal",
  "ip": "192.168.1.1",
  "userId": "123",
  "params": {},
  "query": {},
  "body": { "username": "testuser" }
}

4.2 错误日志中间件

错误日志中间件自动捕获和处理所有未处理的错误。

基本用法

const { createErrorLogger } = require("../logger");

// 创建错误日志中间件（放在路由之后）
app.use(createErrorLogger("error"));

日志内容

{
  "level": "error",
  "message": "Error occurred during request processing",
  "method": "POST",
  "url": "/api/users",
  "ip": "192.168.1.1",
  "userId": "123",
  "errorName": "ValidationError",
  "errorMessage": "用户名不能为空",
  "errorStack": "Error: 用户名不能为空\n    at ...",
  "statusCode": 400
}

4.3 请求 ID 追踪

请求 ID 追踪用于跨服务/请求的关联追踪。

基本用法

const requestIdMiddleware = require("../middlewares/requestIdMiddleware");

// 请求 ID 中间件（必须最先使用）
app.use(requestIdMiddleware);

工作原理

从请求头获取 X-Correlation-ID（如果存在）
如果不存在，自动生成新的 correlation_id
设置到 req.correlationId 和 global.correlationId
在响应头中添加 X-Correlation-ID

跨服务追踪

// 服务 A 发起请求
const correlationId = req.correlationId;
fetch("http://service-b/api/data", {
  headers: {
    "X-Correlation-ID": correlationId, // 传递 correlation_id
  },
});

// 服务 B 接收请求
// 自动从请求头获取 correlation_id，所有日志都会包含相同的 correlation_id
logger.info("处理请求", { correlationId: req.correlationId });

4.4 动态调整日志级别

可以在运行时动态调整日志级别。

全局级别

const { setGlobalLogLevel } = require("../logger");

// 设置全局日志级别
setGlobalLogLevel("warn"); // 只记录警告和错误

模块级别

const { setModuleLogLevel } = require("../logger");

// 设置特定模块的日志级别
setModuleLogLevel("controllers.userController", "debug");
setModuleLogLevel("models.userModel", "warn");

5. 架构设计

5.1 模块结构

src/logger/
├── index.js              # 入口文件，导出所有功能
├── enhanced-logger.js    # 增强日志（模块级别控制、调用方信息）
├── logger-core.js        # 核心功能（写盘、轮转、格式化）
├── data-masker.js        # 敏感信息脱敏
└── utils.js              # 工具函数（目录创建、ID生成等）

5.2 日志流程

应用代码
    ↓
getLogger(moduleName)
    ↓
logger.debug/info/warn/error()
    ↓
shouldLog() 检查级别
    ↓
logger-core.log() 格式化
    ↓
data-masker.maskObject() 脱敏
    ↓
writeLogToFile() 写入文件
    ↓
checkLogRotation() 检查轮转

5.3 日志轮转

自动轮转

当日志文件大小超过 10MB 时，自动进行轮转：

logs/output/2025-12-10.log (当前文件，10MB)
    ↓ 超过大小限制
logs/output/2025-12-10.log.1 (备份1)
logs/output/2025-12-10.log.2 (备份2)
...
logs/output/2025-12-10.log.5 (备份5，最旧的会被删除)

轮转配置

// config/base/logger.js
const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
const LOG_BACKUPS = 5; // 保留5个备份文件

6. 配置说明

6.1 基础配置

配置文件位置：config/base/logger.js

module.exports = {
  // 日志目录
  LOG_DIR: "./logs",
  ERROR_LOG_DIR: "./logs/error",
  OUTPUT_LOG_DIR: "./logs/output",

  // 默认日志级别
  DEFAULT_LOG_LEVEL: "info",

  // 文件配置
  MAX_LOG_SIZE: 10 * 1024 * 1024, // 10MB
  LOG_BACKUPS: 5, // 保留5个备份

  // 性能监控
  SLOW_REQUEST_THRESHOLD: 1000, // 1秒
};

6.2 模块级别配置

const MODULE_LOG_LEVELS = {
  default: "info", // 默认级别
  database: "warn", // 数据库模块
  api: "info", // API模块
  auth: "debug", // 认证模块（受全局限制）
  cache: "warn", // 缓存模块
};

6.3 脱敏配置

const SENSITIZATION_CONFIG = {
  enabled: true, // 全局脱敏开关
  rules: [
    {
      enabled: true,
      pattern: /"password":"([^"]*)"/g,
      replace: '"password":"******"',
    },
    // ... 其他规则
  ],
};

7. 最佳实践

✅ 推荐做法

统一使用结构化日志：所有日志都通过 logger 模块记录
合理选择日志级别：根据场景选择合适的级别
包含足够上下文：记录操作相关的用户ID、操作类型等
避免记录大量数据：只记录关键标识信息（ID、键名、数量等）
使用模块级别控制：为不同模块设置合适的日志级别
关联 ID 传递：跨服务调用时传递 correlation_id

❌ 避免做法

不要使用 console.log：使用 logger 模块统一记录
不要记录敏感信息：依赖自动脱敏，但也要注意不要记录未脱敏的数据
不要记录完整列表：只记录分页信息和总数
不要过度使用 DEBUG：生产环境应适当提高日志级别
不要忽略错误日志：所有错误都应该记录

8. 常见问题

Q1: 日志文件无法写入？

原因：

目录权限不足
磁盘空间不足

解决：

检查目录权限：ls -la ./logs
确保应用有写入权限：chmod -R 755 ./logs
检查磁盘空间：df -h

Q2: 日志级别不生效？

原因：

模块名称不匹配
全局级别限制

解决：

检查模块名称是否符合命名规范
检查全局日志级别是否限制了模块级别
查看配置是否正确加载

Q3: 敏感信息未脱敏？

原因：

字段名不在脱敏规则中
脱敏配置未启用

解决：

检查敏感字段是否包含在配置中
验证日志是否通过 logger 模块记录
检查 SENSITIZATION_CONFIG.enabled 是否为 true

Q4: 日志文件过大？

原因：

日志级别过低（DEBUG）
记录了大量数据

解决：

提高日志级别（生产环境使用 INFO 或 WARN）
减少记录的数据量
检查日志轮转是否正常工作

Q5: 如何查看日志？

方法：

查看错误日志：tail -f ./logs/error/2025-12-10.log
查看输出日志：tail -f ./logs/output/2025-12-10.log
搜索特定内容：grep "用户创建" ./logs/output/2025-12-10.log
按 correlation_id 追踪：grep "correlation_id.*abc123" ./logs/output/2025-12-10.log

日志是个好东西

1. 概述

1.1 什么是日志模块

日志管理模块是后端服务的核心组件，提供了统一的日志记录功能，支持：

✅ 多级别日志：DEBUG、INFO、WARN、ERROR 四个级别
✅ 模块级别控制：不同模块可以设置不同的日志级别
✅ 结构化输出：JSON 格式，便于日志分析和检索
✅ 敏感信息脱敏：自动脱敏密码、邮箱、手机号等敏感信息
✅ 自动轮转：按文件大小自动轮转，防止日志文件过大
✅ 请求追踪：支持 correlation_id，便于跨服务追踪

核心特性

✅ 精细化管理：支持全局和模块级别的日志级别控制
✅ 安全可靠：自动脱敏敏感信息，保护用户隐私
✅ 易于分析：结构化 JSON 格式，便于日志检索和分析
✅ 自动维护：自动轮转和清理，防止日志文件过大
✅ 追踪能力：支持 correlation_id，实现跨服务请求追踪

1.2 为什么需要日志

日志是系统运维和问题排查的重要工具：

🔍 问题排查：快速定位错误和异常
📊 性能监控：监控请求响应时间和系统性能
🔐 安全审计：记录用户操作和系统行为
📈 数据分析：分析用户行为和系统使用情况

1.3 5分钟上手

步骤 1：导入 Logger

const { getLogger } = require("../logger");
const logger = getLogger("controllers.userController");

步骤 2：记录日志

// 业务操作成功
logger.info("用户创建成功", { userId: 123 });

// 错误异常
logger.error("用户创建失败", { error: err, payload: req.body });

// 调试信息
logger.debug("获取用户列表", { page, limit, filters });

// 警告信息
logger.warn("访问次数超过限制", { userIp, accessCount });

步骤 3：使用中间件（可选）

const { createRequestLogger, createErrorLogger } = require("../logger");
const requestIdMiddleware = require("../middlewares/requestIdMiddleware");

// 请求 ID 中间件（必须最先使用）
app.use(requestIdMiddleware);

// 请求日志中间件
app.use(createRequestLogger({ moduleName: "http", logBody: true }));

// 错误日志中间件（放在路由之后）
app.use(createErrorLogger("error"));

恭喜！ 你已经掌握了日志的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 日志级别

日志模块支持四个日志级别，按优先级从高到低：

级别	优先级	使用场景	示例
ERROR	3	错误异常，需要立即处理	系统错误、数据库查询失败
WARN	2	警告信息，需要关注但不影响主流程	权限不足、访问限制、慢请求
INFO	1	业务操作成功和关键流程节点	用户创建成功、登录成功
DEBUG	0	调试信息、缓存操作、查询操作	缓存命中、查询参数、内部状态

级别选择指南

DEBUG - 调试信息、缓存操作、查询操作

// ✅ 正确使用
logger.debug("缓存命中", { cacheKey });
logger.debug("从缓存获取用户列表", { page, limit });
logger.debug("获取用户列表参数", { page, limit, filters });

// ❌ 错误使用
logger.info("缓存命中", { cacheKey }); // 应该用 debug
logger.debug("用户创建成功", { userId }); // 应该用 info

INFO - 业务操作成功、关键流程节点

// ✅ 正确使用
logger.info("用户创建成功", { userId: 123 });
logger.info("用户更新成功", { userId: 123 });
logger.info("文件上传成功", { userId, filename });
logger.info("SSE连接已建立", { userId });

// ❌ 错误使用
logger.debug("用户创建成功", { userId }); // 应该用 info
logger.info("获取用户列表", { list }); // 查询操作应该用 debug，且不要记录完整列表

WARN - 警告信息，不影响主流程

// ✅ 正确使用
logger.warn("访问次数超过限制", { userIp, accessCount });
logger.warn("权限不足", { currentUserId, targetUserId });
logger.warn("请求慢响应", { duration: 1500, url: "/api/users" });

// ❌ 错误使用
logger.error("访问次数超过限制", { userIp }); // 应该用 warn
logger.info("权限不足", { userId }); // 应该用 warn

ERROR - 错误异常，需要立即处理

// ✅ 正确使用
logger.error("获取用户列表失败", { error: err });
logger.error("用户创建失败", { error: err, payload: req.body });
logger.error("数据库查询失败", { error: err, sql });

// ❌ 错误使用
logger.warn("用户创建失败", { error: err }); // 应该用 error
logger.error("访问次数超过限制", { userIp }); // 应该用 warn

2.2 模块级别控制

模块级别控制允许为不同的模块设置不同的日志级别，实现精细化的日志管理。

工作原理

全局日志级别（上限）
    ↓
模块日志级别（可以更严格，但不能更宽松）
    ↓
最终有效级别 = max(全局级别, 模块级别)

配置示例

// config/base/logger.js
const MODULE_LOG_LEVELS = {
  default: "info", // 默认级别
  database: "warn", // 数据库模块：只记录警告和错误
  api: "info", // API模块：记录信息、警告和错误
  auth: "debug", // 认证模块：记录所有日志（但受全局限制）
  cache: "warn", // 缓存模块：只记录警告和错误
};

模块名称映射规则

系统会自动将模块名称映射到配置键：

精确匹配（最高优先级）：
- infra.dbClient → database
- controllers.authController → auth
- cache.redisCache → cache
前缀匹配：
- models.* → database
- controllers.* → api
- routes.* → api
- middlewares.* → api
默认匹配：
- 未匹配到的模块使用 default 配置

实际效果示例

全局级别	模块级别	有效级别	说明
`info`	`debug`	`info`	模块不能比全局更宽松
`info`	`warn`	`warn`	模块可以更严格
`warn`	`debug`	`warn`	模块不能比全局更宽松
`warn`	`error`	`error`	模块可以更严格
`debug`	`warn`	`warn`	模块可以更严格

2.3 结构化日志

日志以 JSON 格式输出，包含以下字段：

{
  "timestamp": "2025-12-10T10:00:00.000Z",
  "level": "info",
  "message": "用户创建成功",
  "app_id": "node-express-mysql",
  "service_name": "api-service",
  "environment": "production",
  "correlation_id": "uuid-v4-string",
  "module": "controllers.userController",
  "file": "userController.js",
  "line": 123,
  "function": "createUser",
  "meta": {
    "userId": 123,
    "username": "testuser"
  }
}

关键字段说明

timestamp：ISO 格式的时间戳
level：日志级别（debug/info/warn/error）
message：日志描述信息
correlation_id：关联 ID，用于跨请求/服务追踪
module：模块名称
file/line/function：调用位置信息
meta：附加元数据

2.4 敏感信息脱敏

日志模块自动对敏感信息进行脱敏处理，保护用户隐私。

脱敏规则

字段类型	脱敏方式	示例
password	完全脱敏	`password123` → `***`
token	完全脱敏	`abc123` → `***`
email	邮箱脱敏	`user@example.com` → `us***@example.com`
phone	中间脱敏	`13812345678` → `138****5678`
idCard	中间脱敏	`110101199001011234` → `110101********1234`
bankCard	中间脱敏	`6222021234567890` → `6222********7890`

自动脱敏

所有通过 logger 记录的日志都会自动脱敏：

logger.info("用户登录", {
  username: "testuser",
  password: "secret123", // 自动脱敏为 ***
  email: "user@example.com", // 自动脱敏为 us***@example.com
  phone: "13812345678", // 自动脱敏为 138****5678
});

3. 基础使用

3.1 获取 Logger 实例

基本用法

const { getLogger } = require("../logger");

// 为当前模块创建 logger 实例
const logger = getLogger("controllers.userController");

模块命名规范

为了确保模块级别日志配置生效，请遵循以下命名规范：

Controllers: controllers.{ControllerName}
Models: models.{ModelName}
Routes: routes.{RouteName}
Middlewares: middlewares.{MiddlewareName}
Services: services.{ServiceName}
Infrastructure: infra.{ClientName}
Cache: cache.{CacheName}

3.2 记录日志

DEBUG 级别

// 缓存操作
logger.debug("缓存命中", { cacheKey: "user:123" });
logger.debug("缓存未命中", { cacheKey: "user:123" });

// 查询操作
logger.debug("获取用户列表", { page: 1, limit: 10, filters: { username: "test" } });

// 内部状态
logger.debug("初始化缓存服务", { provider: "RedisCache" });

INFO 级别

// 业务操作成功
logger.info("用户创建成功", { userId: 123, username: "testuser" });
logger.info("用户更新成功", { userId: 123 });
logger.info("用户删除成功", { userId: 123 });

// 关键流程节点
logger.info("用户登录成功", { userId: 123 });
logger.info("文件上传成功", { userId: 123, filename: "avatar.jpg" });
logger.info("SSE连接已建立", { userId: 123 });

WARN 级别

// 警告信息
logger.warn("访问次数超过限制", { userIp: "192.168.1.1", accessCount: 100 });
logger.warn("权限不足", { currentUserId: 123, targetUserId: 456 });
logger.warn("请求慢响应", { duration: 1500, url: "/api/users" });

ERROR 级别

// 错误异常
logger.error("获取用户列表失败", { error: err });
logger.error("用户创建失败", { error: err, payload: req.body });
logger.error("数据库查询失败", { error: err, sql: "SELECT * FROM users" });

3.3 日志级别选择

选择指南

何时使用 DEBUG：

缓存操作（命中/未命中/设置）
数据库查询操作
内部状态变化
详细的调试信息

何时使用 INFO：

业务操作成功（创建/更新/删除）
关键流程节点（登录/登出/上传）
重要状态变化（定时任务完成）

何时使用 WARN：

权限不足、访问限制
降级处理、非关键操作失败
慢请求（响应时间 > 1秒）
配置问题、参数验证警告

何时使用 ERROR：

系统错误、异常
操作失败（数据库查询失败、服务调用失败）
关键业务逻辑错误

避免记录大量数据

// ❌ 错误：记录完整列表数据
logger.debug("获取用户列表", { list: users }); // 列表可能很大

// ✅ 正确：只记录关键信息
logger.debug("获取用户列表", { page: 1, limit: 10, total: 100 });

// ❌ 错误：记录完整缓存数据
logger.debug("缓存命中", { cacheData: largeObject });

// ✅ 正确：只记录缓存键
logger.debug("缓存命中", { cacheKey: "user:123" });

4. 进阶使用

4.1 请求日志中间件

请求日志中间件自动记录所有 HTTP 请求的详细信息。

基本用法

const { createRequestLogger } = require("../logger");

// 创建请求日志中间件
app.use(
  createRequestLogger({
    moduleName: "http",
    logBody: true, // 是否记录请求体（默认 true）
    logHeaders: false, // 是否记录请求头（默认 false）
  })
);

配置选项

moduleName：模块名称（默认 "http"）
logBody：是否记录请求体（默认 true，GET 请求不记录）
logHeaders：是否记录请求头（默认 false）

自动日志级别

中间件会根据响应状态码和响应时间自动选择日志级别：

状态码 >= 500：ERROR 级别
状态码 >= 400：WARN 级别
响应时间 > 1秒：WARN 级别（慢请求）
其他：DEBUG 级别

日志内容

{
  "level": "debug",
  "message": "请求完成",
  "method": "POST",
  "url": "/api/users",
  "status_code": 200,
  "duration_ms": 150,
  "response_size": 1024,
  "response_time_category": "normal",
  "ip": "192.168.1.1",
  "userId": "123",
  "params": {},
  "query": {},
  "body": { "username": "testuser" }
}

4.2 错误日志中间件

错误日志中间件自动捕获和处理所有未处理的错误。

基本用法

const { createErrorLogger } = require("../logger");

// 创建错误日志中间件（放在路由之后）
app.use(createErrorLogger("error"));

日志内容

{
  "level": "error",
  "message": "Error occurred during request processing",
  "method": "POST",
  "url": "/api/users",
  "ip": "192.168.1.1",
  "userId": "123",
  "errorName": "ValidationError",
  "errorMessage": "用户名不能为空",
  "errorStack": "Error: 用户名不能为空\n    at ...",
  "statusCode": 400
}

4.3 请求 ID 追踪

请求 ID 追踪用于跨服务/请求的关联追踪。

基本用法

const requestIdMiddleware = require("../middlewares/requestIdMiddleware");

// 请求 ID 中间件（必须最先使用）
app.use(requestIdMiddleware);

工作原理

从请求头获取 X-Correlation-ID（如果存在）
如果不存在，自动生成新的 correlation_id
设置到 req.correlationId 和 global.correlationId
在响应头中添加 X-Correlation-ID

跨服务追踪

// 服务 A 发起请求
const correlationId = req.correlationId;
fetch("http://service-b/api/data", {
  headers: {
    "X-Correlation-ID": correlationId, // 传递 correlation_id
  },
});

// 服务 B 接收请求
// 自动从请求头获取 correlation_id，所有日志都会包含相同的 correlation_id
logger.info("处理请求", { correlationId: req.correlationId });

4.4 动态调整日志级别

可以在运行时动态调整日志级别。

全局级别

const { setGlobalLogLevel } = require("../logger");

// 设置全局日志级别
setGlobalLogLevel("warn"); // 只记录警告和错误

模块级别

const { setModuleLogLevel } = require("../logger");

// 设置特定模块的日志级别
setModuleLogLevel("controllers.userController", "debug");
setModuleLogLevel("models.userModel", "warn");

5. 架构设计

5.1 模块结构

src/logger/
├── index.js              # 入口文件，导出所有功能
├── enhanced-logger.js    # 增强日志（模块级别控制、调用方信息）
├── logger-core.js        # 核心功能（写盘、轮转、格式化）
├── data-masker.js        # 敏感信息脱敏
└── utils.js              # 工具函数（目录创建、ID生成等）

5.2 日志流程

应用代码
    ↓
getLogger(moduleName)
    ↓
logger.debug/info/warn/error()
    ↓
shouldLog() 检查级别
    ↓
logger-core.log() 格式化
    ↓
data-masker.maskObject() 脱敏
    ↓
writeLogToFile() 写入文件
    ↓
checkLogRotation() 检查轮转

5.3 日志轮转

自动轮转

当日志文件大小超过 10MB 时，自动进行轮转：

logs/output/2025-12-10.log (当前文件，10MB)
    ↓ 超过大小限制
logs/output/2025-12-10.log.1 (备份1)
logs/output/2025-12-10.log.2 (备份2)
...
logs/output/2025-12-10.log.5 (备份5，最旧的会被删除)

轮转配置

// config/base/logger.js
const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
const LOG_BACKUPS = 5; // 保留5个备份文件

6. 配置说明

6.1 基础配置

配置文件位置：config/base/logger.js

module.exports = {
  // 日志目录
  LOG_DIR: "./logs",
  ERROR_LOG_DIR: "./logs/error",
  OUTPUT_LOG_DIR: "./logs/output",

  // 默认日志级别
  DEFAULT_LOG_LEVEL: "info",

  // 文件配置
  MAX_LOG_SIZE: 10 * 1024 * 1024, // 10MB
  LOG_BACKUPS: 5, // 保留5个备份

  // 性能监控
  SLOW_REQUEST_THRESHOLD: 1000, // 1秒
};

6.2 模块级别配置

const MODULE_LOG_LEVELS = {
  default: "info", // 默认级别
  database: "warn", // 数据库模块
  api: "info", // API模块
  auth: "debug", // 认证模块（受全局限制）
  cache: "warn", // 缓存模块
};

6.3 脱敏配置

const SENSITIZATION_CONFIG = {
  enabled: true, // 全局脱敏开关
  rules: [
    {
      enabled: true,
      pattern: /"password":"([^"]*)"/g,
      replace: '"password":"******"',
    },
    // ... 其他规则
  ],
};

7. 最佳实践

✅ 推荐做法

统一使用结构化日志：所有日志都通过 logger 模块记录
合理选择日志级别：根据场景选择合适的级别
包含足够上下文：记录操作相关的用户ID、操作类型等
避免记录大量数据：只记录关键标识信息（ID、键名、数量等）
使用模块级别控制：为不同模块设置合适的日志级别
关联 ID 传递：跨服务调用时传递 correlation_id

❌ 避免做法

不要使用 console.log：使用 logger 模块统一记录
不要记录敏感信息：依赖自动脱敏，但也要注意不要记录未脱敏的数据
不要记录完整列表：只记录分页信息和总数
不要过度使用 DEBUG：生产环境应适当提高日志级别
不要忽略错误日志：所有错误都应该记录

8. 常见问题

Q1: 日志文件无法写入？

原因：

目录权限不足
磁盘空间不足

解决：

检查目录权限：ls -la ./logs
确保应用有写入权限：chmod -R 755 ./logs
检查磁盘空间：df -h

Q2: 日志级别不生效？

原因：

模块名称不匹配
全局级别限制

解决：

检查模块名称是否符合命名规范
检查全局日志级别是否限制了模块级别
查看配置是否正确加载

Q3: 敏感信息未脱敏？

原因：

字段名不在脱敏规则中
脱敏配置未启用

解决：

检查敏感字段是否包含在配置中
验证日志是否通过 logger 模块记录
检查 SENSITIZATION_CONFIG.enabled 是否为 true

Q4: 日志文件过大？

原因：

日志级别过低（DEBUG）
记录了大量数据

解决：

提高日志级别（生产环境使用 INFO 或 WARN）
减少记录的数据量
检查日志轮转是否正常工作

Q5: 如何查看日志？

方法：

查看错误日志：tail -f ./logs/error/2025-12-10.log
查看输出日志：tail -f ./logs/output/2025-12-10.log
搜索特定内容：grep "用户创建" ./logs/output/2025-12-10.log
按 correlation_id 追踪：grep "correlation_id.*abc123" ./logs/output/2025-12-10.log

日志是个好东西

1. 概述#

1.1 什么是日志模块#

核心特性#

1.2 为什么需要日志#

1.3 5分钟上手#

步骤 1：导入 Logger#

步骤 2：记录日志#

步骤 3：使用中间件（可选）#

2. 核心概念#

2.1 日志级别#

级别选择指南#

2.2 模块级别控制#

工作原理#

配置示例#

模块名称映射规则#

实际效果示例#

2.3 结构化日志#

关键字段说明#

2.4 敏感信息脱敏#

脱敏规则#

自动脱敏#

3. 基础使用#

3.1 获取 Logger 实例#

基本用法#

模块命名规范#

3.2 记录日志#

DEBUG 级别#

INFO 级别#

WARN 级别#

ERROR 级别#

3.3 日志级别选择#

选择指南#

避免记录大量数据#

4. 进阶使用#

4.1 请求日志中间件#

基本用法#

配置选项#

自动日志级别#

日志内容#

4.2 错误日志中间件#

基本用法#

日志内容#

4.3 请求 ID 追踪#

基本用法#

工作原理#

跨服务追踪#

4.4 动态调整日志级别#

全局级别#

模块级别#

5. 架构设计#

5.1 模块结构#

5.2 日志流程#

5.3 日志轮转#

自动轮转#

轮转配置#

6. 配置说明#

6.1 基础配置#

6.2 模块级别配置#

6.3 脱敏配置#

7. 最佳实践#

✅ 推荐做法#

❌ 避免做法#

8. 常见问题#

Q1: 日志文件无法写入？#

Q2: 日志级别不生效？#

Q3: 敏感信息未脱敏？#

Q4: 日志文件过大？#

Q5: 如何查看日志？#

1. 概述#

1.1 什么是日志模块#

核心特性#

1.2 为什么需要日志#

1.3 5分钟上手#

步骤 1：导入 Logger#

步骤 2：记录日志#

步骤 3：使用中间件（可选）#

2. 核心概念#

2.1 日志级别#

级别选择指南#

2.2 模块级别控制#

1. 概述

1.1 什么是日志模块

核心特性

1.2 为什么需要日志

1.3 5分钟上手

步骤 1：导入 Logger

步骤 2：记录日志

步骤 3：使用中间件（可选）

2. 核心概念

2.1 日志级别

级别选择指南

2.2 模块级别控制

工作原理

配置示例

模块名称映射规则

实际效果示例

2.3 结构化日志

关键字段说明

2.4 敏感信息脱敏

脱敏规则

自动脱敏

3. 基础使用

3.1 获取 Logger 实例

基本用法

模块命名规范

3.2 记录日志

DEBUG 级别

INFO 级别

WARN 级别

ERROR 级别

3.3 日志级别选择

选择指南

避免记录大量数据

4. 进阶使用

4.1 请求日志中间件

基本用法

配置选项

自动日志级别

日志内容

4.2 错误日志中间件

基本用法

日志内容

4.3 请求 ID 追踪

基本用法

工作原理

跨服务追踪

4.4 动态调整日志级别

全局级别

模块级别

5. 架构设计

5.1 模块结构

5.2 日志流程

5.3 日志轮转

自动轮转

轮转配置

6. 配置说明

6.1 基础配置

6.2 模块级别配置

6.3 脱敏配置

7. 最佳实践

✅ 推荐做法

❌ 避免做法

8. 常见问题

Q1: 日志文件无法写入？

Q2: 日志级别不生效？

Q3: 敏感信息未脱敏？

Q4: 日志文件过大？

Q5: 如何查看日志？

1. 概述

1.1 什么是日志模块

核心特性

1.2 为什么需要日志

1.3 5分钟上手

步骤 1：导入 Logger

步骤 2：记录日志

步骤 3：使用中间件（可选）

2. 核心概念

2.1 日志级别

级别选择指南

2.2 模块级别控制