后台任务

这页专门解释 SakuraMedia 后台定时任务的作用、默认频率，以及哪些任务最值得优先关注。

如果你只是第一次部署并确认服务能跑起来，这页不一定要马上细看；但只要你开始关心“为什么系统会自动抓影片、自动导入、自动生成缩略图”，这页就会很有用。

后台任务都做什么

当前版本默认启用了后台调度器。下面这张表按当前代码实现整理了每个任务的作用和默认频率：

任务	作用	默认频率
订阅女优影片同步	抓取已订阅女优的最新影片	每天 02:00
已订阅缺失影片自动下载	搜索并提交符合条件的影片资源	每天 02:30
影片热度重算	更新影片热度字段	每天 00:15
影片互动数同步	回刷评分、想看、评论等互动统计，并联动热度	每小时整点
排行榜同步	同步排行榜数据	每天 01:45
JavDB 热评同步	同步热评和关联影片快照	每天 01:20
合集影片同步	同步合集标记	每天 01:00
下载任务状态同步	同步 qBittorrent 任务到本地任务表	每 1 分钟
已完成下载自动导入	把已完成下载交给导入流程	每 3 分钟
媒体文件巡检	检查文件是否存在并补视频信息	每 6 小时
影片描述回填	为历史影片补抓原文描述 desc	每天 04:00
影片简介翻译	把已抓到的原文描述翻译成中文 desc_zh	每天 04:15
影片标题翻译	把影片原始标题翻译成中文 title_zh	每天 04:20
媒体缩略图生成	为媒体生成缩略图	每 5 分钟
以图搜图索引	为待处理缩略图生成向量并入索引	每天 00:00
影片相似度重算	离线重算影片相似结果	每天 03:30
以图搜图索引优化	压缩或优化向量索引	每天 03:00

按任务说明

订阅女优影片同步

作用：

• 抓取已订阅女优的最新影片并补进本地库
• 适合让“女优上新”持续保持更新

默认频率：

• 每天 02:00

已订阅缺失影片自动下载

作用：

• 为“已订阅但本地还没有媒体”的影片搜索可用资源并提交下载
• 它依赖索引器、下载器和路径映射已经配置正确

默认频率：

• 每天 02:30

影片热度重算

作用：

• 更新影片热度字段
• 热度会被排行榜、排序和部分推荐场景复用

默认频率：

• 每天 00:15

影片互动数同步

作用：

• 回刷影片评分、想看数、评论数等互动统计
• 当互动数据变化时，会联动刷新热度相关结果
• 任务执行时会按影片状态分层挑选候选，不是所有影片都按同一节奏重复同步

默认频率：

• 每小时整点
• 排行榜中的影片：每 1 小时判定一次是否需要回刷
• 已订阅影片：每天同步一次
• 未订阅但上映时间在最近 60 天内：每天同步一次
• 未订阅且上映时间在 60 到 180 天内：每 3 天同步一次
• 更早的影片，或缺少上映日期的影片：每 7 天同步一次

排行榜同步

作用：

• 同步排行榜数据
• 适合保持榜单页面和发现页内容新鲜

默认频率：

• 每天 01:45

JavDB 热评同步

作用：

• 同步热评和关联影片快照
• 适合补充发现页和影片讨论相关数据

默认频率：

• 每天 01:20

合集影片同步

作用：

• 同步合集标记
• 用于持续修正哪些影片应被识别成合集

默认频率：

• 每天 01:00

下载任务状态同步

作用：

• 同步 qBittorrent 任务到本地任务表
• 让 SakuraMedia 知道下载是否开始、完成、失败或卡住

默认频率：

• 每 1 分钟

已完成下载自动导入

作用：

• 把已完成下载交给导入流程
• 让下载后的文件继续进入媒体识别、入库和后续增强链路

默认频率：

• 每 3 分钟

媒体文件巡检

作用：

• 检查文件是否存在并补视频信息
• 适合在外部手工删改文件后，让系统重新修正本地状态

默认频率：

• 每 6 小时

影片描述回填

作用：

• 为历史影片补抓原文描述 desc
• 这一步主要依赖 DMM 描述抓取链路

默认频率：

• 每天 04:00

影片简介翻译

作用：

• 把已抓到的原文描述翻译成中文 desc_zh
• 它依赖 [movie_info_translation] 配置的大模型接口可用
• 如果你不确定模型怎么选，可以看 常见问题里的模型建议

默认频率：

• 每天 04:15

影片标题翻译

作用：

• 把影片原始标题翻译成中文 title_zh
• 它和“影片简介翻译”共用 [movie_info_translation] 配置
• 一般会优先处理已订阅影片、已订阅女优相关影片，再处理普通影片

默认频率：

• 每天 04:20

媒体字幕识别

作用：

• 为媒体执行字幕识别，补齐页面可用的字幕内容
• 适合本地没有现成字幕、但媒体文件本身可识别的场景

默认频率：

• 每 6 小时的第 45 分钟

