告别杂乱：使用 Shoko + Jellyfin 实现 100% 准确的番剧刮削

为什么要部署 Shoko？

在使用 Jellyfin、Plex 或 Emby 等流媒体服务时，所有的动漫爱好者几乎都会遇到一个令人头疼的通病：自带的刮削器对番剧极其不友好。

传统的刮削器（如 TMDB、TVDB）大多是为欧美剧集设计的，它们依赖规范的文件命名（如 S01E01）。但是，我们下载的番剧往往命名五花八门（包含字幕组名称、分辨率、乱码等），且经常包含各种特典（SP）、OVA、剧场版。这就导致了几个致命问题：

• 识别率极低：文件名稍微不规范，就刮削出莫名其妙的影视剧。
• 季数与集数混乱：部分番剧采用绝对集数（如第 1 到 100 集），而传统媒体库强迫按季（Season 1, Season 2）分类，导致集数错乱。
• 特典无处安放：OVA 和 SP 经常被错误识别或直接忽略。

Shoko Server 就是为了彻底解决这些痛点而生的。 它是一个独立于媒体服务器之外的专属“番剧大脑”。它的核心优势在于：

1. 无视文件名的 Hash 匹配：Shoko 不看你的文件名叫什么，而是直接读取文件的底层 Hash 值，去全球最权威的动漫数据库 AniDB 进行比对。这意味着，哪怕你的文件名是一串纯乱码，只要文件本身没损坏，它都能 100% 精准识别！
2. 完美的元数据与海报墙：配合插件，它可以为你抓取到最完美的中文剧集详情、角色信息、多维度海报，连特典和 SP 都能安排得明明白白。
3. 拯救强迫症的目录映射：就算你的本地下载文件夹里各种番剧混杂在一起“乱成一锅粥”，Shoko 也可以通过“虚拟文件系统（VFS）”功能，在不破坏原文件（不影响 PT 保种）的前提下，向 Jellyfin 映射出一个结构极其严谨、命名极其规范的虚拟目录。

简而言之，前期虽然需要投入时间让它扫描，但一旦完成，以后你只需要把下载好的番剧“无脑”丢进文件夹，剩下的整理和刮削工作，Shoko 会瞬间且完美地自动完成。

部署前提与注意事项

在开始这场“媒体库革命”之前，请务必了解以下几点：

• 硬件要求：教程以 Debian 12 物理机 + Docker Compose 部署为例。由于初期扫描几百 G 甚至几 T 的视频文件并计算 Hash 值非常吃 CPU 性能和磁盘 I/O，建议直接部署在存放番剧的宿主机（NAS）上。本地读取速度最快，不占用局域网带宽。性能方面，主流的家用 NAS CPU（如 Intel N 系列或 E3 级别）完全够用。
• 做好“熬大夜”的心理准备：Shoko 极其强大，但初次扫描会非常漫长。为了防止滥用并保护官方服务器，AniDB 对 API 请求有严格的限速（几秒钟才能请求一次）。你的库越庞大，初次刮削的时间就越长（2T 大概需要1天，仅供参考）。请耐心等待，这段等待绝对是物超所值的。
• 语言门槛：Shoko 目前没有官方的纯中文 Web UI，后台是全英文的。请善用浏览器的自带翻译插件来辅助配置。

详细操作步骤

第一步：注册 AniDB 账号（必须）

Shoko 的核心全靠 AniDB 的数据库，所以你必须拥有一个“通行证”。

1. 用电脑浏览器打开 AniDB 官网：https://anidb.net/
2. 点击右上角的 Register 注册一个账号。
3. 记住你的用户名和密码，稍后我们要把它填进 Shoko Server 里，让它拿着你的账号去向官方服务器请求数据。

第二步：使用 Docker Compose 部署 Shoko

建议使用 Docker Compose 部署，方便日后管理和升级。在你习惯存放 Docker 配置的目录下创建一个 docker-compose.yml 文件，填入以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

version: '3.8'
services:
  shoko-server:
    image: shokoanime/server:latest
    container_name: shoko-server
    restart: unless-stopped
    environment:
      - PUID=0  # 给予最高 root 权限，无视乱七八糟的文件夹权限问题
      - PGID=0
      - TZ=Asia/Shanghai
    ports:
      - "8111:8111"  # Shoko 的 Web 管理界面端口
    volumes:
      # 冒号左边是你的 NAS 真实路径，右边是容器内部路径
      - /你宿主机真实的路径/shoko:/root/.shoko    # 挂载核心数据库和配置文件
      - /你的番剧文件夹路径/BANGUMI:/media/BANGUMI  # 挂载你的总番剧文件夹（请务必填对）

执行启动命令拉取并运行容器。

第三步：登入 Shoko WebUI（唤醒神明）

容器启动后，稍微等个 1 分钟让它初始化数据库。然后打开电脑浏览器，输入：http://你的NAS_IP地址:8111

恭喜你！你现在应该能看到 Shoko Server 极其炫酷的 WebUI 欢迎界面了。默认的初始管理员账号和密码如下：

• 账号：Default
• 密码：（留空，什么都不填直接登录）

你也可以在后续设置中修改账号密码，但请务必记住，后面配置 Jellyfin 插件时会用到。

第四步：核对暗号（配置 AniDB 与 TMDB）

进入后台后，系统会引导你进行初次设置（First Time Setup），你也可以直接点击左侧菜单的 Settings (设置) -> AniDB。

