🎯 学习目标：掌握 MetaTube 插件的完整部署流程，包括后端服务搭建、插件配置、文件命名规范及常见问题排查

一、MetaTube 概述与架构理解

1.1 什么是 MetaTube？

MetaTube 是一款专为 Jellyfin/Emby 媒体服务器设计的元数据刮削插件，主要用于日本成人影片（JAV）的信息获取与整理。它采用服务端 + 插件的分离式架构，能够自动从多个数据源抓取完整的影片元数据。

MetaTube 的核心功能包括：

1.2 工作原理与架构

理解 MetaTube 的工作原理对于后续的部署和故障排查至关重要：

┌─────────────────┐     ①发送文件名      ┌──────────────────┐
│                 │ ──────────────────▶ │                  │
│   Jellyfin/     │                     │   MetaTube       │
│   Emby 插件     │ ◀────────────────── │   Server 后端    │
│                 │    ④返回元数据       │                  │
└─────────────────┘                     └──────────────────┘
                                               │ ②请求数据
                                               ▼
                                        ┌──────────────────┐
                                        │   数据源网站     │
                                        │  (FANZA/DMM/    │
                                        │   MGS/FC2等)    │
                                        └──────────────────┘
                                               │
                                               ▼ ③获取信息
                                        ┌──────────────────┐
                                        │   图片/元数据    │
                                        └──────────────────┘

工作流程详解：

1. 文件扫描：Jellyfin/Emby 扫描媒体库，将文件名（通常包含番号）发送给 MetaTube 插件
2. 请求转发：插件将番号信息发送到 MetaTube Server 后端
3. 数据抓取：后端根据番号向各个数据源网站（如 FANZA、DMM、MGS、Arzon 等）发起请求
4. 数据处理：后端对抓取的数据进行处理（包括图片裁剪、人脸识别、文字翻译等）
5. 返回结果：处理后的元数据返回给插件，最终由 Jellyfin/Emby 保存和展示

1.3 为什么需要自建后端？

许多初学者会问：为什么不能直接使用公共后端服务？ 这里需要详细解释：

结论：强烈建议自建后端服务，尤其是有长期使用需求的用户。本课程将重点讲解如何使用 Docker Compose 部署自建后端。

二、Docker Compose 部署 MetaTube Server

2.1 部署前的准备工作

2.1.1 环境要求

在开始部署之前，请确保你的系统满足以下要求：

2.1.2 网络环境的特殊说明 ⚠️

这是 MetaTube 部署中最关键也最容易被忽视的问题：

由于刮削源（如 FANZA、DMM、MGS 等）的地域限制，MetaTube 后端必须能够访问"真正的互联网"，且最好出口 IP 为日本或美国。部分刮削源仅对这两个地区完全开放。

部署环境优先级（从高到低）：

1. 🥇 Cloud-Native 云原生部署（如 Huggingface Space、Koyeb、Railway 等）
2. 🥈 海外 VPS 部署（日本/美国/新加坡等地区的云服务器）
3. 🥉 本地部署 + 代理配置（需要稳定的代理环境）

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

配置项详解：

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]:[端口]

可行的代理环境方案：

1. 局域网内的代理软件：在 Windows/Mac 上运行 Clash/V2Ray，开启"允许局域网连接"
2. 旁路由代理：OpenWrt/软路由上运行代理服务
3. 虚拟组网：通过 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:
      - jellyfin

2.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 添加插件仓库

1. 登录 Jellyfin 管理后台
2. 进入 控制台 → 插件 → 存储库
3. 点击 添加 按钮
4. 输入以下信息：

⚠️ 注意：CDN 地址可能存在缓存延迟，更新可能不是最及时。

3.1.2 安装插件

1. 进入 控制台 → 插件 → 目录
2. 在列表中找到 MetaTube
3. 点击进入，选择版本后点击 安装
4. 重启 Jellyfin 服务（这一步很重要！）

3.2 配置 MetaTube 插件

3.2.1 基础配置

重启完成后：

1. 进入 控制台 → 插件 → MetaTube（或在已安装插件列表中点击）
2. 配置以下关键参数：

配置要点：

• 如果 Jellyfin 和 MetaTube 部署在同一台机器上，可以使用 http://localhost:8080
• 如果 Docker 网络隔离，建议使用实际的局域网 IP 地址
• 如果使用 Docker 内部网络，可以使用容器名 http://metatube-server:8080

