K-Vault 2GB大文件传输揭秘:自部署Bot API加Webhook回链的原理与配置
K-Vault 2GB大文件传输揭秘:自部署Bot API加Webhook回链的原理与配置
K-Vault 是一款基于 Cloudflare Serverless 的免费聚合云盘,以 Telegram 为核心存储后端,同时兼容 R2、S3、Discord、HuggingFace 等多种存储。它的最大亮点是:通过自部署 Bot API + Webhook 回链,把 Telegram 文件直接变成公网直链,单文件常见可传到 2GB,全程零存储成本。本文带你看懂这套 2GB 大文件传输背后的原理,并给出完整的配置步骤与排错清单。
为什么官方 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:
- 投喂:把 Bot 拉进群或频道,用户用 Telegram 客户端直接把文件发给群/频道(这一步不受网页上传的大小限制);
- 接收:Telegram 把
message/channel_post类型的 update POST 到https://你的域名/api/telegram/webhook,若配置了TG_WEBHOOK_SECRET,接口会先校验请求头X-Telegram-Bot-Api-Secret-Token,防止伪造推送; - 回链:接口解析出文件的
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 等存储类型筛选、搜索和管理:
配置指南:环境变量一键设置
以下变量在 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——代价是文件不再出现在后台列表,标签/黑白名单等功能也会失效,按需取舍。
常见问题排查清单
setWebhook返回ok:true但 Bot 不回链:ok:true只代表 Telegram 接受了地址。用getWebhookInfo确认 Telegram 正在向你的域名投递更新,并检查 Pages Functions 日志中 Webhook 响应的directLink、reply.ok、reply.reason字段;reply.ok=false:确认 Bot 在频道中是管理员(或群里有发言权限);确认TG_UPLOAD_NOTIFY没有被设为false;secret_token与TG_WEBHOOK_SECRET必须完全一致;- 群聊里 Bot 收不到普通消息:这是 Telegram 的隐私模式所致,去 BotFather 关闭 privacy mode,或让用户显式 @Bot 发送;
- 下载卡住或变慢:自部署 Bot API 首次下载会缓存到本地磁盘,检查磁盘余量与 I/O;
- 网页上传 2GB 文件失败:这是预期行为,见下一节说明。
重要提醒:网页上传不等于 2GB 直传
2GB 大文件只走「Telegram 客户端 → 群/频道 → Webhook 回链」这一条路。网页端的上传链路受前端策略与 Cloudflare 请求体大小限制影响(分片上传单文件建议不超过 100MB),并且网页选择 Telegram 存储时,文件仍需经过 Bot API 转发,不等同于从网页直传 2GB。想要大文件体验,请直接用 Telegram 客户端投喂给频道,这是最省心的用法。
小结
K-Vault 的 2GB 大文件方案本质是三个环节的组合:自部署 Bot API 解除 50MB 上限 → Webhook 自动回链生成直链 → 签名直链降低存储消耗。配置上只需要 5 个环境变量加一条 setWebhook 命令,配合 README.md 中的 Cloudflare Pages 或 Docker 部署方式,几十分钟就能搭好一个免费、无限容量的私有数据金库。上手后不妨先去管理后台 /admin.html 看看你的第一张直链图片,再考虑是否把 R2、S3 等后端也接入进来。


