# 快速开始

[文档首页](README.md) · [使用指南](user-guide.md) · [常见问题](faq.md)

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

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

## 开始前的准备

| 准备项 | 用途 | 从哪里获取 |
| --- | --- | --- |
| 一台能持续运行的机器 | 运行 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（推荐）

```bash
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](https://github.com/Derrors/reelay/releases) 选择。`.env` 只放部署参数；账号与密钥之后在管理台填写。

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

### 本机运行

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

```bash
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` 的这一行：

```yaml
- "127.0.0.1:28080:28080"
```

改为：

```yaml
- "28080:28080"
```

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

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

### 设置管理台密码

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

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

> [!NOTE]
> 默认使用 Docker 命名卷保存数据，不需要手动修改目录权限。想使用 NAS 上的 `./data` 目录时，按 [宿主机目录部署说明](deployment.md#用宿主机目录存放数据) 配置两个服务的用户、`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 时可配置代理，或按 [配置参考](configuration.md#ai-服务与-tmdbllm--tmdb) 选择可达地址。

### 115 网盘

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

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

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

### Docker

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

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

```bash
docker compose up -d
```

### 本机运行

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

```bash
python -m reelay.login
python -m reelay.main
```

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

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

## 5. 设置保存目录

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

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

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

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

## 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 有没有卡片。

如果转存停住，按 [常见问题](faq.md) 排查，不要反复创建同一条任务。

## 接下来怎么配置

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

## 推荐来源

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

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

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

---

下一步：[日常使用指南](user-guide.md) · 遇到问题：[常见问题](faq.md) · 查配置项：[配置参考](configuration.md)