微信视频号下载器 API 服务完全指南:从启动配置到下载任务提交
微信视频号下载器 API 服务完全指南:从启动配置到下载任务提交
导读
wx_channels_download(微信视频号下载器)在启动后会默认开启一个本机 API 服务,下载器前端页面通过该服务提交下载任务,由 API 服务在后台完成下载。本文以 docs/config/api.md 为骨架,结合仓库源码深入讲解 config.yaml 中 api 段的三个核心配置项(protocol、hostname、port)及其底层生效原理,并展开介绍 API 服务实际暴露的下载任务、视频号数据、公众号、MCP、代理与证书等接口能力,帮助读者把"本地一键下载"扩展为可编程、可远程控制的下载能力。
API 服务是什么:下载任务的"后台调度中枢"
在默认架构中,视频号页面上点击下载按钮后,注入到页面中的前端脚本并不会直接写文件,而是通过 HTTP 请求将下载任务提交给本机 API 服务,由 API 服务在后台创建任务、调度下载并回传进度。这一设计使得:
- 下载与页面解耦,页面关闭后任务仍在后台继续;
- 下载任务具备完整的生命周期管理(创建、暂停、恢复、重试、删除);
- 外部程序可以通过 HTTP 接口复用下载器的全部能力。
这一机制在源码中得到了印证:internal/api/server.go 中的 APIServer.Start() 使用 net.Listen("tcp", addr) 监听地址并启动 http.Server;路由注册集中在 internal/api/routes.go,覆盖下载任务、视频号数据、公众号、文件传输助手、MCP、代理与证书等数十个端点。
通过 config.yaml 配置 API 服务
API 服务地址通过 config.yaml 配置,默认监听本机。完整配置段如下:
api:
protocol: http
hostname: 127.0.0.1
port: 2022
三个配置项的含义:
| 配置项 | 默认值 | 说明 |
|---|---|---|
protocol |
http |
API 服务协议(协议头)。该字段在配置注册时被标记为只读(Readonly: true),运行时不可通过配置接口修改 |
hostname |
127.0.0.1 |
API 服务监听地址。设为 0.0.0.0 时监听所有 IPv4 接口;此时本机前端和其他本机客户端仍通过 127.0.0.1 连接 |
port |
2022 |
API 服务端口 |
这些默认值在 internal/config/config.go 的字段注册中定义:api.protocol 默认 "http",api.hostname 默认 "127.0.0.1",api.port 默认 2022。完整的模板参考 internal/config/config.template.yaml。
hostname 设为 0.0.0.0 时客户端如何连接
监听地址与客户端连接地址并不总是同一个值。源码中专门提供了两个辅助函数解决这一差异:
APIClientHostname(bind_hostname):当绑定地址为空,或解析后为未指定地址(如0.0.0.0)时,返回127.0.0.1,因为未指定地址只能用于监听,不能作为连接目标;APIClientOrigin(protocol, bind_hostname, port):基于上述逻辑拼接出客户端可用的 HTTP origin,如http://127.0.0.1:2022。
实现见 internal/config/config.go。这正是文档中"设为 0.0.0.0 时监听所有 IPv4 接口;本机前端和其他本机客户端仍通过 127.0.0.1 连接"的代码级依据。
配置如何注入前端页面
下载器通过本地代理拦截视频号页面并注入脚本,同时将 API 地址以变量形式注入页面。在 internal/adapter/wxchannels/adapter.go 的 new_interceptor_config 中:
api_protocol := c.GetString("api.protocol")
api_bind_hostname := c.GetString("api.hostname")
api_port := c.GetInt("api.port")
// ...
"apiHost": config.APIClientHost(api_bind_hostname, api_port),
"apiOrigin": config.APIClientOrigin(api_protocol, api_bind_hostname, api_port),
"apiProtocol": api_protocol,
也就是说,无论 hostname 配置成什么,页面脚本拿到的 apiHost 都被规范化为本机可连接的地址(通常是 127.0.0.1:2022),从而保证"0.0.0.0 监听 + 本机连接"的体验。
API 服务提供了哪些接口
API 服务基于 Gin 框架构建(internal/api/client.go),所有路由统一注册在 internal/api/routes.go。按功能可划分为以下几类:
1. 下载任务 v1 接口(核心)
路由注册于 internal/api/routes.go,完整接口清单:
| 接口 | 方法 | 用途 |
|---|---|---|
/api/v1/download_task/prepare |
POST | 预览/准备下载任务 |
/api/v1/download_task/prepare_by_url |
POST | 按 URL 预览下载任务 |
/api/v1/download_task/create |
POST | 批量创建下载任务 |
/api/v1/download_task/create_by_url |
POST | 按 URL 批量创建任务 |
/api/v1/download_task/start |
POST | 启动任务 |
/api/v1/download_task/pause |
POST | 暂停任务 |
/api/v1/download_task/resume |
POST | 恢复任务 |
/api/v1/download_task/retry |
POST | 重试任务 |
/api/v1/download_task/delete |
POST | 删除任务(可携带 delete_files 清理本地文件) |
/api/v1/download_task/start_all / pause_all |
POST | 批量启动 / 批量暂停 |
/api/v1/download_task/clear / clear_all |
POST | 清理任务 |
/api/v1/download_task/check_files |
POST | 检查任务文件是否存在 |
/api/v1/download_task/list |
GET | 任务列表 |
/api/v1/download_task/detail |
GET | 任务详情 |
/ws/v1/download_task |
GET | WebSocket 订阅任务状态推送 |
请求与响应结构定义见 internal/api/handler_download_task.go,对应的 OpenAPI 文档位于 docs/public/openapi/download_task。
批量创建任务的请求示例(来自 docs/public/openapi/download_task/create.json):
{
"objects": [
{
"platform": "wxchannels",
"content": {
"id": "14545102784038246591"
},
"download_dir": "downloads",
"auto_start": true,
"config": {
"download_cover": true,
"existing_action": "skip"
}
}
]
}
其中 existing_action 可选 skip、duplicate、overwrite,用于处理已存在相同内容任务的情况;对应全局默认值由 download.defaultActionWhenExisting 配置项控制(见 internal/config/config.go)。
2. 视频号数据接口
通过 API 可以直接拉取视频号数据,而无需手工打开页面复制链接。例如 docs/public/openapi/channels/feed_profile.json 定义的"获取视频号指定视频详情"接口,支持 oid+nid、url 或 eid 三种定位参数组合,返回视频的完整信息(标题、封面、播放地址、多档清晰度 spec、作者信息、发布时间等)。
需要注意的是,视频号相关接口依赖页面保持打开状态:OpenAPI 文档在 docs/public/openapi/index.json 中说明,调用时需保持视频号页面打开,否则会提示 {"code":400,"msg":"请先初始化客户端 socket 连接"};出现该提示时打开视频号页面即可,若已打开则刷新一下。
3. 公众号接口与 MCP 接口
- 公众号相关接口同样要求保持任意公众号文章页面打开的状态(docs/public/openapi/index.json),相关路由与后端实现在 internal/adapter/wxmp;
- MCP(Model Context Protocol)服务可通过
/mcp端点以 HTTP 方式访问,也可通过POST /api/mcp/enable、POST /api/mcp/disable按需启停(internal/api/routes.go),配套文档见 docs/feature/mcp.md 与 docs/cli/mcp.md。
4. 代理、证书与系统配置接口
/api/proxy/* 系列提供代理启停、系统代理切换、根证书安装/卸载/替换等能力;/api/certificate/*、/api/cookies/update 等端点分别管理证书与 CookieCloud 数据同步。此外 GET /api/config 可读取当前配置全量 schema 与生效值,POST /api/config 可修改配置。
用 /api/status 验证 API 服务是否正常运行
API 服务提供 GET /api/status 健康检查端点(实现见 internal/api/routes.go),返回结构包含版本号、各服务运行状态、API 与代理的实际监听地址及端口探测结果:
{
"code": 0,
"msg": "ok",
"data": {
"version": "v260613",
"server_statuses": { "api": "running", "interceptor": "running" },
"api": {
"addr": "127.0.0.1:2022",
"listening": true,
"status": "running"
},
"proxy": {
"addr": "127.0.0.1:2023",
"listening": true,
"status": "running"
}
}
}
其中 listening 字段通过 TCP 拨测(500ms 超时)判断端口是否可连接(internal/api/routes.go),是排查"API 服务是否真的起来了"的最直接手段。
通过 WebSocket 订阅下载进度
/ws/v1/download_task 将连接升级为 WebSocket,用于实时接收任务状态。消息协议定义在 docs/public/openapi/download_task/ws.json:
- 未指定
task_id时接收全部任务事件;指定后只接收该任务的task_create、task_upsert、task_update、task_delete事件,并在连接建立时立即推送一次task_upsert; - 客户端可发送
{"type":"subscribe","task_id":42}动态切换为单任务订阅; - 服务端每 10 秒发送 Ping,30 秒未收到 Pong 会断开连接;
- 服务端消息类型:
task_create/tasks与task_upsert/tasks携带完整任务记录,task_update/updates携带可变状态与进度(status、size、downloaded、speed、progress),task_delete/task_ids携带被删除的 ID,task_stats/stats携带聚合计数。
{"type": "task_stats", "stats": {"total": 5, "downloading": 1, "paused": 1, "waiting": 1, "finished": 2, "error": 0}}
跨机器远程下载:download.remoteServer
API 服务默认只服务本机,但通过 download.remoteServer 配置段可以将本机下载器作为"远程下载服务器",供局域网内另一台机器上的下载器提交任务(docs/config/download.md):
download:
remoteServer:
enabled: false
protocol: "http"
hostname: "192.168.1.2"
port: 2022
enabled:是否启用远程服务下载,默认false;protocol/hostname/port:远程 API 服务的协议、地址与端口(与api段对应)。
前端脚本在 new_interceptor_config 中会将 remoteServerOrigin(如 http://192.168.1.2:2022)一并注入页面(internal/adapter/wxchannels/adapter.go),实现"本机点击、远程机器落盘"的下载模式。该能力要求远程机器的 API 服务监听地址能被局域网访问(即 api.hostname 需配置为 0.0.0.0 或局域网 IP)。
通过 API 修改配置(含重启确认机制)
POST /api/config 允许以编程方式修改配置(实现见 internal/api/handler_config.go)。请求体为:
{
"values": {
"api.port": 3022
}
}
处理流程为:校验配置项是否存在 → 类型规范化(config.NormalizeValue)→ 与当前值比较 → UpdateAndSave 原子写入 → 生成配置摘要 → 安排应用重启。响应会返回 restart_token 与 next_action 指引,提示调用方在连接恢复后通过 GET /api/restart/status?restart_token=... 确认重启完成、config_applied=true。
另外,配置 schema 中 api.protocol 被标记为 Readonly: true(internal/config/config.go),意味着协议头只能通过手动编辑 config.yaml 修改,不能通过配置接口动态变更。
常见问题排查
- 启动 API 服务失败,提示端口被占用:
APIServer.Start()中监听失败会返回"启动API服务失败,端口被占用"(internal/api/server.go)。此时修改api.port或释放占用端口的进程即可。 - 视频号接口返回"请先初始化客户端 socket 连接":如 OpenAPI 文档所述,保持视频号页面打开并刷新。
- 修改了 hostname/port 但前端仍连旧地址:配置在应用启动时一次性读取并注入前端变量(
apiHost、apiOrigin),修改配置后需要重启应用生效。 - 想从局域网其他设备调用 API:将
api.hostname设为0.0.0.0,本机客户端仍走127.0.0.1,远程设备则通过http://<本机局域网IP>:2022访问,同时确保防火墙放行对应端口。
小结
api 配置段虽然只有三个字段,却是整个下载器"页面点击 → 后台调度 → 文件落盘"架构的枢纽:protocol 定义传输协议头(默认 http 且只读),hostname 定义监听地址(0.0.0.0 通配与 127.0.0.1 本机回环的差异化处理有源码级规范),port 定义服务端口(默认 2022)。在此基础上,API 服务对外提供下载任务全生命周期管理、视频号与公众号数据查询、WebSocket 实时进度、配置热修改、MCP 服务等能力,配合 download.remoteServer 还能把任意一台运行下载器的机器变成局域网下载服务器,值得深入探索与二次开发。
进一步阅读:docs/config/api.md、docs/config/download.md、docs/public/openapi/index.json(完整接口清单)、internal/api/routes.go(路由实现)、internal/config/config.go(配置注册与默认值)。