115reelay/docs/user-guide.md

使用指南

文档首页 · 快速开始 · 常见问题

这份指南面向已经启动 Reelay 的用户，按日常操作说明怎么配置来源、审批资源、追剧和处理异常。还没部署时，先走完 快速开始。配置字段的完整定义在 配置参考，本页不要求你手写 YAML。

目录

• 先认识管理台
• 理解一条资源的处理结果
• 配置监听来源
• 选择适合你的处理方式
• 审批、修正与重新识别
• 追剧订阅与不再接收
• 仅处理订阅
• 保存目录与整理
• 转存或整理异常时怎么办
• 在 Telegram 和 Agent 中操作
• 日常维护清单

先认识管理台

页面	主要用途	使用提示
总览	看后台、连接状态、待处理资源与告警	页面能打开不代表 Worker 和 115 都正常
待审批	处理「待确认」和「待人工」资源	前者决定收不收，后者通常需要解决转存或整理问题
任务	查看每条消息的状态、处理轨迹和可用操作	没收到卡片时先来这里查，不要直接认定没收到消息
媒体库	汇总 Reelay 已入库的作品、季集与路径	不是扫描整个 115 网盘，也不是播放器
追剧订阅	管理在追的作品与季、看缺集、继续或取消订阅	订阅以一季为单位，不自动订阅下一季
统计	看处理情况、来源表现与 AI 调用统计	用来判断某个来源是否适合逐步自动化
设置	管账号、来源、保存目录、默认处理方式等	多数设置保存后生效，少数需要重启后台
插件	管 TMDB 补全、分享读取、整理、追更、日报等	关闭插件会影响依赖它的能力
工具 → 115 目录	浏览文件夹、定位目录、复制目录编号	不是完整的网盘文件管理器
工具 → 运行日志	看日志、搜索错误、暂停刷新	分享日志前先脱敏；清空会删除日志历史

理解一条资源的处理结果

Reelay 不是“收到链接就立即下载”。它会经过识别、决策、转存核验和整理。

你看到的状态	意味着什么	通常该做什么
待识别 / 已识别	消息已收到，尚未走完识别与决策	等待后台；长时间不变时检查 Worker
待确认	等你决定是否保存	核对识别、版本和目录，再批准、忽略或修正
排队中	已获准处理，等后台执行	不要重复批准或重建任务
转存中 / 已转存 / 整理中	正在写入网盘、核验或整理	等待完成，必要时查看轨迹
已入库	转存和整理已完成并核验	可在媒体库和 115 检查结果
已忽略 / 已过滤	没进入转存，可能是过滤、重复、未订阅或广告等原因	看轨迹中的具体原因
失败	某一步没有完成	看错误属于临时问题还是配置/资源问题，再按可用按钮处理
待人工	自动流程不能安全继续，可能已有文件落地	按具体原因核验或处理冲突，不能一概点重试

按钮由状态和已有检查点决定。正在转存、已入库或有未决转存的任务，不会提供与普通待审批任务完全相同的操作。

配置监听来源

来源与来源卡片

在「设置 → 监听来源」添加 Bot、频道或群组。填写 @username 或数字 ID，并确保登录的个人 Telegram 账号本来就能看到它。

一张卡片可以填多个来源，它们共用确认方式、识别规则、过滤、保存目录等设置。建议把消息格式相近的来源放在一起；某个来源需要不同规则时，拆成独立卡片。

• 新来源从加入后开始监听，不自动导入之前的历史消息。
• 停机或断线后的补拉是另一回事：已有来源会根据保存的进度和补拉上限恢复，见 配置参考。
• 修改来源设置只影响新接收的任务；已有任务通常保留接收时的设置。主动「重新识别」会采用当前设置。

全局默认与来源覆盖

「设置 → 基础 → 默认处理方式」提供默认值。来源卡片中未单独设置的项继承全局；单独设置后，以来源为准。

例如全局开启 Bot 通知，某个来源可以单独关闭；全局开启「仅处理订阅」后，也可以为某个来源明确关闭。“关”与“恢复默认”不同：前者覆盖全局，后者重新继承。

过滤规则怎么写

设置	判断方式	常见误区
消息必须包含	正文或链接包含其中任意一项就通过	不是必须包含所有词；只写 115 会挡住只有电驴链接的消息
包含这些词直接忽略	正文命中任意屏蔽词就跳过	过于宽泛的词可能误伤正常片名或简介
类型、地区等允许/排除规则	根据识别与 TMDB 补全后的字段判断	元数据缺失时不能假定一定符合条件
最低清晰度	低于要求不收，未知时可能转人工	“没写清晰度”不等于符合最低清晰度
收藏偏好	放行方式为「AI 按偏好判断」时进一步筛选	不是保存目录规则，也不能替代严格的订阅过滤

