---
outline: [2, 3]
---

# 常见问题

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

- 所有结论都以当前后端实现为准
- 如果你改过 `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，**所有已登录的客户端都会立即失效**，需要用新账号重新登录
- 整个过程在同一个事务里，中途失败会回滚，不会出现“旧账号删了、新账号没建”导致完全登不上的情况

详见 [常用命令 → 重置账号](/guide/commands#重置账号-忘记用户名-密码)。

## 搜索与数据

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

可以先在「总览」页跑一次「组件诊断」，看 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`
- 建议宿主机路径和容器内路径保持一致，后续创建媒体库、配置下载器时路径最不容易搞混

详细的路径规划可以看：

- [快速开始](/guide/quick-start) 里的媒体目录挂载说明
- [进阶部署](/guide/docker) 里的路径规划

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

结论：这是 `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 索引器连通。

如果你想立刻手动触发一次，可以看 [常用命令](/guide/commands) 里的 `auto-download-subscribed-movies`。


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

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

最常见原因有：

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

更直白一点：

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

这类问题优先去看：

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

## 播放与解码

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

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

说明：

- 播放器底层采用的是 `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`](/guide/commands#字幕位置统一)；搬完后这个配置项可以从 `config.toml` 里删掉

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

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

说明：

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

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

- [后台任务](/guide/tasks)
- [常用命令](/guide/commands)

## 任务中心

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

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

可以这样理解：

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

一般来说：

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

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

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

说明：

- 通过 `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]` 配置](/guide/config#media) 里按你机器的实际情况调整。

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

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

说明：

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

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

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

说明：

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

## 相关页面

- 想看后台任务默认频率和用途： [后台任务](/guide/tasks)
- 想看配置项说明： [配置说明](/guide/config)
- 想看手动命令： [常用命令](/guide/commands)
- 想看 PornBox 视频管理： [PornBox 视频管理](/guide/videos)
