Ubuntu Jellyfin的插件如何安装与管理

Ubuntu 下 Jellyfin 插件的安装与管理

一 前置准备

• 本机安装与运行 Jellyfin（Ubuntu 常见方式）
  • 添加仓库并安装：更新系统后导入 GPG 密钥，写入 APT 源，安装并启动服务，最后通过浏览器访问 http://服务器IP:8096 完成初始化。
  • 常用命令：
    • 更新与安装依赖：sudo apt update && sudo apt install apt-transport-https ca-certificates gnupg curl -y
    • 导入密钥：curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
    • 写入源（示例）：echo “deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/ubuntu $(lsb_release -cs) main” | sudo tee /etc/apt/sources.list.d/jellyfin.list
    • 安装与启动：sudo apt install jellyfin -y && sudo systemctl enable --now jellyfin
    • 访问控制台：打开 http://服务器IP:8096，完成管理员设置与媒体库添加。
• Docker 部署要点
  • 运行容器时务必映射插件目录：将宿主机的 /path/to/config 挂载到容器内 /config，插件将位于 /config/plugins。
  • 示例：docker run -d --name jellyfin -e PUID=1000 -e PGID=1000 -p 8096:8096 -v /path/to/config:/config -v /path/to/media:/media jellyfin/jellyfin
  • 后续插件安装与更新，均围绕 /config/plugins 目录进行（宿主机侧或容器内操作）。

二 安装方式

• 方式一 通过插件仓库在线安装（推荐）
  • 入口：控制台 → 插件 → 存储库 → 添加，粘贴仓库 Manifest URL，保存后到 插件目录 搜索并安装；多数插件安装后需重启生效。
  • 常用仓库示例（任选其一或两者结合，提升可用性与速度）：
    • 中文元刮削仓库（含 Metashark）：https://gitee.com/cwhzy/jellyfin-plugin-metashark/releases/download/manifest/manifest_cn.json
    • 第三方插件集合仓库：https://gitee.com/jjm2473/jellyfin-plugins-repo/raw/master/manifest.json
  • 安装后在“已安装”中启用/配置，必要时重启 Jellyfin。
• 方式二 手动安装 ZIP 或拷贝 DLL
  • 下载插件的 ZIP 包，解压后将插件目录（内含 .dll 等）放到 /config/plugins/插件名/；Docker 环境可用 docker cp 将目录拷入容器对应路径，然后重启 Jellyfin。
  • 示例：docker cp 插件目录 jellyfin:/config/plugins/插件名
• 方式三 Docker 环境专用提示
  • 插件目录未映射会导致“安装即丢失”；务必确保 -v 映射了 /config。
  • 手动安装后若未生效，优先检查目录权限与容器重启是否执行。

三 常用插件示例

• Metashark（中文元数据刮削）
  • 适配 10.8.x，安装后在“已安装”中启用并进入配置；可设置 豆瓣 Cookie 与 TMDB API Key 提升命中率与中文演职人员显示效果；旧库条目建议“手动识别/刷新元数据”以更新。
• Merge Versions（合并重复版本）
  • 仓库 Manifest：https://raw.githubusercontent.com/danieladov/JellyfinPluginManifest/master/manifest.json
  • 安装后在“任务计划”中运行 Merge Versions 任务，自动将同一影片的多版本（不同清晰度/语言）合并展示，保持库整洁。
• MaxSubtitle（中文字幕下载）
  • 添加仓库（国内镜像）：https://gitee.com/caryyu/jellyfin-plugin-repo/raw/master/manifest-cn.json
  • 安装后在插件配置中设定语言偏好与自动下载策略，便于自动匹配并下载中文字幕。

四 插件管理与维护

• 启用与配置
  • 控制台 → 插件 → 已安装：选择插件进行启用、配置与更新；部分插件修改后需重启才能生效。
• 更新与卸载
  • 在线安装：在“存储库/目录”中检查更新并执行升级；手动安装：下载新版本 ZIP，覆盖 /config/plugins/插件名/ 后重启。
  • 卸载：删除 /config/plugins/插件名 目录并重启；Docker 环境可用 docker exec -it jellyfin rm -rf /config/plugins/插件名 后重启。
• 故障排查
  • 插件目录不显示或安装失败：检查 /config/plugins 挂载是否正确、目录权限是否为 Jellyfin 运行用户（PUID/PGID） 可写；必要时重启 Jellyfin 或宿主机。
  • 仓库访问慢或失败：更换为国内镜像源（如上示例），或暂时使用手动安装方式。