# log-stream-spring-boot-starter

**Repository Path**: kuke1363/log-stream-spring-boot-starter

## Basic Information

- **Project Name**: log-stream-spring-boot-starter
- **Description**: SSE推送后台日志到前端
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Log Stream Spring Boot Starter

基于 Spring Boot 的日志流式推送组件，通过 SSE (Server-Sent Events) 实时推送日志到前端页面。

## 功能特性

- **实时日志推送**：通过 SSE 机制实时将后端日志推送到前端
- **自动配置**：基于 Spring Boot Starter 自动配置，开箱即用
- **历史日志缓冲**：支持配置历史日志缓存数量，新连接可获取最近日志
- **日志级别过滤**：支持配置只推送指定级别的日志
- **高性能队列**：使用阻塞队列实现异步日志处理

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.example</groupId>
    <artifactId>log-stream-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 配置参数

在 `application.yml` 中添加配置：

```yaml
log:
  stream:
    enabled: true
    path: /logs/stream
    queue-capacity: 10000
    history-size: 100
    includeLevels: INFO, WARN, ERROR
```

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| enabled | 是否启用日志流功能 | true |
| path | SSE 端点路径 | /logs/stream |
| queue-capacity | 日志队列容量 | 10000 |
| history-size | 历史日志缓存数量 | 100 |
| includeLevels | 接收的日志级别 | INFO, WARN, ERROR |

### 3. 前端接入

```javascript
const eventSource = new EventSource('/logs/stream');

eventSource.onmessage = function(event) {
    const log = JSON.parse(event.data);
    console.log(`[${log.timestamp}] [${log.level}] ${log.message}`);
    
    // 将日志展示到页面
    const logElement = document.createElement('div');
    logElement.textContent = `[${log.timestamp}] [${log.level}] ${log.message}`;
    document.getElementById('log-container').appendChild(logElement);
};

eventSource.onerror = function() {
    console.log('连接断开，尝试重新连接...');
    eventSource.close();
    setTimeout(() => {
        eventSource = new EventSource('/logs/stream');
    }, 3000);
};
```

## 工作原理

```
┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ Logback     │────▶│ SseLogAppender  │────▶│ LogBroadcastBroker│
│ 日志输出    │     │ (日志拦截器)     │     │ (日志广播器)      │
└─────────────┘     └─────────────────┘     └────────┬─────────┘
                                                     │
                                    ┌────────────────┼────────────────┐
                                    │                │                │
                              ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
                              │ Client 1  │   │ Client 2  │   │ Client N  │
                              │ (SSE)     │   │ (SSE)     │   │ (SSE)     │
                              └───────────┘   └───────────┘   └───────────┘
```

1. **日志拦截**：通过 Logback 的 `SseLogAppender` 拦截应用日志
2. **队列缓冲**：日志事件进入阻塞队列，实现异步处理
3. **广播分发**：`LogBroadcastBroker` 将日志广播给所有连接的客户端
4. **SSE 推送**：通过 Spring MVC 的 `SseEmitter` 向前端推送日志

## 核心组件

### LogStreamAutoConfiguration

自动配置类，会在 classpath 存在 Spring MVC 和 Logback 时自动配置。

### LogBroadcastBroker

日志广播器，负责：
- 管理 SSE 连接
- 维护历史日志缓存
- 将日志广播给所有连接的客户端

### SseLogAppender

Logback 自定义 appender，将日志事件发送到广播器。

### LogStreamController

提供 SSE 端点，支持跨域访问。

## 注意事项

1. 前端使用 `EventSource` 接收日志，注意处理连接断开和重连
2. 根据实际需求调整 `queue-capacity` 和 `history-size` 参数
3. 生产环境建议配置合适的日志级别，避免日志量过大

## 许可证

MIT License