MediaGo 3.5.0 常用 CLI 命令与工具详解

目标：讲清 MediaGo 3.5.0 服务端随附的命令行工具全家桶——自研 mediago CLI 的全部参数与实测用法、五个开源引擎的版本与定位，以及通过 curl 命令行调用服务端 HTTP API 的完整用法。所有命令与回显均在 MediaGo 3.5.0 服务端真实环境实测取得（Linux amd64，实测日期 2026-10-25）。

一、环境信息

组件：MediaGo 服务端 3.5.0（部署过程见站内同专栏《MediaGo 3.5.0 Docker Compose 部署指南》）
随附工具目录：/app/deps/（服务端程序目录，安装后固定存在）
演示管理账号：admin / q1w2e3r4；服务端 Web 端口 8899
测试素材：公开测试流 https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8（Mux 公开 HLS 测试流，无版权问题）与 https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4（公开教学样本）
代理出口：http://192.168.1.62:7897（下载境外源实测可用，配置方法见配置篇）
组件定位与选型背景见《MediaGo 3.5.0 介绍与选型指南》

随附工具目录实测清单（六个二进制全部随服务端附带，无需单独安装）：

ls -la /app/deps/
# 实测回显：
# -rwxr-xr-x 1 root root 21896752 BBDown
# -rwxr-xr-x 1 root root 19572072 N_m3u8DL-RE
# -rwxr-xr-x 1 root root  9926088 aria2c
# -rwxr-xr-x 1 root root 78683840 ffmpeg
# -rwxr-xr-x 1 root root  6660388 mediago
# -rwxr-xr-x 1 root root 36109712 yt-dlp

二、工具概览

MediaGo 的命令行工具分两组：下载引擎 CLI（被服务端调度，也可独立手动使用）与 服务端 HTTP API（curl 命令行调用，覆盖任务管理全操作）。

工具	版本（实测）	定位	服务端任务类型
`mediago`	v0.2.1	自研通用流下载器：HLS(m3u8)/DASH(mpd)，并发分片、AES-128 解密、自动合并	`mediago`
`N_m3u8DL-RE`	0.3.0+ea9de55e	业界标准 m3u8/DASH 下载器，Master 列表多码率解析	`m3u8`
`yt-dlp`	2026.03.17	YouTube、Twitter/X、Instagram、Reddit 等 1000+ 站点	`youtube`
`BBDown`	—（随附构建）	哔哩哔哩专精下载器	`bilibili`
`aria2c`	1.36.0	直链文件多线程下载	`direct`
`ffmpeg`	6.0-static	分片合并、格式转换	（内部依赖）

版本号实测回显（BBDown 的 --version 需要任务参数，故不列）：

/app/deps/mediago --version
# 实测回显：mediago version v0.2.1

/app/deps/N_m3u8DL-RE --version
# 实测回显：0.3.0+ea9de55eacbd5e9dabf8dd92f5991ab1a37d80f2

/app/deps/aria2c --version
# 实测回显：aria2 version 1.36.0

/app/deps/yt-dlp --version
# 实测回显：2026.03.17

/app/deps/ffmpeg -version
# 实测回显：ffmpeg version 6.0-static https://johnvansickle.com/ffmpeg/  Copyright (c) 2000-2023 the FFmpeg developers

💡 技术拓展：流媒体下载工具的「合并」环节有两条技术路线——二进制拼接（binary merge，把 TS 分片首尾相连，速度快但只适用于 MPEG-TS）与 ffmpeg 转封装（concat demuxer 重封装为 MP4，兼容性好、可处理 fMP4/加密流）。MediaGo 的 mediago CLI 用 --binary-merge 开关切换两者，merge_type 在解析阶段输出；N_m3u8DL-RE 默认 ffmpeg 转封装。本文实测的随附 ffmpeg 为静态构建，个别 MPEG-TS 流存在转封装崩溃现象（详见部署篇常见问题），此时用 binary merge 或换发行版 ffmpeg 规避。

三、前置条件

