# m3u8proxy

**Repository Path**: johnroot/m3u8proxy

## Basic Information

- **Project Name**: m3u8proxy
- **Description**: 一个轻量级、高性能的 IPTV 和直播流代理服务器。它旨在解决复杂的直播源播放问题，并提供统一的 m3u8 输出接口。支持将各种流媒体协议（RTSP, RTMP, RTP, UDP）、本地文件甚至采集设备转换为标准的 HLS (m3u8) 直播流。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 2
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# m3u8proxy - 直播流代理服务

**m3u8proxy** 是一个轻量级、高性能的 IPTV 和直播流代理服务器。它旨在解决复杂的直播源播放问题，并提供统一的 m3u8 输出接口。支持将各种流媒体协议（RTSP, RTMP, RTP, UDP）、本地文件甚至采集设备转换为标准的 HLS (m3u8) 直播流。

## ✨ 主要功能

- **多协议支持**：支持代理 HTTP(S) m3u8、RTSP、RTMP、RTP、UDP 等多种流媒体协议。
- **本地文件直播**：支持将服务器本地视频文件（mp4, flv 等）循环转换为直播流输出。
- **采集设备支持**：支持读取 Linux 采集设备（如 USB 摄像头 `/dev/video0`）并转为直播流。
- **Web 管理界面**：内置基于 Bootstrap 5 的美观管理后台，支持在线添加、删除代理路由。
- **动态更新**：路由配置动态生效，无需重启服务。数据本地持久化保存。
- **安全保护**：支持 Web 管理界面 Basic Auth 密码认证。
- **智能处理**：
  - **复杂源解析**：自动处理多重重定向、Cookie 保持、Token 参数继承。
  - **嵌套 m3u8**：自动检测并处理嵌套的 m3u8 列表。
  - **性能优化**：使用 FFmpeg 进行转码或切片，支持内存盘（RAM Disk）以减少硬盘磨损。
  - **自动清理**：服务重启或路由删除时，自动清理残留的临时切片文件。

## 🚀 快速开始 (Docker)

推荐使用 Docker 运行，并将临时目录映射到内存（`/dev/shm`）以获得最佳性能。

### 1. 启动容器

```bash
docker run -d \
  --name m3u8proxy \
  -p 8080:8080 \
  -v $(pwd)/cfg/:/cfg/ \
  -e AUTH_USER=admin \
  -e AUTH_PASS=your_password \
  -e TEMP_DIR=/dev/shm/m3u8proxy \
  --restart always \
  registry.cn-hangzhou.aliyuncs.com/johnroot/m3u8proxy:latest
```

### 开启 HTTPS 支持

只需将证书文件 (后缀为 `.pem` 或 `.crt` 的证书和 `.key` 的私钥) 挂载到容器的 `/cfg/cert` 目录即可。程序会自动扫描并加载该目录下的第一个匹配文件。

```bash
docker run -d \
  --name m3u8proxy \
  -p 8443:8080 \
  -v $(pwd)/cfg/:/cfg/ \
  -v $(pwd)/cert/:/cfg/cert/ \
  -e AUTH_USER=admin \
  -e AUTH_PASS=your_password \
  -e TEMP_DIR=/dev/shm/m3u8proxy \
  --restart always \
  m3u8proxy:latest
```

*注意：开启 HTTPS 后，容器内部端口仍然是 8080 (但协议变为 HTTPS)，你可以通过 Docker 端口映射将其映射到外部的 443 或其他端口。*

*注意：如果需要使用采集设备（如 `/dev/video0`），请添加 `--device /dev/video0:/dev/video0` 参数。*

### 2. 命令行参数启动 (覆盖环境变量)

程序支持通过命令行参数（Flags）直接配置，优先级高于环境变量。

```bash
./m3u8proxy -port 8080 -user admin -pass 123456 -temp /dev/shm/m3u8proxy
```

**所有可用参数：**

