FluxDown REST API — 17800 端口上的任务队列管理接口

架构位置

FluxDown 所有形态（桌面端、Server、Android）都通过 Agent 层暴露本地 API——默认绑定 127.0.0.1:17800（Server 形态绑定 0.0.0.0:17800）。桌面端在「设置 → 本地服务器」里可以开启 LAN 访问，把绑定改成 0.0.0.0。

同一个端口上挂了三套协议：

路由组	协议	用途
`/api/v1/*`	REST（JSON）	官方管理 API
`/jsonrpc`	aria2 JSON-RPC	兼容现有 aria2 工具和 userscript
`/mcp`	MCP	给 AI agent 调用

认证

所有写操作和敏感操作需要 Bearer Token 认证：

Authorization: Bearer <token>

Token 从 Agent 首次启动时自动生成，存于：

桌面端 Windows：%APPDATA%\FluxDown\access_key.txt
Docker Server：容器内 /data/access_key.txt
Android：App 内设置页查看

可以在「设置 → 安全」里重置。

常用 REST 接口

加一个下载任务

curl -X POST http://127.0.0.1:17800/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.zip", "segments": 8}'

{"taskId": "t-abc123def", "status": "queued"}

列出所有任务

curl http://127.0.0.1:17800/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN"

返回所有任务的元信息、状态、进度、速度、剩余时间。

暂停 / 恢复 / 删除

curl -X POST http://127.0.0.1:17800/api/v1/tasks/t-abc123def/pause -H "Authorization: Bearer $TOKEN"
curl -X POST http://127.0.0.1:17800/api/v1/tasks/t-abc123def/resume -H "Authorization: Bearer $TOKEN"
curl -X DELETE http://127.0.0.1:17800/api/v1/tasks/t-abc123def -H "Authorization: Bearer $TOKEN"

队列相关

# 列出所有队列
curl http://127.0.0.1:17800/api/v1/queues -H "Authorization: Bearer $TOKEN"

# 暂停整个队列
curl -X POST http://127.0.0.1:17800/api/v1/queues/main/pause -H "Authorization: Bearer $TOKEN"

跨域与 Host 验证

默认只接受 Origin 和 Host 为 localhost 的请求——防止恶意网页偷用你的本地 FluxDown。桌面端开了 LAN 访问后会接受所有 Host 请求，但 Origin 验证仍然严格。

Interactive Documentation

FluxDown 提供 OpenAPI 格式的完整接口文档——在 Server 的 Web UI 里有 Swagger UI，可以直接交互式调用每个接口看参数和返回值。