常见问题

这页整理当前版本里最常见的一批行为说明。

• 所有结论都以当前后端实现为准
• 如果你改过 config.toml，后台任务频率请以你自己的配置为准

代理配置

配置文件中，metadata.proxy 用于 GFriends 资源访问和 DMM 网站抓取。DMM网站需要日本节点的IP, 所以这个代理需要你自己做好分流，确保访问 DMM 的请求能走到日本节点的代理上；GFriends 资源访问则没有地域限制，能访问github就可以了。

metadata.license_proxy 是另一项独立配置，只用于访问数据源授权中心。授权中心部署在 Cloudflare Workers，如果你所在地区或网络环境无法直接访问，可以在这里填写 HTTP 代理，例如 http://192.168.1.1:7890。

javdb 相关接口不走代理，所以代理配置对 javdb 无效，如果你路由器开了透明代理，需要确保c0.jdbstatic.com域名直连，或者至少不要让它走日本节点的代理，因为这个域名不允许日本节点访问。

数据源授权

为什么外部数据源需要激活？

SakuraMedia 前端与后端主体代码仍保持开源；外部数据源实现不再完全开源，需要通过免费激活授权后使用。

引入激活授权仅用于控制同时使用人数，不会收取费用。授权失效只会影响外部数据抓取相关功能，不会影响登录、本地媒体库、已导入内容浏览、播放等基础能力。

激活码在哪里获取？

激活码通过 Telegram 机器人发放：SakuraMedia Bot。

一个 Telegram 用户只能获取 1 个激活码。激活码不收费，请不要从第三方购买或转卖。

在哪里激活数据源？

登录桌面端 APP 后，进入 配置中心 → 数据源，在“数据源授权”卡片中粘贴激活码，然后点击“激活授权”。

激活码只在激活请求中使用。前端不会保存激活码，后端也不会把激活码写入配置文件。

一个激活码可以激活多个服务吗？

单个激活码可以多次使用，但同一时间只能激活 1 个服务。

如果你使用同一个激活码激活新的 SakuraMedia 服务，之前已经激活的服务会失效。这适合迁移机器、重装服务或切换部署实例时使用，但不适合把同一个激活码同时分发给多台服务。

授权多久刷新一次？

激活成功后，后端会每 6 小时自动刷新一次授权状态。只要服务能够正常访问授权中心，通常不需要手动处理。

如果服务连续超过 24 小时无法完成授权刷新，授权会失效。授权失效后，可以先在 配置中心 → 数据源 中点击“同步授权”或“测试连接”。

授权失效后还能继续用吗？

可以继续使用基础功能。授权失效只影响外部数据抓取相关功能，例如在线搜索外部数据、抓取外部元数据等。

登录、本地媒体库、已导入内容浏览、播放等基础能力仍可正常使用，已经入库的数据也不会因为授权失效而丢失。

授权中心连不上怎么办？

授权中心部署在 Cloudflare Workers。某些地区或网络环境可能无法直接访问授权中心，可以在配置文件 [metadata] 中填写 license_proxy：

[metadata]
license_proxy = "http://192.168.1.1:7890"

license_proxy 只用于访问授权中心，不等同于用于 DMM 与 GFriends 的 metadata.proxy。如果代理配置后仍然失败，优先确认 SakuraMedia 后端容器内是否能访问该代理。

搜索与数据

在线搜索入库影片或女优失败

排查c0.jdbstatic.com域名是否能否正常访问，如果是软路由开了透明代理，确认这个域名不要让它走日本节点的代理， 这个域名不允许日本节点访问.

为什么刚启动后看不到影片或女优？

结论：这是正常现象。刚部署完成时，本地数据库通常还是空的。

说明：

• 本地搜索只会查已经入库的数据
• 第一次部署后，如果你还没有导入历史媒体，也还没有做过在线搜索，本地自然查不到结果
• 这时候可以在搜索页打开 联网 图标，再去搜索影片或女优
• 搜索成功后，对应元数据会自动写入本地库
• 下次再搜索同一部影片或同一位女优时，通常就不需要再开 联网

为什么“女优上新”可能是空的？

结论：这个页面只看“已订阅女优”的影片更新，不是全站女优影片信息。

说明：

• 后端的“女优上新”只返回至少关联一位已订阅女优的影片
• 如果你还没有订阅任何女优，这个页面为空是正常的
• 即使你本地已经有影片，只要这些影片没有关联到“已订阅女优”，这里也不会出现

为什么以图搜图没有结果？

结论：通常不是搜索坏了，而是还没有可检索的缩略图向量数据。

说明：

• 以图搜图依赖两步前置数据：
• 先有媒体资源
• 后台再生成缩略图(媒体文件的每10截一帧图)，这个任务默认是晚间运行的
• 再把缩略图写入图片搜索索引
• 如果还没生成缩略图，或者缩略图还没完成索引，搜索会成功返回，但结果可能为空

