bili-auto

自动扫描 B 站收藏夹、获取 UP 主最新动态、将新视频入队，并以最高画质下载合并为 MP4 的异步工具。

免责声明

本项目仅供个人学习与技术研究使用，请勿用于任何商业或违法用途。

• 下载的视频版权归原作者及 B 站平台所有，请在 24 小时内删除，勿二次传播
• 使用本工具须遵守 哔哩哔哩用户协议 及相关法律法规
• 因使用本工具导致的账号封禁、法律责任等一切后果由使用者自行承担，与作者无关

功能

• 扫码登录：浏览器打开页面即可扫码，Cookie 存入 Redis，无需本地文件
• 收藏夹扫描：调用 /scan_fav 自动扫描指定收藏夹，增量入队新视频，同时自动删除已入队的收藏内容
• 最高画质下载：DASH 流优先选最高分辨率 + 最高码率，支持 4K；支持断点续传、失败自动重试
• 音视频合并：ffmpeg 合并后自动删除临时 m4s 文件；超大文件自动按大小分割
• UP 主动态监控：检查多个 UP 主是否有新视频，自动入队；支持获取 UP 主全部历史视频动态
• 关注列表：获取当前账号关注的所有 UP 主
• Redis 状态追踪：每个视频有独立 hash 记录下载状态（ready / downloading / done / failed），完成后自动过期
• 下载限流：每次最多处理配置数量视频，间隔可配，防止封禁
• 并发保护：扫描锁 + 下载锁，下载锁可查询实时进度
• Cookie 保活：提供保活接口，可配合定时任务维持登录态
• 健康检查：检查 Redis / ffmpeg / B 站接口 / 登录态
• API 鉴权：支持 X-API-Key 请求头鉴权
• 目录结构：有收藏夹名时为 下载目录/fav-收藏夹名/标题.mp4，否则为 下载目录/作者名/标题.mp4

依赖

• Python 3.10+
• Redis
• ffmpeg（需在系统 PATH 中）

安装

从 PyPI 安装（推荐）：

pip install bili-auto
# 或
uv add bili-auto

配置

复制示例文件并按需修改：

cp .env.example .env

完整环境变量参见 .env.example，核心配置如下：

使用

1. 启动 API 服务

bili-auto
# 或（开发模式）
uvicorn bili_auto.api:app --host 0.0.0.0 --port 8000

2. 扫码登录

浏览器打开 http://localhost:8000/login_qrcode，用 B 站 App 扫码，Cookie 自动写入 Redis。

3. 扫描收藏夹

curl "http://localhost:8000/scan_fav?folder_name=我的收藏" \
  -H "X-API-Key: YOUR_KEY"

扫描后将新增视频写入下载队列，同时从收藏夹中删除已入队的视频。

4. 查看收藏夹内容

curl "http://localhost:8000/fav_items?folder_name=我的收藏" \
  -H "X-API-Key: YOUR_KEY"

5. 执行下载

# CLI 方式
bili-downloader

# API 方式（后台执行，立即返回）
curl -X POST http://localhost:8000/download \
  -H "X-API-Key: YOUR_KEY"

# 查询下载进度
curl http://localhost:8000/download/status \
  -H "X-API-Key: YOUR_KEY"

每次运行最多下载 MAX_DOWNLOADS_PER_RUN 个视频。

6. UP 主动态监控

检查多个 UP 主是否有新视频（推荐定时调用）：

curl "http://localhost:8000/check_up_new_video?uids=123456&uids=789012" \
  -H "X-API-Key: YOUR_KEY"

逻辑：首次见到该 UID 时记录最新 dynamic_id；后续调用若 dynamic_id 变化则将新 BV 写入下载队列。

获取指定 UP 主全部历史视频动态并入队：

curl "http://localhost:8000/up_video_dynamic_all?uid=123456" \
  -H "X-API-Key: YOUR_KEY"

自动翻页获取全部视频动态，过滤已完成/已入队的 BV 后批量写入下载队列。

7. 获取关注列表

curl http://localhost:8000/my_followings \
  -H "X-API-Key: YOUR_KEY"

8. Cookie 保活

curl http://localhost:8000/keep_alive \
  -H "X-API-Key: YOUR_KEY"

9. 健康检查

curl http://localhost:8000/health

返回示例：

{
  "overall": "ok",
  "redis": "ok",
  "ffmpeg": "ffmpeg version 7.1 Copyright (c) 2000-2024 the FFmpeg developers",
  "logged_in": true,
  "bilibili_api": "ok"
}

10. 定时任务

配合 cron 定时执行：

# 每小时扫描一次收藏夹
0 * * * * curl -s "http://localhost:8000/scan_fav?folder_name=我的收藏" -H "X-API-Key: YOUR_KEY"

# 每 30 分钟检查一次 UP 主新视频
*/30 * * * * curl -s "http://localhost:8000/check_up_new_video?uids=123456&uids=789012" -H "X-API-Key: YOUR_KEY"

# 每小时触发一次下载
30 * * * * curl -s -X POST "http://localhost:8000/download" -H "X-API-Key: YOUR_KEY"

# 每 6 小时保活一次
0 */6 * * * curl -s "http://localhost:8000/keep_alive" -H "X-API-Key: YOUR_KEY"

API 路由一览

项目结构

bili-auto/
├── src/
│   └── bili_auto/
│       ├── __init__.py         # 包初始化
│       ├── api.py              # FastAPI 应用入口，路由定义（仅编排）
│       ├── bilibili_api.py     # B 站 API 交互层（登录轮询、收藏扫描、动态获取）
│       ├── config.py           # 统一配置管理（环境变量加载）
│       ├── downloader.py       # 下载核心（断点续传、队列消费、ffmpeg 合并/分割）
│       ├── redis_client.py     # Redis 连接与数据读写操作
│       ├── templates.py        # 登录页面 HTML 模板
│       └── utils.py            # 通用工具函数（WBI 签名、文件名清洗、码流选择等）
├── .env.example                # 配置示例
├── pyproject.toml
├── logs/                       # 日志目录（自动创建）
└── downloads/                  # 视频下载目录（自动创建）

Redis 数据结构

OpenAPI 文档

启动服务后，访问 http://localhost:8000/docs 查看 Swagger UI 在线文档。

TODO（计划功能）

• 下载通知：下载完成/失败时通过 Webhook（企业微信、飞书、Telegram 等）推送通知
• 简易 Web UI：一个轻量前端页面，展示队列状态、下载进度和历史记录
• 下载格式可选：支持仅下载音频流并转为 MP3
• 自动重试失败任务：定时扫描 failed 状态的视频并重新入队
• 带宽限制：支持配置下载速度上限，避免占满带宽
• Docker 部署：提供 Dockerfile 和 docker-compose.yml，一键部署
• 多账号支持：支持切换多个 B 站账号的 Cookie，按账号隔离下载目录