Skip to content

Spore 技术设计文档(Go 版) ​

本文是 Go 重写后的技术设计,替代旧的 TypeScript + grammY + copyMessage 方案。 §11 为按当前代码整理的执行顺序与运行时流程;§12 为业务全景流程图(唯一权威版本,链路变更时同步更新)。

1. 架构总览 ​

Spore 是一个 Telegram 受保护消息提取机器人。用户把频道消息链接发给 Bot,系统通过 MTProto 用户账号读取源消息,重新构造为一条全新消息发回给用户。新消息不保留 Forward Header,可正常再次转发——这是与 Bot API copyMessage/forwardMessage 的本质区别。实现上不依赖 Telegram 的转发/复制通道,也没有针对源频道 noforward 标志的专门检查:能否读取取决于登录的读取账号对源频道的访问权限。

核心原则:

Bot API 负责"和用户聊天",MTProto 负责"以用户身份访问 Telegram",业务层负责"把源消息转换成新的消息"。

1.1 双通道架构(两个 MTProto 会话) ​

Bot 会话(data/bot-session.json,internal/mtproto/bot.go)复用 BOT_TOKEN 登录、 异常退出指数退避自动重启;大文件直传(internal/mtproto/botsend.go)用 gotd uploader 把下载好的媒体字节上传为 Bot 自己的新文件后 messages.sendMedia 发送——绕过官方 Bot API 服务器的 50MB 上传硬上限(MTProto 通道上限 2000MB)。未就绪时仅超过 Bot API 上限的媒体以 LARGE_CHANNEL_UNAVAILABLE 确定性失败,小文件不受影响。

1.2 一次请求的完整数据流 ​

(运行期的完整执行顺序、并发模型与退出路径见 §11。)

1.3 运行模型 ​

  • 单进程、长驻运行;SIGINT/SIGTERM 优雅退出。
  • 所有 MTProto 调用必须发生在 gotd client.Run 的回调作用域内,因此 Bot 轮询与 worker 均在 MTProto 就绪后启动。
  • 业务数据存内嵌 SQLite(data/spore.db,见 §3.7);无消息结果缓存、无 Redis。MTProto 会话 data/session.json 与 AccessHash 缓存 data/peers.json 仍是文件,不入库。
  • Worker 数默认 1,通过 WORKER_COUNT 可调。

2. 目录结构与模块职责 ​

text
spore/
├── cmd/bot/main.go              # 唯一入口:启动编排(依赖装配,无业务逻辑)
├── frontend/                    # React SPA 管理端(构建产物经 embed 进 Go 二进制)
├── internal/
│   ├── config/                  # 环境变量加载与校验
│   ├── apperr/                  # AppError 错误模型 + 错误码 + 中文用户提示
│   ├── botapi/                  # Bot 长轮询、私聊过滤、命令分流、链接提交
│   ├── access/                  # 用户准入六步链、申请/审批、额度、管理取消/删除/重试
│   ├── tmeurl/                  # t.me 消息链接与邀请链接解析(纯函数)
│   ├── mtproto/                 # 用户号/Bot 号两个 gotd 客户端:登录、Peer 解析、取消息、
│   │                            #   成员加入、大文件直传、DC 重定向
│   ├── message/                 # 源消息标准化、媒体类型判定、Entity→HTML、caption
│   ├── media/                   # 媒体下载句柄(流式 io.Pipe / 内存管道 / 临时文件)与清理
│   ├── delivery/                # 发送路由:Bot API 上传 / Bot 号 MTProto 大文件直传 / 相册
│   ├── queue/                   # 双通道优先级 Job 队列 + worker:普通投递、缓存复用、云盘任务(云盘低优先)
│   ├── dumpcache/               # 缓存频道干净副本写入与复制(转存频道复用)
│   ├── recovery/                # 已处理历史恢复:固定候选/目标、缓存优先、持久化控制与安全续跑
│   ├── watch/                   # 监听源(/watch)生命周期:申请/审批/上限/移除、
│   │                            #   专属转发目标(/watchtarget)与逐源全局镜像投递计划
│   ├── listener/                # 监听源消息接收:相册聚合 → 缓存频道预热 →
│   │                            #   按源投递计划转发(专属目标/全局镜像,双路径)
│   ├── binding/                 # 用户频道绑定(/bind 与管理端共用校验)与脚注来源
│   ├── joinmgr/                 # 频道加入:/join、审批、静音/归档、外部拉入处理
│   ├── progress/                # 下载/上传进度的内存注册表(5 秒粒度占位编辑)
│   ├── store/                   # SQLite 持久化(连接、版本化迁移、各聚合 DAO)
│   ├── syscfg/                  # 系统身份与频道加入等运行设置的读取/校验
│   ├── transfercfg/             # 下载/上传线程与连接数的运行时覆盖(DB 覆盖 env)
│   ├── cloudarchive/            # 云盘下载:cloud-drive.json 配置、rclone 封装、远端布局
│   ├── monitor/                 # 进程资源与传输速率采样(RSS/临时目录/CPU,48h 历史)
│   ├── notify/                  # 系统事件:按 key 合并、冷却、模板化通知正文(templates/)与活动通知
│   ├── errlog/                   # 错误日志中心写入门面:逐条落 error_logs(截断/节流/保留清理),与事件中心互补
│   ├── notifycfg/               # 通知通道/策略配置、凭据加密与 Bot/Webhook 适配器
│   └── web/                     # 管理端:SPA 壳、/api/v1 JSON、登录会话、CSV/QR 端点
├── data/                        # spore.db / session.json / bot-session.json / peers.json /
│                                #   tmp/ / cloud-drive.json 等(gitignore)
├── go.mod / go.sum / Makefile / .env.example / README.md / docker-compose.yml
包职责不负责
botapi接收 Update、私聊过滤、命令分流(/start /help /status /usage /cancel /join 等)、链接入队、状态消息任何 MTProto 操作、业务处理
access用户准入六步链(状态/去重/频率/额度/并发/队列满)、/start 申请、审批、管理端取消/删除/重试/补存入口Telegram 协议、投递执行
tmeurl文本 → SourceRef(纯函数)访问网络、验证频道存在
queueJob 缓冲、worker 生命周期、普通/复用/云盘任务编排、进度与取消具体发送与下载实现
mtproto用户号/Bot 号登录、Peer 解析、取消息、成员加入、大文件直传消息语义解释、准入规则
message源消息标准化、媒体类型判定、Entity→HTML 渲染网络调用
media下载策略选择(流式/内存管道/临时文件/拒绝)与句柄清理上传
delivery通过 Bot API 或 Bot 号 MTProto 发送新消息(按大小路由)消息内容构造
dumpcache / binding / joinmgr缓存频道副本、用户频道绑定、频道加入与审批—
watch / listener监听源申请审批与生命周期(Bot /watch 与 Web 共用);专属转发目标(申请人 /watch 提交后即选或 /watchtarget 重选/清除,同 Bot 路由 + 双向防循环校验,私有邀请先暂存、激活即转移)与逐源全局镜像开关;源消息接收、相册聚合与缓存频道预热,快路径与受保护内容回退共用同一份按源投递计划(专属目标按源 Bot 精确路由,失联不回退主 Bot)watch_sources
storeSQLite 连接/迁移与各聚合 DAO(用户、请求、用量、审计、事件、设置、会话、加入留痕等)业务准入规则、Telegram 协议
webSPA 壳与 /api/v1 JSON API、登录会话/CSRF、CSV/QR 功能端点业务准入决策(经 access/joinmgr 等服务)
config / apperr / syscfg / transfercfg横切:环境配置、错误模型、运行设置与传输覆盖—
cloudarchive / monitor / notify / notifycfg / progress云盘 rclone 封装、资源监控、事件目录/冷却/模板化通知正文/活动通知、通知通道与策略配置/投递、进度注册表—

