# 日志系统使用说明

## 概述

本项目集成了完整的日志系统，基于Spring Boot + Logback实现，提供了多层次的日志记录和管理功能。

## 日志配置

### 配置文件位置
- 主配置文件：`src/main/resources/logback-spring.xml`
- 应用配置：`src/main/resources/application.yml`

### 日志文件存储位置
- 根目录：`logs/`
- 系统信息日志：`logs/sys-info.log`
- 系统错误日志：`logs/sys-error.log`
- 相机操作日志：`logs/camera.log`
- 二维码识别日志：`logs/qrcode.log`
- 定时任务日志：`logs/schedule.log`

### 日志轮转策略
- 单个文件最大大小：100MB
- 保留历史文件：30天
- 总大小限制：3GB（系统日志）、1GB（相机日志）、500MB（其他日志）

## 日志级别

- **DEBUG**: 详细的调试信息，主要在开发环境使用
- **INFO**: 一般信息，记录重要的业务流程
- **WARN**: 警告信息，不影响程序运行但需要注意
- **ERROR**: 错误信息，程序发生异常或错误

## 使用方式

### 1. 使用Lombok注解

```java
@Slf4j
@Service
public class YourService {
    public void yourMethod() {
        log.info("这是一条信息日志");
        log.error("这是一条错误日志", exception);
    }
}
```

### 2. 使用LogUtil工具类

LogUtil提供了更丰富的日志记录方法：

```java
// 相机操作日志
LogUtil.logCameraStart("camera001", "captureImage");
LogUtil.logCameraSuccess("camera001", "captureImage", 1500);
LogUtil.logCameraError("camera001", "captureImage", "连接超时");

// 二维码识别日志
LogUtil.logQRCodeStart("image.jpg", "complexDecode");
LogUtil.logQRCodeSuccess("image.jpg", "QR123456", 800);
LogUtil.logQRCodeError("image.jpg", "无法识别二维码", 1200);

// 定时任务日志
LogUtil.logScheduleTask("清理任务", "START", "开始执行清理任务");
LogUtil.logScheduleTask("清理任务", "SUCCESS", "清理完成，删除了50个文件");

// API请求日志（自动记录）
// 通过LogAspect切面自动记录所有Controller的请求和响应

// 性能监控
LogUtil.logPerformance("复杂计算", 5000, 2000); // 超过阈值会记录警告

// 业务日志
LogUtil.logBusiness("INFO", "OrderService", "订单{}创建成功", orderId);
```

### 3. 异常处理

```java
try {
    // 业务逻辑
} catch (Exception e) {
    LogUtil.logSystemException("UserService", "createUser", e);
    // 或
    log.error("用户创建失败", e);
}
```

## API接口

系统提供了日志管理的REST API：

### 1. 获取日志文件列表
```
GET /api/logs/files
```

### 2. 下载日志文件
```
GET /api/logs/download/{fileName}
```

### 3. 查看日志内容
```
GET /api/logs/view/{fileName}?lines=100
```

### 4. 清理日志文件
```
DELETE /api/logs/clear?keepDays=7
```

## 最佳实践

### 1. 日志级别使用建议
- **生产环境**: INFO级别，关闭DEBUG
- **测试环境**: DEBUG级别，便于问题排查
- **开发环境**: DEBUG级别，详细记录

### 2. 日志内容规范
- 包含关键业务标识（如用户ID、订单号、设备ID）
- 记录操作耗时，便于性能分析
- 异常日志要包含完整的堆栈信息
- 避免记录敏感信息（密码、密钥等）

### 3. 性能考虑
- 避免在循环中频繁记录日志
- 大对象日志要谨慎，可能影响性能
- 合理使用日志级别，避免不必要的字符串拼接

## 日志分析

### 1. 常用日志查询
```bash
# 查看相机错误日志
grep "ERROR" logs/camera.log

# 查看特定相机的操作记录
grep "camera001" logs/camera.log

# 查看超时的请求
grep "超过阈值" logs/sys-info.log
```

### 2. 日志监控
可以结合ELK、Graylog等日志分析工具进行实时监控和告警。

## 故障排查

### 1. 日志文件过大
- 检查日志级别设置
- 使用清理API定期清理旧日志
- 调整logback-spring.xml中的轮转参数

### 2. 日志无法记录
- 检查logs目录权限
- 确认logback配置正确
- 查看应用启动日志是否有配置错误

### 3. 性能问题
- 减少DEBUG级别日志
- 优化高频调用的日志记录
- 考虑异步日志配置

## 扩展配置

如需添加新的日志分类，在`logback-spring.xml`中添加：

```xml
<!-- 新的日志分类 -->
<appender name="custom_log" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${log.path}/custom.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
        <fileNamePattern>${log.path}/custom.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
        <maxFileSize>50MB</maxFileSize>
        <maxHistory>15</maxHistory>
    </rollingPolicy>
    <encoder>
        <pattern>${log.pattern}</pattern>
        <charset>UTF-8</charset>
    </encoder>
</appender>

<logger name="com.example.lxcameraapi.your.package" level="INFO" additivity="false">
    <appender-ref ref="custom_log"/>
    <appender-ref ref="console"/>
</logger>
```