# media-server

**Repository Path**: huangRZ/media-server

## Basic Information

- **Project Name**: media-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 流媒体服务器

基于zlm4j和Spring Boot 3.x构建的高性能流媒体服务器，支持RTMP/RTSP/HLS/HTTP-FLV协议的流接入与分发。

## 核心特性

- ✅ **多协议支持**：RTMP/RTSP/HLS/HTTP-FLV协议的流接入与分发
- ✅ **RESTful API**：完整的流管理API（开始/停止/查询流状态）
- ✅ **Webhook事件**：实时接收流媒体服务的关键事件通知
- ✅ **按需转码**：基于FFmpeg的流转码功能
- ✅ **安全控制**：Token鉴权、IP白名单机制
- ✅ **容器化部署**：Docker支持，一键部署
- ✅ **性能优化**：支持高并发、低延迟的流媒体传输

## 技术栈

- **Spring Boot 3.2.x**：现代化Java应用框架
- **zlm4j**：ZLMediaKit的Java封装库
- **FFmpeg**：音视频转码工具
- **Swagger/OpenAPI 3.0**：API文档生成
- **Docker**：容器化部署

## 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.6+
- FFmpeg 4.0+
- zlm4j库（需要手动获取并安装到本地Maven仓库）

### 2. 安装zlm4j库

由于zlm4j库在公共Maven仓库中不可用，需要手动获取并安装到本地Maven仓库：

```bash
# 克隆zlm4j仓库
git clone <zlm4j-repository-url>
cd zlm4j

# 编译并安装到本地Maven仓库
mvn clean install -DskipTests
```

### 3. 编译构建

```bash
# 克隆代码
git clone <repository-url>
cd media-server

# 编译打包
mvn clean package -DskipTests
```

### 3. 运行应用

```bash
# 直接运行
java -jar target/media-server-1.0.0.jar

# 或使用环境变量配置
java -jar target/media-server-1.0.0.jar --zlm4j.rtmp.port=1935 --zlm4j.http.port=8080
```

### 4. Docker部署

```bash
# 构建Docker镜像
docker build -t media-server:1.0.0 .

# 运行Docker容器
docker run -d \
  --name media-server \
  -p 8080:8080 \
  -p 1935:1935 \
  -p 554:554 \
  -p 80:80 \
  -v /path/to/media:/app/media \
  -v /path/to/logs:/app/logs \
  media-server:1.0.0
```

## 配置说明

主要配置文件位于 `src/main/resources/application.yml`，核心配置项说明：

### zlm4j 核心配置

```yaml
zlm4j:
  core:
    maxConnections: 1000     # 最大并发连接数
    workThreads: 4          # 工作线程数
    streamTimeout: 30       # 流超时时间（秒）
    mediaRoot: ./media      # 媒体文件目录
    logLevel: info          # 日志级别
```

### 协议配置

```yaml
zlm4j:
  rtmp:
    enabled: true
    port: 1935
  rtsp:
    enabled: true
    port: 554
  http:
    enabled: true
    port: 80
  hls:
    enabled: true
    fragmentDuration: 3     # HLS分片时长（秒）
    windowSize: 3          # HLS窗口大小
```

### 安全配置

```yaml
zlm4j:
  security:
    tokenAuthEnabled: true
    tokenExpire: 3600       # Token过期时间（秒）
    tokenSecret: "your-secret-key"
    ipWhitelistEnabled: false
    ipWhitelist:
      - "127.0.0.1"
      - "192.168.1.0/24"
```

### 转码配置

```yaml
zlm4j:
  transcode:
    enabled: true
    ffmpegPath: /usr/bin/ffmpeg
    defaultParams: "-c:v libx264 -preset ultrafast -c:a aac -b:v 500k -b:a 64k"
```

## API文档

启动服务后，可通过以下地址访问API文档：

- Swagger UI: `http://localhost:8080/swagger-ui.html`
- OpenAPI JSON: `http://localhost:8080/v3/api-docs`

### 核心API

| API路径 | 方法 | 描述 |
|---------|------|------|
| `/api/v1/streams/push` | POST | 开始推流 |
| `/api/v1/streams/push/{app}/{streamId}` | DELETE | 停止推流 |
| `/api/v1/streams/{app}/{streamId}/status` | GET | 查询流状态 |
| `/api/v1/streams` | GET | 获取所有流列表 |
| `/api/v1/streams/transcode` | POST | 开始转码 |
| `/api/v1/streams/transcode/{app}/{streamId}` | DELETE | 停止转码 |
| `/api/v1/streams/{app}/{streamId}/play-url` | GET | 获取播放地址 |

## Webhook事件

服务器会向配置的Webhook地址发送以下事件：

- `pushStreamStart`：推流开始
- `pushStreamStop`：推流停止
- `playStreamStart`：播放开始
- `playStreamStop`：播放停止
- `recordComplete`：录制完成
- `transcodeComplete`：转码完成
- `streamTimeout`：流超时
- `streamException`：流异常

## 性能调优

### JVM参数调优

推荐的JVM参数配置：

```bash
JAVA_OPTS="-Xms4g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+ParallelRefProcEnabled -XX:+DisableExplicitGC -XX:InitiatingHeapOccupancyPercent=35"
```

### 系统参数调优

```bash
# 增加文件描述符限制
ulimit -n 65535

# 优化网络参数
sysctl -w net.core.somaxconn=65535
sysctl -w net.ipv4.tcp_max_syn_backlog=65535
sysctl -w net.ipv4.tcp_fin_timeout=30
sysctl -w net.ipv4.tcp_tw_reuse=1
sysctl -w net.ipv4.tcp_tw_recycle=1
```

## 监控与运维

### 健康检查

- 健康检查接口：`http://localhost:8080/actuator/health`
- 指标监控：`http://localhost:8080/actuator/metrics`
- Prometheus监控：`http://localhost:8080/actuator/prometheus`

### 日志管理

日志文件默认位于 `logs/media-server.log`，可通过配置调整日志级别和路径。

## 测试

```bash
# 运行单元测试
mvn test

# 运行集成测试
mvn integration-test

# 代码覆盖率
mvn jacoco:report
```

## 开发指南

### 代码结构

```
src/main/java/com/example/mediaserver/
├── config/          # 配置类
├── controller/      # API控制器
├── service/         # 业务逻辑
│   └── impl/        # 具体实现
├── model/           # 数据模型
├── webhook/         # Webhook事件处理
├── security/        # 安全模块
└── MediaServerApplication.java # 应用入口
```

### 扩展开发

1. **添加新协议支持**：在 `service` 包中实现新的协议处理逻辑
2. **自定义事件处理**：在 `webhook` 包中扩展 `WebhookHandler` 接口
3. **添加新的安全策略**：在 `security` 包中实现新的安全验证逻辑

## 许可证

MIT License

## 联系方式

- 项目地址：<repository-url>
- 问题反馈：<issue-url>
- 技术交流：<contact-info>