添加转换任务
转换任务是 OpenList to Stream 的核心功能，用于将 OpenList 中的文件列表转换为 STRM 流媒体文件。本页详细介绍如何创建和管理转换任务。
什么是转换任务？
转换任务定义了如何将 OpenList 中的特定路径转换为 STRM 文件：
- 指定要转换的 OpenList 路径
- 设置 STRM 文件的输出位置
- 配置转换选项（更新模式、刮削等）
- 设置定时执行计划
文件处理器链
系统在处理视频文件时，采用责任链模式依次执行多个处理器：
| Order | 处理器 | 功能 | 说明 |
|---|---|---|---|
| 10 | FileDiscoveryHandler | 文件发现 | 遍历 OpenList 文件树，收集所有文件信息 |
| 20 | FileFilterHandler | 文件过滤 | 过滤出需要处理的视频文件 |
| 30 | StrmGenerationHandler | STRM 生成 | 生成 STRM 流媒体文件 |
| 40 | NfoDownloadHandler | NFO 下载 | 下载媒体信息文件（三级优先级：本地 > OpenList > 刮削） |
| 41 | ImageDownloadHandler | 图片下载 | 下载海报、背景图、缩略图 |
| 42 | SubtitleCopyHandler | 字幕复制 | 复制同目录下的字幕文件 |
| 50 | MediaScrapingHandler | 媒体刮削 | 从 TMDB/AI 获取媒体信息 |
| 60 | OrphanCleanupHandler | 孤立文件清理 | 清理不再存在的源文件对应的 STRM |
处理器链执行流程
视频文件 → STRM生成 → NFO下载 → 图片下载 → 字幕复制 → 媒体刮削 → 清理孤立文件每个处理器都可以独立启用或通过配置控制是否执行。
创建新任务
前置条件
在创建任务之前，请确保：
- ✅ 已添加至少一个 OpenList 配置
- ✅ 已准备好 STRM 文件的输出目录
第一步：访问任务管理页面
- 登录系统
- 在首页的 OpenList 配置列表中，找到对应的配置
- 点击操作列中的「管理任务」按钮
- 在任务管理页面中，点击「创建任务」按钮
第二步：基本信息
任务名称
给任务起一个描述性的名字，例如：
- 「电影库转换」
- 「电视剧同步」
- 「纪录片更新」
注意：任务管理页面已经关联到特定的 OpenList 配置，无需再次选择配置。
第三步：路径配置
任务路径
填写要转换的 OpenList 路径：
路径示例：
/电影- 电影目录/电视剧- 电视剧目录/纪录片- 纪录片目录
注意：这是必填字段，需要填写完整的 OpenList 路径
STRM 输出路径
设置 STRM 文件的保存路径：
路径结构：
- 固定前缀：
/app/backend/strm/（系统固定，不可修改） - 子路径：您可以自定义子路径（可选）
示例：
- 子路径留空：
/app/backend/strm/ - 子路径为
movies：/app/backend/strm/movies - 子路径为
tv/series：/app/backend/strm/tv/series
路径建议
- 按媒体类型创建不同的子路径（如 movies、tv、documentaries）
- 避免使用特殊字符和中文路径
- 保持路径结构简洁明了
第四步：更新模式
全量更新
每次执行时重新处理所有文件：
- 优点：确保所有文件都是最新状态
- 缺点：处理时间长，重复刮削
增量更新
只处理新增或修改的文件：
- 优点：执行速度快，节省资源
- 缺点：需要配合 NFO 文件存在性检查
增量模式工作原理：
- 检查对应的 NFO 文件是否已存在
- 如果 NFO 存在，跳过该文件的刮削
- 如果 NFO 不存在，执行刮削
- 处理完成后清理孤立文件
第五步：资源下载配置
字幕文件配置
- 保留字幕文件：开启后自动下载视频同目录下的字幕文件
支持的字幕格式：
.srt- SubRip 字幕.ass- Advanced Substation Alpha.vtt- WebVTT 字幕.ssa- SubStation Alpha.sub- SubViewer.idx- VobSub 索引
字幕下载逻辑：
- 获取视频所在目录的所有文件
- 筛选出字幕格式的文件
- 下载到 STRM 文件同一目录
- 自动避免重复下载
图片文件配置
- 使用已有刮削信息：开启后优先使用本地文件
图片下载优先级（三级）：
- 本地检查：本地是否存在
{baseFileName}-poster.jpg等 - OpenList 下载：从 OpenList 同级目录下载
- TMDB 刮削：通过 API 获取媒体信息
支持的图片类型：
-poster.jpg- 海报图片-fanart.jpg- 背景图-thumb.jpg- 缩略图- 任意命名图片（降级策略）
NFO 文件配置
- 生成 NFO 文件：自动生成 Kodi/Plex 兼容的媒体信息文件
NFO 下载优先级：
- 本地是否存在同名 NFO
- OpenList 是否存在同名 NFO
- 通过 TMDB/AI 刮削获取
第六步：定时设置
Cron 表达式
设置任务的自动执行时间（可选）：
常用表达式：
| 表达式 | 说明 |
|---|---|
0 2 * * * | 每天凌晨2点 |
0 */6 * * * | 每6小时 |
0 0 * * 0 | 每周日午夜 |
0 0 1 * * | 每月1号午夜 |
0 0 * * 1-5 | 工作日午夜 |
配置说明：
- 留空表示不启用定时任务，只能手动执行
- 使用标准 Cron 表达式格式
- 系统会根据配置自动执行任务
第七步：保存和测试
保存任务
所有配置完成后，点击「保存」按钮创建任务。
注意：
- 任务名称和任务路径为必填项
- STRM 子路径和 Cron 表达式为可选项
- 系统会自动验证配置的有效性
管理现有任务
任务列表
在任务管理页面可以看到所有任务的状态：
| 任务名称 | OpenList 配置 | 状态 | 最后执行 | 下次执行 | 操作 |
|---|---|---|---|---|---|
| 电影库转换 | 家庭媒体服务器 | ✅ 运行中 | 2024-01-15 02:00 | 2024-01-16 02:00 | 执行/编辑/删除 |
| 电视剧同步 | 家庭媒体服务器 | ⏸️ 已暂停 | 2024-01-14 20:00 | - | 启动/编辑/删除 |
执行任务
手动执行
- 在任务列表中找到要执行的任务
- 点击「立即执行」按钮
- 确认执行操作
查看执行状态
- 等待中：任务已加入执行队列
- 执行中：正在处理文件
- 已完成：任务执行完成
- 失败：执行过程中出现错误
查看执行详情
任务执行时，您可以查看：
- 处理的文件数量统计
- 成功/失败统计
- 刮削结果统计（海报、NFO、字幕）
- 详细的执行日志
编辑任务
- 在任务列表中找到要编辑的任务
- 点击「编辑」按钮
- 修改配置信息
- 点击「保存」确认修改
暂停/启动任务
- 在任务列表中找到要管理的任务
- 点击「暂停」或「启动」按钮
- 暂停的任务不会自动执行，但仍可手动执行
删除任务
- 在任务列表中找到要删除的任务
- 点击「删除」按钮
- 在确认对话框中点击「确认删除」
删除警告
删除任务不会删除已生成的 STRM 文件，但会停止所有未来的自动执行。
任务执行详情
执行日志
每个任务执行都会生成详细的日志：
日志信息包括：
- 开始和结束时间
- 处理的文件数量
- 成功/失败统计
- 错误信息和堆栈跟踪
- 刮削结果统计（NFO、海报、字幕）
性能统计
- 处理速度：文件/秒
- 网络请求：API 调用次数
- 资源占用：CPU 和内存使用情况
- 执行时长：总耗时
刮削统计
- NFO 文件：成功/失败/跳过
- 海报图片：成功/失败/跳过
- 背景图片：成功/失败/跳过
- 字幕文件：成功/失败/跳过
特殊配置项说明
并发控制配置
系统支持以下特殊的并发控制配置：
- 最大并发任务数：控制同时运行的任务数量
- 单任务最大文件处理数：限制单个任务处理的文件数量上限
- 网络请求超时时间：设置 HTTP 请求的最长等待时间
错误处理配置
提供多种错误处理策略选择：
- 失败重试：自动重试失败的文件，提高成功率
- 跳过错误：跳过错误文件继续处理其他文件，保证整体进度
- 停止执行：遇到错误时立即停止任务，便于快速定位问题
通知配置
支持多种通知方式：
- 执行完成通知：任务完成后发送系统通知
- 错误通知：执行失败时发送告警信息
- 邮件通知：通过邮件发送详细的执行报告
常见问题
Q: 任务执行很慢怎么办？
A: 可以尝试以下优化：
- 启用增量更新模式
- 减少并发任务数
- 开启「使用已有刮削信息」避免重复刮削
- 检查网络连接质量
- 考虑分批处理大量文件
Q: 如何处理大量文件？
A: 建议采用以下策略：
- 按媒体类型分别创建任务
- 使用增量更新模式
- 设置合适的执行时间（避开高峰期）
- 监控系统资源使用情况
- 开启字幕和图片的本地优先模式
Q: STRM 文件无法播放？
A: 检查以下几点：
- 确认 STRM 文件路径正确
- 检查媒体服务器配置
- 验证原始文件是否可访问
- 查看任务执行日志
- 检查 URL 编码设置
Q: 字幕文件没有下载？
A: 可能的原因：
- 未开启「保留字幕文件」选项
- OpenList 目录中不存在字幕文件
- 字幕格式不支持
- 查看执行日志确认是否有下载错误
Q: 图片文件没有下载？
A: 可能的原因：
- 未开启相关刮削选项
- 「使用已有刮削信息」设置不正确
- OpenList 目录中不存在图片文件
- TMDB API 未配置或无法访问
Q: 如何减少重复刮削？
A: 推荐配置：
- 开启「增量更新」模式
- 开启「使用已有刮削信息」
- 开启「保留字幕文件」
- 配置正确的图片下载优先级
最佳实践
1. 任务规划
- 按媒体类型（电影、电视剧、纪录片）分别创建任务
- 使用描述性的任务名称
- 设置合理的执行时间
2. 路径管理
- 保持 OpenList 路径和输出路径的一致性
- 使用绝对路径避免路径混淆
- 定期清理无用的任务和文件
3. 资源下载配置
- 首次运行：关闭增量模式，全量刮削
- 日常更新：开启增量模式 + 使用已有刮削信息
- 有本地资源：开启字幕保留 + 本地图片优先
4. 性能优化
- 优先使用增量更新
- 合理设置并发数量
- 监控系统资源使用
- 开启本地优先模式减少 API 调用
5. 监控和维护
- 定期查看执行日志
- 设置错误通知
- 及时处理失败的任务
- 监控刮削成功率