# rtsp-service

**Repository Path**: ZhangALiang/rtsp-service

## Basic Information

- **Project Name**: rtsp-service
- **Description**: rtsp推流转发+验签
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RTSP to HLS Streaming Service

This project converts an RTSP stream to HLS format for browser playback, with HTTPS support.

## 服务监控

为了保证服务的稳定性，我们提供了外部看门狗程序来监控服务状态：

### Python看门狗程序

我们提供了一个独立的Python脚本(`service_watchdog.py`)来监控RTSP服务是否正常运行：

- 定期检查服务状态（默认每30秒检查一次）
- 检测服务状态变化（在线/离线）
- 支持钉钉告警通知
- 日志记录功能

### 结论

我们已经实现了一个完整的监控解决方案，具有以下特点：

1. **灵活的监控控制**：通过Web管理界面可以动态启用或禁用任务监控，避免不必要的告警
2. **安全的钉钉集成**：支持钉钉机器人的timestamp和sign签名验证，确保告警消息的安全性
3. **容器化部署**：提供了完整的Docker和docker-compose配置，简化部署过程
4. **开机自启动**：在Linux系统上支持通过systemd配置开机自启动
5. **易于维护**：所有配置都通过环境变量管理，便于不同环境的部署和维护

### 使用方法

1. 直接运行（使用默认配置）：
   ```bash
   python3 service_watchdog.py
   ```

2. 通过环境变量配置运行：
   ```bash
   export SERVICE_URL=http://your-server-ip:port
   export DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=your_token
   export DINGTALK_SECRET=your_secret_key  # 钉钉加签密钥（可选）
   export CHECK_INTERVAL=60
   python3 service_watchdog.py
   ```

3. 后台运行：
   ```bash
   nohup python3 service_watchdog.py > service_watchdog.log 2>&1 &
   ```

### 配置参数

- `SERVICE_URL`: RTSP服务地址（默认http://127.0.0.1:8090）
- `DINGTALK_WEBHOOK`: 钉钉Webhook URL（可选）
- `DINGTALK_SECRET`: 钉钉加签密钥（可选，用于安全验证）
- `CHECK_INTERVAL`: 检查间隔秒数（默认30秒）

### 任务监控开关

为了更灵活地控制告警，我们为每个任务提供了独立的监控开关：

1. 在启动任务时可以通过`enableMonitoring`参数控制是否启用监控：
   ```bash
   curl -X POST "http://localhost:8090/stream/start?filename=test&rtspUrl=rtsp://your-url&enableMonitoring=true"
   ```

2. 通过管理页面可以动态控制任务的监控状态：
   - 访问管理页面：http://localhost:8090/manager
   - 在任务列表中点击"启用监控"或"禁用监控"按钮来切换监控状态

3. 只有启用监控的任务在出现异常时才会发送钉钉告警，未启用监控的任务即使出现异常也不会发送告警

## 目录

