系统 Logger 配置 - Xpert AI

概览
配置项
输出行为
控制台
文件
轮转规则
请求元数据与安全处理
启动集成方式
推荐配置示例
相关源码

本文说明后端系统 logger 的配置方式，以及各个配置项在运行时会影响什么行为。

概览

当前 logger 基于 nestjs-pino 和 pino 实现。

HTTP 请求日志和 Nest 应用日志会走同一套 logger 管线。
日志会同时输出到控制台和轮转文件。
非生产环境下，控制台日志会通过 pino-pretty 做可读化格式化。
生产环境下，控制台会保持结构化 JSON 输出到 stdout。
默认日志文件名为 xpert-server.log。

配置项

变量	默认值	说明
`NODE_ENV`	`development`	控制控制台输出格式。`production` 时输出 JSON 到 `stdout`；其他环境使用单行可读格式。
`LOG_LEVEL`	`log`	基础日志级别。Nest 风格级别会映射为 pino 级别：`verbose -> trace`、`debug -> debug`、`log -> info`、`warn -> warn`、`error -> error`、`fatal -> fatal`。也可以直接使用 `trace`、`info`、`fatal`、`silent` 等 pino 级别。
`LOG_FILE_PATH`	未设置	当前日志文件的完整路径。设置后优先级高于 `LOG_DIR`。
`LOG_DIR`	`<process.cwd()>/logs`	在未设置 `LOG_FILE_PATH` 时使用的日志目录，当前文件名固定为 `xpert-server.log`。
`LOG_FILE_MAX_SIZE`	`10m`	当前日志文件达到该大小后触发轮转。支持单位：`b`、`k`、`kb`、`m`、`mb`、`g`、`gb`。
`LOG_FILE_MAX_FILES`	`5`	保留的日志文件总数，包含当前活跃文件。

输出行为

控制台

NODE_ENV=production：原样输出 JSON 日志到 stdout。
其他环境：日志会带颜色、压成单行，并附带可读时间格式。

文件

文件日志始终是结构化 JSON。
如果目标目录不存在，logger 会自动创建目录。
日志文件以追加模式打开，服务重启后会继续写入当前活跃文件。
路径解析优先级为：LOG_FILE_PATH -> LOG_DIR/xpert-server.log -> <process.cwd()>/logs/xpert-server.log。

轮转规则

当下一次写入会让当前文件超过 LOG_FILE_MAX_SIZE 时，先轮转再写入。
轮转后的文件命名为 xpert-server.log.1、xpert-server.log.2 等。
LOG_FILE_MAX_FILES=5 表示保留 1 个当前文件和 4 个历史备份。
LOG_FILE_MAX_FILES=1 表示不保留备份，每次轮转都会直接替换当前文件。

请求元数据与安全处理

每条请求日志会附加以下字段：

service: xpert-server
env
traceparent
tracestate

同时会启用以下保护逻辑：

仅当请求头中的 x-request-id 是合法 UUID 时才复用。
如果请求没有提供合法 request id，会自动生成新的 UUID。
最终 request id 会回写到响应头 x-request-id。
/health 和 /api/health 的自动访问日志会被忽略。
敏感字段会被替换为 [Redacted]。

当前脱敏字段包括：

req.headers.authorization
req.headers.cookie
req.headers["x-api-key"]
req.body.password
req.body.token
req.body.accessToken
req.body.refreshToken

启动集成方式

logger 在 Nest 启动阶段接入：

providePinoLoggerModule() 注册 pino HTTP logger。
app.useLogger(app.get(Logger)) 让 Nest 使用基于 pino 的 logger。
NestLogger.overrideLogger(resolveNestLogLevels()) 让 Nest 内部日志级别与 LOG_LEVEL 保持一致。

这意味着框架日志和请求日志都会受到同一套配置控制。

推荐配置示例

按目录配置日志输出：

NODE_ENV=production
LOG_LEVEL=info
LOG_DIR=/var/log/xpert
LOG_FILE_MAX_SIZE=50m
LOG_FILE_MAX_FILES=7

按固定文件路径配置：

NODE_ENV=production
LOG_LEVEL=debug
LOG_FILE_PATH=/var/log/xpert/xpert-server.log
LOG_FILE_MAX_SIZE=100m
LOG_FILE_MAX_FILES=10

设置了 LOG_FILE_PATH 之后，LOG_DIR 会被忽略。

相关源码

xpert/packages/server/src/logger/pino-logger.ts
xpert/packages/server/src/logger/pino-rotating-file.stream.ts
xpert/packages/config/src/environments/ienvironment.ts
xpert/packages/server/src/bootstrap/index.ts

环境 GitHub 配置