企业官网建设流程全解析

• 音视频
• 桌面应用
• 后端

MediaGo 将下载引擎以 HTTP 服务的形式对外开放：桌面客户端监听39719端口，Docker 部署监听9900端口。本文围绕官方下载 API 文档，系统讲解统一响应结构、认证方式、媒体检测（Discovery）接口、下载任务的创建/查询/控制流程以及 Server-Sent Events（SSE）事件订阅，并辅以仓库源码（apps/core/internal/api）验证实现细节。读完本文，你可以用 curl、Python、Node.js 或 Postman 等任意 HTTP 工具，直接对 MediaGo 完成"发现媒体 → 创建任务 → 启动下载 → 实时感知完成"的完整闭环，甚至自己编写一个下载客户端。

基本概念与 Base URL

MediaGo 的下载引擎是一个常驻的 HTTP 服务，任何"会说 HTTP"的工具（curl / Python / Node.js / Postman 等）都能直接调用它来创建、开始、停止下载任务并获取进度。MediaGo 自身的浏览器扩展与 AI Skill 也正是这个 API 的使用者。

不同部署形态对应不同的 Base URL：

所有端点都位于/api前缀之下。文档中的示例默认使用桌面版端口39719；如果是 Docker 部署，把端口替换为映射后的端口即可。

从源码看，桌面版端口有明确出处：CLI 客户端在 apps/core/cmd/cli/main.go 中声明了const defaultBaseURL = "http://127.0.0.1:39719"，也就是说命令行工具与 HTTP API 共用同一地址。

统一响应格式

