常见问题
这页整理当前版本里最常见的行为说明。后台任务频率以你自己的 config.toml 为准。
代理配置
外部站点请求使用容器环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。索引器、下载 provider 和媒体 provider 的连接参数在各自配置中填写。
账号与登录
忘记用户名或密码了怎么办？
在后端容器运行 reset-account，用新的用户名和密码重建账号：
docker exec -it --user app -w /app sakuramedia python -m src.start.commands reset-account也可以使用 --username 和 --password 直接传参。命令会清空 refresh token，已登录客户端需要重新登录。详见常用命令。
搜索与数据
在线搜索入库影片或女优失败
先在「概览」页运行「组件诊断」，确认 JavDB 连通；再检查容器网络、代理规则和 DNS。如果图片域名无法访问，也需要检查相同的网络设置。
如果软路由开启了透明代理，且 JavDB 数据源异常，检查 c0.jdbstatic.com 的分流规则。该图片域名经日本节点出口时可能被拒绝；将它设为直连或使用非日本IP出口后再重试。
为什么刚启动后看不到影片或女优？
本地搜索只查询已入库数据。首次部署后，打开搜索页的「联网」开关执行一次在线搜索，成功结果会写入本地库。
为什么“女优上新”是空的？
该页面只展示已订阅女优的影片更新。没有订阅、同步任务尚未完成或没有符合条件的新作时，空列表是正常结果。女优订阅不会主动订阅她的影片，看到想看的作品后需要单独订阅影片。详见发现与女优订阅。
以图搜图需要什么条件？
图库来自可播放媒体生成的缩略图，特征提取由 SigLIP2 嵌入服务完成，向量存放在 Qdrant。三者都准备好后，后台任务会逐步生成和索引图片。
如果结果为空，先在「概览」页检查嵌入服务，再在任务中心运行「媒体缩略图生成」「以图搜图缩略图向量索引」和「以图搜图剧情图向量索引」。
媒体库与导入
导入普通视频时如何选择来源？
进入「管理 → 资源导入」，切换到「视频」，新建导入并选择目标媒体库，再使用来源浏览器选择文件或目录。导入前确认是否保留源文件。
普通视频可以归入视频合集；导入任务完成后，在合集页调整成员顺序即可。详情见普通视频与视频合集。
导入时提示“文件太小”怎么办？
影片导入会使用 [media].allowed_min_video_file_size 过滤过小的视频，默认值为 256 MB。需要导入更小的视频时，在系统设置或 config.toml 中调低该值。
为什么影片已经订阅了，但没有自动下载？
自动下载需要同时满足：影片还没有可播放媒体、索引器能返回候选、索引器已绑定下载器，且下载器 provider 配置可用。可以先运行组件诊断，再在任务中心手动触发「已订阅缺失影片自动下载」。
自动下载如何选择候选？
候选必须有可用来源、体积在 1 GiB 到 40 GiB 之间且做种数大于 0。系统按体积从大到小排序，并使用索引器名称和标题稳定排序；提交时使用该索引器绑定顺序中的第一个下载器。
下载完成后如何进入媒体库？
下载 provider 返回 completed 和 completed_source_ref 后，后台任务会将该来源交给目标媒体库 provider 导入。检查时依次确认：下载器状态已同步、任务含完成来源引用、媒体库 provider 配置可用，以及「已完成下载自动导入」任务没有失败。
播放与解码
播放地址从哪里来？
后端为每个媒体生成带签名的 play_url，客户端使用该地址播放。签名地址有有效期，客户端会在需要时重新获取。
播放时是否需要服务端转码？
播放解码由客户端完成。播放器能否硬件解码取决于当前设备、系统和媒体编码；服务端负责提供媒体和签名播放地址。
播放卡顿时先检查什么？
先确认媒体库 provider 连通、play_url 能在客户端打开，再检查客户端设备的解码能力和网络带宽。可以在「概览」页运行组件诊断。
任务中心
通知中心和任务中心分别看什么？
通知中心展示提醒；任务中心展示后台作业的状态、进度、结果和错误信息。下载同步、自动导入、缩略图、图片索引、插件任务等都在任务中心查看。
下载任务可以删除吗？
可以。在下载任务列表删除时选择是否让 provider 同步删除远端任务及文件。删除只移除选中的任务记录，不会删除已经导入媒体库的影片。
切片与视频合集
删除媒体后，时刻还在吗？
当前版本会随媒体删除关联时刻及其合集成员关系。时刻不支持脱离媒体后自动接回。已生成的独立切片会保留，清理前请先验证切片可播放。详见媒体库管理。
切片存在哪里？
切片是独立的 mp4 文件，存放在 [media].media_clip_root_path（默认 /data/media-clips）。该目录需要持久化，删除来源影片不会删除切片文件。
为什么切片过长或生成失败？
单个切片时长受 media_clip_max_duration_seconds 限制，ffmpeg 执行时间受 media_clip_ffmpeg_timeout_seconds 限制。调整方式见配置说明。
视频合集可以连续播放吗？
可以。合集保存视频成员及顺序，播放时客户端按顺序播放；同一个视频可以加入多个合集。