快速开始

文档首页 · 使用指南 · 常见问题

这份指南带你从零开始，完成 启动管理台 → 配置账号 → 登录 Telegram → 添加来源 → 确认第一条资源入库。第一次建议先手工确认一条，核对无误后再开启订阅放行或自动处理。

IMPORTANT

只用来处理你有权获取和保存的内容。使用前请阅读 免责声明。先不要开启自动洗版或覆盖，避免把配置问题放大到已有文件。

开始前的准备

准备项	用途	从哪里获取
一台能持续运行的机器	运行 Reelay；Docker 方式支持 amd64 / arm64	NAS、Linux 服务器等；Windows 推荐 Docker
Docker 与 Compose v2.24+	运行管理台与后台服务	用 docker --version、docker compose version 检查
Telegram 个人账号	读取你已加入的频道、群组或已对话的 Bot	你自己的账号
Telegram API ID / API Hash	让程序以个人账号登录	https://my.telegram.org → API development tools
115 账号	存放转存或云下载的文件	之后在管理台用 115 App 扫码
控制 Bot Token（推荐）	接收审批卡片、通知和处理命令	在 Telegram 找 @BotFather 创建 Bot
你的 Telegram 数字 ID（使用控制 Bot 时需要）	限制只有你能操作控制 Bot	例如向 @userinfobot 查询；填数字，不是 @用户名
OpenAI 兼容 AI 接口（推荐）	AI 识别、生成规则、对话等	你选择的服务商或兼容的本地模型
TMDB 密钥（推荐）	确认作品身份、规范片名、海报和订阅匹配	https://www.themoviedb.org/settings/api

个人账号和控制 Bot 是两回事：

• 个人账号负责看消息：只能读取该账号本来就能访问的来源。仅创建控制 Bot，不能让 Reelay 自动获得所有频道的消息。
• 控制 Bot 负责与你交互：给你发卡片、通知，接收审批与查询命令。建议先打开你创建的 Bot，发送 /start。

不配置控制 Bot 也能在管理台审批。不使用 AI 时，可给来源选择「规则识别」；默认 AI 识别在接口不可用时会降级，并强制人工确认。不配置 TMDB 会影响身份校验、分类与自动放行；需要订阅匹配时应配好 TMDB。

1. 启动服务

Docker（推荐）

mkdir reelay && cd reelay
curl -fsSLO https://raw.githubusercontent.com/Derrors/reelay/main/compose.yaml
docker compose pull
docker compose up -d web

这些命令先启动 Web 管理台，还没有开始监听 Telegram。后续的 docker compose 命令都在这个目录执行。

默认使用最新正式版镜像。固定版本时，在同目录的 .env 中设置 REELAY_VERSION=<版本号>，版本号从 Releases 选择。.env 只放部署参数；账号与密钥之后在管理台填写。

成功标志：docker compose ps 中 web 正在运行，稍后健康状态为 healthy。

本机运行

不用 Docker 时，需要 Python 3.12+、Node.js（建议与项目 Docker 构建保持一致，使用 Node.js 24）和 npm。

git clone https://github.com/Derrors/reelay && cd reelay
python3.12 -m venv .venv
source .venv/bin/activate
pip install -c constraints.txt -e ".[all]"
npm ci --prefix web
npm run build --prefix web
python -m reelay.web

这个终端需要保持运行。之后登录 Telegram、运行后台时，另开终端，进入同一仓库目录并执行 source .venv/bin/activate。

TIP

只想体验流程、暂时不配置真实账号时，运行 python -m reelay.main --dry-run。它使用内置样例与内存网盘，不读本机配置和密钥，也不访问网络。模拟通过不代表真实账号已经连通。

2. 打开管理台

打开管理台

浏览器就在部署机器上：访问 http://127.0.0.1:28080。

部署在 NAS 或局域网另一台机器上：默认配置只允许部署机器本机访问。把 compose.yaml 中 web.ports 的这一行：

- "127.0.0.1:28080:28080"

改为：

- "28080:28080"