1. AniDB 设置：填入你刚才注册好的 AniDB Username（用户名）和 Password（密码）。下方的 Client Port 保持默认即可，点击保存并测试连接。
2. TMDB 设置：在左侧找到 TMDB/TvDB 相关的设置。为了能拉取精美的中文海报，请务必勾选允许它从 TMDB 刮削元数据（新版 Shoko 通常默认已集成并开启）。

第五步：挂载媒体库（⚠️ 极其危险，切勿踩坑！）

现在到了最激动人心、但也最容易出错的一步：把庞大的番剧库喂给它。

1. 在 Shoko 后台，找到左侧的 Import Folders (导入文件夹) 。
2. 点击添加文件夹，选择容器内的路径（即我们在 Docker Compose 中映射的 /media/BANGUMI）。

生死攸关的选项说明：

• Drop Source (拖放源) / Drop Destination (拖放目标) ：慎重选择！ 如果你的文件没有在 PT 站保种，且希望 Shoko 帮你物理整理文件夹，你可以配置这些。但如果你需要保种（原文件坚决不能动），请务必保持只读。
• Watch (监控) ：强烈建议打勾。这意味着以后只要有新文件放进这个目录，Shoko 就会自动触发扫描。

原理解释：如果误勾了不该勾的移动选项，Shoko 可能会自作聪明地启用“文件重命名和自动移动”功能，把你 NAS 里的原文件直接切碎重组挪位置！对于 PT 玩家来说这是灾难。我们现阶段只让它做“只读扫描”算 Hash，坚决不准它碰物理文件！

第六步：修改中文元数据并开始扫描

先不要急着点击 Import！

1. 先进入设置界面，将元数据语言偏好修改为中文 (Chinese) ，确保扫出来的信息、标题和简介都是中文的。

   

2. 确认无误后，回到 Dashboard，点击 Import，让神明开始工作！此时你会看到数据开始疯狂滚动，计算 Hash 并向外请求数据。

第七步：在 Jellyfin 中安装 Shokofin 插件

在 Shoko 辛勤扫描的这几天里，我们可以先去 Jellyfin 把“接收端”配置好。Shoko 只是“幕后大脑”，要把数据完美呈现在海报墙上，我们需要 Jellyfin 的专属插件：Shokofin。

1. 进入 Jellyfin 控制台 -> 左侧底部 “插件” -> 顶部 “存储库” 。
2. 点击 + 号 (添加)，填入以下信息：

• 名称：Shoko
• URL：https://raw.githubusercontent.com/ShokoAnime/Shokofin/metadata/stable/manifest.json

3. 保存后，点击顶部 “目录” ，往下翻找到 Anime 分类，点进去安装 Shoko 插件。
4. 安装完成后，必须重启 Jellyfin 服务（在物理机终端执行 systemctl restart jellyfin）。

第八步：让 Jellyfin 连上 Shoko 的大脑

1. 重启 Jellyfin 后，进入控制台 -> “插件” -> 找到已安装的 Shoko，点击进入设置。
2. 在设置里填入你 Shoko Server 的连接信息：

• Server URL：http://你的NAS_IP:8111
• Username：Default
• Password：（留空，或者填入你修改后的密码）

3. 点击保存，Jellyfin 就成功与 Shoko 大脑连通了！

第九步：扫描完成后的终极整理（分情况讨论）

等挂机几天，Shoko 把所有的 Tasks（任务）全部跑完，右上角的“未识别”也清理干净后，我们要开始释放它的真正威力：

• 情况 A：不需要保种（纯自己看）
  那太爽了！直接在 Shoko 后台一键开启“自动移动重命名 (Auto Rename & Move)”。几秒钟的时间，它会在你的 NAS 里自动建好类似 工作细胞/Season 1/ 这种极其标准的文件夹，把原本的乱码文件重命名为标准的 S01E01.mkv，并分门别类地挪进去。垃圾堆瞬间变成教科书级别的完美媒体库！
• 情况 B：需要保种（不能改动原文件）
  绝对不能移动物理文件！我们需要在 Shoko 里开启 “硬链接 (Hardlink) / 虚拟文件系统 (VFS)” 模式。开启后，Shoko 会“虚空”生成一份整理好的、完美命名的镜像目录给 Jellyfin 看，同时完全不破坏你原本那些用于保种的乱码文件。

第十步：在 Jellyfin 建立完美媒体库

回到 Jellyfin：

1. 新建一个媒体库，文件夹选择物理机上的番剧目录（会自动替换成Shoko 生成的 VFS 虚拟目录）。
2. 最关键的一步：在下方的刮削器（元数据下载器）选项中，全部只勾选 Shoko，其他的（如 TMDB、TVDB）一律取消勾选！
3. 点击保存。

接下来就是见证奇迹的时刻，Shoko 会像变魔术一样，把最完美的中文海报墙展现在你面前。

补充：手动匹配未能识别的番剧

因为 Shoko 是严格按照 Hash 来识别的，如果你下载的是某个非常冷门的字幕组压制的版本，或者文件被修改过，它的 Hash 可能还没有被上传到 AniDB 的数据库，此时就会出现“未识别”。

不用担心，Shoko 提供了强大的手动匹配工具。你可以在后台找到这些未识别的文件，手动搜索番剧名称进行绑定。绑定后，它依然能为你生成完美的刮削数据。