已处理历史恢复 ​

recovery 整合请求、缓存条目和监听事件,按已知来源别名、相册成员及缓存坐标合并恢复单元。预览只查询聊天/成员权限,不复制或删除测试消息;创建时重新验证并固定候选、目标及实际机器人 ID。恢复单独发送到指定目标,不调用普通请求的私聊、绑定同步或缓存写回副作用。

任务和逐项结果存于 recovery_jobs / recovery_items,仅保存索引、状态、受控诊断与输出坐标,正文、caption、实体内容、媒体本体及会话凭据不入库。创建和管理员控制的成功审计与状态变化在同一短事务中提交,事务不跨 Telegram 网络调用。

执行优先复制可读缓存,再在确定没有发送的失败情况下尝试其他副本或原来源。选定 Bot 必须精确匹配且可用,不能静默切换;原来源提取沿用用户账号取数和既有发送管线。恢复运行器附着于 MTProto 生命周期,关闭时取消并等待在途工作退出。

发送前持久化 processing;部分相册、超时、输出数量异常或中断可能已经发送,保存已知输出并标记 uncertain,不自动重试。启动时把运行任务暂停、在途项目转为结果不确定;数据库恢复也不能触发未审核的自动重发。SQLite 与 Telegram 无法原子提交,因此不承诺 exactly-once。

恢复结果独立于普通 dump_entries:不覆盖旧索引,不自动切换配置,也不自动发布为普通链接复用缓存。恢复只覆盖系统已登记历史,不是源频道全量扫描,更不是数据库内容备份。

3. 关键技术决策 ​

3.1 Bot API 库:go-telegram/bot ​

候选结论
go-telegram/bot(采用)活跃维护,跟进 Bot API 10.3;上传路径用 io.Pipe() + multipart.NewWriter 构造请求体(chunked 传输),models.InputFileUpload{Filename, Data io.Reader} 接受任意 Reader,MTProto 下载流可直接灌进 Bot API 上传,全程不落盘不驻留内存
telegram-bot-api v5API 形态陈旧,文件上传先读入 bytes.Buffer
telebot v3版本跟进滞后

这是实现 "优先 Streaming"媒体策略的决定性条件:gotd downloader → io.Pipe → multipart body 形成真正的背压串联;临时文件路径(fileGate 同样是顺序 Reader)复用同一参数。

3.2 MTProto:gotd/td + gotd/contrib(仅 floodwait 中间件),两个客户端 ​

进程内并存两个 gotd 客户端(internal/mtproto/client.go 用户号 + bot.go Bot 身份),分工:

客户端会话文件登录方式职责
用户账号data/session.json扫码 / 手机号+验证码(人工一次)读源频道、取消息、下载、file reference 过期刷新
Bot 身份data/bot-session.jsonAuth().Bot(ctx, BOT_TOKEN)(非交互,自动)大文件直传(§3.8)
  • 两个客户端都以 floodwait.NewSimpleWaiter().WithMaxRetries(5) 包装 invoker:自动对 *tg.ErrorFloodWait(及 FLOOD_PREMIUM_WAIT)限幅重试(SimpleWaiter 透传零开销、遇限流才内联等待,选型见 client.go 注释)。
  • 两个客户端都 NoUpdates: true:入站更新一律走 Bot API 长轮询,MTProto 侧只按需调用。
  • 同一 BOT_TOKEN 同时维持 Bot API 长轮询与 MTProto 会话——等价于 Bot 的"多设备登录",互不冲突。
  • 传输连接池 + DC 重定向:两个会话的 api 都经 client.Pool(*_CONNECTIONS)(DOWNLOAD_CONNECTIONS / UPLOAD_CONNECTIONS,默认 4、1–16)+ redirectInvoker 装配,替换直连主连接——N 个并发分片线程默认全部复用单条 TCP 连接(单连接吞吐典型 15–30MB/s,受单 TCP 窗口与单连接串行加解密限制),池让分片各走独立连接(并行 TCP 窗口 + 每连接独立 AES-IGE)。池惰性开连、空闲约 1 条、共享主会话 auth key;裸 pool 不可直接使用:它不会执行 gotd 主连接 invokeDirect 内建的 *_MIGRATE 重定向,文件位于非主 DC 时首片会以 303 FILE_MIGRATE_X 失败(真机 2026-09-07:1.4GB 视频在 DC5)。redirectInvoker 捕获 FILE/STATS_MIGRATE,经 client.DC(ctx, X, connections) 自动迁移授权并缓存目标 DC 池后重发;其他会话级 MIGRATE 回退主连接处理。floodwait 包在 redirectInvoker 最外层(tg.NewClient(waiter.Handle(redir))),FLOOD_WAIT 睡眠不占任何池连接;设 1 即回退单连接现状。
  • Bot 会话 CompressThreshold: -1 关闭出站 gzip:gotd 对 >1KB 出站 payload 无条件压缩(压不小也照发),512KB 上传分片是不可压缩媒体,每 GB 白耗约 10–20s CPU;下载响应是否 gzip 由服务端决定,不受影响。用户会话保持默认。

3.3 AccessHash:自研轻量缓存(头号难点) ​

私有频道链接 t.me/c/<internal_id>/<msg_id> 只携带裸 ChannelID,而构造 tg.InputChannel 必须有 AccessHash——它只能从该用户账号"见过"的 peer 信息中获得。

方案结论
自研 data/peers.json 缓存(采用)只需 bareChannelID → accessHash 一种映射,约 80 行,完全可控、可单测
gotd telegram/peers 包官方标注 experimental / WIP,排除主路径
gotd/contrib bbolt PeerStorage实现的是 contrib 自有 storage.PeerStorage 接口,与 peers.Storage 方法集不匹配,接线有坑

解析流程(internal/mtproto/resolve.go):

前提:用户账号必须是目标频道成员(或频道可公开访问)。缓存持久化避免每次重启全量遍历。