| 参数 Flag | 对应环境变量 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `-port` | `PORT` | `8080` | 服务监听端口 |
| `-user` | `AUTH_USER` | `admin` | 管理后台用户名 |
| `-pass` | `AUTH_PASS` | `123456` | 管理后台密码 |
| `-routes`| `ROUTES_PATH`| (空) | 路由配置文件路径 (默认为当前目录 routes.json) |
| `-temp` | `TEMP_DIR` | (系统TEMP) | 视频切片临时存储目录 |
| `-vcodec`| `FFMPEG_VCODEC`| `auto` | FFmpeg 视频编码器 (如 libx264, h264_nvenc, copy) |
| `-preset`| `FFMPEG_PRESET`| `ultrafast`| FFmpeg 编码速度预设 |

**示例 (开启硬件加速):**
```bash
./m3u8proxy -vcodec h264_nvenc -preset p1
```

### 3. 环境变量说明

| 变量名 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `AUTH_USER` | `admin` | 管理后台用户名 |
| `AUTH_PASS` | `123456` | 管理后台密码 |
| `ROUTES_PATH` | `/cfg/routes.json` | 路由配置文件路径 |
| `TEMP_DIR` | `/tmp/m3u8proxy` | 视频切片临时存储目录 (建议使用内存盘) |
| `FFMPEG_VCODEC` | `libx264` | FFmpeg 视频编码器 |
| `FFMPEG_PRESET` | `ultrafast` | FFmpeg 预设 (越快延迟越低) |

## 🛠️ 本地编译运行

如果你想在本地直接运行：

1.  **安装 FFmpeg**：确保系统已安装 `ffmpeg` 并加入 PATH 环境变量。
2.  **编译**：
    ```bash
    go build -o m3u8proxy .
    ```
3.  **运行**：
    ```bash
    ./m3u8proxy
    ```

## 🐳 Docker 镜像构建

如果你希望自己构建 Docker 镜像，可以使用以下命令：

### 1. 标准构建
```bash
docker build -t m3u8proxy .
```

### 2. 多架构构建 (Buildx)
项目根目录提供了 `build_push.sh` 脚本供参考，支持 `linux/amd64`, `linux/arm64`, `linux/arm/v7` 等多架构构建。

手动构建示例：
```bash
# 创建 builder (如果尚未创建)
docker buildx create --use --name mybuilder

# 构建并加载到本地 (仅限单架构)
docker buildx build --platform linux/amd64 -t m3u8proxy --load .

# 或构建并推送到仓库
docker buildx build --platform linux/amd64,linux/arm64 -t your-registry/m3u8proxy --push .
```

## 🖥️ 使用指南

### 访问管理后台
打开浏览器访问 `http://your-ip:8080/dashboard`，输入配置的用户名和密码。

### 添加代理
在后台点击“添加代理”，填写以下信息：
- **路由路径**：访问该流的 URL 后缀，例如 `/live/cctv1`。
- **源地址**：
  - **网络流**：`http://...`, `rtsp://...`, `rtmp://...`
  - **本地文件**：`/data/video.mp4` (服务器绝对路径)
  - **采集设备**：`/dev/video0` (需确保设备可访问)

### 播放地址
添加成功后，使用播放器 (VLC, PotPlayer 等) 访问：
`http://your-ip:8080/live/cctv1`

## ⚙️ 高级特性

### 采集设备 (Linux)
可以直接将 `/dev/video*` 设备作为源。系统会自动识别并应用 `-f v4l2 -fflags nobuffer` 参数以实现低延迟直播。
**Docker 运行示例**：
```bash
docker run -d --device /dev/video0:/dev/video0 ...
```

### 内存盘优化
为了防止 FFmpeg 频繁读写硬盘损伤寿命，强烈建议将 `TEMP_DIR` 设置为内存文件系统：
- **Docker**: 使用 `--tmpfs` 或挂载 `/dev/shm`。
- **Linux**: 设置环境变量 `TEMP_DIR=/dev/shm/m3u8proxy`。

## 📝 配置文件 (routes.json)
路由信息存储在 JSON 文件中，格式如下：
```json
{
  "/live/test": {
    "Path": "/live/test",
    "SourceURL": "http://example.com/stream.m3u8",
    "UseFFmpeg": false
  }
}
```
*通常不需要手动编辑此文件，通过 Web 界面管理即可。*