如果已经有媒体资源了可以手动跑一次，可以看 常用命令 里的：

• generate-media-thumbnails
• index-image-search-thumbnails

影片信息翻译

为什么有些影片会出现中文标题或中文简介，有些没有？

结论：中文标题和中文简介都不是导入后立刻就有，它们共用同一组影片信息翻译配置；其中中文简介还依赖“先补原文描述，再跑翻译任务”这两步。

说明：

• 当前影片详情页里的中文标题来自 title_zh，中文简介来自 desc_zh
• 标题翻译和简介翻译共用 [movie_info_translation] 这一组 OpenAI 格式大模型接口配置
• 标题翻译直接基于影片原始标题执行，不依赖 DMM 描述抓取链路
• 系统通常会先通过 DMM 描述抓取链路补原文描述 desc
• 只有原文描述已经抓到，后续翻译任务才会继续生成中文简介
• 如果你没有启用这组配置，系统不会自动生成 title_zh 和 desc_zh

如果你想手动补跑，可以看 常用命令 里的：

• aps sync-movie-desc
• aps translate-movie-desc
• aps translate-movie-title

做影片信息翻译时，推荐用什么模型？

结论：强烈建议优先使用 Gemma 4 31B。

说明：

• 这条链路本质上是在调用一个 OpenAI 格式的大模型接口，不是固定绑定某一家翻译服务
• 当前影片标题翻译和影片简介翻译共用同一套模型配置
• 从当前项目场景看，Gemma 4 系列的内容审查相对更宽松，更适合处理影片日语描述这类文本
• 如果你主要目标是先把简介翻译链路稳定跑通，Gemma 4 31B 是当前最推荐的选择
• 不建议优先使用国内模型，这类模型在这类文本上更容易触发审查、拒答或输出不稳定

为什么强烈建议用 Gemma 4 31B？在哪里可以先试？

结论：因为它更容易跑通这一类文本，而且试用门槛也比较低。

说明：

• Gemma 4 31B 在这个场景下通常比很多国内模型更稳定
• 如果你只是想先验证整条翻译链路，不一定要先自建完整模型服务
• 一个相对省事的做法，是先通过 Ollama Cloud 的 free 计划试用 Gemma 4 31B
• 等你确认效果和稳定性都符合预期，再决定后续是否切到自己的长期模型部署方案

为什么 DMM 描述抓取失败？

结论：最常见的问题不是任务没跑，而是 metadata.proxy 没配好。

优先检查这些点：

• metadata.proxy 是否已经配置；旧版 metadata.dmm_proxy 只作为兼容回退
• 代理是否是可访问 DMM 的日本 IP
• 代理本身是否还能正常连通目标站点

如果这里没配对，影片原文描述回填链路通常就会失败或结果不稳定，进而影响简介翻译；但它不会阻止影片标题翻译运行。

自动下载

什么情况下系统会自动搜索影片资源并下载？

只有“已订阅、缺媒体、无下载记录、且搜索到合格候选”的影片，才会进入自动下载。

系统会同时检查这些条件：

1. 影片已订阅，也就是 is_subscribed = true
2. 影片当前没有任何有效媒体
3. 影片当前没有任何下载任务记录
4. Jackett 至少返回一个可用候选
5. 候选通过基础过滤

这里的基础过滤包括：

• 有 magnet_url 或 torrent_url
• seeders >= 3
• 体积在 1 GiB 到 40 GiB 之间

因此，下面这些情况通常不会触发自动下载：

• 影片未订阅
• 已经导入过本地媒体
• 数据库里已经有该影片的任何下载任务记录
• 搜索结果为空
• 搜索结果都被过滤掉

自动下载时，系统怎么选资源？

结论：系统会先过滤掉不合格候选，再按固定优先级排序，只选最优的一个资源提交下载。

排序规则是：

1. 4K 优先
2. 在同一候选池里，PT 优先于 BT
3. 在同一候选池里，中字 优先于非中字
4. 再按做种人数从高到低
5. 再按体积从大到小
6. 最后按标题等字段做稳定排序

要注意：

• 4K 是一级优先级，高于 PT/BT 和 中字
• 这里说的 4K 是下载候选标签，不是本地媒体解析出来的标签

为什么影片已经订阅了，但还是没有自动下载？

结论：最常见的原因不是任务没跑，而是影片没有满足自动下载前提。

优先检查这些点：

• 它是否已经可播放了(已经有媒体资源了)
• 数据库里是否已经有它的历史下载任务记录
• Jackett 是否能搜到可用候选
• 下载器、索引器和媒体库绑定是否完整