账号不是成员时的补救通道(internal/joinmgr + internal/mtproto/membership.go):

  • Bot 命令 /join <t.me/+邀请链接>:经 messages.importChatInvite 让读取账号(非 Bot)加入频道;号主提交即时生效,普通用户默认落 join_requests 表待号主在管理端审批(同意时延时执行加入并 Bot 私聊通知结果)。准入边界与普通链接不同:/join 不经过普通链接的 enabled 用户状态准入链(不调用 access 校验、不扣额度),是否可用由 join 总开关(join_enabled,默认关)与审核/数量上限配置控制;而普通链接、/download、/bind 都要求 enabled 用户。
  • 加入后按配置执行 account.updateNotifySettings(静音)与 folders.editPeerFolders(归档到 folder 1)——归档不影响 WalkDialogs 收割(本来就遍历 folder 0/1)。
  • 外部拉入(被邀请)的频道同样按配置归档:用户号会话轻量消费 update(ChannelUpdateBridge,只提取批次携带的频道对象,不建 updates 状态管理),经 peer 缓存过滤出的"新见"频道秒级补静音/归档;已加入频道页刷新、/join 提交(已是成员分支)与 30 分钟周期对账兜底(覆盖离线窗口漏收的 update,重连不补差异)。归档调用幂等(已在归档夹直接成功)。「自动退出外部拉入」开启时退出优先,归档让位给 Enforce 的惰性退出。
  • 创建者保护:读取账号自己创建的频道、超级群组不执行自动静音/归档,无加入留痕或留痕为 external 时也跳过。实时更新、列表刷新、周期对账、/join 已是成员补处理与待批准加入对账均使用 Telegram 的创建者标记判断;邀请预检通过 InviteInfo.Creator 传递该标记。列表展示与加入留痕继续保留,已有通知和归档状态由账号自行管理。
  • 管理端「MTProto受邀管理」菜单(加入审批 + 已加入频道 + 受邀设置三页):审批记录表(服务端分页/筛选/单条与批量删除)+ 已加入频道实时列表(对话遍历、手动刷新加载)+ 单条/批量退出(channels.leaveChannel);/join 配置(总开关 join_enabled 默认关、自动退出、审核、静音/归档、数量上限)在「受邀设置」页维护,总开关关闭时 /join 直接拒绝。「自动退出外部拉入」(join_auto_leave_external,默认关)开启后,列表刷新与 /join 提交会惰性退出"非本系统加入"的频道(留痕来源 external 或无留痕;Telegram 无"拒绝被拉入"的服务端开关,只能事后拦截)。
  • 数据边界:join_requests.invite_hash 为审批延时执行所必需,展示层一律脱敏;joined_channels 只留痕 ID/标题/来源/时间,不存 access_hash(数据范围红线)。

3.4 媒体传输策略(统一"下载 → 上传",大文件经 Bot 号 MTProto 直传) ​

媒体发送统一走"下载 → 上传":worker 打开下载句柄后交 delivery.routerSender 按媒体大小路由(internal/queue/worker.go + internal/delivery/router.go,Bot 会话见 §3.8):

分卷拆分投递(split,internal/queue/split.go):超过单文件 MTProto 上传 上限(2000MB)的媒体不再失败——切为 N 个分段(⌈Size/1800MB⌉, 相册 10 成员上限 → 单条消息总量约 17.6GB,超出仍 FILE_TOO_LARGE),经相册 整组直传为同一条消息。两种切段形态:

  • 可播放视频分段(视频首选,双模式按 moov 位置判定):下载流头部 缓冲 64KB 解析 MP4 顶层 box 头(media.SniffMoovPosition,确定性预判 非试错;判定字节经 io.MultiReader 接回消费流)—— 头 moov → 单遍流式切段:下载流(有界窗口并行,保持 DOWNLOAD_THREADS)直接喂 ffmpeg stdin(-f mp4 -i pipe:0 -c copy -f segment -segment_format matroska -segment_time T,T 按字节占比 换算,与落盘路径切点公式同源),源文件全程不落盘、盘上只产生分段 (峰值磁盘 1×,TEMP_DIR_MAX_SIZE 5GB 默认下有效切段上限 ~5GB); 产出段数以关键帧实际切点为准(±1 偏差),逐段防御大小上限。 尾 moov / 非 MP4 / 无法判定 → 回退完整落盘:立即取消在途流式下载 (浪费带宽上限 ≈ 窗口 128MB),显式按 2× 预检 TEMP_DIR(装不下立即 TEMP_DIR_FULL、不重新下载),经 media.OpenSplitFile 重新完整落盘后 逐段 -ss/-t 流复制切段;切段完成立即删源(上传阶段盘上只剩分段)。 落盘路径:ffmpeg 流复制(-c copy 不转码,秒级、无损)切出 N 个真实 视频文件(输出容器显式 -f matroska,段名 .mkv;镜像精简 ffmpeg 已含 matroska 封装器,启动期探测缺失即告警), 以 video 形态上传(挂 DocumentAttributeVideo;mkv 不标 SupportsStreaming 且 MIME 如实 video/x-matroska——虚标流式会诱导服务端重生成预览,覆盖 已上传封面),每段 点开即播、无需下载合并;切段点按字节占比换算时间(平均码率近似),实际 边界对齐关键帧标志(-ss 输入快定位;open-GOP 流段首仍带参考缺失的 前导 B 帧,首帧未必干净),段长有 ±GOP 级偏差;段 大小 1800MB 留 200MB margin 防关键帧偏移使单段超 2000MB;逐段封面 = 首段源缩略图优先 → 段文件抽首个 I 帧,其余段段文件抽首个 I 帧 (media.ExtractSegmentCoverJPEG,按画面类型筛帧规避坏前缀;流式路径 段落定后同样逐段抽帧)。任一环失败(下载断/ffmpeg 死/ stdin EPIPE/段超限)清全部段、零字节已发、整组原子,不降级。
  • 字节分段 document(兜底):非视频 / 缺时长 / ffmpeg 不可用或切段 失败——纯字节切割为普通 document(不挂 video 属性,避免假播放器), 文件名 <原名>.part<i>of<N>,caption 只挂首段并附合并提示 (cat / copy /b);第 2 段起按"段起始字节 / 总大小 × 总时长"换算时间戳 对完整文件 ffmpeg -ss 定位抽帧。

切段能力前置校验、不降级(设计决策 2026-09-20):超限视频在下载开始前 校验切段条件(ensurePlayableSplit:ffmpeg 可用且含 matroska 封装器、源带 时长属性),不满足直接以 SPLIT_UNAVAILABLE 报错终止任务——不发起下载、 不降级字节分段;混合相册在打开任何成员前整组原子报错(图片不会先发出); 切段运行期失败(冷门编码等)同样原样报错。字节分段只用于非视频媒体 (压缩包等,那是唯一路径而非降级)。启动期探测 ffmpeg 的 muxer 列表 (media.CheckMatroskaMuxer),缺 matroska 即告警(镜像自带精简 ffmpeg 已含,构建期亦自检)。

相册原子化:混合相册(图片 + 超限视频)经 planAlbumSend 预检(纯元数据) 走拆分整组——图片与大视频的分段合成同一条相册 [图片, 段1, 段2] 整组 直传,任务级原子(任何成员失败整组失败、零字节发出);展开后超相册 10 成员 上限时回退逐条(非视频成员走字节分段)。拆分放弃"边下边传"交叠(相册整组 发送需全段落定):头 moov 走流式切段(源不落盘,峰值磁盘 1×);回退路径 先 WaitDownloaded 再切再传,磁盘峰值 ≈ 2× 文件大小(TEMP_DIR_MAX_SIZE 需覆盖,切段完成即删源——上传阶段回落 1×)。缓存频道干净副本与 投递同为"恰好组首一条合并 caption":worker 从实际展开条目以同一合并语义 生成 canonical clean caption(剥离频道脚注),副本只重写组首。 delivery_mode 记 split(仅成功时,失败回落 upload 由错误码记录原因)。

