常见问题

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

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

代理配置

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

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

搜索与数据

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

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

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

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

说明：

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

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

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

说明：

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

以图搜图的图片库从哪里来？需要什么条件？

结论：以图搜图要正常工作，必须同时满足两个条件，缺一不可。

• 图库来源是可播放影片的缩略图：以图搜图的检索对象，是从已下载、可播放的影片资源中生成的缩略图。也就是说，它只能匹配到媒体库里实际存在且能够播放的影片；尚未下载或无法播放的资源不会进入图库，也就搜不到。
• JoyTag 服务可用：以图搜图依赖 JoyTag 服务来提取图片特征，因此还需要 JoyTag 服务正常在线。JoyTag 不可用时，整个以图搜图能力都无法工作。

只有「由可播放影片生成的缩略图图库」和「在线可用的 JoyTag 服务」两者同时具备，以图搜图才会返回有效结果。

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

结论：通常不是搜索坏了，而是上面两个前置条件还没满足，或者缩略图还没完成索引。

说明：

• 先确认 JoyTag 服务是否可用，这是以图搜图的硬性依赖
• 再确认图库数据是否就绪，它依赖以下几步前置数据：
• 先有可播放的媒体资源
• 后台再生成缩略图（媒体文件每 10 秒截一帧），这个任务默认是晚间运行的
• 再把缩略图写入图片搜索索引
• 如果还没生成缩略图，或者缩略图还没完成索引，搜索会成功返回，但结果可能为空

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

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

为什么本地影片很少的时候，以图搜图几乎搜不出东西？

结论：这是正常现象，不是功能坏了。以图搜图的图库完全由你本地影片生成的缩略图构成，本地资源越少，能被检索的画面就越少，效果自然差。

说明：

• 每部可播放影片会按每 10 秒一帧生成缩略图，这些缩略图才是以图搜图真正的检索对象
• 如果本地只有寥寥几部影片，整个图库的画面样本就非常有限，很多查询自然匹配不到相似结果
• 这个功能的价值会随本地媒体库规模增长而显现：需要跑上一段时间、本地积累了一定量影片资源之后，相似画面探索才会真正好用
• 换句话说，刚部署、本地几乎没有影片时，不要用以图搜图的结果来判断功能是否正常——先把媒体库养起来

历史媒体导入

导入已有媒体时，为什么浏览不到我的影片目录？

结论：最常见的原因是媒体目录没有挂载到容器内的 /mnt 下。

说明：

• 导入已有媒体时，后端的目录浏览 API 只能从 /mnt 这个根开始往下浏览
• 如果你在 compose.yaml 里把媒体目录挂到了 /data、/media 等其他位置，导入界面里就根本看不到、也选不到它们
• 解决办法是把 volumes 里媒体挂载的容器内路径（冒号右侧）改成以 /mnt/ 开头，例如 /mnt/volume1/media:/mnt/volume1/media
• 建议宿主机路径和容器内路径保持一致，后续创建媒体库、配置下载器时路径最不容易搞混

详细的路径规划可以看：

• 快速开始 里的媒体目录挂载说明
• 进阶部署 里的路径规划

导入时提示“文件太小”被跳过，怎么办？

结论：这是 allowed_min_video_file_size 在起作用，它限制了允许导入的视频最小体积，小于该值的文件会被判定为“文件太小”并跳过，按需把阈值调小即可。

说明：

• 该配置项在 [media] 下，单位是字节，默认 1073741824（= 1 GiB），也就是小于 1GB 的视频不会被导入
• 如果你要导入的是体积较小的影片（预告、合集小档、低码率资源等），就会命中这个限制
• 常见换算：256MB = 268435456、512MB = 536870912、1GB = 1073741824
• 不建议设为 0 或调得过低：BT 种子里常夹带大量垃圾小视频（采样片、广告、无关文件），阈值太低会把这些一并尝试导入。建议不要低于 256MB

详见 [media] 配置 里的 allowed_min_video_file_size。

导入时哪些视频会被合并成一部？多碟（cd1/cd2）为什么是分开的？

结论：只有 VR 影片的多个分段会被自动合并成一部；其它情况（包括 cd1/cd2、part1/part2、A/B 等多碟）都不会合并，而是作为同一番号下的多条独立媒体分别导入。

