kindergarten_java/docs/LOGBACK_CONFIG.md

# Logback 日志配置说明

## 配置位置

- **配置文件**: `reading-platform-java/src/main/resources/logback-spring.xml`
- **日志目录**: `logs/`（应用启动时自动创建）

---

## 日志滚动策略

### 保留策略
| 配置项 | 值 | 说明 |
|--------|-----|------|
| 保留天数 | 30 天 | 自动删除 30 天前的日志 |
| 单文件大小 | 100MB | 单个日志文件最大 100MB |
| 总大小上限 | 2GB | 所有日志文件总计不超过 2GB |

### 滚动规则
1. **按天滚动**: 每天生成一个新的日志文件
2. **按大小滚动**: 当单个文件超过 100MB 时自动切分
3. **自动清理**: 超过 30 天的日志自动删除
4. **总量控制**: 当日志总量达到 2GB 时，删除最旧的日志

---

## 日志文件分类

| 日志类型 | 文件名 | 说明 | 大小上限 |
|---------|--------|------|---------|
| 主日志 | `reading-platform.log` | 业务日志、系统日志 | 2GB |
| 错误日志 | `reading-platform-error.log` | 仅记录 ERROR 级别日志 | 500MB |
| 请求日志 | `reading-platform-request.log` | 所有 API 请求日志 | 500MB |
| SQL 日志 | `reading-platform-sql.log` | 仅记录慢 SQL 和错误 SQL | 300MB |

### 日志文件命名示例

```
logs/
├── reading-platform.log                    # 当前主日志
├── reading-platform.2026-03-26.1.log       # 按天滚动
├── reading-platform.2026-03-26.2.log       # 按大小滚动
├── reading-platform-error.log              # 当前错误日志
├── reading-platform-error.2026-03-26.1.log
├── reading-platform-request.log            # 当前请求日志
├── reading-platform-request.2026-03-26.1.log
└── reading-platform-sql.log                # 当前 SQL 日志
```

---

## 日志级别配置

### 生产环境 (prod)

| 日志类别 | 日志级别 | 输出目标 | 说明 |
|---------|---------|---------|------|
| 根日志 | INFO | FILE, ERROR_FILE | 基础日志级别 |
| 业务日志 | INFO | FILE | `com.reading.platform` 包 |
| **请求日志** | **INFO** | **REQUEST_FILE** | **所有 API 请求单独输出** |
| **SQL 日志** | **WARN** | **SQL_FILE** | **仅记录慢 SQL 和错误 SQL** |
| Spring 框架 | WARN | - | 框架日志 |

### 开发环境 (dev)

| 日志类别 | 日志级别 | 说明 |
|---------|---------|------|
| 业务日志 | DEBUG | 详细业务日志 |
| 请求日志 | INFO | 所有 API 请求单独输出 |
| SQL 日志 | DEBUG | 全量 SQL 日志 |

---

## 请求日志格式

每个 API 请求会记录以下信息：

```
===== 请求开始 =====
接口地址：POST /api/v1/teacher/courses
请求方法：com.reading.platform.controller.teacher.CourseController.createCourse
请求参数：{"name":"新课程","gradeId":1}
响应时间：156ms
响应结果：{"code":"SUCCESS","data":123}
===== 请求结束 =====
```

异常请求：

```
===== 请求异常 =====
接口地址：POST /api/v1/teacher/courses
执行时间：45ms
异常信息：参数校验失败
异常类型：com.reading.platform.common.exception.BusinessException
堆栈信息：...
===== 请求异常结束 =====
```

---

## SQL 日志策略

### 生产环境（推荐）

**只记录慢 SQL 和错误 SQL**，通过设置 `WARN` 级别实现：
- `DEBUG` 级别：所有 SQL（开发环境）
- `INFO` 级别：SQL 摘要（测试环境）
- `WARN` 级别：**仅慢 SQL 和错误 SQL**（生产环境）
- `ERROR` 级别：仅错误 SQL

### 慢 SQL 配置（可选）

如需记录执行时间超过指定阈值的 SQL，可在 MyBatis-Plus 配置中设置：

```yaml
# application-prod.yml
mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
```

---

## 常用命令

### 查看实时请求日志
```bash
tail -f logs/reading-platform-request.log
```

### 查看实时错误日志
```bash
tail -f logs/reading-platform-error.log
```

### 查看实时 SQL 日志
```bash
tail -f logs/reading-platform-sql.log
```

### 查看指定日期的日志
```bash
cat logs/reading-platform-request.2026-03-26.1.log
```

### 搜索特定接口日志
```bash
grep "/api/v1/teacher/courses" logs/reading-platform-request.*.log
```

### 搜索错误日志
```bash
grep "ERROR" logs/reading-platform-error.log
```

### 查看日志目录大小
```bash
du -sh logs/
```

### 手动清理日志（可选）
```bash
# 删除 7 天前的日志
find logs/ -name "*.log" -mtime +7 -delete
```

---

## 配置修改

### 调整日志保留天数

修改 `logback-spring.xml`：
```xml
<property name="LOG_MAX_HISTORY" value="30"/>  <!-- 修改这里的数字 -->
```

### 调整单个文件大小限制

```xml
<property name="LOG_MAX_FILE_SIZE" value="100MB"/>  <!-- 修改文件大小 -->
```

### 调整总日志大小上限

```xml
<property name="LOG_TOTAL_CAP" value="2GB"/>  <!-- 修改总大小 -->
```

### 修改后重启服务

```bash
cd /www/wwwroot/reading-platform
./stop.sh
./start.sh
```

---

## 环境切换

### 开发环境
```bash
export SPRING_PROFILES_ACTIVE=dev
java -jar reading-platform.jar
```

### 生产环境
```bash
export SPRING_PROFILES_ACTIVE=prod
java -jar reading-platform.jar
```

---

## 注意事项

1. **请求日志独立输出**: 所有 API 请求日志输出到 `request.log`，不影响主日志
2. **SQL 日志精简**: 生产环境仅记录 WARN 和 ERROR 级别 SQL，避免日志爆炸
3. **错误日志单独记录**: 所有 ERROR 级别日志输出到 `error.log`，便于问题排查
4. **日志目录权限**: 确保 `logs` 目录有写权限（chmod 755）
5. **磁盘空间监控**: 建议设置磁盘告警，当日志目录接近总上限时收到通知

---

## 故障排查

### 请求日志不输出
- 检查 `RequestLogAspect` 切面是否生效
- 确认日志级别配置为 `INFO`
- 检查 `additivity="false"` 是否配置

### SQL 日志不输出
- 生产环境只记录 WARN 和 ERROR 级别（慢 SQL 和错误 SQL）
- 如需查看全量 SQL，临时改为 `DEBUG` 级别

### 日志文件丢失
- 检查是否达到 `maxHistory`（30 天）
- 检查是否达到 `totalSizeCap`（总大小上限）

---

**配置日期**: 2026-03-26
**最后更新**: 2026-03-26