K-Vault 2GB大文件传输揭秘:自部署Bot API加Webhook回链的原理与配置

原创2026-10-27 22:13:061,664 阅读

K-Vault 2GB大文件传输揭秘:自部署Bot API加Webhook回链的原理与配置

K-Vault 是一款基于 Cloudflare Serverless 的免费聚合云盘,以 Telegram 为核心存储后端,同时兼容 R2、S3、Discord、HuggingFace 等多种存储。它的最大亮点是:通过自部署 Bot API + Webhook 回链,把 Telegram 文件直接变成公网直链,单文件常见可传到 2GB,全程零存储成本。本文带你看懂这套 2GB 大文件传输背后的原理,并给出完整的配置步骤与排错清单。

K-Vault 上传首页:选择 Telegram 存储上传文件并返回直链

为什么官方 API 传不了 2GB?先看懂限制瓶颈

Telegram 官方 Bot API 对 Bot 收发文件有大小限制:Bot 上传文件上限 50MB,接收消息中的文件上限 20MB。想突破这个限制,业界通行做法是自部署一套 Bot API(即在你自己的服务器上运行与官方 API 兼容的服务),把 API 地址切换过去。

K-Vault 通过环境变量 CUSTOM_BOT_API_URL 实现了这个切换,不配置时默认指向官方 API。整个链路的关键设计是:

  • 文件本体始终留在 Telegram 服务器,K-Vault 只保存消息里的 file_id,因此不占用你的任何磁盘空间;
  • 文件到达群/频道后,Telegram 主动推送 update 到 K-Vault 的 Webhook 接口,接口提取 file_id 与元数据,自动生成 /file/... 直链并回复给消息;
  • 他人访问直链时,K-Vault 通过 Bot API 的 getFile 从 Telegram 拉取文件并代理下载——自部署 Bot API 的下载会先缓存在你服务器的本地磁盘,需要预留足够空间并关注 I/O(详见 README.md 中的说明)。

一句话总结:2GB 能力来自自部署 Bot API,免费托管来自 Webhook 回链,两者缺一不可。

原理拆解:Webhook 回链的三步闭环

整套流程由一个 HTTP 接口驱动,核心实现位于 functions/api/telegram/webhook.js:

  1. 投喂:把 Bot 拉进群或频道,用户用 Telegram 客户端直接把文件发给群/频道(这一步不受网页上传的大小限制);
  2. 接收:Telegram 把 message / channel_post 类型的 update POST 到 https://你的域名/api/telegram/webhook,若配置了 TG_WEBHOOK_SECRET,接口会先校验请求头 X-Telegram-Bot-Api-Secret-Token,防止伪造推送;
  3. 回链:接口解析出文件的 file_id、文件名、大小等信息,写入一条轻量 KV 索引(用于后台列表展示),随后调用 sendMessage 在原消息下回复一条包含直链、文件大小、File ID 的通知。

Telegram 相关的工具函数集中在 functions/utils/telegram.js,Docker 部署下的同名逻辑在 server/lib/utils/telegram-webhook.js,网页上传走的 Telegram 存储适配器见 server/lib/storage/adapters/telegram.js。

生成的直链会出现在管理后台的文件列表中,你可以按 TG、KV、R2、S3 等存储类型筛选、搜索和管理:

K-Vault 管理后台:按 Telegram 等存储类型筛选的 2GB 大文件与图片网格列表

配置指南:环境变量一键设置

以下变量在 Cloudflare Pages 的「设置 → 环境变量」或 Docker 的 .env 中配置(变量清单与官方说明见 README.md):

变量名 说明 示例
TG_Bot_Token Bot 的 Token(Docker 也兼容 TG_BOT_TOKEN 写法,见 server/lib/config.js) 123456:ABC-DEF...
TG_Chat_ID Bot 所在的频道/群 ID -1001234567890
CUSTOM_BOT_API_URL 自部署 Bot API 地址(2GB 能力来源) http://127.0.0.1:8081
PUBLIC_BASE_URL 回链时使用的公网域名,强烈建议填写 https://img.example.com
TG_WEBHOOK_SECRET Webhook 密钥,与 setWebhook 的 secret_token 保持一致 your-secret