所有/api/*端点都返回统一的 JSON 包装结构：

{ "success": true, "code": 0, "message": "ok", "data": { ... } }

下文各示例的"响应"部分只展示data字段的内容。

需要留意的是，HTTP 状态码与code字段并不总是完全一致。例如在下载创建接口中，当请求的 URL 已存在于下载列表中时，handler 会返回 HTTP409 Conflict（download.go）；而 Discovery 系列的错误则分别映射到400/404/409/429/503等状态码（详见 discovery.go），读取响应时应当同时关注两者。

认证方式

• 桌面版：默认无需认证，直接向localhost:39719发起请求即可。
• Docker 部署：若开启了认证，需要先从 MediaGo 的设置页面获取 API Key，并在后续请求中携带Authorization: Bearer <key>请求头。

从认证中间件实现（auth.go）可以确认更完整的规则：

• 当配置中不存在apiKey（即尚未设置认证）时，所有请求直接放行；
• 一旦设置了apiKey，除白名单路径（如/healthy、/api/auth/*、静态资源等）外，所有请求都需携带有效 token；
• Token 的提取优先级为：X-API-Key请求头 >Authorization: Bearer <token>请求头 >?token=查询参数。之所以保留查询参数方式，是因为浏览器的EventSource无法自定义请求头，订阅 SSE 时只能通过 URL 查询参数传 token。

媒体检测（Discovery / 嗅探与解析）

媒体检测是异步任务。inspect直接解析 HLS 流；browser则让 Electron 主进程创建一个隐藏、隔离的浏览器视图来收集媒体通信，不会移动或替换用户正在查看的素材提取标签页。三种模式的行为差异如下：

• auto：直接面对.m3u8URL 时走inspect，其他 HTTP(S) 页面走browser。
• inspect：只接受直接的 M3U8 URL，不需要 Electron。
• browser：需要连接 Core 的桌面版。独立的 Docker / Core 部署下，页面检测会返回discovery_executor_unavailable。

模式选择的底层逻辑在 service.go 中：请求经过 URL 合法性校验后，若指定模式为inspect，或模式为auto且 URL 路径以.m3u8结尾（不区分大小写），则进入 inspect 执行路径；否则进入 browser 执行路径。

Discovery 核心端点

# 创建媒体检测任务（异步） curl -X POST http://localhost:39719/api/discoveries \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/watch/1","mode":"browser","timeoutMs":20000,"useSessionCookies":false}' # 查询检测结果 curl http://localhost:39719/api/discoveries/<discovery-id> # 取消检测 curl -X POST http://localhost:39719/api/discoveries/<discovery-id>/cancel # 查看 executor 可用状态 curl http://localhost:39719/api/discovery-executor/status # 从检测结果创建下载任务 curl -X POST http://localhost:39719/api/discoveries/<discovery-id>/downloads \ -H "Content-Type: application/json" \ -d '{"sourceIds":["source-1"],"startDownload":true}'

关键约束与安全边界

• 超时限制：timeoutMs被限制在 3000–30000 ms 之间。源码 types.go 定义了MinTimeoutMS = 3_000、MaxTimeoutMS = 30_000、DefaultTimeoutMS = 20_000，且 service.go 会对超出范围的输入值做 clamp 修正，即使你不传该字段也会自动使用 20 秒默认值。
• 结果保留期：内存中的检测结果约 10 分钟后失效（DefaultRetention = 10 * time.Minute），过期任务会被清理，因此应在结果有效期内完成下载交接。
• 会话 Cookie：useSessionCookies默认为false，仅在需要登录态桌面会话时才应显式开启。Cookie、Authorization 等凭据不会出现在公开 API、CLI 和 MCP 的结果中，且重启后失效。
• 用途边界：该 API 不是用于绕过 DRM 或站点访问控制的功能。

检测结果的下载交接

POST /api/discoveries/:id/downloads是"检测 → 下载"的交接点。从 discovery.go 可以看到：

• 请求体除sourceIds与startDownload外，还支持folder、names、variantUrls（见 dto/discovery.go）；
• 当任务尚未完成（既非completed也非failed）时返回409 discovery_invalid_transition；
• 当sourceId不存在时返回404 discovery_source_not_found；
• 浏览器私有凭据只在内存中用于延迟启动与重试，落库记录只保留安全的请求头子集（PersistentDiscoveryHeaders）；
• 单次最多处理 20 个来源（maxDiscoveryDownloadSources），请求体上限 64KB、URL 上限 8KB。

CLI 中的等价操作

桌面版自带的命令行工具封装了同样的流程（main.go）：

mediago discover "https://example.com/watch/1" --mode browser --json mediago discover get <discovery-id> --json mediago discover cancel <discovery-id> mediago discover download <discovery-id> --source source-1

CLI 与 API 行为一致：discover默认--mode auto、--timeout 20s（对应DefaultTimeoutMS），并会在等待期间收到 Ctrl+C 时自动取消任务；--no-wait可创建后立即返回。

此外，对应能力也以 MCP 工具形式暴露：discover_media、get_media_discovery、cancel_media_discovery、download_discovered_media。/mcp端点使用 Bearer token 认证，需要在设置中启用。

快速入门：三条命令打通完整下载流程

下面三个 curl 命令可以一口气跑通"创建任务 → 启动下载 → 完成通知"的完整流程。

第 1 步：创建下载任务

curl -X POST http://localhost:39719/api/downloads \ -H "Content-Type: application/json" \ -d '{ "tasks": [ { "type": "m3u8", "url": "https://example.com/video.m3u8", "name": "我的视频" } ], "startDownload": true }'

参数说明：

• type：下载类型，可选m3u8/bilibili/direct/youtube/mediago；
• url：视频 URL（必填，缺失时 DTO 校验会直接拒绝，见 dto/download.go 中的binding:"required"）；
• name：任务名，作为保存文件名使用；
• startDownload：是否在创建后立即开始下载。

创建接口支持批量提交：tasks是一个数组，一次请求可同时创建多个任务，startDownload对所有任务统一生效。

响应示例：

[ { "id": 123, "name": "我的视频", "type": "m3u8", "url": "https://example.com/video.m3u8", "status": "waiting", "createdDate": "2026-04-23T10:00:00Z" } ]

记下返回的id，后续所有控制操作都依赖它。

值得注意的实现细节：当startDownload为true时，handler 会从运行时配置读取local（保存目录）与deleteSegments配置并自动启动下载（download.go）。如果该 URL 已存在于下载列表，会返回409 Conflict与"URL 已存在"提示，而不是重复创建。

第 2 步：订阅下载事件（SSE）

curl -N http://localhost:39719/api/events

这是一个长连接，服务器推送的内容会原样持续输出：

event: download-start data: {"id": "123"} event: download-success data: {"id": "123"}

浏览器 / Node.js 中的订阅写法：

const es = new EventSource("http://localhost:39719/api/events"); es.addEventListener("download-success", (e) => { const { id } = JSON.parse(e.data); console.log("任务完成:", id); });

从实现看（event.go），该端点返回text/event-stream，并设置了Cache-Control: no-cache、Connection: keep-alive、X-Accel-Buffering: no响应头；客户端断连时，服务端会通过请求上下文感知并清理订阅。特别说明：该事件流不包含进度更新事件，需要获取下载进度时应轮询GET /api/downloads/:id。

第 3 步：状态查询与手动控制

# 列出所有下载任务（分页） curl "http://localhost:39719/api/downloads?current=1&pageSize=20" # 获取单个任务 curl http://localhost:39719/api/downloads/123 # 启动已有任务 curl -X POST http://localhost:39719/api/downloads/123/start \ -H "Content-Type: application/json" \ -d '{"localPath": "/Downloads/MediaGo", "deleteSegments": true}' # 停止任务 curl -X POST http://localhost:39719/api/downloads/123/stop # 获取任务日志 curl http://localhost:39719/api/downloads/123/logs

其中start接口传入的localPath会同步写回运行时配置（h.conf.Set("local", req.LocalPath)），也就是说后续任务无需再重复指定保存路径。

下载事件（SSE 事件表）

GET /api/events是与下载相关的事件流，事件定义如下：

download-create的广播在创建成功后由 handler 主动触发（download.go），这样主窗口、悬浮对话框以及外部客户端等所有连接者都能即时刷新各自的状态，而不依赖跨 WebContents 的 IPC。

端点参考

列表与查询

GET /api/downloads— 分页列表

查询参数：

• current（number，默认 1）：页码；
• pageSize（number，默认 20）：每页大小；
• filter（string，可选）：按状态过滤（downloading/success/failed）；
• localPath（string，可选）：按保存路径过滤。

响应：

{ "total": 42, "list": [/* DownloadTask[] */] }

