zzhfinalize/m3u8-download-server
一个基于异步架构的 m3u8 视频下载器 Docker 镜像，提供 RESTful API 服务。
Image
Networking
0
2.3K
zzhfinalize/m3u8-download-server repository overview
m3u8 下载器 - Docker 镜像
一个基于异步架构的 m3u8 视频下载器 Docker 镜像，提供 RESTful API 服务。
项目特点
- 🚀 异步架构：基于 Quart 和 aiohttp，高性能并发下载
- 📦 开箱即用：镜像已内置 ffmpeg，无需额外配置
- 🔧 RESTful API：完整的 API 接口，支持任务管理和缓存控制
- 🐳 Docker 优化：轻量级镜像，支持健康检查和环境变量配置
快速开始
1. Docker Compose 部署（推荐）
创建 docker-compose.yml 文件：
version: '3.8'
services:
m3u8-downloader:
image: zzhfinalize/m3u8-download-server:latest
container_name: m3u8-downloader
ports:
- "6900:6900"
volumes:
- ./output:/output
- ./data:/data
environment:
- SERVER_HOST=0.0.0.0
- SERVER_PORT=6900
- MAX_THREADS=32
- LOG_LEVEL=INFO
- DEBUG=false
- LOG_DIR=/data/logs
- CACHE_DIR=/data/task_cache
- OUTPUT_DIR=/output
restart: unless-stopped
# 硬件加速支持 (根据实际情况配置)
devices:
- /dev/dri:/dev/dri # 主要渲染设备
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:6900/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 5s
启动服务：
# 启动容器
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
2. Docker 命令部署
docker run -d \
--name m3u8-downloader \
-p 6900:6900 \
-v $(pwd)/output:/output \
-v $(pwd)/data:/data \
-e SERVER_HOST=0.0.0.0 \
-e SERVER_PORT=6900 \
-e MAX_THREADS=32 \
-e LOG_LEVEL=INFO \
-e LOG_DIR=/data/logs \
-e DEBUG=false \
-e CACHE_DIR=/data/task_cache \
-e OUTPUT_DIR=/output \
--restart unless-stopped \
zzhfinalize/m3u8-download-server:latest
环境变量配置
| 变量名 | 默认值 | 说明 |
|---|---|---|
SERVER_HOST | 127.0.0.1 | 监听地址 IP |
SERVER_PORT | 6900 | 监听端口 |
MAX_THREADS | 32 | 下载并发数上限。如果 API 请求传入的 threads 值大于此值，将使用此值。 |
LOG_LEVEL | INFO | 日志级别 (DEBUG/INFO/WARNING/ERROR/CRITICAL) |
LOG_DIR | /data/logs | 日志目录 |
DEBUG | false | 启用调试模式（启用后日志级别自动设为 DEBUG） |
CACHE_DIR | /data/task_cache | 缓存目录（存放临时分片和任务缓存） |
OUTPUT_DIR | /output | 输出目录 |
目录挂载说明
| 容器路径 | 宿主机路径 | 说明 |
|---|---|---|
/output | ./output | 下载完成的视频文件 |
/data | ./data | 日志 (/data/logs) 和缓存 (/data/task_cache) |
使用 Edge 插件
本项目提供 Edge 浏览器插件前端
打包好的插件可以在https://github.com/ZZH-Finalize/m3u8-downloader/releases下载到。
API 简介
提交异步下载任务，立即返回 task_id，后台异步执行。
请求
# 提交下载任务
curl -X POST http://localhost:6900/api/download \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/video.m3u8",
"threads": 8,
"output_name": "my_video.mp4",
"encoder": "software",
"output_encoding": "copy"
}'
成功响应
{
"task_id": "74a993fffd15ddbe"
}
说明
- 该接口是异步接口，提交任务后立即返回
task_id - 使用返回的
task_id可通过/api/tasks/<task_id>查询进度 task_id是 URL 的 MD5 哈希值（前 16 位字符）
其余完整的 API 文档请查看项目中的 API.md 文件。
使用示例
下载视频并跟踪进度
# 提交任务并获取 task_id
TASK_ID=$(curl -s -X POST http://localhost:6900/api/download \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/video.m3u8"}' | jq -r '.task_id')
# 轮询查询进度
while true; do
STATE=$(curl -s http://localhost:6900/api/tasks/$TASK_ID | jq -r '.state')
DOWNLOADED=$(curl -s http://localhost:6900/api/tasks/$TASK_ID | jq -r '.segments_downloaded')
TOTAL=$(curl -s http://localhost:6900/api/tasks/$TASK_ID | jq -r '.total_segments')
echo "进度：$DOWNLOADED/$TOTAL 状态：$STATE"
[ "$STATE" = "completed" ] && break
sleep 2
done
注意事项
- Docker 镜像已内置 ffmpeg，无需额外安装
- Docker 镜像内的编码器组件已全部移除，使用 Docker 镜像后端时，用户只能选择 copy 作为编码方式，copy 是最常用的模式，它直接复制视频流而不重新编码
- 如果用户确实需要其他编码方式，可以使用原生部署直接使用宿主机上功能齐全的 ffmpeg，或者自行转码处理 Docker 合并完成的输出文件
- 后端服务需要保持运行才能使用 Edge 插件
- 默认情况下，下载完成后会清理分片文件，保留元数据
- 完整的 API 文档请查看 API.md
相关资源
- GitHub 仓库: https://github.com/ZZH-Finalize/m3u8-downloader
- Docker Hub: https://hub.docker.com/r/zzhfinalize/m3u8-download-server
- 完整 API 文档: https://github.com/ZZH-Finalize/m3u8-downloader/blob/master/API.md
许可证
GNU General Public License v3.0 (GPL-3.0)
Tag summary
Content type
Image
Digest
sha256:296d43a2f…
Size
38.3 MB
Last updated
6 months ago
docker pull zzhfinalize/m3u8-download-server