然后执行 docker compose up -d web，用 http://NAS的局域网IP:28080 打开，并通过防火墙确保仅可信网络可达。本机运行则用 REELAY_WEB_HOST=0.0.0.0 python -m reelay.web 监听局域网，同样需要限制访问来源。

部署在远程公网服务器上：优先用 SSH 隧道或受控的内网访问。不要直接开放管理端口后，等待任意公网访问者完成首次设置。HTTPS、反向代理和可信地址配置见 部署与运维。

设置管理台密码

第一次打开时设置登录密码，至少 8 个字符。首次设置只允许从本机或局域网、通过 IP 地址或 localhost 访问；用域名打开时不能完成首次设置，先用 IP 或安全隧道完成，再配置域名访问。

成功标志：设置密码后进入控制台，能打开「设置」页。

NOTE

默认使用 Docker 命名卷保存数据，不需要手动修改目录权限。想使用 NAS 上的 ./data 目录时，按 宿主机目录部署说明 配置两个服务的用户、HOME 与挂载，不要直接给整个数据目录开放所有权限。

3. 填写账号与网络设置

按下面顺序设置，每个页面完成后保存。

网络代理（按需）

在「设置 → 网络代理」填写 HTTP 或 SOCKS5 代理，选择 Telegram、TMDB、AI 中哪些服务走代理，再点「测试代理」。115 始终直连。

Docker 容器里的 127.0.0.1 指容器自己。如果代理运行在宿主机或其他设备，填写容器能够访问的局域网地址，而不是照抄宿主机上的 127.0.0.1。

Telegram

填写：

• API ID、API Hash：个人账号登录所需。
• 控制 Bot Token：可选，但推荐填写。
• 你的数字 ID：控制 Bot 的唯一操作者。

这里保存的是接入信息；个人账号还需在下一步的终端里登录。

AI 与 TMDB

• AI：填写兼容接口地址、密钥，从模型列表选择模型；不确定推理强度时先留空。点「测试连通性」，通过后保存。
• TMDB：填写 API Key 或 Read Access Token，确认连通。

测试 AI 会访问你选择的服务，可能消耗少量 Token。国内网络无法连接 TMDB 时可配置代理，或按 配置参考 选择可达地址。

115 网盘

打开「设置 → 115 网盘」，使用自己的 115 App 扫码授权，等待页面显示已登录。

成功标志：115 凭证显示就绪；配置了 AI / TMDB 的，连通性测试通过。密钥只显示是否已设置，不会从页面读回原文。

4. 登录个人账号并启动监听

Docker

docker compose run --rm --no-deps -it worker python -m reelay.login

按提示输入个人账号手机号、验证码；开启 Telegram 两步验证时输入密码。完成后启动两个服务：

docker compose up -d

本机运行

在已激活虚拟环境的另一个终端执行：

python -m reelay.login
python -m reelay.main

后台主进程需要一直运行；不能只开管理台。

成功标志：总览「运行状态」里的后台 Worker 在线、Telegram 已连接、115 凭证就绪。还没配置或登录时 Worker 可能显示 unhealthy，不要仅凭这一项反复重建容器，先完成账号配置。

5. 设置保存目录

打开「设置 → 基础 → 保存目录」：

1. 新增别名，例如「电影」「剧集」「默认」。
2. 点击「选择 115 目录」，为每个别名选择网盘目标文件夹。
3. 在「默认处理方式」选择默认保存目录，确认方式先用「人工确认」。
4. 保存。

别名是 Reelay 里显示的名称，不是直接输入的本地磁盘路径。 默认整理插件还会在目标目录下按分类和作品建立子目录；路径如何决定，见 使用指南：保存目录与整理。

第一次建议选择一个单独的测试目录，确认整理结果符合预期后再用于正式媒体库。

6. 添加一个监听来源

先确认个人账号能看到它

在 Telegram 里先关注频道、加入群组，或者与 Bot 对话。Reelay 不能绕过账号访问权限。

来源	填法
有用户名的 Bot、频道、群组	@username，例如 @example_channel
没有用户名的私有频道、群组	以 -100 开头的数字 ID；若消息链接形如 https://t.me/c/1234567890/42，来源填 -1001234567890

手动添加（先理解设置）