GET /api/downloads/active— 活动任务列表

返回所有waiting/downloading状态的任务（对应源码FindActiveTasks）。

GET /api/downloads/:id— 获取单个任务

响应（DownloadTask结构）：

{ "id": 123, "name": "我的视频", "type": "m3u8", "url": "https://example.com/video.m3u8", "folder": "my-folder", "headers": "User-Agent: ...", "isLive": false, "status": "success", "file": "/path/to/saved.mp4", "createdDate": "2026-04-23T10:00:00Z", "updatedDate": "2026-04-23T10:05:30Z" }

任务不存在时返回 404。

GET /api/downloads/folders— 不重复的保存目录列表

响应：string[]

GET /api/downloads/export— 导出下载列表

纯文本格式，每行一个 URL。

GET /api/downloads/:id/logs— 获取下载日志

响应：{ id, log: string }

创建 / 删除

POST /api/downloads— 批量创建下载任务

请求体：

{ "tasks": [ { "type": "m3u8 | bilibili | direct | youtube | mediago", "url": "https://example.com/video.m3u8", "name": "任务名", "folder": "可选的子目录", "headers": "可选的多行 HTTP 头" } ], "startDownload": true }

响应：DownloadTask[]

headers字段值得一提：当startDownload=true时，提交的多行请求头会拆分成"运行时临时头"（仅本次启动与重试使用，不落库）与"持久化安全头"（写入数据库记录）两部分，避免把敏感凭据写入持久存储（见 download.go）。

DELETE /api/downloads/:id— 删除任务

响应：{}

编辑 / 状态

PUT /api/downloads/:id— 编辑任务

