eafonyang
37 lines
2.3 KiB
Markdown
37 lines
2.3 KiB
Markdown
---
|
|
kind: logging_system
|
|
name: 后端日志系统（Winston 双输出）
|
|
category: logging_system
|
|
scope:
|
|
- '**'
|
|
source_files:
|
|
- backend/src/config/logger.js
|
|
- backend/logs/app.log
|
|
- backend/src/app.js
|
|
---
|
|
|
|
## 1. 使用的系统与框架
|
|
- 后端采用 Winston 作为统一日志框架，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
|
|
- 前端未引入独立日志库，主要依赖浏览器控制台与网络请求拦截器进行调试。
|
|
|
|
## 2. 核心文件与位置
|
|
- backend/src/config/logger.js — Winston 初始化、格式与传输配置
|
|
- backend/logs/app.log — 应用运行期日志落盘文件
|
|
- backend/src/app.js — 启动阶段 DB 建表、服务监听等关键流程的日志埋点
|
|
- 各路由/配置模块（如 routes/auth.js、config/redis.js）按需 require('./config/logger') 使用
|
|
|
|
## 3. 架构与约定
|
|
- 单例 logger：所有模块共享同一 Winston logger 实例，避免重复配置。
|
|
- 输出目标：同时写入 Console 和 File，文件路径固定为 backend/logs/app.log，编码 UTF-8。
|
|
- 时间戳格式：YYYY-MM-DD HH:mm:ss。
|
|
- 日志级别：默认 level 为 info，业务中广泛使用 info/warn/error，未见 debug 级别使用。
|
|
- 结构化字段：通过 printf 将 message 与 meta 对象拼接成一行文本；meta 存在时以 JSON 字符串追加在消息末尾。
|
|
- 数据库层日志：Sequelize 在开发环境开启 SQL 语句打印到 console，生产环境关闭。
|
|
- 历史兼容痕迹：早期日志中存在 Python 风格（sqlalchemy.engine.Engine、__main__）记录，说明项目曾混用 Python 组件，当前 Node 端已统一到 Winston。
|
|
|
|
## 4. 开发者应遵循的规则
|
|
- 统一从 ./config/logger 引入 logger，不要直接调用 console.log 输出业务日志。
|
|
- 优先使用 logger.info 记录正常业务流程，logger.warn 记录可恢复异常或降级场景，logger.error 记录错误堆栈或失败原因。
|
|
- 需要附带上下文信息时，以第三个参数传入对象（会被序列化为 JSON 附加到行尾），便于后续解析。
|
|
- 敏感信息（密码、token、完整请求体）不应直接写入日志，必要时脱敏后再记录。
|
|
- 如需新增日志输出目标（如按天分片、接入远程收集），应在 backend/src/config/logger.js 中集中扩展 transports，保持全局一致。 |