Bot 使用指南
本页是 Spore Telegram Bot 的使用入口,面向终端用户和管理员,覆盖:申请使用、发送链接、全部命令、任务进度、媒体与相册行为、配额限流、频道绑定、频道加入、取消任务和常见提示。
相关页面:
1. 使用前提
- Bot 只在私聊中工作。群组、频道里发送的内容会被忽略。
- Bot 只读取文字消息。直接发送图片、视频等媒体给 Bot 不会解析,Bot 会回复"现阶段只支持发送文字消息链接"。
- 使用需要经过审批:向 Bot 发送
/start提交申请,管理员在 Web 管理端批准后,Bot 会私聊通知你。审批结果通知失败不影响审批本身。
用户状态与对应表现:
| 状态 | 发送 /start 或链接时的表现 |
|---|---|
| 未申请 | 创建待审批申请,携带你的 Telegram 用户名和昵称 |
| 待审批 | 刷新申请时间(重复发送无副作用),提示等待审批 |
| 已启用 | 正常使用,/start 返回欢迎与帮助信息 |
| 已停用 / 已归档 | 提示账号已停用 |
2. 发送消息链接
2.1 支持的链接写法
把 Telegram 消息链接直接发给 Bot 即可。以下写法都支持:
| 形式 | 示例 |
|---|---|
| 公开频道/群组消息 | https://t.me/durov/120、t.me/durov/120 |
| 私有频道消息(内部 ID) | https://t.me/c/1234567890/456 |
telegram.me 域名 | telegram.me/durov/120 |
带 www 前缀 | www.t.me/durov/120 |
带 /s/ 前缀 | t.me/s/durov/120 |
省略 http:// / https:// | t.me/durov/120 |
补充规则:
- 链接前后可以有其他文字或中文标点,例如"看这个 https://t.me/durov/120 转给我"。
- 链接上的查询参数(
?...)和锚点(#...)会被忽略。 - 公开链接的用户名为 4–64 位字母、数字或下划线;消息 ID 和私有频道内部 ID 为正整数,最多 16 位。
- 处理时统一按规范化后的
https://t.me/...链接记录与去重。
2.2 一次提交多条链接
一条普通消息可以包含多个链接,/download 也可以携带多个链接并上传到同一目的地。Bot 按出现顺序为每条有效链接独立创建请求;提交频率按整条输入检查一次,去重、日额度、并发和队列限制仍逐条计算,因此同一批次允许部分成功、部分失败,提交结束后会返回汇总。
默认每次最多处理 10 条有效链接,管理员可在「运行设置」中调整为 1–50 条。超过当前上限时整批拒绝,不创建任务、不扣额度;请拆分后重新发送。非法片段不计入条数,重复出现的有效链接仍分别进入校验。
当前不支持:消息 ID 区间抓取、按日期范围抓取、话题(Forum Topic)与回复线程归属保留。/cancel 仍一次只取消第一条有效链接。
2.3 来源访问权限
- 公开链接:由系统登录的读取账号解析并拉取消息。
- 私有频道链接(
t.me/c/...):不要求你本人加入了该频道,要求的是系统的读取账号能访问。读取账号未加入时,Bot 会提示使用/join让它加入。
关于"受保护内容":Spore 不使用 Telegram 的转发/复制通道,而是读取账号取数后重新下载媒体并构造新消息发送。能否提取取决于读取账号是否有权限访问该消息。
2.4 引用回复操作任务(/pin、/cancel)
/pin 与 /cancel 支持作为对 Bot 消息的回复发送(Telegram 原生命令用法):长按/右键回复 Bot 发出的任务消息(进度提示、投递结果、失败通知)再输入命令,命令即作用于该消息对应的任务,无需复制链接。消息坐标落库后跨重启有效;功能上线前的历史消息、其他 bot 发出的消息查不到时会返回引导文案。
/cancel回复在途任务的任意消息 → 取消该任务(进度提示、已送达的部分消息均可回复)/pin回复在途任务的消息 → 补置顶标记,任务完成时副本照常置顶/pin回复已完成任务的投递消息 → 按落库的频道副本坐标事后补置顶(逐目标执行并回写结果;完成时无频道副本则提示无法补置顶)- 命令带链接参数时优先按链接处理,回复被忽略;无参且不是回复任务消息时进入 ForceReply 输入引导,可查看用法或取消
2.5 置顶+转存网盘(/pin 输入引导)
云盘功能开启时,通过 /pin 的输入引导(无参发送 /pin 后回复粘贴链接)提交会先弹出提交方式选择:
- 📌 仅置顶:与直接发送
/pin 链接完全一致,只做转发与置顶。 - 📌☁️ 置顶+转存网盘:同一链接同时提交两个任务——先转发置顶,再把媒体上传到网盘默认目的地(需要账号有云盘下载权限)。两个任务各占一次每日额度;云盘任务优先级较低,仅在无转发任务排队时执行,因此确认消息会稍后到达。
云盘功能关闭、账号无下载权限或未配置默认目的地时不会出现选择按钮(或自动降级为仅置顶并提示)。需要指定非默认目的地时,请单独使用 /download 目的地 链接。
3. 命令总览
Bot 命令菜单均需在私聊中使用。命令支持 /命令@机器人用户名 的写法,也可携带参数;无法识别的首个词会按链接解析;/pin、/cancel 还支持作为对 Bot 消息的回复发送(见 2.4 节)。
| 命令 | 说明 |
|---|---|
/start | 申请使用;已启用用户显示欢迎与帮助 |
/help | 查看使用帮助 |
/usage | 查询今日已用额度、限额、剩余次数和重置时间 |
/status | 查看服务运行状态(读取账号连接、大文件通道、数据库、队列等) |
/health | 健康自检 |
/cancel <链接> | 取消该链接的在途任务;也可回复任务消息直接使用 |
/download [目的地] <链接> | 下载到网盘而不是重发到 Telegram;无参时可回复链接并按启用目的地自动选择/弹出选择按钮,详见下载功能 |
/pin <链接> | 提交任务并在成功后置顶到绑定的频道/群组;也可回复任务消息使用(在途补标记、已完成补置顶)。无参进入输入引导时还可选择「置顶+转存网盘」一并上传到默认目的地(云盘功能开启时),见 下载功能 |
/bind <频道> | 绑定频道,任务成功后自动发副本 |
/unbind <频道> | 解绑频道 |
/channels | 查看已绑定的频道列表 |
/join <邀请链接> | 让系统读取账号加入频道 |
/watch <频道> | 添加监听源频道/群组,新消息自动预热缓存,提交后即可选择专属转发目标 |
/watchtarget <频道> | 为我的监听源选择/重选/清除专属转发目标 |
/watchlist | 查看我的监听源与邀请申请状态(含专属转发目标) |
/unwatch <频道> | 移除我的监听源 |
4. 任务处理与进度
提交链接后的流程:
- Bot 先回复一条"正在获取消息..."占位消息。
- 任务通过准入检查后进入队列(队列满会直接提示,不发送占位)。
- 读取账号拉取消息、标准化文本与媒体、下载媒体。
- 通过 Bot API(或大文件直传通道)发送给你。
- 成功或失败后删除占位消息。
进度显示:
- 占位消息约每 5 秒检查一次,内容有变化才编辑;显示下载、上传两行的百分比和字节数。
- 纯文本任务、无占位消息的任务不显示进度。
- 进度只保存在内存中,服务重启后自然消失。
超时与中断:
- 拉取消息的超时为 15 分钟;发送窗口为 15 分钟加上每 1MB 约 1 秒,最长 2 小时。
- 服务重启时,未完成任务标记为"已中断",Bot 会提示重新发送链接;管理员也可以在管理端对失败的请求发起重试(累计尝试上限默认 3 次,可在「运行设置」页配置为 1–10;已达上限的请求可在消息记录详情页重置尝试计数后再次重试)。
5. 支持的内容类型
5.1 文本消息
原样重发文本(保留加粗、斜体、下划线、删除线、代码、代码块、引用、剧透、链接等格式),顶部附"原消息"链接。
- 正文上限 4096(UTF-16 单位),媒体说明文字上限 1024,超限会截断并提示"原文过长已截断"。
5.2 媒体类型
| 类型 | 支持 | 说明 |
|---|---|---|
| 图片 | 支持 | 官方 Bot API 模式下超过 10MB 的图片按文件发送 |
| 视频 | 支持 | |
| 文件 | 支持 | |
| 音乐 | 支持 | |
| 语音 | 支持 | |
| GIF 动图 | 支持(按视频处理) | video/mp4 动图按视频发送 |
| 贴纸、投票、联系人、位置、故事等 | 不支持 | 提示"暂不支持这种消息类型" |
| 网页预览 | 未确认 | 当前实现没有专门的网页预览处理分支,带网页预览的消息可能按不支持处理,请以实际表现为准 |
5.3 相册
- 发送相册中任意一条消息的链接即可识别整组,按消息 ID 升序发送。
- 相册最多 10 项;不会自动拆分成多个相册。
- 只有图片和视频能整组发送;包含文件、音乐、语音的相册会退化为逐条单独发送。
- 每条成员保留各自的说明文字;"原消息"链接只附在第一条。
- 任一成员下载失败时,整组任务失败。
6. 大小限制与发送通道
| 场景 | 行为 |
|---|---|
文件超过 MAX_FILE_SIZE(默认 2000 MiB) | 下载前直接拒绝,提示超过大小上限 |
| 不超过 50MB(官方 Bot API 模式) | 由 Bot API 直接发送 |
超过 50MB 且不超过 MAX_FILE_SIZE | 走机器人账号的 MTProto 直传通道;该通道未就绪时提示"大文件发送通道暂不可用",小文件不受影响 |
| 相册成员都不超 50MB 但整组总量超过 50MB(官方 Bot API 模式) | 整组改走机器人账号的 MTProto 直传通道(Bot API 的 sendMediaGroup 受整个请求体的容量上限约束,不按单个附件计),相册仍作为同一条消息整组送达 |
配置了本地 Bot API 服务器(BOT_API_URL) | 上传上限放宽到 MAX_FILE_SIZE,不再使用 MTProto 直传 |
说明:
- 20MB 以内的媒体边下边传(流式),更大的媒体先下载到内存或临时文件再上传,临时文件在任务结束后清理;同时下载共享一个进程级"内存预算"(管理端运行设置可调),预算不足的文件自动改走临时文件路径,多任务并发也不会把内存占满。
- 云盘下载(
/download)同样受MAX_FILE_SIZE限制,并不绕过 Telegram 下载上限。 - Bot API 的媒体上传遇到限流不会自动重试(媒体数据只能消费一次);轻量文本操作最多自动重试一次。MTProto 侧的限流会自动等待重试,仍失败时提示"请求过于频繁"。
7. 配额、限流与去重
每次提交链接(含 /download)都要通过同一套准入检查:
| 步骤 | 检查 | 默认值 |
|---|---|---|
| 1 | 账号状态为已启用 | — |
| 2 | 链接不在去重窗口内 | 窗口默认 10 分钟 |
| 3 | 距上次提交超过间隔 | 10 秒 |
| 4 | 当日额度未用完 | 50 次/天 |
| 5 | 未完成任务数未达并发上限 | 2 个 |
| 6 | 内存队列未满 | 容量默认 64 |
规则:
- 被拒绝时不创建任务、不扣除额度。
- 额度按运营时区(默认
Asia/Shanghai)每日重置;失败和取消不返还额度。 - 去重只针对"投递到 Telegram 的成功记录":窗口内重复提交同一条链接会提示"该链接刚刚已处理"。失败和取消的记录不进入去重。
- owner(号主)跳过间隔、额度、并发三项检查,但仍受账号状态、去重和队列满约束。
/usage可查询当日已用、限额、剩余和重置时间;owner 显示为不限额度。- 管理员可在管理端为单个用户调整以上限额。
8. 缓存频道复用
8.1 效果与行为
- 任务成功时会把结果保存一份"干净副本"到每个启用的缓存频道(不含任何用户的频道脚注;多缓存频道 = 多一份冗余,Bot API 写入量按频道数增加)。
- 之后任意用户再次发送同一条链接,可直接从缓存频道复制结果,不限媒体大小,相册保持整组,速度更快;复用在全部启用频道范围内查命中。
- 绑定了频道的用户命中缓存时,会额外补上自己的频道脚注。
- 缓存条目不存在或复制失败时,自动回退到完整的下载上传流程,任务仍会正常完成。
- 可在管理端"频道设置"中配置多个缓存频道并逐个开关(最多 10 个);没有任何启用频道时始终走完整流程。
8.2 一次性配置步骤
- 用管理员账号新建一个频道(可直接建私有;或先建公开、配置后再转私有——数字 ID 不变,转私有后照常使用)。
- 把 Bot 拉进该频道并设为管理员(只需发消息权限)。
- 打开 Web 管理端「频道设置 → 缓存频道(重复链接复用)」,填入
@用户名、t.me 链接(公开频道)或-100数字 ID(私有频道;可从管理端频道列表复制,或把频道消息转发给@userinfobot查询),点「验证并添加」——服务端解析并校验 Bot 已是管理员后,保存数字 ID 与标题,即时生效、无需重启。 - 需要冗余时可继续添加更多缓存频道(每频道独立启用开关:停用后不读不写,历史副本保留,重新开启即恢复;移除走二次确认)。单个频道即可满足基本复用,多频道仅为可选冗余。
也可以在 .env 里预置 DUMP_CHANNEL_ID(仅作 Web 配置为空时的兜底,详见配置参考)。
8.3 安全边界
- 不配置或全部停用则完全没有复用(每次完整下载上传);复用总开关与去重窗口都在管理端「频道设置」页(移除全部频道同样关闭复用)。
- 缓存频道会累积所有成功投递的副本;副本集中存放于这些频道,账号封禁会连带失效(多频道互为冗余可降低单点风险),敏感度与管理员 Session 同级,勿公开该频道。
- 缓存频道不能开启 Telegram 的「限制保存内容」(限制转发):复制会失败并回落完整下载上传;当前实现不会在启动时预检该设置。
- 缓存频道不能同时作为监听源:监听预热把副本写回缓存频道会再次触发监听,形成循环转发。两侧配置入口都有校验拦截(监听源注册与缓存频道添加互斥),监听运行时也会跳过来自缓存频道的消息兜底。
8.4 已处理历史恢复
管理端「历史恢复」(/admin/recovery)可把系统已登记的历史批量发送到新目标,不需要逐条手动转发,也不遍历原来源的全部历史。管理端该页面(列表页与任务详情页)右上角的「操作文档」按钮可直接打开本节。
- 在 Telegram 提前创建新的频道或非论坛超级群组,把执行机器人加入并授予发送权限。私有目标使用
-100数字 ID;公开目标可用用户名。 - 确认执行机器人能访问用于恢复的缓存频道。通常使用现有机器人即可;换成其他已配置机器人时,需要另行补齐缓存和目标权限,不会自动继承原机器人的权限。
- 填写来源、用户、时间范围(可留空)、目标与机器人,点击预览。来源/目标/用户三个框都可下拉选择、也可直接输入:来源下拉带出生效监听源(含频道/超级群组类型)、有效绑定频道与提取历史来源;目标下拉带出有效绑定频道(含标题),输入新目标即可恢复到新频道;用户下拉带出用户管理中的启用用户(含显示名)。下拉数据只是建议,查询失败不影响手动输入。预览检查聊天与权限信息,不试发消息;显示可读不代表每条旧消息一定存在。
- 确认预览后创建任务。后台优先复制已知缓存副本,没有可用缓存时走与普通提取相同的下载上传管线,直接发送到恢复目标;只有明确没有发送成功时才尝试其他副本或原来源。原来源提取依赖当前登录的读取账号仍有访问权限。
- 查看逐项结果,按需暂停、继续、取消或重试可安全重试的失败项。点击任务列表中的「任务 #ID」进入独立详情页(
/admin/recovery/jobs/ID,可刷新、可收藏链接);有运行中任务时页面每 5 秒自动刷新,空闲时停止轮询。重启后任务暂停,需手动继续;结果不确定的项目不会自动重发。
8.5 更换恢复执行机器人
恢复默认使用主机器人;如需换成新机器人,按以下步骤操作:
- 向 @BotFather 创建新 bot,取得 Token(也可复用已在池中的其他机器人,跳到第 3 步)。
- 打开管理端「机器人池管理」→「添加机器人」,粘贴 Token 提交;系统会自动建立该 Bot 的 MTProto 会话并上线(离线/停用状态在恢复表单中不可选)。
- 手动把新机器人加入两类聊天并授权,权限不会从旧机器人继承:
- 恢复目标(新频道/超级群组):设为管理员并授予发帖权限;
- 缓存频道:至少保证它能看到频道消息(私有缓存频道必须手动拉入)。
- 在历史恢复表单的「执行机器人」下拉中选择新机器人并完成预检;创建后任务会固定该机器人的实际 ID,不再自动切换。
- 换机器人继续同一目标的恢复是安全的:已恢复项的跳过与「不确定结果」保护都按目标聊天匹配,不区分执行机器人——旧机器人已恢复过的项在新任务中自动跳过,旧任务留下不确定结果时新任务会被拒绝创建(先人工核对)。
- 若新机器人权限不全:目标发帖失权会让任务暂停并在详情页提示,补权限后可「继续」;缓存不可读时该项自动改走原来源提取,读取账号也无法访问才标记「无法恢复」。预览中的「缓存频道权限」列表会逐个标出该机器人对每个缓存频道的可读性,照着补齐即可。
- 旧任务是否还能「继续」:旧任务固定的是旧机器人;若旧机器人仍在池中在线,直接继续旧任务即可。若旧机器人已离线/移除,无法继续旧任务,用新机器人对同一目标新建任务续跑——已恢复项会自动跳过,只补剩余部分。
注意:机器人池的容量上限与登录状态见「机器人池管理」页;添加机器人后其 MTProto 会话凭据保存在服务端数据目录,随数据库/部署一并保护。
重要边界:
- 只发送到任务固定目标,不重新发给用户私聊,不同步其他绑定,不自动更改绑定或全局缓存配置。
- 数据库备份保存索引与恢复进度,不保存正文、caption、实体内容或媒体;所有副本与原来源都不可读时,项目无法恢复。
- 相册部分复制、发送超时或发送中断等可能已产生消息的情况标记为「结果不确定」。先人工核对目标中的实际消息,不要通过重新建任务绕过此提示。
- 新消息有新的 ID 和发送时间,不承诺恢复原链接、作者、回复关系或原始全局时间顺序;从缓存恢复的是缓存中保存的呈现内容。
- 恢复结果保存为独立任务坐标,不会自动发布为普通缓存复用索引。仅把恢复目标手动设为全局缓存,不代表所有旧链接立即命中;可读旧缓存的索引迁移仍使用「迁移旧缓存」,或由后续提交/缓存补写重新建立索引。
- 现有数据库备份和云盘功能保持不变;本功能不新增云盘存储或云盘内容恢复。
8.6 缓存迁移(迁移旧缓存)
新增/切换缓存频道后,旧频道里仍可读的副本可以整批复制到当前全部启用的缓存频道(免重新提取,逐频道落新消息坐标),供重复链接继续秒回。发起入口在管理端「频道设置」页的「迁移旧缓存」(填旧频道 ID;升级前的存量会自动建议源频道)。
- 后台执行、断点可续:分批限速(不占满 Bot API 配额);目标频道已有现行条目自动跳过;源频道不可读时结束并记录原因(剩余条目由复用自愈重建)。中断后重新发起会自动续跑,已迁移条目计入「跳过」。
- 进度与逐条明细:管理端「缓存迁移」页(
/admin/dump-migrate)展示运行历史与最新进度(已迁移/跳过/失败计数、进度条);点击运行进入详情页,逐条查看来源坐标 → 各目标频道落地的新消息 ID 或失败原因,可按状态筛选、分页,运行中自动刷新。频道设置页的进度提示也带跳转链接。 - 暂停 / 继续 / 取消:运行中可暂停(秒级生效,占用配额的复制即刻停住),暂停中可继续(从断点恢复)或取消(结束本次运行、保留明细,之后可重新发起幂等续跑);同时至多一个运行。
- 重启语义:服务重启会中断进行中(含暂停中)的迁移并如实标记「已中断」,重新发起即可续跑;已完成的运行记录与明细保留可查(最近 20 次)。
9. 绑定频道与副本投递
9.1 绑定命令
/bind <频道>:目标可以是@用户名、t.me/频道链接、t.me/c/<内部ID>(可带消息段)、t.me/+…/t.me/joinchat/…私有邀请链接,或-100开头的频道 ID。- 使用邀请链接时,系统会先确认链接指向频道/超级群组,再让读取账号实际加入以解析频道 ID;邀请无效、已过期或指向普通群组会直接拒绝。若频道开启加入审核,请先等待频道管理员批准读取账号加入,再重试
/bind;也可改用t.me/c/…或-100ID。 - 邀请链接不会自动添加 Bot。仍须人工把当前接收
/bind的机器人加入目标并授予所需管理员权限;Web 绑定则校验主机器人。 /unbind <频道>:只能解绑自己名下的频道。/channels:查看已绑定频道,展示公开链接或私有频道内部链接。
前置条件:
- 仅已启用用户可绑定。
- Bot 必须是目标频道的管理员且拥有发帖权限,否则提示先把它设为频道管理员。
- 一个频道只能绑定给一个用户。
- 绑定数量有上限:普通用户默认 1 个,owner 默认 3 个,管理员可在管理端按用户调整。
9.2 投递行为
- 任务成功后,已发给你的消息会被复制到你的绑定频道;文本和媒体末尾会附频道脚注(形如「📢 频道」,每个频道独占一行,公开频道显示可点击的用户名,私有频道显示标题和内部链接)。
- 置顶结果确认(含
/pin回复补置顶)里的频道名同样是可点击链接,多个频道逐行列出。 - 频道副本是尽力而为:单个频道复制失败只记录日志,不影响你收到消息,也不构成与用户消息的原子双投递。
10. 监听源预热(/watch)
用途:把你管理的频道/超级群组配置为监听源——bot 接收源内新消息并自动转存一份到缓存频道,之后任何人把该源的消息链接发给 bot 都直接命中缓存复用秒回(无需等下载上传)。
- 前提:先把 bot 加为该频道/群的管理员(管理员身份保证 bot 能收到全部消息;超级群组若不加管理员,需在 BotFather
/setprivacy关闭)。 - 目标支持频道与超级群组,可配置多个监听源;受保护内容(开启"禁止转发")的源会自动改走读取账号下载重传管线(需读取账号能访问该源)。
- 支持私有邀请链接(
t.me/+…、t.me/joinchat/…):提交后进入邀请申请流程——审批通过(或免审批)时系统读取账号经邀请加入目标;若该频道开启了"加入需审核",则等待频道管理员批准后自动继续。注意平台边界:邀请链接只能让读取账号加入,Bot 不会被自动拉入,仍需人工把 Bot 设为频道/群管理员;读取账号加入后 Bot 管理员校验通过,监听才正式生效(期间申请处于"等待 Bot 管理员权限"状态,配置完成后自动/手动重试生效)。 - 管理端为独立「监听源」菜单组:「监听源管理」页直接添加(支持公开标识与私有邀请链接,不受上限约束)、审批用户申请与邀请申请、重试等待中的邀请申请、暂停/删除;监听源列表与邀请申请均支持状态/关键词筛选(「查询」按钮生效),监听源列表支持批量同意/拒绝/暂停/恢复/删除。「监听源配置」页管理申请开关、审批模式与上限(总数缺省 20、每用户缺省 3),即时生效;「监听记录」页是逐次转储留痕(哪个 Bot、哪个源、消息直链、路径与关联请求),支持按源/按方式筛选、单条与批量删除留痕(不影响已缓存副本)。移出 Bot 经监听源删除流程处理(全部机器人退出源并删配置)。
- 业务统计页的「监听源」页签:源状态计数、按源/按 Bot/按用户的转储聚合与按日趋势,随页首时间范围与机器人筛选查询。
/watch不带参数查看我的监听源与邀请申请状态;/unwatch移除自己的源(任意状态)。
专属转发目标(/watchtarget)
你申请的每个监听源,源内新消息除了预热缓存,还可以自动转发一份到你自己的频道或超级群组(专属转发目标):
- 前提:先用同一个 Bot
/bind绑定目标频道/群组并通过验证(监听与转发须由同一 Bot 完成,避免误投)。 /watch提交成功后会立即弹出选择面板(即使源还在待审批),从你已验证的绑定中单选一个;私有邀请链接的申请同样可以先选,激活为监听源时自动生效。/watchtarget <频道>随时重选或清除(清除后只保留缓存预热);/watchlist会显示每个源的专属转发状态(已设置 / 未设置 / 目标已失效)。- 目标绑定被解绑或失效后专属转发自动停止(缓存预热不受影响),重新
/bind后再/watchtarget重选即可恢复。 - 目标不能是任何监听源或缓存频道(防止循环转发),全局也不能把已有监听源配成转发频道;这些冲突在选择时与配置时都会被直接拒绝。
- 管理员可在「监听源管理」页按源开启"全局镜像",让该源的内容额外转发到系统全局转发频道(用户源默认关、管理员源默认开);管理员只能看你的专属目标状态,不能替你选择。
权限边界(与 /join 相反):/watch 要求用户已 /start 通过(enabled),申请默认需号主审批(可配免审批);每用户上限与总上限同时约束普通监听源与邀请申请(活动中的邀请申请计入上限)。
11. 频道加入(/join)
用途:让系统的读取账号加入频道(例如访问私有频道取数需要读取账号可见)。
- 输入支持
t.me/+分享链接、t.me/joinchat/...或裸邀请码。 - 功能默认关闭,管理员需在管理端"受邀设置"中开启。
权限边界(与其他命令不同):
/join不检查用户的"已启用"状态:功能开启时,待审批或未授权用户也可能提交加入申请或直接加入。管理员应结合这一差异决定是否开启该功能。
审核与结果:
| 场景 | 行为 |
|---|---|
| owner | 即时加入 |
| 普通用户(默认开启审核) | 提交申请,号主在管理端审批后实际加入 |
| 关闭审核 | 普通用户直接加入 |
| 请求制邀请链接 | 提示已向频道管理员发送加入请求,等待 Telegram 侧批准 |
| 已是成员 | 直接提示 |
补充:
- 实际加入动作由读取账号完成;加入成功后按配置自动静音、归档。
- 最大同时加入频道数默认 20。
- 被外部拉入的频道会按配置补静音/归档;"自动退出外部拉入频道"默认关闭。
- 读取账号自己创建的频道、超级群组跳过自动静音与归档;已被旧版本处理的对话需在 Telegram 客户端手动取消归档、恢复通知。
- 创建者的频道无法退出。
12. 云盘下载(/download)
/download <t.me 消息链接>
/download <目的地名称> <t.me 消息链接>与普通链接的差异:
- 成功后发送确认文本,不会把媒体重发到 Telegram,也不生成频道副本和脚注。
- 共用同一套准入检查(状态、去重、间隔、额度、并发、队列),此外还需要:管理员开启云盘功能、rclone 可用,以及你的账号被授予云盘下载权限(默认仅 owner)。
- 未授权、待审批或已停用用户看到与普通链接相同的提示,不会暴露云盘功能是否存在。
目的地的配置、网盘账号、备份恢复和排障见下载功能。
13. 取消任务
/cancel <原消息链接>:取消你提交的、该链接对应的所有排队中和处理中的任务,并返回取消数量(0 个时提示无进行中任务)。- 也可以回复 Bot 发出的任务消息(进度提示、投递结果、失败通知)直接发送
/cancel,取消该消息对应的任务,无需复制链接(见 2.4 引用回复操作任务)。 - 取消不返还当日额度;请求记录保留,可在管理端查看。
- 已停用的用户仍可以取消自己在途的任务。
- 管理员也可以在管理端单条或批量取消请求。
取消后的画面:占位消息不会被删除,而是改为"任务已取消"并附删除线的来源链接。
14. 服务状态与健康
| 命令 | 内容 |
|---|---|
/status | 用户号连接、大文件直传通道、数据库、队列水位、处理中数量、worker 数 |
/health | 健康判定:用户号连接正常 + 数据库正常 + worker 在运行 |
- 大文件直传通道未就绪不会让
/health变为不健康,也不会影响文本和小文件;它只影响超过 Bot API 上限的媒体。 /status输出经过脱敏,不包含链接、Session 等敏感信息。
15. 常见提示与错误
Bot 的失败提示都是受控中文文案,底层错误细节只写日志。任务执行失败的提示会附带来源链接(可点击),一次处理多条链接时可据此区分是哪条失败了。常见对应关系:
| 提示要点 | 含义与处理建议 |
|---|---|
| 无法识别有效的 t.me 消息链接 | 链接格式不受支持,检查写法 |
| 找不到这条消息 | 消息已删除或链接无效 |
| 无法访问该频道 | 读取账号无法访问,可用 /join 让它加入 |
| 这是一条服务消息 | 目标是加群/置顶等服务消息,无可提取内容 |
| 暂不支持这种消息类型 | 贴纸、投票等类型不在支持范围 |
| 文件超过大小上限 | 超过 MAX_FILE_SIZE,详见配置参考 |
| 临时目录空间已满 | 管理员需清理或调整临时目录容量 |
| 媒体下载失败 / 发送失败 | 多为暂时性错误,可稍后重试或请管理员重试 |
| 请求过于频繁 | Telegram 侧限流,稍后再试 |
| 大文件发送通道暂不可用 | 大文件直传通道未就绪;小文件不受影响 |
| 当前任务较多 | 队列满,稍后再试 |
| 该链接刚刚已处理 | 去重窗口内重复提交 |
| 提交过于频繁 / 今日额度已用完 / 还有未完成的任务 | 触发限流、额度或并发限制,等待重置或完成 |
| 任务因服务重启被中断 | 重新发送链接,或请管理员重试 |
| 请求已取消 | 任务被你或管理员取消,额度不返还 |
更多排查路径见问题与解决记录;管理端 API 的错误码定义见 API 参考。
16. 支持边界与限制
- 仅支持私聊文字消息;不能把媒体直接发给 Bot 解析。
- 一次可处理多条链接(默认最多 10 条,运行设置可调 1–50);不支持区间、定时抓取,不保留话题/回复线程归属。
- 相册最多 10 项,不自动拆组;仅图片和视频能整组发送。
- 贴纸、投票、联系人、位置等类型不支持;网页预览行为未确认,不作为承诺能力。
- 单文件上限默认 2000 MiB;云盘下载不绕过该上限。
- Bot API 媒体上传遇限流不自动重试;频道副本与脚注为尽力而为。
- 缓存频道开启"限制保存内容"会导致复用失效并回退完整链路。
- 取消和失败不返还额度;额度按运营时区每日重置。
- 任务进度仅保存在内存中,重启后清零;服务重启会中断在途任务。
- 自动化测试覆盖纯逻辑部分;Telegram 登录、频道读取、媒体上传、相册与大文件等真实链路仍待真机验收,使用中遇到问题请结合问题与解决记录反馈。