47 lines
3.0 KiB
Markdown
47 lines
3.0 KiB
Markdown
|
---
|
|||
|
|
kind: logging_system
|
|||
|
|
name: 基于 Winston 的日志系统
|
|||
|
|
category: logging_system
|
|||
|
|
scope:
|
|||
|
|
- '**'
|
|||
|
|
source_files:
|
|||
|
|
- backend/src/config/logger.js
|
|||
|
|
- backend/src/app.js
|
|||
|
|
- backend/src/config/database.js
|
|||
|
|
- backend/package.json
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 使用的系统与框架
|
|||
|
|
- 后端采用 **Winston v3** 作为统一日志框架，通过 `backend/src/config/logger.js` 集中创建并导出单例 logger。
|
|||
|
|
- 前端（Vue3）未发现专用日志库，未在前端代码中引入结构化日志输出。
|
|||
|
|
- Sequelize 在开发环境将 SQL 查询直接 `console.log` 到控制台，生产环境关闭 SQL 日志。
|
|||
|
|
|
|||
|
|
## 2. 核心文件与包
|
|||
|
|
- `backend/src/config/logger.js` — Winston 实例定义、格式与传输配置
|
|||
|
|
- `backend/src/app.js` — 应用启动时记录数据库同步、服务监听等关键事件
|
|||
|
|
- `backend/package.json` — 依赖声明 `winston: ^3.14`
|
|||
|
|
- `backend/logs/app.log` — 默认文件日志输出路径
|
|||
|
|
- `backend/src/config/database.js` — Sequelize 的 `logging` 开关逻辑
|
|||
|
|
|
|||
|
|
## 3. 架构与约定
|
|||
|
|
- **单例导出**：`logger.js` 使用 `winston.createLogger()` 创建全局 logger，并通过 `module.exports = logger` 供各模块 `require('../config/logger')` 复用。
|
|||
|
|
- **日志级别**：全局默认 level 为 `info`；业务代码中使用 `logger.info / warn / error` 三个级别，未见 `debug` 调用。
|
|||
|
|
- **输出格式**：时间戳 + 级别 + 消息 + 可选 JSON meta 字段，形如：
|
|||
|
|
```
|
|||
|
|
2026-06-09 12:34:56 - info - User admin logged in {}
|
|||
|
|
```
|
|||
|
|
- **双通道输出**：同时写入 Console 和文件 `backend/logs/app.log`，编码 UTF-8。
|
|||
|
|
- **无按级别/日期分片**：当前仅一个 `app.log` 文件，未启用 `FileTransport` 的 `maxsize`、`maxFiles`、`filename` 模板等滚动策略。
|
|||
|
|
- **Sequelize SQL 日志**：仅在 `isDevelopment` 时开启，输出到 `console.log`，不经过 Winston。
|
|||
|
|
- **中间件层**：未集成 Express 请求日志中间件（如 `morgan`），HTTP 访问日志未统一采集。
|
|||
|
|
|
|||
|
|
## 4. 开发者应遵循的规则
|
|||
|
|
- **统一入口**：所有日志必须通过 `const logger = require('../config/logger')` 获取，禁止直接使用 `console.log` 输出业务日志。
|
|||
|
|
- **级别选择**：
|
|||
|
|
- `info`：正常业务流程事件（登录成功、密码修改、数据操作完成等）
|
|||
|
|
- `warn`：可恢复异常或潜在问题（登录失败、参数校验警告等）
|
|||
|
|
- `error`：不可恢复错误（数据库异常、外部服务调用失败等）
|
|||
|
|
- **结构化字段**：通过第三个参数传入对象以附加上下文，例如 `logger.warn({ username, ip }, 'Login failed')`，该对象会被序列化为 JSON 追加到消息末尾。
|
|||
|
|
- **敏感信息**：避免在日志中记录明文密码、完整 token 等敏感内容。
|
|||
|
|
- **SQL 调试**：如需查看底层 SQL，确保环境变量处于开发模式以使 Sequelize logging 生效；生产环境应保持关闭以避免性能损耗。
|
|||
|
|
- **日志轮转**：当前未配置自动轮转，部署时应配合外部工具（如 `logrotate`、Docker log driver）管理 `backend/logs/app.log` 大小。
|