- [RTSP协议简介](#rtsp协议简介)
- [HLS协议简介](#hls协议简介)
- [为什么需要RTSP到HLS的转换](#为什么需要rtsp到hls的转换)
- [项目概述](#项目概述)
- [核心功能](#核心功能)
- [项目架构](#项目架构)
- [整体流程](#整体流程)
  - [启动流程](#启动流程)
  - [监听与转换流程](#监听与转换流程)
  - [关闭流程](#关闭流程)
- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [使用说明](#使用说明)
- [部署](#部署)

## RTSP协议简介

RTSP（Real Time Streaming Protocol）是一种网络应用协议，专门用于控制实时流媒体数据的传输。它提供了一种可扩展、多功能、可定制的流媒体传输控制方式，广泛应用于互联网直播、视频监控、远程教育等领域。

RTSP协议的主要功能包括：

*   **流媒体播放控制**：允许客户端对流媒体资源进行播放、暂停、停止、快进、快退等操作。
*   **多媒体会话管理**：支持多个媒体流（如音频、视频）的同步传输和播放。
*   **音视频同步**：与RTP（Real-time Transport Protocol）和RTCP（Real-time Transport Control Protocol）协议协同工作，实现音视频数据的实时传输和同步。

RTSP协议的工作原理是基于客户端与服务器之间的消息应答机制。客户端通过发送RTSP请求来控制媒体流的传送，如播放、暂停、快进等。服务器则根据客户端的请求，执行相应的操作，并返回应答消息。

## HLS协议简介

HLS（HTTP Live Streaming）是由苹果公司提出的一种基于HTTP的流媒体网络传输协议。它的工作原理是把整个流分成一个个小的基于HTTP的文件来下载，每次只下载一些。当媒体流正在播放时，客户端可以选择从许多不同的备用源中以不同的速率下载同样的资源，允许流媒体会话适应不同的数据速率。

HLS协议的主要优势包括：

*   **跨平台兼容性**：基于HTTP协议，支持在几乎所有的设备和浏览器中播放。
*   **自适应比特率流**：客户端根据当前的网络带宽动态选择不同质量的视频流。
*   **易于分发**：可以利用现有的HTTP缓存机制和CDN进行高效分发。

## 为什么需要RTSP到HLS的转换？

尽管RTSP协议功能强大，但它在Web浏览器中的支持并不友好。大多数现代浏览器无法直接播放RTSP流。而HLS协议由于其基于HTTP的特性，在Web浏览器中具有良好的兼容性。因此，将RTSP流转换为HLS流，可以方便地在Web页面中进行播放。

## 项目概述

本项目是一个基于Java和Spring Boot的RTSP到HLS流媒体转换服务。它能够接收RTSP视频流，并将其转换为可以在浏览器中播放的HLS格式。项目使用FFmpeg进行流媒体处理，并通过Spring Boot提供Web服务。

### 核心功能

1.  **协议转换**：将RTSP流转换为HLS流。
2.  **Web服务**：提供HTTP接口用于启动、停止流转换任务，并查看任务状态。
3.  **页面管理**：提供简单的Web页面用于管理和播放流媒体。

### 项目架构

项目采用Spring Boot框架，主要包含以下组件：

*   **StreamService**：核心服务类，负责流媒体的转换和管理。
*   **StreamController**：控制器类，处理HTTP请求。
*   **StreamTask**：任务类，封装单个流转换任务的状态和操作。

## 整体流程

### 启动流程

1.  **应用启动**：Spring Boot应用启动，`RtspHlsServiceApplication`类作为入口点。
2.  **服务初始化**：`StreamService`通过`@PostConstruct`注解的`init()`方法初始化，获取服务器IP地址和端口。
3.  **目录创建**：在启动默认流转换任务前，创建HLS输出目录（默认为用户主目录下的`hls`文件夹）。

### 监听与转换流程

1.  **接收请求**：客户端通过HTTP POST请求`/stream/start`接口启动流转换任务。
2.  **任务检查**：`StreamService`检查任务是否已在运行，如果已在运行则直接返回HLS地址。
3.  **启动新任务**：如果任务未运行，则创建一个新的`StreamTask`对象，并提交到线程池中执行。
4.  **RTSP探测**：在`StreamTask`中，首先探测RTSP URL是否可达。
5.  **FFmpeg转换**：如果RTSP URL可达，则调用FFmpeg命令将RTSP流转码为HLS格式，并保存到指定目录。
6.  **状态管理**：`StreamTask`负责管理任务的状态（探测中、运行中、已停止），并处理异常情况。

### 关闭流程

1.  **接收请求**：客户端通过HTTP POST请求`/stream/stop`接口停止流转换任务。
2.  **任务停止**：`StreamService`根据任务ID查找并停止对应的`StreamTask`，清理相关资源。
3.  **应用关闭**：当应用关闭时，`StreamService`通过`@PreDestroy`注解的`shutdown()`方法关闭所有正在运行的任务，并释放线程池资源。

## Prerequisites

- Java 8+
- Maven
- FFmpeg

## Setup

1. Ensure FFmpeg is installed and accessible in your PATH.
2. Update the RTSP URL in `StreamService.java` if needed.
3. Build and run the project:
   ```bash
   mvn spring-boot:run
   ```
4. Access the stream:
   - HTTP: `http://localhost:8080/stream`
   - HTTPS: `https://localhost:8443/stream`

Note: The HTTPS certificate is self-signed. Your browser will show a security warning, which you can bypass for development purposes.



```shell
keytool -genkeypair -alias rtsp-hls-service -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore /Users/zhangliangliang/qiuguo/rtsp-hls-service/src/main/resources/keystore.p12 -validity 3650 -storepass changeit -keypass changeit -dname "CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown"
```

## 使用说明 rtsp.url 为机器狗地址。直接启动就行了。
```shell
java -jar rtsp-hls-service-1.0-SNAPSHOT.jar --rtsp.url=rtsp://10.11.10.150:8554/test

```


## 部署

### 容器化部署

我们提供了Docker和docker-compose配置文件来简化部署过程，包括RTSP服务和看门狗监听程序。

1. 构建项目：
   ```shell
   mvn clean package
   cp target/rtsp-hls-service-1.0-SNAPSHOT.jar Docker/
   cp watchdog.py service_watchdog.py Docker/
   ```

2. 使用docker-compose启动服务：
   ```shell
   cd Docker
   # 设置钉钉配置（可选）
   export DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=your_token
   export DINGTALK_SECRET=your_secret_key
   # 启动服务
   docker-compose up -d
   ```

3. 访问服务：
   - RTSP服务: http://localhost:8090
   - 管理页面: http://localhost:8090/manager

### 开机自启动配置

在Linux系统上，可以使用systemd配置开机自启动：

1. 运行安装脚本：
   ```shell
   cd Docker
   sudo ./install-watchdog-service.sh
   ```

2. 启动服务：
   ```shell
   sudo systemctl start rtsp-watchdog.service
   ```

3. 检查服务状态：
   ```shell
   sudo systemctl status rtsp-watchdog.service
   ```


```shell
1 # 启动一个名为 test1 的流转换任务  当前任务是只有一个视频流。则表示
2 curl -X POST "https://localhost:8090/stream/start?filename=stream" -k
3 
4 # 停止该任务
5 curl -X POST "https://localhost:8090/stream/stop?filename=stream" -k
```