> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 系统 Logger 配置

本文说明后端系统 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` 保持一致。

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

## 推荐配置示例

按目录配置日志输出：

```bash theme={null}
NODE_ENV=production
LOG_LEVEL=info
LOG_DIR=/var/log/xpert
LOG_FILE_MAX_SIZE=50m
LOG_FILE_MAX_FILES=7
```

按固定文件路径配置：

```bash theme={null}
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`