已部署 MediaGo 3.5.0 服务端（引擎与 API 随服务端提供）；
执行引擎命令需在服务端程序目录 /app/deps/ 下（或用绝对路径调用）；
HTTP API 调用需先有管理令牌（登录接口获取，见六.1）；
下载境外源需服务端已配置代理（proxy + useProxy 键，见配置篇），或 CLI 手动带 --proxy。

四、mediago CLI 详解（自研核心下载器）

4.1 用法与全局参数

/app/deps/mediago --help
# 实测回显（全量）：
# mediago - Streaming media downloader
#
# Supports HLS (m3u8) and DASH (mpd) protocols with concurrent segment
# downloading, AES-128 decryption, and automatic merging.
#
# DISCLAIMER: This software is for educational and research purposes only.
# Users are responsible for ensuring compliance with applicable laws.
#
# Usage:
#   mediago [url] [flags]
#
# Flags:
#       --auto-select                Auto-select best quality
#       --binary-merge               Force binary concatenation
#       --custom-hls-iv string       Force HLS IV (HEX)
#       --custom-hls-key string      Force HLS key (HEX)
#       --custom-hls-method string   Force HLS encryption method
#       --del-after-done             Delete temp files after merge (default true)
#       --ffmpeg-path string         Path to ffmpeg binary (default "ffmpeg")
#   -H, --header stringArray         Custom HTTP header (can be specified multiple times)
#   -h, --help                       help for mediago
#       --key stringArray            Decryption key in HEX (can be specified multiple times)
#       --live                       Force live mode
#       --live-duration string       Recording duration (HH:mm:ss)
#       --live-wait-time int         Playlist refresh interval in seconds
#       --log-level string           Log level (debug/info/warn/error) (default "info")
#       --no-log                     Disable logging
#       --no-merge                   Download only, skip merge
#       --proxy string               Proxy URL (http/socks5)
#   -r, --retry-count int            Retry count per segment (default 3)
#   -d, --save-dir string            Save directory (default ".")
#   -n, --save-name string           Output filename (without extension)
#       --select-audio string        Audio stream filter
#       --select-video string        Video stream filter
#   -t, --thread-count int           Concurrent download threads (default 8)
#       --timeout int                HTTP request timeout in seconds (default 30)
#       --tmp-dir string             Temporary directory for segments
#   -v, --version                    version for mediago

参数分组解读：

下载目标与产出：[url] 位置参数（m3u8/mpd 地址）；-d/--save-dir（保存目录，默认当前目录）；-n/--save-name（输出文件名，不含扩展名）；--tmp-dir（分片临时目录，默认系统临时目录下的 mediago/<任务名>/，实测见 4.3）；
并发与容错：-t/--thread-count（分片并发线程，默认 8）；-r/--retry-count（单分片重试次数，默认 3）；--timeout（HTTP 超时秒数，默认 30）；
流选择：--auto-select（自动选最佳画质）；--select-video/--select-audio（按条件过滤视频/音频流）；
加密流：--key（HEX 解密密钥，可多次）、--custom-hls-key/--custom-hls-iv/--custom-hls-method（强制指定 HLS 加密三要素）；
直播录制：--live（强制直播模式）、--live-duration（录制时长 HH:mm:ss）、--live-wait-time（播放列表刷新间隔秒数）；
合并策略：默认 ffmpeg 转封装；--binary-merge（强制二进制拼接）；--no-merge（只下载不合并）；--del-after-done（合并后清理分片，默认 true）；--ffmpeg-path（指定 ffmpeg 路径）；
网络与杂项：--proxy（http/socks5 代理）；-H/--header（自定义请求头，可重复传）；--log-level/--no-log（日志控制）。

4.2 实测：完整下载一个 HLS 测试流