希望同时接收 115 分享和电驴消息时，可把 115.com、115.cn、115cdn.com、ed2k:// 分别填入“消息必须包含”。具体来源仍应通过样例测试。

调整识别规则

某个来源经常认错时，优先修来源规则，而不是每条消息都手工改：

1. 打开来源卡片的「识别规则」。
2. 获取最近消息或手动粘贴有代表性的样例。
3. 自己填写片名、年份、季、集等字段规则，或让 AI 起草。
4. 试跑并检查正常、异常和格式变化的消息。
5. 确认规则后保存，再测试完整识别结果。

字段规则是 Python 正则，具体写法见 配置参考。AI 起草失败不代表资源无效，也不表示规则已经保存；检查错误信息，必要时改用手写规则或其他模型。

测试识别是预览，不是手动导入资源。它会按当前草案运行识别和决策，不创建转存任务，但可能调用 AI、TMDB 和分享查询。

选择适合你的处理方式

四个设置各管什么

设置	它回答的问题	不负责什么
识别方式	怎么把消息读成片名、季集等信息？	不直接决定是否转存
确认方式	普通合格资源是等我确认，还是自动处理？	不保证每一条都能自动转存
放行方式	用普通规则、订阅放行，还是再加 AI 偏好？	不决定最终目录结构
仅处理订阅（v1.5.0 起）	未订阅资源是否一律排除？	不是“已订阅就无条件转存”

“AI 处理”是界面中确认方式的名称，不代表必须用 AI 解析。你可以选择「规则识别」并启用自动处理，也可以用 AI 识别但逐条人工确认。

推荐组合

目标	确认方式	放行方式	仅处理订阅
刚开始，每条都自己看	人工确认	规则判断	关
在追的新集自动收，其余问我	人工确认	规则 + 订阅放行	关
只收订阅，符合条件的新集自动入库	人工确认	规则 + 订阅放行	开
只收订阅，但每条仍自己决定	人工确认	规则判断	开
信任某个来源，合格资源尽量自动收	AI 处理	规则判断，或 AI 按偏好判断	按需求

其中「仅处理订阅」设为“开”的组合需要 v1.5.0 或更高版本。

无论哪种组合，广告、过滤条件、去重、置信度和转存校验都仍起作用。低置信度、解析降级或分享信息不明确的资源，不会仅因为启用自动处理就强行转存。开启“仅处理订阅”时，未匹配订阅的会更早被忽略。

AI 按偏好判断只能进一步收紧：可以否决或改为人工确认，不能把本应等你确认的资源强行自动放行，也不会替你修改保存目录。

审批、修正与重新识别

处理待确认资源

打开「待审批 → 待确认」，建议依次检查：

1. 作品是否正确：同名作品尤其看年份和 TMDB 信息。
2. 季集是否正确：不要只看标题里的“全集”或集数范围。
3. 版本是否需要：清晰度、片源等信息是否满足要求。
4. 链接和分享情况：提取到链接不等于分享可访问，更不等于已转存成功。
5. 目录是否合适：看实际预览路径，而不只是目录别名。

然后批准或忽略。批准只是让后台开始处理；最终结果以「已入库」为准。

批量批准、忽略前先核对选中范围。“按建议处理”只处理建议明确为批准或忽略的所选项，需要人工查看的会保留；建议不是正确性保证。

修正与重新识别的区别

操作	适合什么时候	操作后会怎样
修正	片名、年份、季集等少数字段不对，你知道正确值	修改当前结果；不会因为修正就自动批准。失败任务可能还要重试，已有文件的待人工任务可能还要重新整理
重新识别	来源规则已调整，或想从头再判断这条消息	使用当前来源设置重新进入流程，可能待审批、被忽略或自动放行

有未核验的转存、已有转存清单或文件落地时，部分操作会被限制，避免把新识别结果套到旧转存请求上。

网页中填写多个集号时按输入框要求用逗号分隔，不要假定所有输入框都支持 E01-E05 这种范围写法。Telegram 卡片上的「修正」可以用简短字段文字，详见 Telegram 指南。

追剧订阅与不再接收

添加订阅

可以在「追剧订阅」中搜索并选择作品与季，也可以：

• 在资源卡片上选择「追这部剧」。网页可能另行提示是否一并转存相关待审批项。
• 在 Telegram 卡片上点「追剧并转存」，同时订阅并批准当前这一条。
• 给控制 Bot 发 /subs 片名，在 TMDB 候选中选择一季。

订阅的是一个作品的一季，不是自动订阅它以后所有季。TMDB 搜索只用于确定作品，不会替你找到资源下载链接。

已订阅为什么还会让我确认

