ClawShelf：打造精准可控的本地媒体库元数据管理方案

1. 项目概述一个为极客打造的本地媒体资产管理利器如果你和我一样是个喜欢折腾本地影音库、又对现有媒体管理工具比如Plex、Jellyfin的刮削器的识别准确率或自定义能力感到不满的资深玩家那么你很可能已经对“ClawShelf”这个名字有所耳闻或者正在寻找类似的解决方案。ClawShelf直译过来是“爪架”形象地描绘了它从互联网的各个角落精准“抓取”并整理媒体信息为你构建一个井然有序的本地媒体“书架”的核心功能。简单来说ClawShelf 是一个高度可定制、以开发者为中心的本地媒体信息抓取与元数据管理工具。它不提供流媒体服务也不做媒体播放它的核心使命只有一个为你存储在硬盘里的电影、电视剧、动漫文件自动匹配并下载最准确、最符合你需求的元数据包括海报、背景图、简介、演职员表、评分等并将这些信息以结构化的方式如NFO文件保存下来供Kodi、Jellyfin、Plex等媒体中心软件完美读取。与那些开箱即用但“黑盒”化严重的通用刮削器不同ClawShelf 将控制权完全交还给用户。你可以精细地配置数据源优先级比如优先使用TMDB还是豆瓣的数据、定义文件名匹配规则、自定义元数据字段的映射甚至编写脚本来处理异常情况。这种“一切尽在掌握”的感觉正是它吸引技术爱好者和追求完美媒体库用户的关键。接下来我将结合自己搭建和深度使用 ClawShelf 的经验为你彻底拆解这个项目的设计哲学、核心配置以及那些官方文档可能不会明说的实战技巧。2. 核心架构与设计哲学解析2.1 为什么是“刮削器”而不是“流媒体服务器”首先要明确 ClawShelf 的定位。市面上常见的 Jellyfin、Plex 等是“媒体服务器”它们集成了播放、转码、刮削、用户管理等一系列功能。而 ClawShelf 是一个纯粹的“刮削器”或“元数据代理”。这种单一职责的设计带来了巨大优势专注与精深因为只做一件事ClawShelf 可以在元数据抓取的准确性、灵活性和容错能力上做到极致。它不需要考虑播放兼容性、转码性能或用户界面所有代码和逻辑都服务于“如何更好地识别文件并获取信息”。无状态与轻量ClawShelf 通常以命令行工具或后台服务的形式运行。它不管理媒体文件本身只读取文件或目录名然后输出元数据文件。这意味着它资源占用极低可以运行在树莓派甚至路由器上执行一次任务后就可以退出非常适合自动化脚本调度。与播放器解耦你使用 Kodi 还是 Jellyfin 来播放这不再重要。ClawShelf 生成标准化的 NFO 文件后任何支持 NFO 的媒体中心都能读取。你可以随时更换前端播放系统而辛苦整理的元数据资产完全不受影响实现了数据层与展示层的分离。2.2 核心工作流程与组件拆解ClawShelf 的工作流程可以抽象为一个精密的流水线理解这个流程是进行高级配置的基础。媒体文件扫描 - 文件名解析与匹配 - 向数据源发起查询 - 结果筛选与合并 - 元数据下载与格式化 - 写入本地NFO/图片1. 扫描器 (Scanner) 负责遍历你指定的目录找出所有视频文件。ClawShelf 的智能之处在于它不仅能识别MovieName (2023).mp4这样的简单命名更能处理复杂的场景比如包含发布组、编码信息、季集信息的文件名[VCB-Studio] Spy x Family [01][Ma10p_1080p][x265_flac].mkv。扫描器会提取出它认为可能是标题、年份、季、集等关键信息。2. 解析器/匹配器 (Parser/Matcher) 这是整个系统的“大脑”。它接收扫描器提取的零散信息并运用一系列规则正则表达式是核心去尝试匹配。一个设计良好的解析规则能准确地将The.Matrix.1999.1080p.BluRay.x264-ROUGH.mkv识别为标题“The Matrix”和年份“1999”。ClawShelf 通常允许用户自定义多套解析规则并为电影、电视剧、动漫设置不同的规则集这是提升识别率的关键。3. 数据源插件 (Data Source Plugin) ClawShelf 本身不存储任何媒体信息它通过插件与外部API交互。常见的插件包括TMDB (The Movie Database)国际影视数据库信息全面且更新及时是电影和欧美剧集的首选。TVDB (The TV Database)专注于电视剧集集数信息非常权威。豆瓣针对中文影视、华语圈作品其中文简介、评分和社区评论更符合国内用户习惯。Bangumi (番组计划)对于动漫尤其是日本动画的识别和信息准确度远超其他平台。核心配置心得数据源的优先级配置至关重要。例如对于动漫我的优先级是Bangumi TMDB 豆瓣对于国产剧则是豆瓣 TMDB。你可以在配置文件中为不同类型的媒体定义不同的数据源链Provider ChainClawShelf 会按顺序查询直到获得一个满意可配置匹配度阈值的结果。4. 后处理器 (Post-Processor) 在获取到元数据后后处理器负责进行最终加工。这包括图片代理有些数据源如TMDB的图片链接是HTTPS但你的内网媒体服务器可能无法直接访问。可以配置后处理器将图片下载到本地或者替换为其他镜像站的链接。NFO格式化决定NFO文件的格式兼容Kodi、Emby等、包含哪些字段是否写入演员头像URL、是否包含分级信息。重命名与硬链接高级功能可以根据元数据自动重命名文件或文件夹例如整理成电影名 (年份)/电影名 (年份).mkv的标准结构或者为剧集生成剧集名 S01E01 集名.mkv的格式。硬链接功能可以在不占用双倍空间的前提下为文件在另一个目录如按类型分类的目录创建一个“快捷方式”。3. 从零开始ClawShelf 的部署与基础配置实战理论讲完我们进入实战环节。假设你已经在本地NAS或一台常开机的电脑上部署好了 Docker 环境这是运行 ClawShelf 最便捷的方式。3.1 容器化部署与目录映射首先我们需要准备一个配置文件clawshelf.yaml和一个用于持久化数据的目录。# clawshelf.yaml 示例 - 基础版 version: 3.8 services: clawshelf: # 使用最新稳定版镜像具体镜像名需查阅项目官方文档 image: your-registry/clawshelf:latest container_name: clawshelf restart: unless-stopped volumes: # 映射本地配置目录到容器内 - ./config:/config # 映射你的媒体库根目录例如电影和电视剧分别在不同文件夹 - /path/to/your/media:/media:ro # 映射一个输出目录用于存放日志或临时文件可选 - ./data:/data environment: # 设置语言偏好影响元数据语言如简介 - TZAsia/Shanghai - LANGzh_CN.UTF-8 # 通常以命令行参数启动具体命令取决于镜像设计 # command: run --config /config/config.toml关键点在于卷映射./config:/config将容器内的配置目录挂载到本地这样你可以在宿主机上方便地编辑配置文件重启容器即可生效。/path/to/your/media:/media:ro以只读 (ro) 方式挂载你的媒体库。这是安全最佳实践ClawShelf 只需要读取文件信息绝不需要修改或删除原文件。所有生成的NFO和图片文件都应通过配置指定输出到其他位置如每个媒体文件旁边或统一的元数据目录。环境变量LANG设置为zh_CN.UTF-8非常重要这能确保 ClawShelf 正确处理中文路径和文件名避免出现乱码。3.2 核心配置文件深度解读ClawShelf 的威力几乎全部体现在其配置文件中。我们以 TOML 格式的配置为例解析几个核心部分。# config.toml 核心部分解析 [general] library_path /media # 媒体库根目录对应容器内的路径 metadata_path /media # 元数据NFO、图片输出路径。设为与library_path相同则会在每个视频文件旁生成 language zh-CN # 优先获取中文元数据 country CN # 地区影响分级、发行信息等 # 定义一个“电影”扫描任务 [[tasks]] name movie_scanner type movie # 任务类型电影 enabled true schedule 0 2 * * * # 每天凌晨2点自动运行 (Cron表达式) paths [/media/Movies] # 扫描的电影目录 # 为该任务配置解析器 [tasks.parser] # 使用内置的“组合”解析器它尝试多种规则 type compound # 定义一组正则表达式规则来提取标题和年份 patterns [ ^(?Ptitle.?)[. _](?Pyear\\d{4})[. _], ^(?Ptitle.?)[. _]\\[(?Pyear\\d{4})\\], ] # 为该任务配置数据源链 [[tasks.providers]] name tmdb priority 1 api_key ${TMDB_API_KEY} # 建议从环境变量读取API Key # 可以设置最小匹配置信度低于此值则尝试下一个Provider min_score 80 [[tasks.providers]] name douban priority 2 api_key ${DOUBAN_API_KEY} min_score 70 # 定义一个“电视剧”扫描任务 [[tasks]] name tvshow_scanner type tv enabled true schedule 0 3 * * * # 每天凌晨3点运行 paths [/media/TV Shows, /media/Anime] # 可以扫描多个目录 [tasks.parser] type compound # 电视剧解析规则更复杂需要匹配季和集 patterns [ # 匹配 S01E01 或 s01e01 格式 ^(?Ptitle.?)[. _][Ss](?Pseason\\d)[Ee](?Pepisode\\d), # 匹配 01x01 格式 ^(?Ptitle.?)[. _](?Pseason\\d)[Xx](?Pepisode\\d), # 匹配 [01] 格式常见于动漫 ^(?Ptitle.?)[. _]\\[(?Pepisode\\d)\\], ] [[tasks.providers]] name tmdb priority 1 api_key ${TMDB_API_KEY} [[tasks.providers]] name bangumi priority 2 # 对于动漫目录可以调整Bangumi为优先级1配置精髓解析任务 (Tasks)ClawShelf 以任务为单位进行组织。你可以为电影、电视剧、动漫甚至音乐创建独立的任务每个任务有自己的扫描路径、解析规则和数据源链。这种模块化设计使得管理大型混合媒体库变得清晰。解析模式 (Patterns)这是提升识别率的重中之重。你需要根据自己媒体文件的命名习惯来调整正则表达式。例如如果你的电影文件都像星际穿越.Interstellar.2014.1080p.mkv那么模式^(?Ptitle.?)\\.(?Pyear\\d{4})可能更有效。建议先在正则表达式测试网站上验证你的规则。数据源优先级priority数字越小优先级越高。当高优先级数据源返回的匹配分数基于名称、年份等相似度计算低于min_score时系统会自动 fallback 到下一个数据源。对于难以识别的冷门作品这个链条能极大提高成功率。API Key 管理绝对不要将 API Key 硬编码在配置文件中并上传到公开仓库。务必使用环境变量如${TMDB_API_KEY}或在 Docker Compose 文件中通过environment字段传入。3.3 首次运行与目录结构验证配置完成后我们可以先进行一次手动扫描来测试。# 进入容器执行命令或如果镜像支持直接命令行调用 docker exec -it clawshelf clawshelf run --task movie_scanner --dry-run--dry-run参数表示“干跑”即 ClawShelf 会执行扫描、解析、查询等所有步骤但不会真正写入任何 NFO 文件或下载图片。控制台会输出详细的日志显示每个文件被识别成了什么、匹配到了哪个数据源的哪部作品、匹配分数是多少。这是极其关键的调试步骤。通过阅读日志你可以发现解析规则的问题例如把年份识别错了。看到数据源查询的结果确认匹配是否正确。根据日志调整你的解析规则和数据源优先级。当--dry-run的结果令人满意后移除该参数进行正式运行。首次运行可能会花费较长时间因为它需要为所有文件获取元数据并下载图片。之后增量更新会快很多。4. 高级技巧与疑难问题排查实录经过基础搭建你的媒体库应该已经初具规模。但要想让 ClawShelf 真正服服帖帖还需要一些进阶配置和问题处理经验。4.1 针对特殊命名与复杂情况的处理场景一多版本电影识别如加长版、导演剪辑版文件名如阿凡达.Avatar.2009.Extended.Cut.1080p.mkv。默认解析器可能会把 “Extended Cut” 也当作标题的一部分导致匹配失败。解决方案在解析器的patterns中使用更精确的正则表达式或者在匹配后使用“后处理规则”移除这些常见后缀。有些高级配置支持“排除词列表”将Extended、Director‘s Cut、IMAX等词设为排除词使其不参与标题匹配。场景二动漫剧集特殊命名动漫文件名极其复杂例如[Lilith-Raws] 咒术回战 S2 / Jujutsu Kaisen S2 - 20 [Baha][WEB-DL][1080p][AVC AAC][CHT][MP4].mp4。这包含了发布组、中英文标题、季信息、集数、来源、编码、字幕、格式等大量信息。解决方案为动漫创建独立任务在paths中指定动漫专属目录。使用动漫专用解析器如果 ClawShelf 社区有维护针对动漫的解析器插件如anime-parser优先使用。自定义复杂正则针对你的文件命名规律编写强大的正则表达式。例如提取- 20前面的部分作为标题可能不靠谱更好的规则可能是匹配咒术回战 S2或Jujutsu Kaisen S2这部分。优先使用 Bangumi 数据源将bangumiprovider 的priority设为最高并适当降低min_score。Bangumi 对动漫的别名包括中文名、英文名、日文名支持非常好容错率高。场景三电视剧集的多季混合存放你的目录结构可能是/media/TV Shows/The Big Bang Theory/Season 1/...但也可能是/media/TV Shows/The Big Bang Theory/All Seasons/...把所有季混在一起。解决方案ClawShelf 的扫描器通常能根据路径中的Season XX自动识别季数。对于混合存放的就完全依赖文件名解析。此时确保你的电视剧解析规则 (patterns) 必须能同时匹配标题和季号如S01E01中的01。如果文件名里没有季号只有集号识别会非常困难强烈建议整理成标准季目录结构。4.2 元数据定制与NFO文件优化默认生成的NFO文件可能包含了你不需要的字段或者缺少了你想要的字段。自定义字段映射在 provider 的配置中可以指定要获取哪些字段以及如何映射到NFO的标准字段。例如你可能不想获取“演职员表”以减少数据量或者你想将 TMDB 的tagline字段也写入NFO。[[tasks.providers]] name tmdb [tasks.providers.fields] # 字段过滤与映射 include [title, original_title, overview, year, genres, rating] # 可以将tmdb的tagline映射到NFO的tagline字段 mappings { tagline tagline }本地覆盖与锁定对于某些已经完美匹配、无需再更改的作品你可以在媒体文件旁手动创建一个同名的.nfo文件或一个特殊的.clawshelf.lock文件。ClawShelf 在运行时检测到这些文件会跳过对该文件的处理防止自动刮削覆盖你手动精心修改的信息。图片偏好设置你可以指定优先下载哪种尺寸的海报如poster_500w还是poster_original和背景图。对于性能有限的设备如电视盒子下载过大的原始图片可能影响加载速度选择适中的尺寸是平衡画质与性能的关键。4.3 常见问题排查速查表以下是我在长期使用中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案所有文件都无法识别日志显示“No match found”1. API Key 无效或未设置。2. 网络问题无法访问数据源API。3. 解析规则 (patterns) 完全无法匹配文件名。1. 检查环境变量是否正确注入在容器内执行echo $TMDB_API_KEY验证。2. 在容器内尝试curl api.themoviedb.org测试连通性。3. 使用--dry-run并查看日志看解析器提取出的title和year是什么。用一个简单的文件名和简单的规则测试。部分文件识别错误如A电影识别成B电影1. 文件名信息不足或歧义如常见的单字片名。2. 数据源优先级配置不当低质量数据源先匹配了。3. 匹配阈值 (min_score) 设置过低。1. 尝试在文件名中添加年份如触不可及.Intouchables.2011.mkv。2. 调整priority将更准确的数据源如豆瓣对于华语片调高。3. 逐步提高min_score如从70调到80要求更严格的匹配。识别正确但下载的元数据是英文的语言配置错误。检查配置文件中的language和country选项确保设置为zh-CN。同时检查 TMDB 等Provider的配置中是否有独立的语言设置。运行一段时间后刮削速度变慢或失败1. 触发了数据源API的速率限制。2. 缓存文件损坏。1. 数据源API都有调用频率限制。在配置中为每个Provider添加delay参数如delay 1.2秒在请求间插入延迟避免被封。2. 删除 ClawShelf 的缓存目录通常位于/config/cache或/data/cache然后重新运行。生成的NFO文件媒体服务器不识别NFO文件格式不兼容。检查 ClawShelf 的 NFO 输出格式设置。确保它生成的是你的媒体服务器如 Jellyfin兼容的格式。通常选择“Kodi兼容”格式是通用性最好的。硬链接或重命名功能未生效1. 文件系统不支持硬链接如跨磁盘分区。2. 权限不足。3. 重命名规则配置有误。1. 确保源文件和目标目录在同一文件系统分区上。2. 检查 Docker 容器的用户/组权限确保其对媒体目录有读写权限。3. 仔细检查重命名规则的模板字符串使用--dry-run预览重命名结果。4.4 性能优化与自动化集成并发控制在配置文件的[general]部分可以设置concurrency或workers参数来控制同时进行的刮削任务数。设置过高可能导致API限流或本地IO瓶颈设置过低则效率低下。根据你的网络和CPU性能从2-4开始调整测试。增量扫描与监控ClawShelf 应该配置为定时任务如上述Cron表达式。更高效的玩法是使用文件系统监控工具如inotifywait在Linux上当媒体目录有新增文件时触发 ClawShelf 执行针对该路径的扫描实现真正的实时更新。与媒体服务器联动ClawShelf 完成任务后可以触发一个 Webhook 通知你的 Jellyfin 或 Plex 服务器进行元数据刷新。这样新刮削的内容就能立即出现在你的媒体库中无需等待服务器自己的定时扫描。5. 总结从工具到艺术——打造属于你的完美媒体库ClawShelf 不是一个“安装即用”的傻瓜软件它更像是一套乐高积木或者一个功能强大的命令行工具箱。它的上手门槛确实比 Plex 自带的刮削器要高需要你付出一些时间去理解正则表达式、配置数据源、调试匹配规则。但这份投入的回报是巨大的一个识别率接近100%、元数据完全符合你审美和需求的本地媒体库。我个人最深的一点体会是使用 ClawShelf 的过程是一个不断“驯化”工具的过程。最初你可能会被复杂的配置和偶尔的识别失败搞得焦头烂额。但随着你一步步调整规则、优化优先级、处理特例你会越来越了解你的媒体文件命名风格也越来越了解各个数据源的特点。最终ClawShelf 会按照你预设的“思维”去工作那种一切尽在掌控的满足感是使用任何现成黑盒工具都无法带来的。最后分享一个小心得定期维护你的配置文件。随着媒体文件的增多和命名习惯的微小变化旧的解析规则可能会逐渐失效。每添加一批新类型的文件比如开始收藏纪录片或音乐视频最好单独为其创建一个测试任务精心调试好规则后再并入主任务。建立一个属于自己的、经过实战检验的“规则库”和“配置模板”是长期使用 ClawShelf 的最佳实践。当你看到成千上万个杂乱命名的文件被自动整理得井井有条海报墙精美无比时你会觉得所有前期的折腾都是值得的。这或许就是数字生活整理癖的终极乐趣之一。