/app/deps/mediago --proxy http://192.168.1.62:7897 -d /tmp/clitest -n clitest -t 4 "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
# 实测回显（节选，实测首部）：
# Downloading: https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8
# Save as: clitest
# [parse] url=https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8
# [parse] streams: 5, merge_type: 2, is_live: false
# [parse]   stream[0]: type=video bandwidth=2149280 segments=64 has_init=false
# [parse]   stream[1]: type=video bandwidth=246440 segments=64 has_init=false
# [parse]   stream[2]: type=video bandwidth=460560 segments=64 has_init=false
# [parse]   stream[3]: type=video bandwidth=836280 segments=64 has_init=false

[parse] 段说明 CLI 先解析播放列表：本测试流共 5 条码率流、每条 64 个分片、非直播（is_live: false）、默认合并类型 2（ffmpeg 转封装）。

不手动选流时 CLI 默认取最高码率流下载，进度逐分片刷新（实测速度约 49MB/s，64 分片约 2 分钟）：

# 实测回显（节选，实测尾部）：
# [63/64] 98.4% | 49.2 MB/s[download] progress: 64/64 (100.0%) speed=49.2MB/s
# [64/64] 100.0% | 49.2 MB/s[download] complete: 64 segments
#
# Done!

产物验证（分片目录与合并产物按 -d/-n 落位；分片临时目录在系统临时目录下）：

ls /tmp/mediago/clitest | head -5
# 实测回显（分片临时目录，--del-after-done 默认 true 时合并成功后清空）：
# seg_00000
# seg_00001
# seg_00002
# seg_00003
# seg_00004

ls /tmp/mediago/clitest | wc -l
# 实测回显：64

4.3 实测：只下载不合并（--no-merge）

/app/deps/mediago -d /tmp/clitest -n clitest2 -t 8 --no-merge "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
# 实测回显（节选，实测尾部）：
# [63/64] 98.4% | 49.2 MB/s[download] progress: 64/64 (100.0%) speed=49.2MB/s
# [64/64] 100.0% | 49.2 MB/s[download] complete: 64 segments
#
# Done!

--no-merge 模式下 64 个分片完整保留在 /tmp/mediago/clitest2/seg_00000 ~ seg_00063，后续可用 ffmpeg 或 binary 拼接手动合并——这正是排障随附 ffmpeg 转封装问题时的标准工作流（配合部署篇 Q3）。

4.4 常用参数组合速查

# 场景 1：直连可达的内网/国内流，最快下载
/app/deps/mediago -d /data/videos -n lecture01 -t 16 "https://example.internal/live/master.m3u8"
# -t 16 提高并发；无 --proxy 直连

# 场景 2：自动选最高画质 + 下载后自动清理分片
/app/deps/mediago --auto-select -d /data/videos -n movie02 "https://example.com/v/master.m3u8"
# --auto-select 等效默认行为，显式声明便于脚本留痕

# 场景 3：加密 HLS 流（服务端可见密钥时）
/app/deps/mediago --key 0a1b2c3d4e5f60718293a4b5c6d7e8f9 -d /data/videos -n lesson03 "https://example.com/enc/index.m3u8"
# --key 传 16 进制密钥；AES-128 标准流自动识别，非常规加密用 --custom-hls-method/key/iv 三件套

# 场景 4：录制 30 分钟直播
/app/deps/mediago --live --live-duration 00:30:00 --live-wait-time 5 -d /data/live -n live04 "https://example.com/live.m3u8"
# --live-duration 到时停止；--live-wait-time 控制拉流间隔，防过频请求

# 场景 5：源站校验 UA/Referer
/app/deps/mediago -H "User-Agent: Mozilla/5.0" -H "Referer: https://example.com" -d /data/videos -n page05 "https://example.com/v/index.m3u8"
# -H 可重复出现，逐条下发请求头

五、随附引擎工具速览

服务端按任务类型自动调用对应引擎；需要手动精细控制时可直接使用它们（各自完整参数见其官方文档，此处给定位与最常用调用）：