在「设置 → 监听来源」点击「添加来源」，填写：

设置	第一次建议	为什么
Bot 或频道	先添加一个来源	方便发现配置问题；格式不同的来源先分开
确认方式	人工确认	先核对识别和目录，再决定是否转存
识别方式	已配置 AI 用「AI 识别」，否则用「规则识别」	避免没有 AI 时每次都走降级
放行方式	规则判断	第一次确保逐条确认；「规则 + 订阅放行」可能自动放行已订阅新集
仅处理订阅（v1.5.0 起）	先关闭	还没有订阅或 TMDB 未匹配时，开启会直接忽略资源
Bot 通知	已配置控制 Bot 时开启	能在 Telegram 收到卡片；关闭也可在管理台审批
保存到	刚建好的测试目录	先验证，不直接影响现有媒体库

不需要每一项都修改。来源未设置的字段会继承全局默认；布尔开关可以显式关闭来覆盖全局开启。

用样例消息接入（可选）

已经配好 AI 时，也可以点「用样例消息接入」，填写来源并粘贴几条有代表性的消息，让 AI 起草规则，检查每条试跑结果，再加入来源列表并保存。样例最好同时包含正常资源、广告或闲聊，避免只看成功样例。

AI 起草不会替你确认规则正确，仍应核对识别结果和过滤效果。

先点「测试识别」

粘贴一条你有权保存的样例消息，检查：

• 是否识别成正确的作品、年份、季和集。
• 是否显示提取到 115 链接或电驴链接。
• 为什么会转存、待审批或忽略；疑问看处理轨迹。

测试使用卡片上当前的设置，包括尚未保存的修改；不会创建任务，也不会转存，但 AI、TMDB 和分享探测可能访问对应服务。

没问题后保存来源设置。

成功标志：来源出现在列表里，设置无未保存提示。新来源从加入后开始监听，不会自动导入此前的历史消息。

7. 确认第一条资源入库

等这个来源出现一条新的、你有权保存的资源消息：

1. 管理台「任务」出现记录；符合人工确认条件时进入「待审批」。
2. 打开卡片，核对片名、季集、版本与实际保存路径，识别不对先修正。
3. 点击转存。任务先排队，再转存、核验、整理。
4. 最终确认任务显示「已入库」，并在 115 中检查文件夹、文件名和数量。
5. 如果用了 Jellyfin / Emby，再由你已有的挂载或媒体读取方案访问这些文件。

没有进入待审批，不一定是故障：可能命中过滤、已经入库，或符合自动放行条件。先在「任务」看结果和原因，不要只盯着 Telegram 有没有卡片。

如果转存停住，按 常见问题 排查，不要反复创建同一条任务。

接下来怎么配置

• 在追的剧自动收：改为「规则 + 订阅放行」，在「追剧订阅」添加作品与季。
• 只接收订阅资源：使用 v1.5.0 或更高版本，开启「仅处理订阅」，并确认 TMDB 可用；详细边界见 使用指南。
• 减少误识别：调整来源识别规则，试跑正常资源和应忽略的消息后再保存。
• 自动整理：在插件页预览目录与命名模板；了解冲突策略之后再启用自动洗版。
• 长期运行：升级前备份数据，见 部署与运维。

推荐来源

还不知道从哪里开始，可以参考维护者日常使用的 @QukanMovie。它是第三方公开频道，不属于 Reelay；是否使用、转存哪些内容由你自行判断。

1. 用监听的个人账号关注频道，再在来源中添加 @QukanMovie。
2. 「消息必须包含」可填 115.com、115.cn、115cdn.com、ed2k://，每行一个、满足其一即可；只填 115 会挡掉只有电驴链接的消息。
3. 「包含这些词直接忽略」可填 广告、招商。
4. 先用「人工确认」验证；需要订阅新集自动放行时再选「规则 + 订阅放行」。

NOTE

Reelay 不对第三方频道的内容、合法性或可用性作保证，也不提供资源。请遵守所在地法律与版权规定，详见 免责声明。

---

下一步：日常使用指南 · 遇到问题：常见问题 · 查配置项：配置参考