如果你想立刻手动触发一次，可以看 常用命令 里的 auto-download-subscribed-movies。

为什么下载完成了，但影片还没有自动导入？

结论：通常是“下载路径映射”或“自动导入任务”这一层还没对上。

最常见原因有：

• client_save_path 填的是 qBittorrent 容器内路径
• local_root_path 填的是 SakuraMedia 可访问的本地路径
• 这两个路径没有正确映射到同一批真实文件
• 下载任务状态还没有先同步到本地
• 自动导入任务还没跑到，或者导入过程中失败了

更直白一点：

• qBittorrent 知道文件下到了哪里，不代表 SakuraMedia 也能访问到那个目录
• 如果 SakuraMedia 看不到下载完成的实际文件，就没法继续导入

这类问题优先去看：

• 快速开始 里下载器路径填写说明
• 进阶部署 里的路径规划
• 常用命令 里的日志和手动任务命令

播放与解码

播放时的视频解码，依赖服务端转码吗？

结论：不依赖。本项目当前不走服务端解码 / 转码链路，播放时的视频解码全部由客户端完成。

说明：

• 播放器底层采用的是 mpv
• 是否能走硬件解码，取决于当前客户端设备、系统和驱动是否支持对应编解码能力
• 只要客户端硬件支持，默认就会优先使用硬件解码播放
• 如果客户端本身不具备对应硬解能力，才会回退到软件解码

换句话说，播放性能主要看客户端本身的解码能力，而不是看服务端有没有额外帮你做转码。

为什么不支持视频清晰度切换？

结论：这个功能当前不会支持，后续也不在规划内。

说明：

• SakuraMedia 的定位一直是局域网内使用的媒体管理和播放工作台，不是面向公网分发的视频平台
• “切换清晰度”这类能力通常意味着要额外引入服务端转码、多码率产物和分发链路
• 一旦支持这条链路，项目的使用边界和风险模型都会明显变化
• 因此当前会明确保持“不提供清晰度切换”的策略，尽量把项目使用场景限定在局域网内，避免一些不必要的麻烦

如果你更关注播放体验，优先保证这几件事通常更实际：

• 客户端设备具备对应格式的硬件解码能力
• 局域网带宽和存储读取速度足够稳定
• 媒体文件本身的编码规格与你的播放设备能力匹配

字幕与相似影片

为什么字幕页里有些影片没有字幕？

结论：字幕是在导入影片资源时，从影片文件同级目录里的字幕文件一起导入的；字幕页只展示这些已经入库且仍可访问的字幕文件。

说明：

• 导入影片资源时，系统会一起扫描影片文件同级目录中的字幕文件并建立 Subtitle 记录
• 页面会读取已经入库的 Subtitle 记录，并校验对应字幕文件当前仍然可访问
• 如果本地没有可用字幕，页面就会返回空列表
• 你仍然可以通过本地挂载字幕文件、媒体字幕识别等方式，让页面后续出现字幕

subtitle_root_path 现在是做什么的？

结论：它是字幕目录，用于承接导入时识别到的字幕文件，并供后续页面读取和索引。

说明：

• 导入影片资源时，系统会处理影片文件同级目录中的字幕文件
• 页面展示和字幕下载依赖这里对应的字幕文件仍然可访问
• 这是当前版本统一使用的字幕目录

为什么相似影片列表为空，或者改动后没有马上更新？

结论：相似影片列表依赖离线任务 movie_similarity_recompute，不是请求时实时计算。

说明：

• 详情页读取的是后台预计算并已落库的相似影片结果
• 刚导入大量影片、刚调整合集标记、刚同步完元数据后，可能需要等下一次离线重算
• 如果你想立刻刷新，可以手动执行 aps recompute-movie-similarities

想进一步看任务频率和手动触发方式，可以看：

• 后台任务
• 常用命令

活动中心

通知中心和任务中心分别看什么？

结论：通知中心看“提醒”，任务中心看“执行过程和结果”。

可以这样理解：

• 通知中心更像消息列表
• 任务中心更像后台作业记录

一般来说：

• 下载导入成功、新影片可用、异常提醒，更偏通知中心
• 缩略图生成、影片相似度重算、排行榜同步、自动下载等执行进度，更偏任务中心

我已经执行了命令，在哪里看运行进度？

结论：优先去活动中心或任务中心看。

说明：

• 通过 aps ... 触发的任务，通常会在活动中心 / 任务中心留下运行记录
• 你可以在那里看到运行中、成功、失败以及部分进度信息
• 如果是纯 CLI 命令而不是后台任务形式，也可以直接结合容器日志一起看

相关页面

• 想看后台任务默认频率和用途： 后台任务
• 想看配置项说明： 配置说明
• 想看数据源激活规则： 数据源授权
• 想看手动命令： 常用命令