BilibiliHistoryFetcher：哔哩哔哩数据管理工具使用教程

BilibiliHistoryFetcher 是一款功能全面的开源工具，专为哔哩哔哩用户打造，可实现观看历史数据的本地备份、深度分析及可视化展示。通过本工具，用户能够轻松完成哔哩哔哩数据备份，掌握观看历史分析的核心方法，构建个人专属的视频内容管理系统。

一、功能特性解析

1.1 历史记录全量备份

核心能力：完整抓取用户在哔哩哔哩的观看历史数据，包括视频标题、观看时长、观看时间等关键信息，并存储于本地 SQLite 数据库中。

适用场景：

• 担心平台数据丢失的用户
• 需要长期保存个人观看记录的研究者
• 希望离线访问历史记录的用户

技术原理：通过模拟浏览器请求获取用户数据，采用增量更新机制避免重复抓取，确保数据完整性的同时提升效率。

1.2 视频内容管理系统

核心能力：支持批量下载用户投稿视频及收藏夹内容，自动管理下载队列与进度，实现视频资源的本地归档。

适用场景：

• 需要离线观看视频的用户
• 希望珍藏优质内容的爱好者
• 网络条件不稳定的使用环境

1.3 多维度数据分析

核心能力：生成多维度的观看行为分析报告，包括观看时长统计、UP主偏好、观看时段分布等。

适用场景：

• 希望了解个人观看习惯的用户
• 需要制作年度观看总结的内容创作者
• 对自己的娱乐时间分配感兴趣的用户

1.4 智能任务调度

核心能力：支持配置定时任务，实现数据自动同步、邮件日志发送等自动化操作。

适用场景：

• 希望零维护成本运行工具的用户
• 需要远程监控工具运行状态的场景
• 追求自动化工作流的技术爱好者

二、快速上手指南

2.1 环境准备

系统要求：

• Python 3.10 或更高版本
• SQLite 3 数据库支持
• FFmpeg 多媒体框架

安装步骤：

1. 克隆项目仓库

   git clone https://gitcode.com/gh_mirrors/bi/BilibiliHistoryFetcher
   

2. 进入项目目录

   cd BilibiliHistoryFetcher
   

3. 安装依赖包

   pip install -r requirements.txt  # 安装所有必要的Python依赖
   

2.2 基础配置

配置文件路径：config/config.yaml

核心配置项：

# 用户认证配置
SESSDATA: "your_sessdata_value"  # 从浏览器Cookie中获取的用户认证信息

# 服务器配置
server:
  host: "0.0.0.0"  # 允许所有网络访问
  port: 8899       # API服务端口号

# 数据存储配置
database:
  path: "output/bilibili_history.db"  # 主数据库存储路径
  backup_interval: 7                  # 自动备份间隔(天)

⚠️ 注意事项：

• SESSDATA是获取用户数据的关键凭证，需定期更新
• 端口号若被占用，可修改为其他未使用的端口
• 建议定期手动备份output目录，防止数据丢失

2.3 启动服务

原生环境启动：

python main.py  # 启动主程序，默认加载config/config.yaml配置

Docker部署：

# 构建镜像
docker build -t bilibili-history:latest -f docker/Dockerfile.cpu .

# 启动容器
docker run -d -p 8899:8899 -v ./config:/app/config -v ./output:/app/output --name bili-history bilibili-history:latest

服务启动后，可通过访问 http://localhost:8899/docs 查看API文档。

三、核心功能操作指南

3.1 如何导出观看历史数据

操作步骤：

1. 确保服务已正常启动
2. 访问API文档页面 http://localhost:8899/docs
3. 找到 /export/history 接口，点击"Try it out"
4. 选择导出格式（支持JSON、CSV、Excel）
5. 设置时间范围参数，点击"Execute"

参数说明：

参数名	类型	描述
start_date	字符串	起始日期，格式YYYY-MM-DD
end_date	字符串	结束日期，格式YYYY-MM-DD
format	字符串	导出格式，可选json/csv/xlsx

💡 小技巧：若需要定期导出数据，可结合任务调度功能实现自动化导出。

3.2 如何批量下载收藏夹视频

配置下载参数：

download:
  max_concurrent: 3  # 最大并发下载数
  timeout: 300       # 下载超时时间(秒)
  save_path: "output/download_video"  # 视频保存路径
  quality: "720p"    # 下载画质选择

执行下载命令：

python scripts/collection_download.py --collection_id 123456  # 替换为实际收藏夹ID

📌 提示：收藏夹ID可从B站网页版收藏夹URL中获取，格式通常为https://space.bilibili.com/xxx/favlist?fid=收藏夹ID

3.3 如何生成年度观看报告

使用步骤：

1. 确保已积累至少一个月的观看数据
2. 执行分析脚本

   python scripts/analyze_bilibili_history.py --year 2023  # 指定年份
   

3. 报告生成路径：output/analytics/年度报告_2023.html
4. 使用浏览器打开HTML文件查看完整报告

报告内容：

• 年度观看总时长统计
• 最常观看的UP主排名
• 观看时段分布热力图
• 视频类型偏好分析

3.4 如何配置定时同步任务

编辑调度配置文件：config/scheduler_config.yaml

tasks:
  - name: "daily_data_sync"       # 任务名称
    function: "data_sync.sync"    # 执行函数
    schedule: "0 2 * * *"         # 每天凌晨2点执行
    enabled: true                 # 启用任务
    
  - name: "weekly_backup"         # 任务名称
    function: "backup.run"        # 执行函数
    schedule: "0 3 * * 0"         # 每周日凌晨3点执行
    enabled: true                 # 启用任务

启动调度服务：

python scripts/scheduler.py  # 启动任务调度服务

四、高级技巧与最佳实践

4.1 数据迁移与备份策略

完整迁移步骤：

1. 停止当前运行的服务
2. 压缩整个output目录

   zip -r output_backup.zip output/  # 创建备份压缩包
   

3. 在新环境中解压备份文件
4. 确保文件权限正确

   chmod -R 755 output/  # 设置目录权限
   

备份频率建议：

• 日常使用：每周一次完整备份
• 重要数据：启用自动备份功能，设置3-7天的备份间隔
• 迁移前：务必执行手动备份

4.2 高效管理下载内容

空间管理策略：

• 设置自动清理规则，定期删除观看次数少的视频
• 对重要视频进行标记，避免误删除
• 配置视频压缩选项，平衡画质与存储空间

命令示例：

# 清理30天前下载且观看次数少于2次的视频
python scripts/clean_data.py --type video --days 30 --view_count 2

4.3 问题排查与日志分析

查看运行日志：

tail -f output/logs/app.log  # 实时查看应用日志

常见问题解决：

问题现象	可能原因	解决方案
无法获取历史数据	SESSDATA过期	重新获取并更新配置文件
下载速度慢	网络限制	调整并发数或使用代理
报告生成失败	数据量过大	分时段生成或增加系统内存

4.4 社区支持与资源

遇到问题时，可通过以下方式获取帮助：

扫码加入QQ交流群（群号：1030089634），获取最新更新信息和技术支持。

五、总结

BilibiliHistoryFetcher 作为一款强大的哔哩哔哩数据管理工具，不仅能够帮助用户实现观看历史的安全备份，还提供了丰富的数据分析和内容管理功能。通过本教程的指导，您可以快速上手并充分利用工具的各项特性，构建属于自己的个性化视频数据管理系统。

无论是普通用户还是技术爱好者，都能从中找到适合自己的使用方式，让数据管理变得简单高效。随着工具的不断更新迭代，更多实用功能将逐步加入，敬请期待。