SakuraMedia

Appearance

常见问题 ​

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

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

代理配置 ​

可设置容器环境变量 HTTP_PROXY / HTTPS_PROXY，设置后javdb和gfriends请求将会走执行代理。其他qbittorrent / torznab 等链路不会走代理。

账号与登录 ​

忘记用户名或密码了怎么办？ ​

结论：在后端容器里跑一次 reset-account 命令，用新的用户名和密码覆盖式重建单账号即可，不需要校验旧密码。

bash
docker exec -it --user app -w /app sakuramedia python -m src.start.commands reset-account

执行后会依次提示输入新用户名和新密码（密码隐式输入并二次确认）。也可以直接把参数写在命令行里：

bash
docker exec --user app -w /app sakuramedia python -m src.start.commands reset-account --username admin --password 'your-new-password'

要注意：

  • 这是覆盖式重置：会先清空数据库里所有已有账号，再按你给的用户名和密码重建一个单账号
  • 同时会清空所有 refresh token，所有已登录的客户端都会立即失效，需要用新账号重新登录
  • 整个过程在同一个事务里，中途失败会回滚，不会出现“旧账号删了、新账号没建”导致完全登不上的情况

详见 常用命令 → 重置账号。

搜索与数据 ​

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

可以先在「总览」页跑一次「组件诊断」，看 JavDB 项是否连通——不通时会直接给出原因提示。 如果诊断通过但搜索仍失败，排查c0.jdbstatic.com域名是否能否正常访问，如果是软路由开了透明代理，确认这个域名不要让它走日本节点的代理， 这个域名不允许日本节点访问.

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

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

说明：

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

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

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

说明：

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

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

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

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

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

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

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

说明：

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

如果你不想等晚间自动任务，可以到任务中心，依次执行媒体缩略图生成 和 以图搜图缩略图向量索引。 然后再进行以图搜图。

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

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

说明：

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

历史媒体导入 ​

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

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

说明：

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

详细的路径规划可以看：

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

结论：这是 allowed_min_video_file_size 在起作用，它限制了允许导入的视频最小体积，小于该值的文件会被判定为“文件太小”并跳过，按需把阈值调小即可。 可以在系统设置->高级设置里修改.

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

结论：对每个候选做一次过滤，再按「体积主导 + 中字加成」的分数取最高的一个提交下载。选种过程与 preferred_client_kinds 无关，那个配置只决定「选出来的种子交给哪个下载器提交」。

过滤条件（同时满足才进入候选池）：

  • 有可用的 magnet 或 torrent 链接
  • 体积落在 1 GiB ~ 40 GiB 之间
  • 该影片历史下载任务里，没有把它对应的 info_hash 判死（死种黑名单是永久的：info_hash 内容寻址，同一 hash 换索引器仍是死的；要重试就去 qBittorrent 里删掉那条任务）
  • seeders > 0

排序打分（分数最高的胜出）：

  • 基础分 = 候选体积（size_bytes）
  • 候选带 中字 标签时，额外加 2 GiB
  • 分数相同（同一个种子被多个索引器返回时很常见）按 (indexer_name, title) 兜底确定，保证同一批候选每轮都选出同一个——死种黑名单机制依赖这个确定性

换句话说：

  • 体积是主导项：中字 只在两个候选体积差距不超过 2 GiB 时才能翻盘
  • 不再区分 BT / PT，也没有 4K / PT / 做种数的分层优先级
  • 做种门槛只是 > 0，不再要求 seeders >= 3
  • 首选下载器不参与候选筛选：候选选出后，preferred_client_kinds 再决定用哪个绑定的下载器去提交

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

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

优先检查这些点：

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

其中最后一条不用手动逐项核对：「总览」页跑一次「组件诊断」，会检查下载器连通、索引器配置完整性（含下载器绑定）和 Torznab 索引器连通。

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

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

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

最常见原因有：

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

更直白一点：

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

这类问题优先去看：

  • 「总览」页「组件诊断」里该下载器的存储检测——它会实测这两个路径的目录映射和硬链接，「是否指向同一批真实文件」当场就能验证
  • 快速开始 里下载器路径填写说明
  • 进阶部署 里的路径规划
  • 常用命令 里的日志和手动任务命令

播放与解码 ​

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

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

说明：

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

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

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

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

说明：

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

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

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

VR 影片怎么播放？分多个片段的资源能合并播放吗？ ​

结论：VR 影片可以通过外部播放器播放；一部影片拆成多个片段的资源，可以合并为完整影片连续播放。

说明：

  • 外部播放器是移动端（Android）能力：在「外部播放器」设置页选好已安装的播放器（如 VLC、MX Player）作为默认播放器后，点击播放会直接拉起该播放器，不再进入应用内播放页。
  • 多分段资源在外部播放器就绪时提供「合并播放」模式，把多个分段合并成完整影片播放，无需手动切换片段。
  • 115 网盘资源走外部播放器时，默认使用后端 HLS 代理（.m3u8）链接播放，而不是直连 115，播放更稳定。
  • 当前实验性支持 Pico 等 VR 设备以 2D 形式使用本应用。

字幕与相似影片 ​

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

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

说明：

  • 导入影片资源时，系统会一起扫描影片文件同级目录中的字幕文件并建立 Subtitle 记录
  • 页面会读取已经入库的 Subtitle 记录，并校验对应字幕文件当前仍然可访问
  • 如果本地没有可用字幕，页面就会返回空列表
  • 想补字幕，就把字幕文件放到影片文件同级目录再重新导入一次；系统不做语音转字幕，没有现成字幕文件就不会凭空生成

subtitle_root_path 现在是做什么的？ ​

结论：它是 历史版本遗留目录——只用于承接115 云盘导入的老字幕**，新导入不再往这里写。后端v0.4.6及以后版本不再使用。

说明：

  • 新版本的字幕统一落在图片根下的 movies/<shard>/<番号>/subtitles/，本地导入与 115 导入共用同一目录，字幕跟番号走而不跟具体媒体文件走
  • subtitle_root_path 里的存量文件运行时仍然可读，页面展示和字幕下载不受影响
  • 想把这里的存量字幕搬到新布局，可以跑一次 migrate-movie-subtitles；搬完后这个配置项可以从 config.toml 里删掉

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

结论：相似影片列表依赖离线任务 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 元数据。
  • 它只通过视频合集组织（不支持标签 / 人物），合集成员有顺序，可按顺序连续播放。
  • 不提供订阅、自动下载、推荐、相似影片、以图搜图等 JAV 专属能力。
  • 导入方式与限制见常用命令 → 导入已有媒体，功能说明见PornBox 视频管理。

相关页面 ​

Released under the GNU GPL v3 License.

Copyright © 2024-present SakuraMedia