3.2.2 高级配置选项

MetaTube 插件还提供了丰富的高级配置选项：

3.3 创建媒体库

3.3.1 媒体库配置

1. 进入 控制台 → 媒体库 → 添加媒体库
2. 按照以下设置进行配置：

3.3.2 重要提示

⚠️ 务必取消勾选其他元数据下载器（如 TheMovieDB、OMDb 等），避免干扰 MetaTube 的刮削结果。

四、文件命名规范与刮削技巧

4.1 命名规则的重要性

文件命名是影响刮削成功率的最关键因素之一。 MetaTube 通过解析文件名中的番号来匹配元数据，因此正确的命名格式至关重要。

4.2 标准命名格式

4.2.1 基本格式

[番号].mp4
[番号]/[番号].mp4  （独立文件夹模式）

示例：

4.2.2 各类番号格式参考

4.3 命名最佳实践

4.3.1 应该避免的命名方式

4.3.2 批量重命名工具推荐

如果你有大量需要重命名的文件，可以使用以下工具：

4.4 手动刮削与识别

当自动刮削失败时，可以使用手动识别功能：

1. 在 Jellyfin 中找到未识别的影片
2. 右键点击 → 识别
3. 在搜索框中输入正确的番号
4. 从结果中选择正确的条目

五、免费云端部署方案

如果你没有海外服务器，可以考虑以下免费部署方案：

5.1 Huggingface Space 部署（推荐）

Huggingface 提供免费的 Docker 运行环境（2 CPU / 16GB 内存），非常适合部署 MetaTube 后端。

5.1.1 部署步骤

1. 注册账号：访问 Huggingface 官网，使用邮箱注册（需要科学上网）
2. 创建 Space：
   • 点击右上角头像 → New Space
   • 填写 Space 名称（如 my-metatube）
   • 选择 Docker → Blank
   • 选择 CPU Basic（免费）
   • 可见性选择 Public
   • 点击 Create Space
3. 配置 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"]

4. 等待构建完成：通常需要 1-3 分钟
5. 获取服务地址：格式为 https://[用户名]-[space名称].hf.space

5.1.2 注意事项

⚠️ Huggingface Space 的限制：

• 48 小时无访问会自动休眠
• 休眠后首次访问需要等待几秒钟唤醒
• 可以设置定时任务定期访问以保持活跃

5.2 Koyeb 部署

Koyeb 也提供永久免费的部署方案：

1. 访问 MetaTube Koyeb 快速部署 页面
2. 点击一键部署按钮
3. 按照引导完成配置

六、常见问题与故障排查

6.1 插件状态不活跃

症状：在 Jellyfin 插件列表中，MetaTube 显示为不活跃状态

可能原因及解决方案：

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 图片无法加载

可能原因：

6.4 数据库相关问题

问题：刮削数据丢失/每次重启后需要重新刮削

原因：未正确挂载数据库文件

解决方案：

确保 docker-compose.yml 中正确配置了 volumes：

volumes:
  - ./config:/config
command: "-dsn /config/metatube.db"

验证数据库文件是否存在：

ls -la ./config/
# 应该能看到 metatube.db 文件

6.5 刮削速度慢

优化建议：

1. 使用 SQLite 持久化存储：已刮削的数据会被缓存，重复刮削时直接读取缓存
2. 选择更快的代理节点：日本节点通常访问刮削源最快
3. 减少同时刮削的数量：避免短时间内刮削大量影片，可能触发限流

七、维护与更新

7.1 定期更新

推荐每月检查并更新一次，以获取最新功能和修复：

# 进入项目目录
cd ~/metatube

# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

# 验证更新结果
docker compose ps

7.2 备份策略

需要备份的内容：

简单备份脚本：

#!/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"

八、小结

通过本文的学习，你应该已经掌握：

8.2 延伸学习资源

8.3 进阶主题

如果你希望进一步深入，可以探索以下方向：

1. 反向代理配置：使用 Nginx/Caddy 为 MetaTube 添加 HTTPS 支持
2. 多用户管理：为 Jellyfin 配置用户权限和家长控制
3. 硬件转码：配置 Intel QSV / NVIDIA NVENC 硬件加速
4. 自定义演员头像：使用 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

常用命令速查

Jellyfin 插件仓库地址