706 字 ~ 2 分钟阅读

把音视频处理能力封装成 HTTP API

如果你想把 FFmpeg 包成一个可调用服务，ffmpeg-service 是一个上手很快的选择。

这篇文章只回答三件事：

  1. 它能做什么。
  2. 怎么最快跑起来。
  3. 哪些参数最值得先调。

项目定位

ffmpeg-service 采用 Flask + FFmpeg，提供 HTTP 接口来处理音视频，核心能力有：

  1. 媒体信息提取（/info）
  2. 转码与分辨率调整（/process）
  3. 视频截图（/process）
  4. 从视频提取音轨（/process）
  5. 处理结果下载（/download/{filename}）

镜像支持 linux/amd64、linux/arm64、linux/arm/v7，对树莓派、NAS、x86 都比较友好。

快速启动

直接运行 Docker

1
2
3
docker run -d --name ffmpeg-service --restart on-failure \
  -p 8080:8080 \
  funnyzak/ffmpeg-service:latest

使用 docker-compose（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
version: "3.8"
services:
  ffmpeg-service:
    image: funnyzak/ffmpeg-service:latest
    container_name: ffmpeg-service
    environment:
      - TZ=Asia/Shanghai
      - TEMP_DIR=/tmp/videos
      - MAX_FILE_SIZE=524288000
      - FILE_RETENTION_HOURS=2
      - CLEANUP_INTERVAL_MINUTES=30
      - FLASK_HOST=0.0.0.0
      - FLASK_PORT=8080
      - FLASK_DEBUG=false
      - GUNICORN_WORKERS=4
      - GUNICORN_WORKER_CLASS=sync
      - GUNICORN_TIMEOUT=120
      - API_KEYS=replace_with_your_key
    ports:
      - "8080:8080"
    restart: on-failure
    volumes:
      - ./temp:/tmp/videos

说明：

  1. API_KEYS 留空时不鉴权，建议至少配一个 key。
  2. TEMP_DIR 挂载到宿主机目录后，排错和容量管理都更方便。
  3. 所有行为都能通过环境变量调整，不需要改代码。

核心接口

健康检查

1
GET /health

提取媒体信息

1
POST /info

支持 media_url（JSON）或文件上传（multipart/form-data）。

媒体处理（主入口）

1
POST /process

常见组合：

  1. extract_info=true：提取媒体元信息
  2. take_screenshots=true + screenshot_count=5：自动取样截图
  3. convert_format=mp4 + convert_resolution=720p：视频转码
  4. extract_audio=true + audio_format=mp3：提取音轨

一个请求里可以组合多个操作，适合“一次上传，多种输出”。

鉴权与安全

当 API_KEYS 有值时，/process 和 /info 需要请求头：

1
X-API-Key: your_secret_key

状态码：

  1. 401：缺少 API Key
  2. 403：API Key 非法
  3. 413：文件超限（默认 500MB）

建议：

  1. 打开 API Key。
  2. 在反向代理层加限流和来源控制。
  3. 只保留你需要的输入/输出格式。

参数与调优建议

优先关注这些参数：

  1. MAX_FILE_SIZE：上传大小上限
  2. FILE_RETENTION_HOURS：结果文件保留时长
  3. CLEANUP_INTERVAL_MINUTES：清理任务间隔
  4. GUNICORN_WORKERS：并发 worker 数
  5. GUNICORN_TIMEOUT：大文件处理超时

简单经验：

  1. CPU 密集型转码优先 sync worker。
  2. 大文件场景把 GUNICORN_TIMEOUT 调到 120~300 秒。
  3. GUNICORN_MAX_REQUESTS + JITTER 可以平滑重启，减少内存抖动。

常见处理流参考

场景一：视频转码 + 抽帧

  1. 调 /process
  2. 设置 convert_format、convert_resolution
  3. 同时启用 take_screenshots
  4. 从返回的 url 下载结果

场景二：视频提取音频

  1. 调 /process
  2. 设置 extract_audio=true
  3. 指定 audio_format（如 mp3、opus）

场景三：仅做媒体探测

  1. 调 /info
  2. 读取时长、编码、分辨率、码率
  3. 再决定是否转码

总结

ffmpeg-service 的优点是：部署快、接口直观、配置项齐全。

建议先用最小配置跑通，再根据文件大小和并发量逐步调 MAX_FILE_SIZE、GUNICORN_TIMEOUT、GUNICORN_WORKERS。




精选标签
docker ffmpeg flask 音视频