请求体（全部可选，只传需要修改的字段）：

{ "name": "新名称", "url": "新 URL", "headers": "新请求头", "folder": "新子目录" }

handler 会对传入的字段做非空判断（指针字段），仅更新实际提供的属性；URL 若与其他任务重复会返回409。

PUT /api/downloads/:id/live— 切换直播标志

请求体：{ "isLive": true }

该标志用于把任务标记为直播流下载模式（MediaGo 内置了直播恢复能力，见 core/live_recovery.go）。

PUT /api/downloads/status— 批量更新状态

请求体：{ "ids": number[], "status": "waiting | downloading | success | failed | stopped" }

开始 / 停止

POST /api/downloads/:id/start— 开始下载

请求体：

{ "localPath": "/Users/me/Downloads/MediaGo", "deleteSegments": true }

• localPath：保存位置（绝对路径）；
• deleteSegments：m3u8 下载完成后是否删除分片.ts文件。

POST /api/downloads/:id/stop— 停止下载

响应：{}

枚举值

下载类型type

CLI 的download命令同样支持这些类型：--type参数可覆盖类型，缺省时按 URL 自动推断。

任务状态status

源码视角：路由与执行链路

路由注册

所有/api路由在 apps/core/internal/api/server/router.go 中统一注册：

• 下载任务路由挂在/api/downloads下（POST/GET ""、GET "/folders"、GET "/export"、GET "/active"、PUT "/status"、GET|PUT|DELETE "/:id"、POST "/:id/start|stop"、PUT "/:id/live"、GET "/:id/logs"），且仅在数据库可用（downloadHandler != nil）时注册；
• Discovery 系列路由包括POST /discoveries、GET /discoveries/:id、POST /discoveries/:id/cancel、POST /discoveries/:id/downloads、GET /discovery-executor/status；
• 此外还有GET /api/events（SSE）、GET /api/config、/api/tasks/*（无数据库环境下的任务端点）、/api/docker/*（Docker 模式的下载接口）等周边端点。

服务端执行链

POST /api/downloads的处理链为：handler 解析并校验 DTO → 调用DownloadTaskService.AddDownloadTasks落库 → 若startDownload为真则读取配置中的local与deleteSegments并调用StartDownloadIfNeeded→ 通过 SSE Hub 广播download-create。任务的实际下载则由内部的下载引擎（队列、运行器）执行，最终通过download-success/download-failed事件通知订阅者。

Discovery 超时与保留期

Discovery 任务的超时与保留期在 apps/core/internal/discovery 中实现：DefaultTimeoutMS = 20_000、MinTimeoutMS = 3_000、MaxTimeoutMS = 30_000、DefaultRetention = 10 * time.Minute。任务的过期时间在创建时即计算（ExpiresAt = now + timeout + retention，见 store.go），并在服务层以定时器调度取消（service.go）。

注意事项与最佳实践

• 端口确认：桌面版固定为39719；Docker 部署以-p映射为准，默认9900。调用前可用GET /healthy做健康检查（该路径在认证白名单中）。
• 事件流不包含进度：SSE 只推送状态变更类事件；需要百分比进度时应轮询GET /api/downloads/:id。
• 敏感信息处理：认证启用的 Docker 实例务必通过 HTTPS 或可信内网访问；useSessionCookies尽量保持默认false，避免凭据泄漏。
• 批量能力：POST /api/downloads与POST /api/discoveries/:id/downloads均支持批量，一次提交多个任务可减少连接开销。
• 结果时效：Discovery 结果保留约 10 分钟，请及时完成"检测 → 下载"交接，避免结果过期后返回 404。
• 重复 URL 防护：创建任务时若 URL 已存在会返回409 Conflict，可在客户端预先查询列表或在捕获冲突后复用已有任务 ID。

通过上述端点与事件机制，你可以完全绕过图形界面，用任何 HTTP 工具将 MediaGo 的下载能力集成到自己的脚本、服务或自动化工作流中。

• 音视频
• 桌面应用
• 后端