开源软件研究
公開群組
群组类型 大学
活跃于 2 天, 18 時前
开源软件、自托管软件、HomeLab研究。
Jellyfin 刮削插件 MetaTube 完整安装与使用教程
-
-
2026 年 1 月 14 日 上午 2:04 #32310
🎯 学习目标：掌握 MetaTube 插件的完整部署流程，包括后端服务搭建、插件配置、文件命名规范及常见问题排查
一、MetaTube 概述与架构理解
1.1 什么是 MetaTube？
MetaTube 是一款专为 Jellyfin/Emby 媒体服务器设计的元数据刮削插件，主要用于日本成人影片（JAV）的信息获取与整理。它采用服务端 + 插件的分离式架构，能够自动从多个数据源抓取完整的影片元数据。
MetaTube 的核心功能包括：
功能类别 具体内容 📝 元数据支持 标题、简介、类型、导演、演员、制作商等完整信息 🔍 多源搜索 支持跨 20+ 数据提供商搜索电影和演员信息 🎬 预告片支持 无需下载完整视频即可播放预告片段 👤 演员识别 通过 GFriends 和 XsList 自动匹配演员信息与头像 🖼️ 智能封面 人脸检测引擎自动裁剪以面部为中心的封面图 🔄 自动翻译 支持将日文元数据自动翻译为中文 ⏰ 计划任务 自动整理元数据类型并定期更新 1.2 工作原理与架构
理解 MetaTube 的工作原理对于后续的部署和故障排查至关重要：
┌─────────────────┐ ①发送文件名 ┌──────────────────┐ │ │ ──────────────────▶ │ │ │ Jellyfin/ │ │ MetaTube │ │ Emby 插件 │ ◀────────────────── │ Server 后端 │ │ │ ④返回元数据 │ │ └─────────────────┘ └──────────────────┘ │ ②请求数据 ▼ ┌──────────────────┐ │ 数据源网站 │ │ (FANZA/DMM/ │ │ MGS/FC2等) │ └──────────────────┘ │ ▼ ③获取信息 ┌──────────────────┐ │ 图片/元数据 │ └──────────────────┘工作流程详解：
- 文件扫描：Jellyfin/Emby 扫描媒体库，将文件名（通常包含番号）发送给 MetaTube 插件
- 请求转发：插件将番号信息发送到 MetaTube Server 后端
- 数据抓取：后端根据番号向各个数据源网站（如 FANZA、DMM、MGS、Arzon 等）发起请求
- 数据处理：后端对抓取的数据进行处理（包括图片裁剪、人脸识别、文字翻译等）
- 返回结果：处理后的元数据返回给插件，最终由 Jellyfin/Emby 保存和展示
1.3 为什么需要自建后端？
许多初学者会问：为什么不能直接使用公共后端服务？ 这里需要详细解释：
对比项 公共后端 自建后端 💰 成本 免费 需要服务器/Docker环境 ⚡ 稳定性 使用人数多，经常超载或停止服务 完全由自己控制，稳定可靠 🚀 速度 受限于公共资源，速度较慢 独享资源，刮削速度快 🔒 隐私 请求记录可能被第三方获取 数据完全在本地，隐私安全 🌐 网络 依赖公共服务器的网络环境 可自行配置代理，灵活性强 📊 数据持久化 无法保存历史记录 SQLite 数据库持久化存储 结论：强烈建议自建后端服务，尤其是有长期使用需求的用户。本课程将重点讲解如何使用 Docker Compose 部署自建后端。
二、Docker Compose 部署 MetaTube Server
2.1 部署前的准备工作
2.1.1 环境要求
在开始部署之前，请确保你的系统满足以下要求：
要求项 最低配置 推荐配置 操作系统 Linux / Windows / macOS Linux (Ubuntu/Debian) Docker 版本 20.10+ 最新稳定版 Docker Compose v2.0+ 最新稳定版 内存 512MB 1GB+ 存储空间 1GB 5GB+（包含数据库增长空间） 网络 能访问刮削源网站 日本/美国出口 IP（重要！） 2.1.2 网络环境的特殊说明 ⚠️
这是 MetaTube 部署中最关键也最容易被忽视的问题：
由于刮削源（如 FANZA、DMM、MGS 等）的地域限制，MetaTube 后端必须能够访问”真正的互联网”，且最好出口 IP 为日本或美国。部分刮削源仅对这两个地区完全开放。
部署环境优先级（从高到低）：
- 🥇 Cloud-Native 云原生部署（如 Huggingface Space、Koyeb、Railway 等）
- 🥈 海外 VPS 部署（日本/美国/新加坡等地区的云服务器）
- 🥉 本地部署 + 代理配置（需要稳定的代理环境）
2.1.3 安装 Docker 和 Docker Compose
如果你尚未安装 Docker，请按以下步骤操作：
Ubuntu/Debian 系统：
# 更新包管理器 sudo apt update # 安装必要的依赖 sudo apt install -y apt-transport-https ca-certificates curl software-properties-common # 添加 Docker 官方 GPG 密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 添加 Docker 仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 docker --version docker compose version群晖 NAS 用户：
直接在 DSM 套件中心安装 Container Manager（原 Docker 套件）即可。2.2 创建 Docker Compose 配置文件
2.2.1 基础版配置（推荐新手使用）
首先，创建项目目录并编写配置文件：
# 创建项目目录 mkdir -p ~/metatube && cd ~/metatube # 创建配置目录（用于持久化存储） mkdir -p config # 创建 docker-compose.yml 文件 nano docker-compose.yml基础版
docker-compose.yml内容：version: '3.8' services: metatube: image: ghcr.io/metatube-community/metatube-server:latest container_name: metatube-server restart: always command: "-dsn /config/metatube.db" ports: - "8080:8080" volumes: - ./config:/config environment: - TZ=Asia/Shanghai配置项详解：
配置项 说明 image使用官方 GitHub Container Registry 镜像 container_name容器名称，方便管理 restart: always容器意外停止时自动重启 command指定数据库文件路径，使用 SQLite 持久化存储 ports端口映射，主机 8080 端口映射到容器 8080 端口 volumes关键配置！ 将配置目录映射出来，确保数据库文件不会因容器重建而丢失 TZ设置时区为上海（北京时间） 2.2.2 进阶版配置（带代理支持）
如果你在中国大陆部署，需要配置代理才能访问刮削源网站：
version: '3.8' services: metatube: image: ghcr.io/metatube-community/metatube-server:latest container_name: metatube-server restart: always command: "-dsn /config/metatube.db" ports: - "8080:8080" volumes: - ./config:/config environment: - TZ=Asia/Shanghai # ⚠️ 代理配置（必须同时设置 HTTP_PROXY 和 HTTPS_PROXY） - HTTP_PROXY=http://192.168.1.100:7890 - HTTPS_PROXY=http://192.168.1.100:7890 # 可选：不走代理的地址 - NO_PROXY=localhost,127.0.0.1,192.168.0.0/16代理配置说明：
HTTP_PROXY和HTTPS_PROXY必须同时配置，缺一不可- 代理地址格式：
http://[代理服务器IP]:[端口] - 如果代理需要认证：
http://username:password@[IP]:[端口]
可行的代理环境方案：
- 局域网内的代理软件：在 Windows/Mac 上运行 Clash/V2Ray，开启”允许局域网连接”
- 旁路由代理：OpenWrt/软路由上运行代理服务
- 虚拟组网：通过 Tailscale/ZeroTier 连接的远程代理服务器
2.2.3 完整版配置（Jellyfin + MetaTube 一体化部署）
如果你还没有部署 Jellyfin，可以使用以下一体化配置：
version: '3.8' services: # Jellyfin 媒体服务器 jellyfin: image: jellyfin/jellyfin:latest container_name: jellyfin restart: always ports: - "8096:8096" volumes: - ./jellyfin/config:/config - ./jellyfin/cache:/cache - /path/to/your/media:/media # ⚠️ 修改为你的媒体文件路径 environment: - TZ=Asia/Shanghai - PUID=1000 - PGID=1000 # 可选：Intel 核显硬件加速 devices: - /dev/dri:/dev/dri # MetaTube 后端服务 metatube: image: ghcr.io/metatube-community/metatube-server:latest container_name: metatube-server restart: always command: "-dsn /config/metatube.db" ports: - "8080:8080" volumes: - ./metatube/config:/config environment: - TZ=Asia/Shanghai depends_on: - jellyfin2.3 启动与管理服务
2.3.1 启动服务
# 进入项目目录 cd ~/metatube # 拉取最新镜像并启动服务（后台运行） docker compose up -d # 查看服务状态 docker compose ps # 查看实时日志 docker compose logs -f metatube启动成功的标志：
metatube-server | time="2026-01-14T10:00:00+08:00" level=info msg="Server started on :8080"2.3.2 验证服务是否正常运行
在浏览器中访问以下地址进行测试：
http://[你的服务器IP]:8080或者使用 curl 命令：
# 测试服务是否响应 curl http://localhost:8080 # 查看支持的数据源列表 curl http://localhost:8080/v1/providers如果返回 JSON 格式的响应，说明后端服务已正常运行。
2.3.3 常用管理命令
# 停止服务 docker compose down # 重启服务 docker compose restart # 更新到最新版本 docker compose pull && docker compose up -d # 查看容器资源使用情况 docker stats metatube-server # 进入容器内部（调试用） docker exec -it metatube-server /bin/sh三、Jellyfin 插件安装与配置
3.1 安装 MetaTube 插件
3.1.1 添加插件仓库
- 登录 Jellyfin 管理后台
- 进入 控制台 → 插件 → 存储库
- 点击 添加 按钮
- 输入以下信息：
字段 值 名称 MetaTube URL https://raw.githubusercontent.com/metatube-community/jellyfin-plugin-metatube/dist/manifest.json⚠️ 注意：CDN 地址可能存在缓存延迟，更新可能不是最及时。
3.1.2 安装插件
- 进入 控制台 → 插件 → 目录
- 在列表中找到 MetaTube
- 点击进入，选择版本后点击 安装
- 重启 Jellyfin 服务（这一步很重要！）
3.2 配置 MetaTube 插件
3.2.1 基础配置
重启完成后：
- 进入 控制台 → 插件 → MetaTube（或在已安装插件列表中点击）
- 配置以下关键参数：
配置项 说明 示例值 服务器地址 MetaTube 后端 URL http://192.168.1.100:8080Token（可选） 后端访问密钥（如果设置了的话） 留空或填写密钥 配置要点：
- 如果 Jellyfin 和 MetaTube 部署在同一台机器上，可以使用
http://localhost:8080 - 如果 Docker 网络隔离，建议使用实际的局域网 IP 地址
- 如果使用 Docker 内部网络，可以使用容器名
http://metatube-server:8080
3.2.2 高级配置选项
MetaTube 插件还提供了丰富的高级配置选项：
选项 说明 启用翻译 自动将日文元数据翻译为中文 翻译引擎 可选 Google/DeepL 等翻译服务 图片模式 封面裁剪方式（原图/人脸居中等） 命名模板 自定义 NFO 文件命名规则 3.3 创建媒体库
3.3.1 媒体库配置
- 进入 控制台 → 媒体库 → 添加媒体库
- 按照以下设置进行配置：
配置项 设置值 说明 内容类型 电影 ⚠️ 必须选择”电影”，不要选择其他类型 文件夹 你的媒体文件路径 添加包含影片的目录 元数据下载器 勾选 MetaTube 在列表中找到并勾选 图片获取器 勾选 MetaTube 确保能获取封面和海报 实时监控 建议开启 新增文件时自动刮削 3.3.2 重要提示
⚠️ 务必取消勾选其他元数据下载器（如 TheMovieDB、OMDb 等），避免干扰 MetaTube 的刮削结果。
四、文件命名规范与刮削技巧
4.1 命名规则的重要性
文件命名是影响刮削成功率的最关键因素之一。 MetaTube 通过解析文件名中的番号来匹配元数据，因此正确的命名格式至关重要。
4.2 标准命名格式
4.2.1 基本格式
[番号].mp4 [番号]/[番号].mp4 （独立文件夹模式）示例：
✅ 正确命名 ❌ 错误命名 SSIS-541.mp4SSIS-541_1080P_无水印.mp4ABP-123.mp4【某某网站】ABP-123.mp4FC2-PPV-3135559.mp4FC2PPV3135559.mp4（缺少连字符）1pondo-050720_001.mp4一本道-050720_001.mp4（中文名）4.2.2 各类番号格式参考
类型 格式示例 说明 骑兵（有码） SSIS-541、MIDE-999、IPX-888标准格式：字母-数字 步兵（无码） FC2-PPV-3135559、HEYZO-2888注意保留所有连字符 一本道 1pondo-050720_001使用英文名，保留下划线 加勒比 carib-050720-001同上，使用英文名 东京热 Tokyo-Hot-n1234保留完整格式 4.3 命名最佳实践
4.3.1 应该避免的命名方式
问题类型 错误示例 正确做法 网站水印 【XX论坛】SSIS-541.mp4删除所有水印前缀 分辨率后缀 SSIS-541_1080P_4K.mp4只保留番号 多余编号 SSIS-541-C.mp4、SSIS-541-UC.mp4删除 -C、-UC等后缀中文翻译 SSIS-541 中文字幕.mp4不要添加中文描述 特殊字符 SSIS-541【无码破解】.mp4避免使用中文括号等特殊字符 4.3.2 批量重命名工具推荐
如果你有大量需要重命名的文件，可以使用以下工具：
工具 平台 特点 Bulk Rename Utility Windows 功能强大，支持正则表达式 Advanced Renamer Windows 界面友好，支持批量处理 Rename Master Windows 简单易用 Thunar Linux 轻量级文件管理器，内置批量重命名 Hazel macOS 自动化文件整理 4.4 手动刮削与识别
当自动刮削失败时，可以使用手动识别功能：
- 在 Jellyfin 中找到未识别的影片
- 右键点击 → 识别
- 在搜索框中输入正确的番号
- 从结果中选择正确的条目
五、免费云端部署方案
如果你没有海外服务器，可以考虑以下免费部署方案：
5.1 Huggingface Space 部署（推荐）
Huggingface 提供免费的 Docker 运行环境（2 CPU / 16GB 内存），非常适合部署 MetaTube 后端。
5.1.1 部署步骤
- 注册账号：访问 Huggingface 官网，使用邮箱注册（需要科学上网）
- 创建 Space：
- 点击右上角头像 → New Space
- 填写 Space 名称（如
my-metatube） - 选择 Docker → Blank
- 选择 CPU Basic（免费）
- 可见性选择 Public
- 点击 Create Space
- 配置 Dockerfile：
在 Space 中创建
Dockerfile文件，内容如下：FROM ghcr.io/metatube-community/metatube-server:latest # 设置端口（Huggingface 要求使用 7860） ENV PORT=7860 EXPOSE 7860 # 创建数据目录 RUN mkdir -p /data && chmod 777 /data # 设置数据库路径 ENV DSN=/data/metatube.db # 启动服务 ENTRYPOINT ["/metatube-server", "-addr", ":7860"]- 等待构建完成：通常需要 1-3 分钟
- 获取服务地址：格式为
https://[用户名]-[space名称].hf.space
5.1.2 注意事项
⚠️ Huggingface Space 的限制：
- 48 小时无访问会自动休眠
- 休眠后首次访问需要等待几秒钟唤醒
- 可以设置定时任务定期访问以保持活跃
5.2 Koyeb 部署
Koyeb 也提供永久免费的部署方案：
- 访问 MetaTube Koyeb 快速部署 页面
- 点击一键部署按钮
- 按照引导完成配置
六、常见问题与故障排查
6.1 插件状态不活跃
症状：在 Jellyfin 插件列表中，MetaTube 显示为不活跃状态
可能原因及解决方案：
原因 解决方案 Jellyfin 与插件版本不兼容 更新 Jellyfin 到最新版本后重启 插件安装不完整 卸载后重新安装插件 重启未生效 确保完全重启 Jellyfin 服务，而非仅刷新页面 6.2 无法刮削/刮削失败
排查步骤：
步骤 1：验证后端服务
# 检查容器是否运行 docker ps | grep metatube # 查看容器日志 docker logs metatube-server # 测试后端 API curl http://localhost:8080/v1/providers步骤 2：检查网络连通性
在浏览器或命令行中直接访问后端地址，确认能够正常响应。
步骤 3：检查文件命名
确保文件名符合规范，只包含标准番号格式。
步骤 4：检查代理配置
如果使用代理，确认
HTTP_PROXY和HTTPS_PROXY都已正确配置。6.3 图片无法加载
可能原因：
原因 解决方案 后端网络问题 检查代理配置，确保能访问日本网站 图片 CDN 被墙 在 Jellyfin 中配置反向代理或使用本地缓存 部分地区 IP 限制 更换代理节点（建议使用日本或美国 IP） 6.4 数据库相关问题
问题：刮削数据丢失/每次重启后需要重新刮削
原因：未正确挂载数据库文件
解决方案：
确保
docker-compose.yml中正确配置了 volumes：volumes: - ./config:/config command: "-dsn /config/metatube.db"验证数据库文件是否存在：
ls -la ./config/ # 应该能看到 metatube.db 文件6.5 刮削速度慢
优化建议：
- 使用 SQLite 持久化存储：已刮削的数据会被缓存，重复刮削时直接读取缓存
- 选择更快的代理节点：日本节点通常访问刮削源最快
- 减少同时刮削的数量：避免短时间内刮削大量影片，可能触发限流
七、维护与更新
7.1 定期更新
推荐每月检查并更新一次，以获取最新功能和修复：
# 进入项目目录 cd ~/metatube # 拉取最新镜像 docker compose pull # 重新创建容器 docker compose up -d # 验证更新结果 docker compose ps7.2 备份策略
需要备份的内容：
文件/目录 说明 docker-compose.yml配置文件 ./config/metatube.dbSQLite 数据库（包含刮削缓存） 简单备份脚本：
#!/bin/bash BACKUP_DIR="/path/to/backup" DATE=$(date +%Y%m%d) mkdir -p $BACKUP_DIR cp ~/metatube/docker-compose.yml $BACKUP_DIR/docker-compose.yml.$DATE cp ~/metatube/config/metatube.db $BACKUP_DIR/metatube.db.$DATE echo "备份完成：$BACKUP_DIR"7.3 日志管理
长期运行后，Docker 日志可能占用较多磁盘空间。可以在
docker-compose.yml中添加日志限制：services: metatube: # ... 其他配置 ... logging: driver: "json-file" options: max-size: "10m" max-file: "3"八、小结
通过本文的学习，你应该已经掌握：
章节 核心知识点 第一章 MetaTube 架构原理、服务端与插件的关系 第二章 Docker Compose 部署、代理配置、一体化部署 第三章 Jellyfin 插件安装、仓库配置、媒体库设置 第四章 文件命名规范、各类番号格式、手动识别 第五章 Huggingface/Koyeb 免费云端部署 第六章 常见问题诊断与解决方案 第七章 日常维护、更新与备份策略 8.2 延伸学习资源
资源 链接 📖 MetaTube 官方文档 metatube-community.github.io 💻 GitHub 仓库 jellyfin-plugin-metatube 🐳 后端 SDK 仓库 metatube-sdk-go 💬 社区讨论 GitHub Discussions 📝 部署教程参考 liuhouliang.com 8.3 进阶主题
如果你希望进一步深入，可以探索以下方向：
- 反向代理配置：使用 Nginx/Caddy 为 MetaTube 添加 HTTPS 支持
- 多用户管理：为 Jellyfin 配置用户权限和家长控制
- 硬件转码：配置 Intel QSV / NVIDIA NVENC 硬件加速
- 自定义演员头像：使用 Gfriends Inputer 工具批量导入头像
📌 附录：快速参考卡片
Docker Compose 模板（可直接复制使用）
version: '3.8' services: metatube: image: ghcr.io/metatube-community/metatube-server:latest container_name: metatube-server restart: always command: "-dsn /config/metatube.db" ports: - "8080:8080" volumes: - ./config:/config environment: - TZ=Asia/Shanghai # 如需代理，取消下面两行的注释并修改地址 # - HTTP_PROXY=http://192.168.1.100:7890 # - HTTPS_PROXY=http://192.168.1.100:7890常用命令速查
操作 命令 启动服务 docker compose up -d停止服务 docker compose down查看日志 docker compose logs -f更新镜像 docker compose pull && docker compose up -d查看状态 docker compose psJellyfin 插件仓库地址
类型 URL 官方地址 https://raw.githubusercontent.com/metatube-community/jellyfin-plugin-metatube/dist/manifest.jsonCDN 加速 https://cdn.jsdelivr.net/gh/metatube-community/jellyfin-plugin-metatube@dist/manifest.json
-
- 抱歉，回覆主題必需先登入。