N_m3u8DL-RE（m3u8 任务引擎）：/app/deps/N_m3u8DL-RE <url> --save-dir /data/videos --save-name xxx，支持 --select-video 流选择、多线程、Live 录制；服务端日志中的「检测到Master列表，开始解析全部流信息」「调用ffmpeg合并中... Done」即它的输出；
yt-dlp（youtube 任务引擎）：/app/deps/yt-dlp -f "bv*+ba/b" -o "/data/videos/%(title)s.%(ext)s" <页面URL>，站点覆盖以官方支持列表为准；
aria2c（direct 任务引擎）：/app/deps/aria2c -d /data/videos -o file.mp4 <直链URL>，实测直链下载失败时任务报 exit status 22（HTTP 403 类），排查思路见部署篇 Q2；
BBDown（bilibili 任务引擎）：/app/deps/BBDown <B站视频页URL>；
ffmpeg（合并/转码内部依赖）：6.0 静态构建；手动合并分片用法：ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4。

⚠️ 引擎版本由 MediaGo 镜像统一维护，手动升级引擎不影响服务端调度，但「配置篇的 allowBeta/升级通道」只管 MediaGo 自身版本，引擎随版本迭代更新。

六、服务端 HTTP API 命令行调用

服务端全部管理操作都有 HTTP 接口，curl 即 CLI。以下均实测（令牌为示例环境的真实值；你的环境用自己登录令牌替换）。

6.1 认证：登录与令牌

curl -s -X POST http://127.0.0.1:8899/api/auth/signin -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4"}'
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":"77a934b1-a5bd-453d-afa1-45c6944d4c81"}

data 即 Bearer 令牌，后续请求带 -H "Authorization: Bearer <令牌>"。首次部署用 POST /api/auth/setup（同 body）初始化账号，GET /api/auth/status 可查是否已初始化（setuped 布尔）。

6.2 任务管理四件套

TOKEN=77a934b1-a5bd-453d-afa1-45c6944d4c81

# 建任务（type 可选：m3u8 / direct / youtube / bilibili / mediago）
curl -s -X POST http://127.0.0.1:8899/api/tasks -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"url":"https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4","name":"bbb-cli-test","type":"direct"}'
# 实测回显：
# {"success":true,"code":200,"message":"Task created successfully","data":{"id":"caea661f-c3e6-4c33-a0cc-63b4181294f9","message":"Task enqueued successfully","status":"downloading"}}

# 列任务
curl -s http://127.0.0.1:8899/api/tasks -H "Authorization: Bearer $TOKEN"
# 实测回显（节选）：
# {"success":true,"code":200,"message":"OK","data":{"tasks":[{"id":"caea661f-...","type":"direct","url":"https://test-videos.co.uk/...","name":"bbb-cli-test","status":"success","percent":100,"speed":"","isLive":false}],"total":1}}

# 查任务日志（排障主入口）
curl -s "http://127.0.0.1:8899/api/tasks/caea661f-c3e6-4c33-a0cc-63b4181294f9/logs" -H "Authorization: Bearer $TOKEN"
# 实测回显（节选）：
# {"success":true,"code":200,"message":"OK","data":{"id":"caea661f-...","log":"Task started\n10/25 03:36:41 [NOTICE] Downloading 1 item(s)\n..."}}

# 停任务
curl -s -X POST "http://127.0.0.1:8899/api/tasks/caea661f-c3e6-4c33-a0cc-63b4181294f9/stop" -H "Authorization: Bearer $TOKEN"
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":{"message":"Task stopped"}}

任务状态机实测取值：downloading → success | failed | stopped；失败任务在列表回显中带 error 字段（如 "exit status 22"）。

6.3 配置读取与修改

curl -s http://127.0.0.1:8899/api/config -H "Authorization: Bearer $TOKEN" | head -c 400
# 实测回显（节选，25 键全量 JSON）：
# {"success":true,"code":200,"message":"OK","data":{"allowBeta":false,"apiKey":"77a934b1-...","audioMuted":true,...}}

curl -s http://127.0.0.1:8899/api/config/maxRunner -H "Authorization: Bearer $TOKEN"
# 实测回显：{"success":true,"code":200,"message":"OK","data":2}