订阅放行需要：

• 来源的放行方式支持订阅。
• TMDB 匹配成功，并能对应订阅作品与季。
• 置信度、过滤和解析状态满足自动处理条件。
• 不是已全部入库的重复内容，也没有其他安全检查阻止放行。

多季合集、无法确定季、识别降级或 AI 偏好明确排除等情况，都可能无法自动放行。订阅不能绕过这些检查。

缺集、结束与继续订阅

启用「缺集追更」插件后，每日巡检根据订阅、已入库记录和 TMDB 等信息检查缺集。满足播完、收齐及相应完结判定条件后，订阅会标为结束；不是播出结束那一刻立即改变状态。

• 已结束订阅可在管理台继续订阅。
• /subs 主要列仍在追的订阅，不列已结束项。
• 缺集是提醒，不代表 Reelay 会主动搜索并补下缺失资源。
• 媒体库与去重依赖 Reelay 的入库记录，不会自动扫描并识别你在 115 上手动添加的所有文件。

如果页面显示某订阅“只提醒缺集”，它仍属于有效订阅，但不通过订阅机制自动放行。这个模式目前属于 API 支持的能力，普通新增订阅界面没有单独切换入口；来源本身开启自动处理时，仍可能按普通规则转存。

忽略、取消订阅、不再提醒有什么区别

操作	影响范围	不会做什么
忽略一条消息	只处理当前任务	不拉黑整部作品
取消订阅	删除这一季的订阅	不自动取消已批准任务；未开“仅处理订阅”时，之后的资源仍可能按来源规则处理
缺集“不用等了 / 不再提醒”	静音相应缺集或季的提醒	不关闭自动转存
不再接收	按作品屏蔽后续匹配消息，并忽略同作品的待审批项	不删除已经入库的文件
恢复接收	解除“不再接收”的记录	不自动重放此前已忽略的消息

“不再接收”可从 Telegram 审批卡片发起，在管理台订阅页或 /ignored 中查看和恢复。

仅处理订阅

Note

自 v1.5.0 起支持。早于 v1.5.0 的管理台没有这个开关，请先升级；发布记录见 更新日志。

开启方式

1. 先在「追剧订阅」中添加要追的作品和季，确认 TMDB 可用。
2. 只限制某个来源：打开该来源卡片，把「仅处理订阅」设为开。
3. 所有来源默认限制：在「设置 → 基础 → 默认处理方式」开启；来源未设置时继承，也可以单独关掉。
4. 用来源的「测试识别」分别测试一条已订阅和一条未订阅消息，再保存。

开启后的判断

资源情况	结果
匹配到有效订阅的作品与季	继续按原有过滤、置信度、审批与去重规则处理
没有订阅、订阅已取消或结束	直接忽略，不进入待审批、不转发、不发送识别或审批通知
TMDB 未匹配或无法确认所属订阅	直接忽略，不先交给你猜测
未指定单季的多季合集	所涉及的季都必须有有效订阅，否则整条忽略
“只提醒缺集”的有效订阅	可以通过订阅过滤，但仍不因此无条件自动转存

它适用于 115 分享和电驴链接，默认关闭。当前订阅体系面向剧集的季，所以开启后，不应期待未能匹配剧集订阅的电影资源继续进入待审批。

与“规则 + 订阅放行”的区别：订阅放行是让已订阅新集更容易自动通过；“仅处理订阅”是把未订阅资源排除。只选前者，并不等于只收订阅。

还要注意：

• 为判断订阅身份，仍需先解析消息，并按配置进行 TMDB 或分享查询，不是零识别成本的入口过滤。
• 被忽略的消息仍保留任务记录和原因。
• 开关变化不清理已有待审批、不取消已经开始的转存。
• 新增或恢复订阅不会自动重放过去已忽略的消息；符合条件的旧任务可由你主动重新识别，并按当前设置重新判断。

保存目录与整理

目录由什么决定

• 保存目录别名：映射到 115 中的目标目录，不是本机目录。
• 来源的“保存到”：决定这个来源使用哪个目录别名。
• 整理插件的分类：可以按二级分类、媒体类型或不分类。
• 命名模板：决定作品文件夹、季目录与文件名称。

二级分类的一级名称与某个保存目录别名相同时，会使用相应目录作为根目录。例如“剧集”分类可以进入你配置的“剧集”目录；否则在来源指定目录下创建完整分类路径。审批时主动改投与分类不同的目录，会按所选目录直接存入，不再套用原来的分类子目录。

最可靠的核对方式是看卡片上的实际路径与“预览整理效果”，不要仅凭别名推测最终路径。完整优先级见 配置参考：媒体库整理。

集数按消息还是按分享