默认 MaxFileSize 为 2000MB(MTProto 上传硬上限:4000 part × 512KB); 默认 InMemoryLimit 为 512MB(单文件常驻内存上限);内存路径另受进程级 预算闸门(MEMORY_BUDGET,默认 1GB,管理端 memory_budget 即时生效) 约束——每个进入内存管道的文件按大小记账(相册成员同受约束), 预算不足的新文件自动降级临时文件路径(不排队、不失败), 常驻内存被额度封顶而不随并发任务数/相册成员数线性放大; 预算在句柄 Cleanup 时归还,热调小额度不影响在途占用(软上限)。 配置本地 Bot API 服务器后 uploadCap 放宽到 MaxFileSize(全部上传走该服务器, 相册整组恒走 Bot API)。相册成员经 AlbumGroupable 预检(Bot API 承载 ∪ video ≤MaxFileSize 的 MTProto 整组承载);photo 超 photoLimit、document/audio 及超 MaxFileSize 的成员不可整组,相册逐条发送(逐条后超限成员各自走分卷拆分)。

统一返回 media.Handle{Reader, Cleanup};三条路径的 Cleanup 都是"放弃 信号"——关闭数据源唤醒阻塞读者、终止仍在下载的 goroutine(临时文件路径 同时取消下载 ctx),并删除临时文件。相册成员的下载句柄并发打开 (sendAlbumGroup 内 errgroup + 信号量,并发上限 2——与 DOWNLOAD_THREADS 解耦,避免 invoke 并发按成员数×线程数放大触发 FLOOD_WAIT);任一成员失败 整组失败,已打开句柄统一清理。下载分片统一 1MB(upload.getFile 协议上限, downloader.WithPartSize,gotd 默认 512KB 调大后请求次数减半);下载与 上传的并发分片分别经用户/Bot 会话的连接池各走独立 TCP 连接(§3.2)。

低内存机器(≤2.5GB)运维建议:把 MEMORY_BUDGET 降到 256MB(管理端 即时生效)——超预算的内存管道媒体自动落 fileGate 临时文件路径,该路径已做 下载落盘与上传读盘重叠(SSD 上性能损失小),峰值 RAM 随额度直接下降; 也可以把 IN_MEMORY_LIMIT 一并降到 256MB 收紧单文件上限。WORKER_COUNT 不再放大常驻内存(预算封顶),但仍有连接与 FLOOD_WAIT 侧的约束。

重复链接复用(转存频道直拷,internal/queue/reuse.go + internal/dumpcache): 任务成功投递后,同步向 bot 自有的缓存频道(DUMP_CHANNEL_ID 指定的私有 频道,bot 为管理员)写一份无脚注干净副本——给用户的投递 caption 织有 该用户绑定频道的脚注,副本必须剥离:单媒体 copyMessage 带 caption 覆盖 (干净 caption = 引用正文 + 原消息链接,不含频道脚注);单文本 SendMessage 干净渲染;多条逐条投递 copyMessages 整批复制后按条目清洗;相册投递本身 已是"恰好组首一条合并 caption",副本只重写组首为 canonical clean caption (全部成员正文与切段说明按源顺序合并,源条目重建会把多 caption 形态带回 缓存)。副本坐标落 dump_entries(迁移 v13;v16 起 format_version 标记副本布局格式,历史格式行不再命中复用)。同链接再次提交时,runJob 在取数之前先 tryReuseFromDump: 查最新副本条目 → copyMessages(缓存频道 → 目标聊天) 整条复制——服务端 复制媒体与 caption,无损、无转发头、不受媒体大小限制(2GB 与 10KB 同 路径)、相册保组、caption 从构造上无脚注泄露、副本不因原用户删消息失效, 跳过整个 fetch/下载/上传。绑定频道的用户收到复制品后经 fetch 一次重建 caption(1 次 RPC)编辑补上自己的脚注——普通相册合并全部成员正文后只编辑 首条(缓存副本是组首一条合并 caption,只用首条源正文会丢其余成员正文); 拆分展开副本(复制条数 > 源条目数)跳过覆盖,保留缓存 canonical caption (源 items 无法重建运行期切段说明)。复制失败(副本被删等)回落完整 链路,成功后重写副本自愈。额度照扣、终态记 delivery_mode=reuse;总开关 tg_reuse_enabled(settings,默认开,即时生效)与 DUMP_CHANNEL_ID 未 配置均回到完整"下载+上传"链路。历史上的用户聊天坐标复用(v12 sent_chat_id/sent_message_ids_json 列 + 脚注候选规则)已被本方案取代: 列保留在 schema 仅供历史行读取。与历史上移除的"源频道引用直发"不同: 复用的是自己重传成功后的消息,不依赖源频道坐标。

3.5 Entity → HTML 转换(正确性风险最高) ​

MTProto 的 MessageEntity 偏移以 UTF-16 code unit 计(emoji 占 2 unit),Bot API HTML 同样按 UTF-16 语义解析。转换算法(internal/message/html.go):

  1. 逐 rune 扫描文本,构建(字节偏移, UTF-16 累计 unit)映射表;
  2. 实体 [Offset, Offset+Length) 换算为字节区间,越界实体丢弃并记 debug 日志;
  3. 生成事件序列(同位置先闭后开,保证嵌套正确),文本段过 html.EscapeString,href 属性转义引号;
  4. 标签映射:Bold→<b>、Italic→<i>、Underline→<u>、Strike→<s>、Code→<code>、Pre→<pre>(带 Language 时 <pre><code class="language-X">)、URL/TextUrl→<a href>、Blockquote→<blockquote>、Spoiler→<tg-spoiler>;Mention 保持原文(Bot 自动识别);不支持类型退化为纯文本;
  5. 长度限制:文本 >4096 / caption >1024 截断并追加"(原文过长已截断)"(MVP 已知限制)。

独立纯函数 + golden 表驱动测试(CJK、emoji、嵌套实体、TextUrl 引号)。

3.6 Album 聚合 ​

同一 GroupedID 的多条消息是一个 Album,不能按独立消息逐条发送。Fetch 发现 GroupedID != 0 时一次批量取 [ID-9, ID+9] 共 19 个 ID(channels.getMessages 支持批量),过滤相同 GroupedID 按升序返回。发送时逐成员构造语义 caption,路由层发送前统一归一化为"恰好组首一条合并 caption"(全部成员正文按源顺序合并进组首并保留实体;客户端对多成员 caption 的相册首渲染抑制组级展示位——真机 2026-09-20;不做发送后修补)。整组只接受 photo/video,且 AlbumMaxItems=10(超过 10 项暂不拆分,直接返回错误);路由按大小分流——全员在 Bot API 单成员上限内且整组总量不超请求体上限(官方服务器 50MB,sendMediaGroup 把整组字节装进同一 multipart 请求体)走 sendMediaGroup,含超限成员(video/document 且 ≤2000MB)或总量超限时走 Bot 号 MTProto 两阶段整组直传:每成员 uploader.Upload → messages.uploadMedia(注册到目标 peer,换取带新鲜 file_reference 的坐标)→ 汇总为 InputMediaPhoto/InputMediaDocument 引用 → messages.sendMultiMedia 一次整组发送(sendMultiMedia 只接受已注册引用,raw inputMediaUploaded* 会被 400 MEDIA_INVALID 拒绝——真机结论 2026-09-03);photo 超 photoLimit、document/audio 成员或超 2000MB 时整组降级逐条发送。

