教程

零成本！用 CF 搭建基于 TG 的无限容量私有图床加网盘

前言

最近的一个项目叫 K-Vault，一款部署在 Cloudflare 上利用 Telegram 的无限存储空间私人存储与图床方案。类似的方案其实还挺多的，比如 Telegraph-Image、TGIMGHub 等等，推荐这个项目的原因一是比较新，作者更新积极，二是功能比较多，除了 TG 还集成很多其他方案。只要不传一些奇怪的东西，TG 就足够用了。

项目地址：https://github.com/katelya77/K-Vault

功能特性

  • 无限存储 – 不限数量的图片和文件上传
  • 完全免费 – 托管于 Cloudflare，免费额度内零成本
  • 免费域名 – 使用 *.pages.dev 二级域名，也支持自定义域名
  • 多存储后端 – 支持 Telegram、Cloudflare R2、S3 兼容存储、Discord、HuggingFace、WebDAV、GitHub
  • Telegram Webhook 回链 – 机器人在频道/群接收文件后自动回复直链
  • KV 写入优化 – Telegram 可启用签名直链，显著降低 KV 读写消耗
  • 内容审核 – 可选的图片审核 API，自动屏蔽不良内容
  • 多格式支持 – 图片、视频、音频、文档、压缩包等
  • 在线预览 – 支持图片、视频、音频、文档（pdf、docx、txt）格式的预览
  • 分片上传 – 支持最大 100MB 文件（配合 R2/S3）
  • 访客上传 – 可选的访客上传功能，支持文件大小和每日次数限制
  • API Token 认证 – 支持 curl / ShareX / 脚本等程序化上传与调用
  • 多种视图 – 网格、列表、瀑布流多种管理界面
  • 存储分类 – 直观区分不同存储后端的文件
  • 双模部署 – 保留 Cloudflare Pages 部署，同时新增 Docker 自托管（docker compose up -d）
  • 动态存储配置管理 – 支持在管理端通过 API 对存储配置进行新增/编辑/删除/测试/设为默认
  • 可插拔设置存储（Docker） – 基础站点设置可使用 sqlite（默认）或 Redis 协议后端（Upstash / Redis / KVrocks）
  • 前端路径简化 – 以根路径页面为主流程（/、/admin.html、/webdav.html）
  • GitHub Actions 镜像构建 – 主分支/Tag 自动构建并推送 api + web 镜像

准备部署

1. 前置要求

  • Cloudflare 账户
  • Telegram 账户（如使用 Telegram 存储）
  • Docker + Docker Compose（可选，用于自托管部署）

2. 获取 Telegram 凭据

向 @BotFather 发送 /newbot，按提示创建机器人，获得 BOT_TOKEN

3. 创建频道并添加机器人

  1. 创建一个新的 Telegram 频道
  2. 将机器人添加为频道管理员

4. 获取 Chat ID

向 @VersaToolsBot 或 @GetTheirIDBot 发送消息获取频道 ID

部署到 Cloudflare

1. Fork 本仓库

2. 创建 Pages 项目

  1. 登录 Cloudflare Dashboard
  2. 进入 Workers 和 Pages → 创建应用程序 → Pages → 连接到 Git
  3. 选择 Fork 的仓库，点击部署

3. 配置环境变量

进入项目 设置 → 环境变量，添加必需变量：

| 变量名 | 说明 | 必需 |
|——–|——|——|
| TG_Bot_Token | Telegram Bot Token | ✅ |
| TG_Chat_ID | Telegram 频道 ID | ✅ |
| BASIC_USER | 管理后台用户名 | 可选 |
| BASIC_PASS | 管理后台密码 | 可选 |

重新部署 – 修改环境变量后需重新部署生效

配置 KV 存储（图片管理，必需）

启用图片管理功能需要配置 KV：

  1. 进入 Cloudflare Dashboard → Workers 和 Pages → KV
  2. 点击 创建命名空间，命名为 k-vault

如何使用

  1. 初次访问输入账户密码

Telegram 增强模式（自部署 Bot API + Webhook）

项目已支持将 Telegram API 基础地址切换为自部署 Bot API，并支持通过 Webhook 在群/频道接收文件后自动回复直链。官方 Bot API 会有单文件 20MB 限制，自部署的话是 20GB 的限制。

关键环境变量

| 变量名 | 说明 | 示例 |
|——–|——|——|
| CUSTOM_BOT_API_URL | 自部署 Bot API 地址（不填则默认 https://api.telegram.org） | http://127.0.0.1:8081 |
| PUBLIC_BASE_URL | Webhook 回链时使用的公网域名（建议填写） | https://img.example.com |
| TG_WEBHOOK_SECRET | Webhook 密钥，校验头 X-Telegram-Bot-Api-Secret-Token | your-secret |
| TELEGRAM_LINK_MODE | Telegram 链接模式，设为 signed 启用签名直链 | signed |
| MINIMIZE_KV_WRITES | 设为 true 时启用低 KV 写入策略（也会启用签名直链） | true |
| TELEGRAM_METADATA_MODE | Telegram 元数据写入策略：off 关闭后台索引写入，默认写轻量索引 | off |
| TG_UPLOAD_NOTIFY | 网页上传成功后，是否额外发送”直链+File ID”通知消息 | true |
| FILE_URL_SECRET | 签名直链密钥（不填则回退到 TG_Bot_Token） | random-long-secret |

Webhook 部署步骤

  1. 在 Telegram 中把 Bot 拉进目标频道/群并授予发言权限（频道建议管理员）。
  2. 在 Cloudflare Pages 中配置 TG_Bot_Token、PUBLIC_BASE_URL、TG_WEBHOOK_SECRET，然后重新部署。

测试： 新开页面打开以下连接，注意不要有空格

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=【你的url】/api/telegram/webhook&secret_token=【你的SECRET】

然后还可以根据官方文档，添加一些其他的环境变量，或添加其他存储桶。

使用限制

Cloudflare 免费额度：

  • 每日 100,000 次请求
  • KV 每日 1,000 次写入、100,000 次读取、1,000 次列出
  • 超出后需升级付费计划（$5/月起）
  • 建议 Telegram 场景开启签名直链或低 KV 写入模式以降低额度压力

Docker 自托管模式下，Node 运行时不受 Cloudflare 免费额度限制（受你自己的服务器和存储后端限制）

请求数再高的 CF 就无法满足了，可以在境外 VPS 用 docker 部署。有兴趣的可以自己尝试，本文就不在继续演示了。

阅读原文