集数依据	行为	适用场景
分享（默认）	以分享内文件名为准，转存本次范围内未入库的集	分享链接持续更新，希望顺带补齐缺的集
消息	只转存消息声明的集，仍要与分享中的实际文件核对	希望严格按每条消息的集数处理

因此，消息写“更新第 8 集”但分享里有尚未入库的第 1–8 集，默认可能转存多集，这不是把同一集重复保存。

消息明确指定季时只取该季；文件名、季集或同集多版本无法确定时会停止自动选集，必要时用经校验的 AI 方案辅助，而不是随意选文件。

已有文件冲突时

策略	行为	建议
人工处理（默认）	暂停并让你决定	第一次使用保持默认
跳过	保留旧文件，本次冲突文件进入回收站	确认希望始终保留旧文件后再开
并存	新文件加后缀保留	需要保留多个版本时使用
洗版	按版本偏好比较，更好才替换旧文件	会涉及删除/替换，先了解偏好规则并备份

整理不是播放器功能。Jellyfin / Emby 的安装、如何读取 115 文件以及媒体库扫描，需要你在自己的播放方案中设置。

转存或整理异常时怎么办

先看任务详情里的停止原因、已有文件情况和可用按钮。不同问题的恢复方式不同。

情况	优先处理	避免这样做
115 登录失效	在设置中重新扫码，等待后台恢复	不必删除任务或重建数据库
115 风控冷却	等待页面显示的恢复时间	重启通常不会解除冷却，反复操作可能加重问题
分享失效或取消	确认资源是否仍可访问；无效时忽略	对已失效链接无限重试
转存结果未知	使用「核验转存」，或等待后台只读复查	把未知结果当成“肯定没转存”，再次发送同一请求
只有部分文件核验通过	决定继续等待，或「按已到的继续」	误以为按部分继续会自动补下缺少文件
文件已经转存，但整理失败	修正信息或处理冲突后「重新整理」	重新创建下载来解决改名问题
临时失败，且界面提供重试	排除原因后按提示重试	把“重试”当成所有状态通用操作

“按已到的继续”只处理已经核验的文件。“放弃并删除”会清理暂存文件，电驴任务还可能取消对应云下载，操作前确认你确实要放弃。

电驴特别说明：识别到文件名、大小和哈希，仅说明链接可以解析。115 是否能找到资源、云下载是否成功，要看之后的任务结果；Reelay 不保证有源，也不会在自己的主机上替代 115 下载。

转存未知结果的自动复查、登录与风控恢复时机，见 部署与运维：健康检查与故障恢复。

在 Telegram 和 Agent 中操作

Telegram 常用命令

命令	用途
/help	查看帮助
/status	查看运行状态
/pending	查看并处理待审批
/failed	查看失败任务
/subs	查看仍在追的订阅
/subs 片名	搜索 TMDB 作品并选择一季订阅，不是搜索资源链接
/ignored	查看并恢复“不再接收”的作品

控制 Bot 只响应你配置的 owner 数字 ID。日常按钮和命令不以 AI 对话为前提，但作品搜索等功能仍可能访问 TMDB 或使用已配置的 AI 辅助解析。

自然语言与 MCP 的区别

• Bot 自然语言助手：可以查询状态、提出批量审批等操作。写操作先生成计划，你点「执行」后才执行；不能据此认为普通卡片按钮也都存在相同的二次确认步骤。
• MCP：适合让外部 Agent 查询任务或执行已提供的管理工具。推荐先用只读令牌；读写令牌允许工具直接执行写操作，是否向你再次确认取决于 Agent 客户端，而不是 Reelay 每次都弹确认。
• 不是管理台的全部能力：扫码登录、修改设置以及某些核验、重新整理和冲突处理，仍需要管理台或对应 Bot 按钮。

配置方法、完整命令和权限说明见 Telegram 与 Agent。

日常维护清单

平时

• 看总览里的 Worker、Telegram、115 状态。
• 定期处理「待人工」，不要只处理「待确认」。
• 检查订阅和来源是否仍需要，删除不用的监听来源。
• 观察 AI 调用情况和来源误识别，再决定是否扩大自动处理。

改规则时

• 先试跑正常样例和应该被忽略的样例，再保存。
• 核对保存目录与整理预览，先用单独目录验证。
• 记住旧任务不会因设置变化自动重算；重识别可能触发当前的自动放行规则。

升级前

• 阅读更新日志，确认版本是否包含你需要的功能。
• 备份整个数据卷，包含数据库、配置、密钥与会话。
• 回滚时同时考虑程序版本与升级前的数据备份。
• 不执行 docker compose down -v 来“重启”，它会删除数据卷。

下一步：常见问题 · 部署与运维 · 完整配置参考