3.7 持久化:内嵌 SQLite(internal/store) ​

产品化阶段引入 SQLite 作为唯一业务数据库,支撑访问控制、请求记录、用量额度、审计、事件与管理端会话。

选型:modernc.org/sqlite(纯 Go 驱动,无 CGO,保住 make linux 交叉编译)+ 标准库 database/sql。连接级 PRAGMA 挂在 DSN 上(WAL、busy_timeout=5000、foreign_keys=ON、synchronous=NORMAL),连接数固定为 1——SQLite 单写者,容量目标(≤100 用户、约 5,000 请求/日,约 180 万行/年)远低于其上限,不需要外部数据库服务。

表清单(数据库文件 DATA_DIR/spore.db,迁移内嵌于 internal/store/migrate.go,以 PRAGMA user_version 版本化、只增不改):当前 schema(v29)共 22 张业务表(users、requests、usage_daily、audit_log、events、settings、web_sessions、channel_bindings、join_requests、joined_channels、system_metric_samples、cloud_uploads、dump_entries、watch_sources、watch_events、watch_invite_requests、sent_messages、error_logs、recovery_jobs、recovery_items、dump_migrate_runs、dump_migrate_items)。每张表的字段、索引、外键与生命周期,以及 settings 的逻辑键、API 与持久化映射,以 数据库设计参考为唯一权威来源,此处不重复维护。

数据红线:消息正文、caption、媒体本体与明文凭据(Token/Session/手机号)不入库;通知通道与 GitHub OAuth 的可轮换外部凭据以 AES-256-GCM 密文存于 settings,Web 访问密钥只存 SHA-256 哈希;云盘凭据在 data/cloud-drive.json 文件中,不进数据库。data/session.json、data/peers.json、data/tmp/ 维持文件管理方式,不随数据库备份导出。时间字段统一为 Unix 毫秒时间戳。

与执行链路的关系:任务执行仍是内存队列(channel + worker + 退出 drain);requests 行是状态事实来源,worker 在阶段边界更新。数据库不在媒体传输热路径上。

3.8 Bot 身份 MTProto 会话:大文件直传 ​

官方 Bot API 服务器的上传硬上限是 50MB;超过该上限的媒体经 Bot 身份 MTProto 会话直接上传发送(internal/mtproto/bot.go + botsend.go)。历史上该会话曾 用于"媒体坐标引用直发 + 私聊接力"(09-02 任务),因坐标按账号签发、链路复杂 且与"下载 + 上传"双轨维护成本高而移除,改为承载大文件上传:

关键设计:

  • 生命周期:BotClient.Run 指数退避自动重启(5s 起、上限 5min、稳定运行 1min 后重置)——Bot 登录非交互,无需像用户号那样"离线等 Web 扫码"。就绪态在锁内换 *tg.Client 指针,所有发送先经 Available() 守门(gotd 连接随 client.Run 回调存活,回调内 <-ctx.Done() 维持连接);会话只发不收(NoUpdates),入站更新仍走 Bot API 长轮询。
  • 路由契约:delivery.LargeFileSender 接口定义在 delivery(签名仅用 message 类型),mtproto.BotClient 隐式实现,cmd/bot 装配——两个包互不 import;"reader 必须非 nil"防御在 router 层执行。
  • 数据源:>50MB 的媒体来自内存重排序缓冲(≤ InMemoryLimit,边下边发) 或经就绪水位门控的临时文件(超过 InMemoryLimit,边下边发)——两者都支持 顺序阻塞读,bigLoop 单读多发不要求 reader 可重放。
  • caption 双语义(message.Caption):Bot API 上传路径 RenderHTML() 渲染 HTML;MTProto 直传路径 Limited() 按 UTF-16 预算截断后透传源消息原始实体——无"实体→HTML→实体"二次转换失真。两条路径同源于 Item.Text/Entities。
  • 错误处理:FLOOD_WAIT 由 SimpleWaiter 先内联等待,仍限流则按 TELEGRAM_RATE_LIMIT 失败;其余 tgerr 归 BOT_SEND_FAILED,原始 tgerr 经 AppError.Unwrap 链可判定。

4. 内部模型 ​

go
// tmeurl:链接解析结果(links.ts 移植)
type SourceRef struct {
    Kind      PeerKind // PeerUsername | PeerChannelID
    Username  string   // Kind=PeerUsername,不带 @ 前缀
    ChannelID int64    // Kind=PeerChannelID,存裸正 ID
    MessageID int
}

// message:标准化后的消息条目
// Telegram 中文本正文与媒体 caption 为同一字段(tg.Message.Message),Item 只存一份 Text
type Item struct {
    ID        int
    GroupedID int64                   // 0 表示非 Album
    Text      string                  // 正文或 caption
    Entities  []tg.MessageEntityClass
    Media     *Media                  // nil 表示纯文本
}
const AlbumMaxItems = 10 // Telegram 相册单组上限;取数窗口/整组发送/降级判断共用

// message:媒体描述(下载与上传所需的全部信息)
type Media struct {
    Kind      ItemKind
    Location  tg.InputFileLocationClass // 媒体坐标唯一来源:photo/document 的 ID/AccessHash/FileReference
    FileName  string                    // DocumentAttributeFilename / 缺省 "photo.jpg" 等
    Size      int64                     // FILE_TOO_LARGE 预检查与上传通道路由(Bot API / 大文件直传)
    Video     *VideoMeta                // Width/Height/Duration/SupportsStreaming
    Audio     *AudioMeta                // Title/Performer/Duration/Voice
}

// message:媒体 caption 的结构化描述(文本 + 原始 MTProto 实体,UTF-16 偏移)
// Bot API 上传路径经 RenderHTML 渲染 HTML;MTProto 大文件直传路径经 Limited 截断后透传实体
type Caption struct {
    Text     string
    Entities []tg.MessageEntityClass
}

// media:下载句柄(文件名由发送侧取 message.Media.FileName,不在此重复)
type Handle struct {
    Reader  io.Reader
    Cleanup func() // 关闭数据源唤醒读者、终止在途下载,并删除临时文件
}

// queue:任务
type Job struct {
    ID          string        // 时间戳+自增字符串
    ChatID      int64         // 目标私聊
    UserID      int64
    Ref         tmeurl.SourceRef
    StatusMsgID int           // "正在获取消息..." 消息 ID,完成后删除
}

worker 主流程(internal/queue/worker.go):

5. 错误模型 ​