curl -s -X PUT http://127.0.0.1:8899/api/config/maxRunner -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"value":4}'
# 实测回显：{"success":true,"code":200,"message":"Config updated","data":{"message":"Config key 'maxRunner' updated"}}

全部 25 键语义见《MediaGo 3.5.0 配置参数详解》。

6.4 环境与健康检查

curl -s http://127.0.0.1:8899/healthy
# 实测回显：{"success":true,"code":200,"message":"OK","data":{"status":"ok"}}

curl -s http://127.0.0.1:8899/api/env -H "Authorization: Bearer $TOKEN"
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":{"configDir":"/app/mediago/data","binDir":"/usr/local/bin","platform":"linux","playerUrl":"http://127.0.0.1:8899/player/"}}

curl -s http://127.0.0.1:8899/api/v1/videos -H "Authorization: Bearer $TOKEN"
# 实测回显（无入库视频时）：
# []

另有 GET /api/events（SSE 事件流，任务状态实时推送）与 GET /api/url/title（抓取网页标题辅助命名）可用。

七、注意事项

令牌即凭据：apiKey 与登录令牌同值，curl 落盘脚本注意清理 shell 历史；演示环境令牌在交付后已随环境清理；
CLI 与任务队列隔离：手动跑 /app/deps/mediago 不经过服务端任务队列（无 Web 记录、无并发上限约束），大任务请走 API 建任务；
临时目录空间：CLI 分片先落系统临时目录（/tmp/mediago/<任务名>/）再合并，下载超大盘前用 --tmp-dir 指到大容量分区；
合并故障处置：任务 success 无产物（ffmpeg 转封装崩溃）时，--no-merge 拿分片 + binary 拼接/换 ffmpeg 是标准工作流，详见部署篇 Q3；
引擎直调的退出码：aria2c 对 4xx 返回 22、ffmpeg 崩溃返回 139（段错误），脚本化时按退出码分支处理。

八、常见问题

Q1：mediago <url> 输出一屏参数列表？ URL 传了但某参数格式不对（如 --key 值带引号、--live-duration 格式非 HH:mm:ss）会触发帮助页。先简化到最小命令 mediago -d <目录> -n <名字> <url> 跑通，再逐个加参数。

Q2：CLI 下载完成但输出目录找不到文件？ 确认 -d 是否绝对路径；合并环节失败时产物不落盘（分片在临时目录）。用 --no-merge 先确认分片能下齐，再排查合并（--binary-merge 或换 --ffmpeg-path 指向系统 ffmpeg）。

Q3：手动跑引擎和服务端建任务，哪个优先？ 都可用但建议：日常与批量 → API 建任务（有队列、有记录、可多端管理）；临时单个调试 → CLI 直调。两者共用同一磁盘与网络出口，注意别同时打满带宽。

Q4：curl 调 API 返回 401？ 令牌过期或值不对：重新 POST /api/auth/signin 取新令牌；注意 -H "Authorization: Bearer <令牌>" 中 Bearer 与令牌之间有一个空格。

Q5：/api/tasks 列表为空但磁盘上有产物？ 列表展示的是任务库记录；确认查询令牌与建任务时同属一个实例（machineId 区分实例），产物目录以 config.json 的 local 为准（部署篇 4.5 的目录回退问题也会造成「任务在、产物不在预期位置」）。

九、参考链接

官方 README（HTTP API 与 OpenClaw Skill）：https://github.com/mediago-dev/mediago
mediago-core（CLI 上游仓库）：https://github.com/caorushizi/mediago-core
引擎上游：N_m3u8DL-RE（https://github.com/nilaoda/N_m3u8DL-RE）、yt-dlp（https://github.com/yt-dlp/yt-dlp）、BBDown（https://github.com/nilaoda/BBDown）、aria2（https://aria2.github.io/）
官网：https://mediago.torchstellar.com/en/downloader
站内同专栏：《MediaGo 3.5.0 介绍与选型指南》、《MediaGo 3.5.0 配置参数详解》、《MediaGo 3.5.0 Docker Compose 部署指南》