配置完基础变量后重新部署,访问 /api/status 确认 telegram、kv 状态正常即可。

绑定 Webhook:setWebhook 一条命令搞定

把 Bot 加入目标频道/群并授予发言权限(频道建议设为管理员)后,执行 setWebhook 即可让 Telegram 开始向你的域名推送更新。

使用官方 API:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://img.example.com/api/telegram/webhook\",\"secret_token\":\"<YOUR_SECRET>\",\"allowed_updates\":[\"message\",\"channel_post\"]}"

使用自部署 Bot API 时,只需把域名替换为你的服务地址:

curl -X POST "http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://img.example.com/api/telegram/webhook\",\"secret_token\":\"<YOUR_SECRET>\",\"allowed_updates\":[\"message\",\"channel_post\"]}"

注意 allowed_updates 必须包含 channel_post,否则频道消息不会被推送。

进阶优化:签名直链模式,降低 KV 消耗

默认模式下,每次文件下载都需要查一次 KV。若你的文件量大,可以启用签名直链:K-Vault 用 HMAC-SHA256 把 file_id、文件名、大小等信息编码成一个带签名的 tgs_... 标识,下载时直接本地解析,无需读 KV。

  • 设置 TELEGRAM_LINK_MODE=signed,或 MINIMIZE_KV_WRITES=true 即可启用(两种判断逻辑见 functions/utils/telegram.js);
  • 建议配合 FILE_URL_SECRET 指定独立签名密钥,不填时回退到 TG_Bot_Token;
  • 若追求极致省配额,可再设 TELEGRAM_METADATA_MODE=off 让 Telegram 文件完全不写 KV——代价是文件不再出现在后台列表,标签/黑白名单等功能也会失效,按需取舍。

常见问题排查清单

  1. setWebhook 返回 ok:true 但 Bot 不回链:ok:true 只代表 Telegram 接受了地址。用 getWebhookInfo 确认 Telegram 正在向你的域名投递更新,并检查 Pages Functions 日志中 Webhook 响应的 directLink、reply.ok、reply.reason 字段;
  2. reply.ok=false:确认 Bot 在频道中是管理员(或群里有发言权限);确认 TG_UPLOAD_NOTIFY 没有被设为 false;secret_token 与 TG_WEBHOOK_SECRET 必须完全一致;
  3. 群聊里 Bot 收不到普通消息:这是 Telegram 的隐私模式所致,去 BotFather 关闭 privacy mode,或让用户显式 @Bot 发送;
  4. 下载卡住或变慢:自部署 Bot API 首次下载会缓存到本地磁盘,检查磁盘余量与 I/O;
  5. 网页上传 2GB 文件失败:这是预期行为,见下一节说明。

重要提醒:网页上传不等于 2GB 直传

2GB 大文件只走「Telegram 客户端 → 群/频道 → Webhook 回链」这一条路。网页端的上传链路受前端策略与 Cloudflare 请求体大小限制影响(分片上传单文件建议不超过 100MB),并且网页选择 Telegram 存储时,文件仍需经过 Bot API 转发,不等同于从网页直传 2GB。想要大文件体验,请直接用 Telegram 客户端投喂给频道,这是最省心的用法。

K-Vault 图片浏览页面:Webhook 生成的直链支持在线预览大图

小结

K-Vault 的 2GB 大文件方案本质是三个环节的组合:自部署 Bot API 解除 50MB 上限 → Webhook 自动回链生成直链 → 签名直链降低存储消耗。配置上只需要 5 个环境变量加一条 setWebhook 命令,配合 README.md 中的 Cloudflare Pages 或 Docker 部署方式,几十分钟就能搭好一个免费、无限容量的私有数据金库。上手后不妨先去管理后台 /admin.html 看看你的第一张直链图片,再考虑是否把 R2、S3 等后端也接入进来。

登录后查看全文
K-Vault