媒体缩略图生成

作用：

• 为媒体生成缩略图
• 这是时刻预览和以图搜图的前置数据

默认频率：

• 每 5 分钟

以图搜图索引

作用：

• 为待处理缩略图生成向量并入索引
• 没有这一步，以图搜图通常拿不到有效结果

默认频率：

• 每天 00:00

影片相似度重算

作用：

• 只做离线预计算，不在前台请求时实时计算
• 基于影片演员、标签和热度生成相似影片结果
• 详情页相似影片列表依赖这一步的预计算结果

默认频率：

• 每天 03:30

以图搜图索引优化

作用：

• 压缩或优化向量索引
• 适合在大量缩略图完成索引后整理搜索性能

默认频率：

• 每天 03:00

默认 cron 配置

如果你更习惯直接看 cron，当前默认值如下：

[scheduler]
enabled = true
log_dir = "/data/logs"

actor_subscription_sync_cron = "0 2 * * *"
subscribed_movie_auto_download_cron = "30 2 * * *"
download_task_sync_cron = "* * * * *"
download_task_auto_import_cron = "*/3 * * * *"
movie_collection_sync_cron = "0 1 * * *"
movie_heat_cron = "15 0 * * *"
movie_interaction_sync_cron = "0 * * * *"
ranking_sync_cron = "45 1 * * *"
hot_review_sync_cron = "20 1 * * *"
media_file_scan_cron = "0 */6 * * *"
movie_desc_sync_cron = "0 4 * * *"
movie_desc_translation_cron = "15 4 * * *"
movie_title_translation_cron = "20 4 * * *"
media_subtitle_asr_cron = "45 */6 * * *"
media_thumbnail_cron = "*/5 * * * *"
image_search_index_cron = "0 0 * * *"
image_search_optimize_cron = "0 3 * * *"
movie_similarity_recompute_cron = "30 3 * * *"

这些值是当前版本代码里的默认值。只要你在自己的 config.toml 里改过 [scheduler]，实际频率就应该以你的配置为准。

哪些任务最关键

如果你只想先理解系统能不能自动运转，优先看下面这几类任务：

下载链路相关

• download_task_sync_cron 保证 SakuraMedia 知道 qBittorrent 当前任务状态
• download_task_auto_import_cron 保证已完成下载能自动进入导入流程
• subscribed_movie_auto_download_cron 保证已订阅且缺资源的影片会自动去找资源

数据同步相关

• actor_subscription_sync_cron 保证已订阅女优的影片会持续补进来
• movie_collection_sync_cron 保证合集标记持续同步
• movie_interaction_sync_cron 保证影片评分、想看、评论等互动统计持续回刷；排行榜中的影片会按 1 小时窗口优先刷新
• ranking_sync_cron 保证排行榜数据有更新
• hot_review_sync_cron 保证热评数据有更新

媒体增强相关

• movie_desc_sync_cron 先把影片原文描述 desc 补进来
• movie_desc_translation_cron 再把原文描述翻译成中文 desc_zh
• media_thumbnail_cron 为时刻和图片搜索提供基础数据
• image_search_index_cron 把缩略图真正送进图片搜索索引
• image_search_optimize_cron 负责后续索引压缩和优化

如果这些任务长期不跑，系统虽然还能登录和浏览，但自动化能力会明显打折。

任务运行规则

如果你会手动执行后台任务，下面这几点很重要：

• 通过 aps <job> 触发的任务，通常会进入活动中心 / 任务中心，方便看进度和结果
• 同一个 APS 任务在手动执行和定时执行之间是互斥的；如果同任务已经在跑，新的一次触发会被拒绝或跳过
• 服务重启时，系统会回收已经中断的任务状态，避免旧的运行中记录长期卡住
• 像“影片相似度重算”这类离线计算任务，结果更新依赖后台任务跑完，不是请求时即时刷新

什么时候需要改任务频率

默认频率适合先跑通，不建议第一次部署就大改。通常只有下面这些情况，才值得考虑调整：

• NAS 性能比较弱，任务一跑就明显拖慢系统
• 媒体量很大，缩略图和图片索引积压太久
• 下载器任务很多，1 分钟一次同步对你来说太频繁
• 你只想把重任务放到夜间执行

更稳的调整方式是：

1. 先观察几天
2. 一次只改一类任务
3. 优先改缩略图、图片索引这类重任务
4. 下载任务同步和自动导入不要改得太慢

哪些任务第一次先别动

如果你现在还处于“刚跑通”的阶段，通常不建议一上来就改：

• 所有 scheduler cron
• media_thumbnail_cron
• image_search_index_cron
• download_task_sync_cron
• download_task_auto_import_cron

更好的节奏是：

• 先确认任务能正常跑
• 再根据机器性能和数据规模决定是否调整

和配置说明的关系

如果你想看：

• 哪些配置项最常改
• auth、metadata、image_search 这些配置组应该怎么理解

可以继续看配置说明。