go
type AppError struct {
    Code    Code   // 机器可读错误码
    Message string // 内部描述
    Cause   error  // 原始错误(Unwrap)
}
func UserText(code Code) string // 面向用户的中文提示
func From(err error) *AppError  // 把 gotd/Bot API 错误分类为 AppError
错误码触发条件用户提示(中文)
INVALID_URLtmeurl.Parse 失败无法识别有效的 t.me 消息链接,请检查后重试。
MESSAGE_NOT_FOUNDtg.ErrMessageIdInvalid、消息不存在找不到这条消息,可能已删除或链接无效。
CHANNEL_NOT_ACCESSIBLEtg.ErrChannelPrivate、ErrChatAdminRequired、AccessHash 拿不到无法访问该频道:系统的读取账号(负责读取源频道内容的 Telegram 账号,不是机器人)未加入该频道。可发送 /join 频道邀请链接让它加入(详见 apperr.UserText)。
SERVICE_MESSAGE*tg.MessageService 或转换后无可提取内容这是一条服务消息,没有可提取的内容。
MEDIA_UNSUPPORTED贴纸、webpage 等暂不支持类型暂不支持这种消息类型。
FILE_TOO_LARGESize > MaxFileSize 且不可拆分(未启用拆分或 > MaxSplitTotalSize≈17.6GB)文件超过单条消息大小上限(约 17.6GB),暂无法发送。
SPLIT_UNAVAILABLE超限视频无法切段(ffmpeg 缺失/缺少 matroska 封装器/源缺时长属性),下载开始前前置校验超大视频可播放切段暂不可用(服务器 ffmpeg 环境不满足),请联系管理员。
MEDIA_DOWNLOAD_FAILED下载流/临时文件失败(非网络、非引用类失败的兜底)媒体下载失败,请稍后重试。
NETWORK_ERROR连接失败/超时/连接重置等传输层故障(取数、下载、发送共用;ctx 取消不在此列,由 worker 改判 INTERRUPTED)网络连接失败或超时,请稍后重试。
TELEGRAM_SERVER_ERRORTelegram RPC 5xx(INTERNAL_SERVER_ERROR、TIMEOUT 等)Telegram 服务暂时故障,请稍后重试。
FILE_REFERENCE_INVALIDfile reference 过期或彻底失效(RefreshMedia 刷新重试后仍不可得)源消息的媒体引用已失效且无法刷新,内容可能已被删除或更换,请确认后重试。
TELEGRAM_RATE_LIMIT*tg.ErrorFloodWait、SLOWMODE_WAIT_X(取数/发送/下载路径共用)请求过于频繁,请稍后重试。
PEER_FLOODTelegram 账号级临时限制(PEER_FLOOD/INVITE_PEER_FLOOD,持续数小时、无等待秒数;发送与加入频道路径)Telegram 对相关账号施加了临时限制(PEER_FLOOD),通常持续数小时,请稍后再试。
SEND_TARGET_INVALIDBot API 目标类失败(chat not found、bot 被拉黑/被踢出、权限不足、群升级迁移 chat、目标用户注销;MTProto 的 CHAT_WRITE_FORBIDDEN/USER_IS_BLOCKED 等——重试无效)消息发送目标不可用:机器人可能已离开你的绑定频道或缺少发言权限,请重新绑定频道或联系管理员。
BOT_SEND_FAILEDBot API / MTProto 其他发送错误(兜底)发送失败,请稍后重试。
LARGE_CHANNEL_UNAVAILABLE超过 Bot API 上限的媒体遇到大文件直传通道(Bot 会话)未就绪大文件发送通道暂不可用,请稍后重试。
INTERNAL_ERROR未分类异常处理失败,请稍后重试。
USER_NOT_AUTHORIZED用户不在白名单(access 六步链第 1 步)此机器人仅限白名单用户使用,请先发送 /start 申请。
USER_PENDING申请待审批你的申请正在等待管理员审批,通过后即可使用。
USER_DISABLED用户被禁用/归档,或重试其请求账号已停用,如有疑问请联系管理员。
DUPLICATE_LINK去重窗口内重复提交同链接该链接刚刚已处理,无需重复提交。
RATE_LIMITED提交间隔未到提交过于频繁,请稍后再试。
QUOTA_EXCEEDED当日额度耗尽今日额度已用完,额度每天自动重置。
CONCURRENT_LIMIT未完成任务数超限你还有未完成的任务,请等待完成后再提交。
QUEUE_FULL内存队列饱和当前任务较多,请稍后再试。
INTERRUPTED进程退出/重启中断的未完成任务任务因服务重启被中断,请稍后重新发送链接。
RETRY_EXHAUSTED受控重试超上限(累计含首次,上限为动态配置 max_request_attempts)该请求已达到最大尝试次数,无法再次重试。
STORE_UNAVAILABLE / STORE_MIGRATION_FAILED / STORE_CONSTRAINTSQLite 不可用 / 迁移失败 / 约束冲突(含停用 owner、重复添加等管理操作拒绝)存储类中文提示(见 apperr.UserText)。
WEB_AUTH_FAILED / WEB_LOGIN_LOCKED / WEB_CSRF_INVALID / OAUTH_STATE_INVALID / OAUTH_EXCHANGE_FAILED管理端登录与 CSRF/OAuth 边界(internal/web)管理端页面中文提示(见 apperr.UserText)。

用户看到 UserText(任务失败提示附来源消息链接),原始异常只进日志(对齐旧 errors.ts 的边界设计)。

失败根因持久化(v23):requests.error_detail 存放截断后的原始错误串(AppError.Cause 错误链,300 字符上限,worker 收尾写入、重试时随 error_code 一并清空),管理端请求详情页以"根因"行展示——管理员无需翻远程日志即可定位 Telegram 原始错误(如 FLOOD_WAIT_X 秒数、PEER_FLOOD)。连续失败告警的 detail 同时附带来源链接与错误码。

置顶失败细分(v20 auto-pin 配套):PinTarget.ErrCode 记录副本发送/置顶失败的分类码(SEND_TARGET_INVALID/MESSAGE_NOT_FOUND/TELEGRAM_RATE_LIMIT 等),完工确认文案与 /pin 事后补置顶回复按码给出具体处置指引(queue.PinFailureHint),不再统一提示"请检查机器人的置顶权限"。

绑定/监听校验(GetChat/GetChatMember 失败)经 binding.ClassifyVerifyError 区分:网络故障/限流透传真实错误码(提示稍后重试),其余才归 CHANNEL_NOT_POSTABLE/CHANNEL_NOT_PINNABLE(提示把机器人设为管理员)——避免网络抖动误导读权限。

6. 配置参考 ​

配置分两层:环境变量(.env,进程启动时读取,校验失败直接退出)与数据库运行设置(管理端"运行设置/频道设置/受邀设置"页写入 settings 表,部分项覆盖环境默认值,即时或重启生效)。

加载顺序:godotenv.Load()(.env,可选)→ config.Load(os.Getenv) → 校验失败直接退出。

环境变量按用途分组概览(默认值、校验规则、优先级与生效方式的逐项完整说明以配置参考为唯一权威来源,此处不重复维护):

