Jellyfin 元数据插件 MetaShark 快速部署指南

Jellyfin-Plugin-MetaShark 是一款专为 Jellyfin 媒体服务器设计的增强型元数据插件，核心功能是整合豆瓣丰富的中文影视资源与 TMDB 的全球影视数据库，为用户提供精准的中文元数据信息，同时支持动漫特有的命名格式解析，让媒体库管理更高效。

📋 环境准备与系统要求

基础依赖检查

在开始安装前，请确保您的系统已满足以下条件：

• .NET SDK 9.0 或更高版本（必选）
• Git 版本控制工具（可选，用于克隆代码库）
• 兼容的操作系统：Windows 10/11、Linux (Ubuntu 20.04+/Debian 11+) 或 macOS 12+

安装 .NET SDK

Windows 系统

1. 访问 .NET 官方下载页面获取安装程序
2. 运行安装包并遵循向导完成安装
3. 验证安装：打开 PowerShell 执行以下命令

   dotnet --version  # 应输出 9.0.x 版本号
   

Linux 系统（以 Ubuntu 为例）

# 添加 Microsoft 包存储库
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb

# 安装 .NET SDK
sudo apt update && sudo apt install -y dotnet-sdk-9.0

# 验证安装
dotnet --version  # 应输出 9.0.x 版本号

macOS 系统

使用 Homebrew 安装：

brew install dotnet-sdk
dotnet --version  # 验证安装

🔧 插件获取与构建

方式一：源码构建（推荐）

# 克隆代码库
git clone https://gitcode.com/gh_mirrors/je/jellyfin-plugin-metashark
cd jellyfin-plugin-metashark

# 恢复依赖项
dotnet restore  # 此命令会下载项目所需的所有 NuGet 包

# 构建发布版本
dotnet publish --configuration Release \
  --output ./build \  # 指定输出目录
  Jellyfin.Plugin.MetaShark/Jellyfin.Plugin.MetaShark.csproj

构建成功后，插件文件将生成在 ./build 目录下，核心文件为 Jellyfin.Plugin.MetaShark.dll。

方式二：直接下载发布包

如果您不想进行源码构建，可以：

1. 访问项目发布页面获取最新版本的 ZIP 压缩包
2. 解压后即可获得编译好的 DLL 文件

🚀 插件部署与配置

部署到 Jellyfin

Windows 系统

# 假设 Jellyfin 数据目录位于默认位置
$pluginPath = "$env:APPDATA\Jellyfin\Plugins\MetaShark"
New-Item -ItemType Directory -Path $pluginPath -Force

# 复制构建好的插件文件
Copy-Item -Path .\build\*.dll -Destination $pluginPath

Linux 系统

# 创建插件目录（根据实际安装路径调整）
plugin_dir="$HOME/.config/Jellyfin/plugins/MetaShark"
mkdir -p "$plugin_dir"

# 复制插件文件
cp ./build/*.dll "$plugin_dir/"

macOS 系统

plugin_dir="$HOME/Library/Application Support/Jellyfin/Plugins/MetaShark"
mkdir -p "$plugin_dir"
cp ./build/*.dll "$plugin_dir/"

服务重启与验证

# Linux 系统重启 Jellyfin 服务
sudo systemctl restart jellyfin

# 验证服务状态
sudo systemctl status jellyfin  # 应显示 "active (running)"

⚙️ 插件配置与优化

基础设置步骤

1. 登录 Jellyfin 管理界面，进入 控制台 > 插件
2. 在已安装插件列表中找到 MetaShark，确认状态为 Active
3. 进入 媒体库 设置，选择目标媒体库：
   • 在 元数据下载器 中勾选 MetaShark
   • 使用上下箭头将其移至首位（确保优先使用）

高级优化配置

推荐配置：

• 防封禁设置：启用 "请求频率限制" 功能，避免因频繁访问豆瓣导致 IP 被封禁
• 数据源优先级：中文内容推荐优先使用豆瓣数据，外文内容可优先 TMDB
• 图片加载优化：配置 Jellyfin 访问域名，解决外部图片加载失败问题

性能调优：

# 在插件配置页面调整以下参数
- 并发请求数：根据服务器性能设置（建议 2-4）
- 缓存过期时间：设置为 7-30 天，减少重复请求
- 剧集数据来源：网络条件差时可仅使用豆瓣数据

🔍 验证安装与功能测试

基础功能验证

1. 添加一个新的电影到媒体库
2. 触发元数据刷新：右键点击媒体 > 刷新元数据
3. 检查信息是否正确加载：
   • 中文标题、导演、演员等元数据
   • 电影海报和背景图片
   • 评分和简介信息

命令行验证（高级用户）

# 查看 Jellyfin 日志确认插件加载状态
tail -f /var/log/jellyfin/jellyfin.log | grep MetaShark
# 应显示 "MetaShark plugin loaded successfully"

❓ 常见问题解决

插件无法加载

症状：Jellyfin 日志显示 System.BadImageFormatException
解决步骤：

# Linux 系统示例
plugin_dir="$HOME/.config/Jellyfin/plugins/MetaShark"
rm -f "$plugin_dir/meta.json"  # 删除损坏的元数据文件
rm -f "$plugin_dir/._*"        # 删除 macOS 生成的隐藏文件
systemctl restart jellyfin

元数据获取失败

可能原因与解决：

1. 网络问题：检查服务器网络连接，确保可访问豆瓣和 TMDB
2. API 限制：启用插件的 "防封禁模式"，降低请求频率
3. 权限不足：验证插件目录权限

   chmod -R 755 "$HOME/.config/Jellyfin/plugins/MetaShark"
   

版本更新检查

# 进入插件目录
cd jellyfin-plugin-metashark

# 检查更新
git pull origin main

# 重新构建
dotnet publish --configuration Release

📝 版本历史与更新日志

• 最新稳定版：支持 Jellyfin 10.9.x/10.10.x 系列
• 主要更新：
  • 优化豆瓣 API 解析逻辑
  • 增强动漫命名格式支持
  • 修复 Linux 系统下的路径问题

⚠️ 注意事项

1. 本插件仅用于个人学习交流，请勿用于商业用途
2. 合理设置请求频率，避免给数据源服务器造成负担
3. 定期更新插件以获取最新功能和 bug 修复

通过以上步骤，您已成功部署并配置了 MetaShark 插件，现在可以享受更丰富、更精准的中文媒体元数据服务了！如有其他问题，请参考项目文档或提交 issue 寻求帮助。