API Server and Docker

API 服务器与 Docker 部署 (API Server & Docker)

BBDown 内置了轻量级 HTTP API 服务器模式（BBDown serve），允许其他应用（如 Web 前端、NAS 下载中心、自动化脚本、移动客户端）通过 RESTful API 向 BBDown 提交下载任务并监控下载进度。

---

1. 启动 API 服务器

基本启动

BBDown serve

默认将在本地回环地址 http://127.0.0.1:23333 启动服务，最大并发任务数为 3。

命令行选项

短选项	长选项	默认值	说明
-l	--listen	http://127.0.0.1:23333	监听地址与端口
	--max-concurrent	3	最大并发下载任务数
	--serve-token	(无)	API 访问鉴权令牌

生产环境与对外暴露示例

BBDown serve -l http://0.0.0.0:23333 --max-concurrent 5 --serve-token "your_secret_token"

---

2. 安全设计与防护规范

1. 非回环监听安全校验：当服务监听地址设为非回环（如 0.0.0.0 或局域网 IP）时，必须配置 --serve-token，否则程序会拒绝启动以保护系统安全。
2. 请求头鉴权：配置 --serve-token 后，客户端的所有 API 请求必须携带 X-Serve-Token: <token> 请求头，否则将直接返回 401 Unauthorized。
3. 入参安全过滤：通过 API 提交的任务（/add-task）中，任何可能引发任意代码执行、凭据泄露或路径穿越的参数字段（如 ffmpegPath、aria2cArgs、workDir、insecure、host 白名单覆盖等）均会被服务端强制忽略。
4. 反向代理建议：内置服务仅支持 HTTP；在公网或跨网络环境下部署时，请务必前置 Nginx 或 Caddy 等 HTTPS 反向代理。

---

3. REST API 接口规范

所有返回均为标准 JSON 格式。如果开启了 --serve-token，请在请求头附带 X-Serve-Token。

3.1 添加任务

• Endpoint: POST /add-task
• Request Body: JSON 对象（至少包含 Url 字段，可选用 MyOption 字段）

  {
    "Url": "https://www.bilibili.com/video/BV1qt4y1X7TW",
    "UseTvApi": true,
    "DownloadDanmaku": true,
    "SelectPage": "1-3"
  }

• Response:
  • 202 Accepted：成功入队，返回任务唯一标识 JobId：

    { "TaskId": "d3b07384-d113-469e-a864-7e9b04f7c123" }

  • 400 Bad Request：请求体解析失败或参数无效。
  • 429 Too Many Requests：任务队列达到上限（最大并发槽位 × 9）。

3.2 获取全部任务

• Endpoint: GET /get-tasks/
• Response: 200 OK，包含运行中与已完成的任务集合。

3.3 获取正在运行的任务

• Endpoint: GET /get-tasks/running
• Response: 200 OK，当前正在下载中的任务数组。

3.4 获取已完成的任务

• Endpoint: GET /get-tasks/finished
• Response: 200 OK，所有已完成（成功或失败）的任务数组。

3.5 查询特定任务详情

• Endpoint: GET /get-tasks/{id}
• Path Param: {id} 为添加任务时返回的 TaskId（JobId），或兼容的视频 Aid。
• Response: 200 OK 返回 DownloadTask 详情对象；若未找到返回 404 Not Found。

3.6 取消任务

• Endpoint: POST /cancel/{id}
• Response:
  • 200 OK：取消成功。
  • 404 Not Found：任务不存在或已完成。

3.7 清理已完成的任务记录

• DELETE /remove-finished：清理所有已完成的任务记录。
• DELETE /remove-finished/failed：仅清理所有失败的任务记录。
• DELETE /remove-finished/{id}：清理指定 ID 的已完成任务记录。

---

4. Docker 容器化部署

本项目提供了基于 Native AOT 编译的超轻量 Docker 镜像，无需在容器内安装 .NET 运行时。

4.1 构建镜像

docker build -t bbdown .

4.2 运行容器

docker run -d \
  --name bbdown \
  -p 23333:23333 \
  -v /volume1/downloads:/app/downloads \
  -v /volume1/bbdown_data:/app/data \
  bbdown \
  serve -l http://0.0.0.0:23333 --serve-token "your_secure_token"

挂载说明：

• /app/downloads：挂载宿主机的下载存储目录。
• /app/data：挂载存放 BBDown.data（账号登录凭据）及 device.wvd（DRM 凭证）的目录。