分组变量
Telegram 凭据(必填)BOT_TOKEN、TG_API_ID、TG_API_HASH;TG_PHONE/LOGIN_MODE 控制登录方式
处理与媒体WORKER_COUNT、MAX_LINKS_PER_MESSAGE、MAX_FILE_SIZE、STREAM_LIMIT、IN_MEMORY_LIMIT、MEMORY_BUDGET、DOWNLOAD_THREADS、UPLOAD_THREADS、DOWNLOAD_CONNECTIONS、UPLOAD_CONNECTIONS、TEMP_DIR_MAX_SIZE
目录与运行DATA_DIR、TEMP_DIR、LOG_LEVEL、WEB_ADDR、BOT_API_URL、ALLOWED_USER_IDS(仅空库首启导入)、DUMP_CHANNEL_ID(缓存频道环境兜底)
Web 与安全GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、WEB_OAUTH_ENCRYPTION_KEY、WEB_TRUSTED_PROXY
事件与云盘NOTIFY_COOLDOWN_MIN、EVENT_BOT_FAIL_THRESHOLD、EVENT_TASK_FAIL_THRESHOLD、EVENT_DISK_LIMIT_GB、RCLONE_BIN

PhotoLimit 不是环境变量:官方 Bot API 模式下为 10MB,本地 Bot API 模式下随 MAX_FILE_SIZE 放宽;图片超过该限制时降级为 document。

config.Load(getenv func(string) string) 注入 getenv 而非直接读全局,测试可传入独立环境(移植旧 config.ts 的设计)。

7. 登录与安全 ​

7.1 MTProto 登录流程 ​

  • 扫码基于 gotd auth/qrlogin 包:独立轮询循环(不依赖 updates 加速信号;用户号会话虽已轻量消费 update 用于频道事件,扫码轮询仍自成循环);二维码由 mdp/qrterminal/v3 渲染。

Bot 身份会话登录(internal/mtproto/bot.go,09-02):与用户号会话完全不同—— Auth().Status 未授权即调 Auth().Bot(ctx, BOT_TOKEN) 换取会话(非交互、秒级), 写入 data/bot-session.json;异常退出由 Run 循环指数退避自动重启,没有任何人工环节。 会话文件丢失/换机后下次启动自动重登(凭 Token 即可),敏感度低于用户号 Session。

  • 验证码流程中 terminalAuth 实现 gotd auth.UserAuthenticator 接口(Phone/Password/Code/AcceptTermsOfService/SignUp)。
  • 仅当 client.Auth().Status() 为未授权时进入登录流程。
  • 首次启动顺序:先完成 MTProto 登录,再启动 Bot 轮询(Bot 不在线期间用户发的消息由 Telegram 排队补拉)。

7.2 安全边界 ​

  • data/(session.json、peers.json、tmp/)整体 gitignore;Session 等效于账号控制权,绝不提交、不进日志。
  • 日志脱敏:不记录 Bot Token、API Hash、手机号、Session 内容、消息正文或完整媒体 URL;只记 job_id/user_id/message_id/媒体类型/大小/错误码,以及受控的消息定位字段。
  • 权限默认 Deny All:白名单由数据库 users 表驱动(internal/access 六步校验链:状态/重复/频率/额度/并发/队列满),陌生用户经 /start 申请待管理员审批。
  • 临时文件:每个 Job 的下载产物在发送后(无论成败)Cleanup 删除。

8. 与旧 TS 实现的关系 ​

旧资产处置
src/telegram/links.ts 解析规则逐条移植为 internal/tmeurl
tests/links.test.ts全量移植为 parse_test.go,另补 RE2 回归用例
src/config.ts 校验语义移植(BOT_TOKEN 正则、正整数校验、getenv 注入)
src/util/errors.ts 提示语义移植进 apperr.UserText
src/middleware/authorize.ts演进为 internal/access 数据库白名单与额度控制(ALLOWED_USER_IDS 仅首启导入)
src/bot.ts / main.ts / grammY / copyMessage移除(无法实现受保护内容提取)

9. 测试与验证 ​

  • 单元测试:tmeurl(全量移植+回归)、apperr(分类)、config(校验)、message/html(golden 表驱动,重点)。
  • 每次变更的基础门禁:go build ./... && go vet ./... && go test ./...。
  • 手动验收应覆盖公开、私有和受保护频道,以及文本、媒体、Album、错误提示和可转发性。当前仓库没有真实 Telegram、媒体、相册或部署验收记录;通过编译和单元测试不等于真机验收完成。

10. 明确不做(MVP 边界) ​

自动监控指定频道并同步新消息、批量迁移、多账号池、付费、OCR、AI 识别、去水印、转码、压缩、Redis 队列。Dockerfile、Docker Compose 和可选本地 Bot API 服务器属于当前已提供的官方部署方式;公网 HTTPS 反向代理由部署环境提供,不等于 Redis 等外部服务依赖已实现。产品化阶段已引入内嵌 SQLite 业务存储(§3.7)、进程内资源监控 internal/monitor(RSS/临时目录/CPU/传输速率采样与 /api/v1/system-metrics,非 Telegram 频道监控)与管理端 Web 服务 internal/web(认证底座 + 管理页面:审批、用户、记录、频道、频道加入、事件、设置、审计、备份/CSV 导出与 MTProto 扫码重连,§11),仍不引入任何外部数据库服务;后续改进方向以实际需求为准。

11. 代码执行顺序与运行时流程 ​

本节按当前实现整理:入口 cmd/bot/main.go,各环节落在 internal/ 对应包。 §1.2 是"数据怎么流"的简化视图,本节是"代码按什么顺序跑"的完整视图。

11.1 进程启动顺序(cmd/bot/main.go) ​

11.2 MTProto 登录与就绪(internal/mtproto/client.go) ​

关键约束:gotd 的连接只活在 client.Run 的回调作用域内,因此 Bot 轮询与 worker 都必须在 ready 回调里启动,ready 返回即本轮收工;每轮重连都会重新执行一遍 ready (上一轮的 Bot/worker 已随上一轮 ctx 结束,无双跑重叠)。登录会话状态机(离线/登录中/ 就绪、扫码 URL、重连信号)在 internal/mtproto/session.go,并发安全。

Bot 会话生命周期(internal/mtproto/bot.go,与用户号 Run 平行的独立 goroutine):

11.3 ready 回调:组装核心链路(回到 main.go) ​

Whoami 闭包经 MTProto 的 users.getUsers 查询自身账号,供 /whoami 命令验证通道。

11.4 运行期并发模型 ​