合并的判定逻辑：

• 导入时先按番号给文件分组，同一番号的文件归到一组
• 只有当一组里文件数大于 1，且这组被判定为 VR 时，才会触发合并
• VR 的判定：番号里含 VR（如 SIVR-001、DSVR-123），或文件名里含 VR，命中其一即可（不区分大小写）
• 合并采用无转码拼接（ffmpeg concat，按文件名排序首尾相接），合并后是一部影片对应一条媒体

非 VR 的情况：

• 即使文件名带 cd1/cd2、part1/part2、A/B 这类多碟标记，系统不会把它们拼成一部
• 它们会作为同一番号下的多条媒体分别导入，也就是一部影片可以挂多条媒体记录
• 如果你确实希望多碟合成一个文件，需要在导入前自行用工具合并好再导入

字幕处理上有一点要注意：

• VR 合并时，如果一组里发现多个不同的外挂字幕，为避免歧义会跳过字幕合并，只保留警告
• 只有当该组字幕唯一时，才会随合并后的影片一起导入

影片信息翻译

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

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

说明：

• 当前影片详情页里的中文标题来自 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 命令而不是后台任务形式，也可以直接结合容器日志一起看

切片与 PornBox 视频

我收藏的切片存在哪里？删了原影片会不会一起没了？

结论：切片是独立文件，存在专门的目录里；删除来源影片不会删掉切片。

说明：

• 切片切出来后是一份独立的 mp4，存放在 [media] 的 media_clip_root_path（默认 /data/media-clips）。
• 切片与来源影片解耦：删掉来源影片资源后，切片记录、文件和番号快照都保留，仍可播放，只是封面 / 预览帧这类实时从来源缩略图解析的内容会缺失。
• 正因为它是独立资产，这个目录必须单独挂一个持久化卷，否则容器重建后切片会丢失。详见切片收藏 → 部署须知。

为什么圈选切片失败，或者提示切片过长？

结论：切片是同步切出来的，所以对区间长度和单次耗时都有上限。

说明：

• 圈选区间不能超过 media_clip_max_duration_seconds（默认 900 秒 / 15 分钟），超了会直接拒绝。
• 单次 ffmpeg 切片还有墙钟超时 media_clip_ffmpeg_timeout_seconds（默认 120 秒），遇到坏文件或慢挂载卡死会被回收并按失败处理。
• 起点和终点选成同一张缩略图、圈不出有效区间时，也会失败。
• 这两个上限都可以在 [media] 配置 里按你机器的实际情况调整。

切片合集能跨影片连续播放吗？

结论：可以，这正是切片合集的用途。

说明：

• 切片合集的成员是切片，可以来自完全不同的影片，按你排好的顺序连续播放。
• 同一个切片可以同时放进多个合集；删切片会自动从所有合集移除，删合集不会删切片本体。
• 它和「影片播放列表」是两套独立机制：播放列表放整部影片，切片合集放切片。

PornBox 视频（非 JAV）怎么纳管？和导入影片有什么区别？

结论：在 Web 界面「媒体导入」页的「PornBox 影片」标签导入，搬入媒体库但不抓元数据。

说明：

• 它面向没有番号、没有外部元数据的普通视频，和 JAV 影片体系平行，定位是「仅播放 + 整理」。
• 导入在「媒体导入」页（管理 → 媒体导入）的「PornBox 影片」标签完成：浏览选源 + 选媒体库 + 必选合集 + 选导入方式，后台异步搬库（与 JAV 同一套硬链接 / 复制语义），标题默认取文件名，不抓 JavDB / DMM 元数据。
• 它只通过视频合集组织（不支持标签 / 人物），合集成员有顺序，可按顺序连续播放。
• 不提供订阅、自动下载、推荐、相似影片、以图搜图等 JAV 专属能力。
• 导入方式与限制见常用命令 → 导入已有媒体，功能说明见PornBox 视频管理。

相关页面

• 想看后台任务默认频率和用途： 后台任务
• 想看配置项说明： 配置说明
• 想看手动命令： 常用命令
• 想看切片怎么用： 切片收藏
• 想看 PornBox 视频管理： PornBox 视频管理