Media-Hoarder：基于Python的自动化媒体抓取与管理框架实战

1. 项目概述一个面向数字内容收藏家的自动化工具箱如果你和我一样是个喜欢在互联网上“囤积”数字内容的人——无论是精彩的视频教程、值得反复品味的电影、播客节目还是那些随时可能消失的珍贵文档——那么你一定对“收藏容易管理难”这句话深有体会。手动下载、重命名、整理元数据、归档备份这套流程不仅枯燥耗时而且极易出错最终导致你的数字仓库变成一片混乱的“数据沼泽”。今天要聊的这个开源项目theMK2k/Media-Hoarder正是为了解决这个痛点而生。它不是一个单一的软件而是一个高度模块化、可编程的自动化媒体抓取与管理框架其核心目标是将用户从繁琐的重复劳动中解放出来构建一个井然有序、可随时访问的个人媒体库。简单来说Media-Hoarder 是一个用 Python 编写的工具集它允许你通过编写配置文件YAML来定义“抓取任务”。你可以告诉它“去关注这个 YouTube 频道每当有新视频发布时就自动用最高质量下载下来然后按照‘频道名/年份-月份/视频标题’的格式整理好再从 The Movie Database (TMDB) 或 TheTVDB 等网站拉取影片信息、封面和简介最后存放到我的 NAS 指定文件夹。” 它就像一个不知疲倦的、严格遵循你指令的数字管家。这个项目特别适合技术爱好者、数据管理员、自媒体从业者以及任何希望拥有一个私有化、高质量媒体库的用户。它不提供图形界面一切通过代码和配置驱动这赋予了它极大的灵活性和强大的能力但同时也意味着需要一定的命令行和 YAML 配置基础。2. 核心架构与设计哲学解析2.1 模块化与管道式设计Media-Hoarder 的设计非常清晰采用了经典的“输入-处理-输出”管道模式。整个系统由多个独立的模块组成每个模块负责一项特定的功能模块之间通过标准化的数据格式通常是包含媒体文件路径和元数据的字典对象进行通信。这种设计带来了几个显著优势首先是可维护性。下载功能出问题了你只需要检查downloader模块如 yt-dlp 的封装。元数据获取不准那就聚焦在metadata模块如 TMDB 刮削器。各个模块解耦互不影响。其次是可扩展性。项目默认支持 YouTube、BitChute 等平台但如果你需要从某个小众网站抓取内容理论上你可以自己实现一个对应的downloader模块只要它遵循项目定义的接口规范就能无缝集成到现有的任务管道中。处理流程也同样可定制你可以在下载后插入自定义的脚本模块进行水印检测、音频转码、敏感内容过滤等操作。最后是灵活性。管道不是固定的。你可以定义一个简单的管道下载 - 重命名 - 移动。也可以定义一个复杂的管道下载 - 商业广告检测与静音 - 提取关键帧生成缩略图 - 从多个源获取元数据并合并 - 硬链接到媒体服务器目录 - 发送通知到 Telegram。这一切都通过 YAML 配置文件来组合和排序。2.2 配置即代码的核心理念Media-Hoarder 将“配置即代码”的理念发挥得淋漓尽致。所有抓取规则、处理流程、存储路径都定义在一个结构化的 YAML 配置文件中。这意味着版本控制你的整个媒体收藏策略配置可以像软件代码一样用 Git 进行管理。你可以回溯历史、创建分支例如为不同类型的媒体创建不同的配置策略、协同工作。可重复性与可移植性一旦配置好一个任务例如订阅某个播客你就可以在任何安装了 Media-Hoarder 的机器上复现完全相同的抓取行为。备份和迁移整个系统变得非常简单只需备份配置文件和任务数据库。动态与条件化配置支持变量和条件判断。例如你可以设置一个变量${date}代表当前日期用在文件夹命名中。你还可以设置条件如果视频时长大于1小时就归类到“电影”文件夹否则归类到“短视频”文件夹。这种设计使得 Media-Hoarder 超越了普通下载器成为一个声明式的媒体资产管理框架。你声明最终想要的状态“我的库中要有这个频道的所有视频并按季整理好”而不是编写每一步操作的命令式脚本。注意对于不熟悉 YAML 的用户初期学习曲线会稍陡。但一旦掌握其带来的效率和清晰度是无可比拟的。建议从修改现成的示例配置开始。3. 核心组件深度拆解与实操要点3.1 任务定义与触发器任务Task是 Media-Hoarder 的核心工作单元。每个任务在配置文件中独立定义包含以下关键部分name: 任务唯一标识符用于日志和数据库记录。url或feed: 抓取的目标源。可以是单个视频 URL也可以是 RSS 订阅源、频道主页 URLMedia-Hoarder 会尝试解析出视频列表。trigger: 定义任务何时执行。这是自动化关键。interval: 最简单的定时触发如interval: 3600表示每3600秒1小时检查一次。cron: 使用更强大的 cron 表达式例如cron: “0 2 * * *”表示每天凌晨2点执行。manual: 仅手动触发。filters: 下载过滤器用于精细化控制抓取内容。这是避免“囤积垃圾”的关键。min_duration/max_duration: 过滤时长不符合要求的视频。match_title: 使用正则表达式匹配标题只下载标题包含特定关键词的视频。exclude_title: 排除标题包含特定垃圾关键词的视频。date_after: 只下载某个日期之后发布的视频。pipeline: 定义该任务需要执行的处理模块列表及顺序。实操心得在定义filters时正则表达式是你的利器。例如你想下载某个科技频道所有关于“Python”的教程但排除掉那些标题带有“直播回放”的可以这样配置filters: match_title: “(?i)python.*(教程|入门|进阶)” # (?i)表示忽略大小写 exclude_title: “直播回放|Live Stream”建议先在 regex 测试网站上验证你的表达式再放入配置。3.2 下载器模块详解Media-Hoarder 自身不实现下载逻辑而是作为“外壳”集成并管理业界最强大的下载工具。目前其核心是yt-dlp它是 youtube-dl 的一个更活跃的分支支持数以千计的网站。在配置中你可以在pipeline的downloader阶段配置 yt-dlp 的几乎所有参数pipeline: - name: downloader config: format: “bestvideo[height1080]bestaudio/best[height1080]” # 优先选择1080p及以下的最佳格式 outtmpl: “{{uploader}}/{{upload_date}} - {{title}}.{{ext}}” # 输出模板 cookies-from-browser: chrome # 使用Chrome浏览器的cookies用于下载需要登录的会员内容 throttle-rate: 2M # 限制下载速度避免占满带宽重要注意事项格式选择format参数极其强大但也复杂。上述示例是一个常用策略它告诉 yt-dlp“首先尝试找视频流bestvideo分辨率不超过1080p的和最好的音频流bestaudio合并如果不行就直接找分辨率不超过1080p的最佳单文件best”。如果你追求极致体积可以使用“best[height720]”。Cookies 使用对于需要会员或登录才能观看/下载的内容通过cookies-from-browser导入浏览器 Cookies 是合法获取内容的关键一步。请确保你拥有内容的观看权限。网络与伦理务必遵守目标网站的服务条款ToS。不要用于大规模盗版或对服务器造成压力的滥用行为。合理的个人存档和备份通常是可接受的但法律和道德界限需自行把握。3.3 元数据刮削与整理模块下载下来的视频文件往往是孤立的缺少海报、简介、演员表等信息。Media-Hoarder 的metadata模块负责将这些“血肉”填充到“骨架”上。数据源主要依赖 TMDB电影/电视剧、TVDB电视剧、MusicBrainz音乐等开放数据库。你需要去这些网站申请免费的 API 密钥并配置在 Media-Hoarder 的全局设置中。匹配逻辑模块会尝试用文件名、文件夹名去数据库搜索匹配。例如文件The.Matrix.1999.1080p.mkv会被成功识别为电影《黑客帝国》。为了提高匹配率建议在下载模板outtmpl中就包含标准化的片名和年份。输出刮削到的元数据会以标准格式保存通常是与媒体文件同名的.nfo文件XML格式以及下载的海报poster.jpg、背景图fanart.jpg等。这种格式被 Kodi, Jellyfin, Plex 等主流媒体服务器广泛支持。配置示例pipeline: - name: metadata config: type: “movie” # 或 “tv”, “music” source: “tmdb” language: “zh-CN” # 优先获取中文元数据 nfo: true poster: true fanart: true踩坑记录自动匹配并非100%准确尤其是对于非英文内容、名字常见的视频或系列剧集。Media-Hoarder 通常会将匹配结果包括可能出错的记录在日志或数据库中。对于重要的媒体库建议定期审查自动刮削结果对于匹配错误的可以手动指定一个正确的 ID如 TMDB ID覆盖配置或者直接手动修正生成的.nfo文件。3.4 后处理与输出模块这是管道中最后也是最灵活的一环负责文件的最终安置和后续动作。renamer: 根据元数据将文件重命名为媒体服务器喜爱的格式如Movie Name (Year)/Movie Name (Year).mkv或TV Show Name/Season 02/TV Show Name - S02E05 - Episode Title.mkv。mover/hardlinker: 将文件移动或硬链接到最终媒体库目录。硬链接是一个关键技巧它允许同一个文件数据块在文件系统中存在多个路径入口但不占用额外空间。这意味着你可以在“下载暂存区”保留一份原始文件供 Media-Hoarder 管理同时在“媒体库目录”创建一个硬链接供 Jellyfin 扫描播放两者同步更新空间只占一份。notifier: 任务完成后发送通知支持 Telegram、Discord、电子邮件等让你及时了解抓取状态。自定义脚本你可以插入exec模块运行任意 Shell 或 Python 脚本。例如调用ffmpeg进行无损压缩、为视频文件生成章节标记、或者将信息写入你自己的数据库。4. 完整部署与工作流搭建实录4.1 基础环境部署假设我们在一个 Linux 服务器如 Ubuntu 22.04上部署作为7x24小时运行的后台服务。步骤1安装系统依赖sudo apt update sudo apt install -y python3-pip python3-venv git ffmpeg # ffmpeg 是 yt-dlp 处理多格式流合并所必需的步骤2克隆项目与创建虚拟环境git clone https://github.com/theMK2k/Media-Hoarder.git cd Media-Hoarder python3 -m venv venv source venv/bin/activate pip install -r requirements.txt步骤3配置全局设置项目根目录下通常有一个config.yaml.example示例文件复制并修改它cp config.yaml.example config.yaml编辑config.yaml关键配置包括database_path: SQLite 数据库文件位置用于存储任务状态和历史。download_dir: 临时下载目录。library_dir: 最终媒体库目录。各个元数据源的 API 密钥。4.2 编写第一个抓取任务让我们创建一个具体的任务配置文件tasks/my_youtube_subscriptions.yaml。tasks: - name: “tech_tutorials_channel” url: “https://www.youtube.com/c/SomeTechChannel” # 替换为目标频道URL trigger: cron: “0 */6 * * *” # 每6小时检查一次 filters: min_duration: 300 # 只下载5分钟以上的视频 exclude_title: “(?i)short|#shorts|预告” # 排除短视频和预告 pipeline: - name: downloader config: format: “best[height1080]” outtmpl: “YouTube/{{uploader}}/{{upload_date}} - {{title}}.{{ext}}” write-thumbnail: true # 同时下载封面图 - name: metadata # YouTube视频通常不适用TMDB这里可以添加一个自定义脚本模块将描述等信息写入文件 config: type: “custom” - name: renamer config: template: “{{upload_date}} {{title}}” # 简单的重命名保留日期和标题 - name: mover config: dest: “{{ global.library_dir }}/YouTube/{{ uploader }}”4.3 运行与调度Media-Hoarder 提供了命令行工具来管理任务。测试任务在正式加入调度前先手动运行一次检查流程是否顺畅输出是否符合预期。python -m media_hoarder.cli run --task tech_tutorials_channel --config tasks/my_youtube_subscriptions.yaml导入任务将任务配置导入到中央数据库。python -m media_hoarder.cli import --file tasks/my_youtube_subscriptions.yaml设置定时服务最可靠的方式是使用系统的 cron 服务。首先创建一个启动脚本run_hoarder.sh#!/bin/bash cd /path/to/Media-Hoarder source venv/bin/activate python -m media_hoarder.cli run-all # 运行所有已导入且到期的任务赋予执行权限chmod x run_hoarder.sh编辑 crontabcrontab -e添加一行例如每30分钟运行一次*/30 * * * * /path/to/Media-Hoarder/run_hoarder.sh /path/to/Media-Hoarder/cron.log 21现在你的自动化媒体收藏库就开始默默工作了。5. 高级技巧与疑难问题排查5.1 性能优化与资源管理并发控制在config.yaml的全局设置中可以配置max_concurrent_downloads和max_concurrent_tasks防止同时发起过多网络连接避免被目标网站封禁或拖垮本地网络。磁盘空间管理Media-Hoarder 本身不包含自动清理旧文件的功能。你需要结合操作系统的工具例如在pipeline最后添加一个exec模块调用脚本检查download_dir目录大小如果超过阈值则按时间删除最旧的文件。或者使用logrotate来管理日志文件。网络优化对于海外资源可以考虑在运行 Media-Hoarder 的服务器上配置更优的网络环境。同时合理设置throttle-rate可以避免影响其他关键服务。5.2 复杂匹配与元数据修正当自动刮削失败时你需要手动干预。Media-Hoarder 的任务数据库会记录每次抓取的状态。查看任务历史使用 CLI 工具或直接查询 SQLite 数据库找到匹配失败的任务 ID。手动指定 ID对于电影或剧集你可以在任务配置中通过metadata模块的附加配置直接指定 TMDB 或 TVDB 的 ID覆盖自动搜索。- name: metadata config: type: “movie” tmdb_id: 603 # 强制指定为《黑客帝国》的TMDB ID使用第三方工具辅助像FileBot这样的工具拥有非常强大的文件名识别和重命名能力。你可以将 Media-Hoarder 的下载目录设置为 FileBot 的监视目录让 FileBot 进行二次精校然后再由 Media-Hoarder 的mover模块移入媒体库。这是一种“混合工作流”。5.3 常见错误与解决方案速查表问题现象可能原因排查步骤与解决方案下载失败报错 “Unable to extract video data” 或 “Unsupported URL”1. 目标网站结构变更。2. 该网站需要特定提取器或登录。1. 首先更新 yt-dlp:pip install –upgrade yt-dlp。2. 检查 yt-dlp 是否支持该网站yt-dlp –list-extractors。3. 尝试在downloader配置中添加cookies-from-browser。任务运行一次后不再触发1. Cron 服务未正确运行。2. 任务触发器配置错误。3. 数据库任务状态异常。1. 检查系统 cron 日志 (sudo grep CRON /var/log/syslog)。2. 手动运行python -m media_hoarder.cli run-all看是否有输出。3. 检查数据库tasks表中对应任务的next_run字段是否更新到了未来时间。元数据刮削全部失败1. API 密钥无效或过期。2. 网络无法访问元数据网站。3. 文件名无法匹配。1. 去 TMDB/TVDB 官网检查 API 密钥状态。2. 在服务器上curl测试 API 端点连通性。3. 尝试手动使用一个标准文件名如Movie Name (1999).mp4测试刮削。硬链接失败提示 “Cross-device link”mover模块配置为hardlink但源目录和目标目录位于不同的文件系统或磁盘分区上。硬链接不能跨文件系统。解决方案1) 将源和目标放在同一分区或 2) 将mover配置改为copy占用双倍空间或move原始文件会消失。下载速度极慢1. 目标网站限速。2. 本地网络问题。3. 服务器地理位置不佳。1. 在downloader配置中增加sleep-interval模拟人类操作避免被封。2. 使用throttle-rate排除本地问题。3. 考虑在网络条件更好的机器或云端运行。5.4 安全与隐私考量配置安全config.yaml中包含 API 密钥务必确保其文件权限设置为仅当前用户可读 (chmod 600 config.yaml)。不要将配置文件提交到公开的 Git 仓库。数据安全定期备份你的任务数据库 (database_path指定的文件)。这个数据库记录了所有任务的抓取历史丢失后可能导致重复下载。合法性再次强调请仅对你拥有观看权或明确允许下载的内容进行自动化抓取。尊重创作者和平台方的劳动与规则。