协程生命周期职责
主协程启动后阻塞在 b.StartBot API getUpdates 长轮询
worker × WORKER_COUNT(默认 1;Web 运行设置 worker_count 可按数据库覆盖 env,1–16,重启生效)q.Run 内 WaitGroup 管理从队列 channel 出队执行 Process
Web 管理端协程web.Server.Run(ctx),MTProto 就绪前即启动,随 ctx 优雅关闭管理端 HTTP:登录/会话/管理页面(审批/用户/记录/频道/事件/设置/审计/备份与 CSV 导出)、MTProto 扫码重连、探针;故障只记日志
流式下载协程每个流式媒体一个,下载结束即退出向 io.Pipe 写数据,与 Bot API 上传背压串联
内存管道下载协程每个内存管道媒体一个(StreamLimit–InMemoryLimit 区间),下载结束即退出downloader.Parallel 多线程乱序写入 reorderBuffer,上传侧顺序阻塞读(边下边发);消费方放弃经 Cleanup 终止
相册并发打开协程每个相册成员一个(errgroup,并发上限 2),打开完成或整组失败即退出并发执行 openWithRefresh(含 file reference 刷新重试),句柄按索引落位
  • 队列是双通道优先级队列(internal/queue/queue.go:hi/lo 两个 chan Job,容量各按设置项 queue_capacity 配置,缺省 64,重启生效):Enqueue 非阻塞按任务形态路由——云盘任务(CloudDest 非空,即 /download 与配对提交的转存路)入低优先级通道,其余任务(TG 投递、/pin、缓存补写)入高优先级通道;各自通道满即拒(access 六步校验链末步按提交形态检查对应通道,直接回繁忙)。worker 出队严格先排空高优先级通道(锁内先 hi 后 lo + 入队信号唤醒),保证高优先级任务排队期间云盘任务不启动——避免云盘大任务占用临时目录预算(TEMP_DIR_MAX_SIZE 预检直接拒绝)导致 TG 任务连带失败。不做运行中任务抢占:云盘任务开始后跑完为止;WORKER_COUNT=1(默认)下任务永不并发,多 worker 部署时建议 ≥2 并接受云盘与 TG 并发的临时目录预检兜底。缓存补写任务不降级的理由:副本越早写入缓存频道,后续同链接 TG 请求越早命中零下载复用,降级反而推迟缓存变热。
  • botapi 的全部发送/删除都经 opt.Sender,统一享受 delivery 的错误分类与 429 重试。

11.5 一次用户请求的执行顺序 ​

阶段 A:接收与入队(internal/botapi/handler.go,轮询协程内) ​

阶段 B:worker 处理(internal/queue/worker.go,worker 协程内) ​

每个 Job 的超时分阶段管理(runJob):取数固定 15 分钟窗口;转换后按媒体总量 自适应发送窗口(15min + 每 1MB 加 1s,封顶 2h——2GB 级文件需要更长传输时间):

阶段 C:媒体下载(internal/media/handle.go) ​

阶段 D:投递(internal/delivery) ​

注意:媒体上传不做 429 重试——上传体是单次消费的流,中途失败无法安全重放, 以最终错误返回,由用户重发链接兜底。

11.6 错误与清理的统一路径 ​

  • gotd 与 Bot API 的错误分别在 classifyTgError / classifyBotError 处归类为 AppError。
  • worker 只消费 apperr.From(err).Code:用户看到 UserText 中文提示(失败提示附来源消息链接),原始错误只进日志。
  • 清理三处兜底:worker defer 清理临时文件句柄、handler 入队失败删占位提示、 main 启动时清空 TempDir。

11.7 退出顺序 ​

11.8 全景流程图 ​

请求链路(用户私聊发 t.me 链接 → 执行 → 成功后副作用)不再维护文字版全景, 统一以 §12 业务全景流程图为准——业务链路变更时只更新那一处,避免两份图各自漂移。

12. 业务全景流程图 ​

本图是业务链路的唯一权威流程图:覆盖用户提交 → 检查排队 → 处理任务 (缓存秒回 / 完整下载上传)→ 收尾(存缓存、转发绑定频道、置顶、云盘下载), 以及缓存从哪来(监听预热、迁移旧缓存、历史恢复)、监听内容转发到哪 (专属目标 + 全局镜像)与记录提醒。 §11 是"代码按什么顺序跑",本图是"一条链接经历什么";功能变更时两处同步更新(见 12.2)。

12.1 关键分支与开关速查 ​

图里说"看缓存""转发绑定频道"的地方,对应的管理端开关与精确行为如下:

图中环节开关 / 前提行为要点
重复链接直接拒绝dedup_window_min(1–1440 分钟)窗口内同用户同链接直接拒绝;窗口外进入缓存秒回判定
缓存秒回(先看缓存)tg_reuse_enabled + 已配置缓存频道命中即从缓存频道整条复制:秒回、不限文件大小、相册保组;收尾不重复存缓存,但照样转发绑定频道;复制失败回落完整流程,成功后补写缓存自愈
转发绑定频道channel_copy_enabled(默认开,即时生效)成功后把发给用户的内容复制到该用户绑定的每个频道并带频道署名;尽力而为,失败只记日志;缓存秒回的任务同样转发
置顶 /pin/pin <链接> 或用户 auto_pin 偏好转发到绑定频道后静音置顶组首,回复逐目标置顶结果;绕过投递总开关
存缓存(干净副本)tg_reuse_enabled(副本只服务复用)无署名干净副本写进缓存频道并记录索引;另有"仅缓存补写"任务形态(不打扰用户)用于复制失败后的自愈补写
云盘下载/download [目的地] 或配对提交慢车道,避免占用临时目录挤占普通任务;不发媒体、不写缓存、不转发绑定频道
缓存预热(/watch 监听频道)申请审批生效频道新消息自动存进缓存频道,之后任何人发该链接直接秒回;同一条消息再按源投递计划转发——申请人专属目标(forward_binding_channel_id,绑定失效即停、不泄漏到全局)+ 管理员逐源全局镜像(global_mirror_enabled,用户源默认关),按目标去重、目标是监听源即运行时过滤防循环;受保护内容回退走同一份计划
缓存迁移(迁移旧缓存)管理端触发(频道设置页发起)换缓存频道后把旧频道可读副本整批搬入并回写索引;后台执行、断点续跑;v29 起运行与逐条明细持久化(dump_migrate_runs/items,保留 20 次),支持暂停/继续/取消(端点即写 DB 状态、执行循环批间感知),管理端「缓存迁移」页可看运行历史、进度与逐条明细;重启把遗留活跃运行收敛为 interrupted,可重新发起幂等续跑
历史恢复管理端发起优先从缓存复制到指定目标,缓存不可读才重新提取;结果独立保存、不回写普通缓存,部分失败标 uncertain 不自动重试

12.2 维护约定(功能变更必读) ​

凡改动本图覆盖的任一环节——提交与准入、队列优先级、取数/下载/发送路由、 成功后副作用(缓存写回 / 绑定频道投递 / 置顶 / 云盘)、监听预热、缓存迁移、 历史恢复、事件告警——必须在同一提交批次更新本图(含分支条件与开关名称), 并同步检查 §11 对应小节。该约定已登记到 .trellis/spec/guides/docs-sync.md 的「改动 → 文档映射表」,提交前检查会执行。

改图时对照 12.1 速查表逐行核对:图里的每个分支判定都应有对应的开关或前提, 表里的每行都应能在图中找到对应环节;对不上的就是图或代码有一方过时了。

本图为 mermaid 代码块:文档站经 vitepress-plugin-mermaid 渲染(跟随站点深浅色), GitHub 原生渲染。mermaid 锁定 v10(docs/package.json devDependencies)——插件的 依赖预打包清单按 v10 整理,升级到 v11 会在 dev 模式出现 CJS 依赖(fastdom 等) 裸文件直出导致页面白屏;升级前先确认插件版本声明支持目标 mermaid 大版本。