Lazy loaded image
部署教程
K-Vault部署教程
Words 2971Read Time≈ 8 min
2026-2-27
2026-2-27
type
Post
status
Published
date
Feb 27, 2026
slug
kvault
summary
免费图片/文件托管解决方案，基于 Cloudflare Pages，支持多种存储后端
tags
cloudflare
github
category
部署教程
icon
password
网址
快速部署
前置要求
  • Cloudflare 账户
  • Telegram 账户（如使用 Telegram 存储）
第一步：获取 Telegram 凭据
  1. 获取 Bot Token
      • 按提示创建机器人，获得 BOT_TOKEN
  1. 创建频道并添加机器人
      • 创建一个新的 Telegram 频道
      • 将机器人添加为频道管理员
  1. 获取 Chat ID
第二步：部署到 Cloudflare
  1. Fork 本仓库
  1. 创建 Pages 项目
      • 进入 Workers 和 Pages → 创建应用程序 → Pages → 连接到 Git
      • 选择 Fork 的仓库，点击部署
  1. 配置环境变量
      • 进入项目 设置 → 环境变量
      • 添加必需变量：
变量名
说明
必需
TG_Bot_Token
Telegram Bot Token
✅
TG_Chat_ID
Telegram 频道 ID
✅
BASIC_USER
管理后台用户名
可选
BASIC_PASS
管理后台密码
可选
重新部署 - 修改环境变量后需重新部署生效
 
存储配置
Telegram 增强模式（自部署 Bot API + Webhook）
项目已支持将 Telegram API 基础地址切换为自部署 Bot API，并支持通过 Webhook 在群/频道接收文件后自动回复直链。
关键环境变量：
变量名
说明
示例
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 拉进目标频道/群并授予发言权限（频道建议管理员）。
  1. 在 Cloudflare Pages 中配置 TG_Bot_Token、PUBLIC_BASE_URL、TG_WEBHOOK_SECRET，然后重新部署。
  1. 调用 setWebhook 指向本项目接口：https://你的域名/api/telegram/webhook。
  1. 频道/群内发送图片或文件，Bot 会自动回复 /file/... 直链。
setWebhook 示例（官方 API）：
setWebhook 示例（自部署 Bot API）：
关于 2G 文件：
使用自部署 Bot API（CUSTOM_BOT_API_URL）并由 Telegram 客户端直接发到群/频道，再由 Webhook 回链，可利用 Bot API 大文件能力（常见可到 2GB）。
但网页上传链路仍受当前前端策略与 Cloudflare 请求体限制影响（见下方“使用限制”），不等同于前端直接上传 2GB。
注意： 自部署 Bot API 下载文件会先缓存到本地磁盘，请预留足够空间并关注 I/O。
Telegram 低 KV 写入模式（可选）
当你担心 Cloudflare KV 每日读写额度不够时，可以启用：
  • TELEGRAM_LINK_MODE=signed（仅 Telegram 文件使用签名直链）
  • 或 MINIMIZE_KV_WRITES=true（同时影响分片上传任务写入策略）
启用后，Telegram 文件默认仍会写入轻量 KV 索引（用于后台列表和管理操作），下载时通过签名参数直接解析 file_id，从而降低 KV 读写压力。
可选取舍： 若你希望 Telegram 文件完全不写入 KV，请额外设置 TELEGRAM_METADATA_MODE=off。此时文件不会出现在后台列表，也无法使用依赖 KV 元数据的标签/黑白名单/删除流程。
KV 存储（图片管理，必需）
启用图片管理功能需要配置 KV：
  1. 进入 Cloudflare Dashboard → Workers 和 Pages → KV
  1. 点击 创建命名空间，命名为 k-vault
  1. 进入 Pages 项目 → 设置 → 函数 → KV 命名空间绑定
  1. 添加绑定：变量名 img_url，选择创建的命名空间
  1. 重新部署项目
R2 存储（大文件支持，可选）
配置 R2 可支持最大 100MB 文件上传：
  1. 创建存储桶
      • Cloudflare Dashboard → R2 对象存储 → 创建存储桶
      • 命名为 k-vault-files
  1. 绑定到项目
      • Pages 项目 → 设置 → 函数 → R2 存储桶绑定
      • 变量名 R2_BUCKET，选择存储桶
  1. 启用 R2
      • 设置 → 环境变量 → 添加 USE_R2 = true
      • 重新部署
S3 兼容存储（可选）
支持任何 S3 兼容的对象存储服务，包括 AWS S3、MinIO、BackBlaze B2、阿里云 OSS 等。
环境变量：
变量名
说明
示例
S3_ENDPOINT
S3 服务端点 URL
https://s3.us-east-1.amazonaws.com
S3_REGION
区域
us-east-1
S3_ACCESS_KEY_ID
访问密钥 ID
AKIA...
S3_SECRET_ACCESS_KEY
秘密访问密钥
wJalr...
S3_BUCKET
存储桶名称
my-filebed
不同服务商的 Endpoint 示例：
服务商
Endpoint 格式
Region
AWS S3
https://s3.{region}.amazonaws.com
us-east-1 等
MinIO
https://minio.example.com:9000
us-east-1
BackBlaze B2
https://s3.{region}.backblazeb2.com
us-west-004 等
阿里云 OSS
https://oss-{region}.aliyuncs.com
cn-hangzhou 等
Cloudflare R2
https://{account_id}.r2.cloudflarestorage.com
auto
部署步骤：
  1. 在你的 S3 服务商创建存储桶
  1. 获取 Access Key ID 和 Secret Access Key
  1. 在 Cloudflare Pages 项目中添加上述环境变量
  1. 重新部署，前端将自动显示 S3 存储选项
Discord 存储（可选）
通过 Discord 频道存储文件，支持 Webhook 和 Bot 两种方式。
注意： Discord 附件 URL 会在约 24 小时后过期。本项目通过代理方式提供文件下载，每次请求时自动刷新 URL。当前版本会优先使用 Bot 查询消息，并在失败时自动回退到 Webhook 查询。若同时配置 Bot + Webhook，请确保 Bot 对 Webhook 所在频道具备读取权限。
环境变量：
变量名
说明
必需
DISCORD_WEBHOOK_URL
Discord Webhook URL（推荐用于上传）
二选一
DISCORD_BOT_TOKEN
Discord Bot Token（用于获取和删除文件）
推荐
DISCORD_CHANNEL_ID
Discord 频道 ID（Bot 模式上传时需要）
Bot 模式
Webhook 方式部署（推荐）：
  1. 在 Discord 服务器中，进入频道设置 → 集成 → Webhook
  1. 创建新的 Webhook，复制 Webhook URL
  1. 在 Cloudflare Pages 添加环境变量 DISCORD_WEBHOOK_URL
  1. （推荐）同时创建 Discord Bot 并添加 DISCORD_BOT_TOKEN，用于文件获取和删除
  1. 重新部署
Bot 方式部署：
  1. 前往 Discord Developer Portal 创建应用
  1. 在 Bot 标签页创建 Bot，获取 Token
  1. 在 OAuth2 → URL Generator 中，选择 bot scope，并给 Bot 授予 Administrator 权限
  1. 使用生成的 URL 邀请 Bot 到你的服务器
  1. 在 Cloudflare Pages 添加 DISCORD_BOT_TOKEN 和 DISCORD_CHANNEL_ID
  1. 重新部署
故障排查（File not found on Discord）：
  1. 确认 DISCORD_WEBHOOK_URL 指向的频道，Bot 也能访问（频道不一致会导致上传成功但直链失败）。
  1. 直接给 Bot 授予 Administrator 权限，避免频道权限遗漏导致读取失败。
  1. 修改环境变量后必须重新部署 Cloudflare Pages（仅保存变量不会即时生效）。
  1. 打开 /api/status 检查 Discord 状态是否显示为 bot、webhook 或 bot+webhook。
限制：
  • 无 Boost 服务器：25MB/文件
  • Level 2 Boost：50MB/文件
  • Level 3 Boost：100MB/文件
HuggingFace 存储（可选）
使用 HuggingFace Datasets API 存储文件。文件以 git commit 的形式保存在 Dataset 仓库中。
环境变量：
变量名
说明
示例
HF_TOKEN
HuggingFace 写入权限 Token
hf_xxxxxxxxxxxx
HF_REPO
Dataset 仓库 ID
username/my-filebed
部署步骤：
  1. 注册 HuggingFace 账户
  1. 创建新的 Dataset 仓库（Settings → New Dataset）
  1. 前往 Settings → Access Tokens 创建 Token（需要 Write 权限）
  1. 在 Cloudflare Pages 添加 HF_TOKEN 和 HF_REPO 环境变量
  1. 重新部署
限制：
  • 普通上传（base64）：约 35MB/文件
  • LFS 上传：最大 50GB/文件
  • 免费用户仓库总大小：约 50GB
访客上传功能
允许未登录用户上传文件，站长可自行配置是否开启及限制规则。
变量名
说明
默认值
GUEST_UPLOAD
启用访客上传
false
GUEST_MAX_FILE_SIZE
访客单文件最大大小（字节）
5242880（5MB）
GUEST_DAILY_LIMIT
访客每日上传次数限制（按 IP 计）
10
启用方式：
  1. 在环境变量中设置 GUEST_UPLOAD = true
  1. 按需调整 GUEST_MAX_FILE_SIZE 和 GUEST_DAILY_LIMIT
  1. 确保已配置 BASIC_USER 和 BASIC_PASS（否则无访客/管理员区分）
  1. 重新部署
功能说明：
  • 访客可在首页直接上传文件，无需登录
  • 访客有单文件大小限制和每日上传次数限制
  • 访客不能使用分片上传和高级存储选项（S3/Discord/HuggingFace）
  • 访客不能访问管理后台和图片浏览页
  • 限制基于访客 IP 地址，每日自动重置
高级配置
变量名
说明
默认值
ModerateContentApiKey
图片审核 API Key（从 moderatecontent.com 获取）
-
WhiteList_Mode
白名单模式，仅白名单图片可加载
false
USE_R2
启用 R2 存储
false
CUSTOM_BOT_API_URL
Telegram API 基础地址（支持自部署 Bot API）
https://api.telegram.org
PUBLIC_BASE_URL
Webhook 回链时使用的公开域名
当前请求域名
TG_WEBHOOK_SECRET
Telegram Webhook 密钥（也兼容 TELEGRAM_WEBHOOK_SECRET）
-
TELEGRAM_LINK_MODE
Telegram 链接模式（signed 为签名直链）
-
MINIMIZE_KV_WRITES
降低 KV 写入（也会启用签名直链）
false
TELEGRAM_METADATA_MODE
Telegram 元数据写入策略（off 关闭后台索引写入）
on
TG_UPLOAD_NOTIFY
网页上传成功后发送“直链+File ID”通知消息
true
FILE_URL_SECRET
签名直链密钥（也兼容 TG_FILE_URL_SECRET）
TG_Bot_Token
CHUNK_BACKEND
分片临时存储后端（auto/r2/kv）
auto
disable_telemetry
禁用遥测
-
页面说明
页面
路径
说明
首页/上传
/
批量上传、拖拽、粘贴上传
图片浏览
/gallery.html
图片网格浏览
管理后台
/admin.html
文件管理、黑白名单
文件预览
/preview.html
多格式文件预览
登录页
/login.html
后台登录
使用限制
Cloudflare 免费额度：
  • 每日 100,000 次请求
  • KV 每日 1,000 次写入、100,000 次读取、1,000 次列出
  • 超出后需升级付费计划（$5/月起）
  • 建议 Telegram 场景开启签名直链或低 KV 写入模式以降低额度压力
各存储后端文件大小限制：
存储后端
单文件最大大小
Telegram（网页直传）
小文件直传 20MB；分片流程当前上限 100MB
Telegram（自部署 Bot API + Telegram 客户端 + Webhook）
受 Bot API 与部署环境影响，常见可达 2GB
Cloudflare R2
100MB（分片上传）
S3 兼容存储
100MB（分片上传）
Discord（无 Boost）
25MB
Discord（Level 2+）
50-100MB
HuggingFace
35MB（普通）/ 50GB（LFS）
说明：/api/upload-from-url 当前仍按 20MB 限制处理 Telegram 上传。
所有环境变量参考
变量名
说明
必需
TG_Bot_Token
Telegram Bot Token
✅
TG_Chat_ID
Telegram 频道 ID
✅
CUSTOM_BOT_API_URL
自部署 Telegram Bot API 地址
可选
PUBLIC_BASE_URL
Webhook 回链域名
可选
TG_WEBHOOK_SECRET
Telegram Webhook 密钥
可选
TELEGRAM_WEBHOOK_SECRET
同上（兼容变量名）
可选
TELEGRAM_LINK_MODE
Telegram 链接模式（signed）
可选
MINIMIZE_KV_WRITES
降低 KV 写入并启用签名直链
可选
TELEGRAM_METADATA_MODE
Telegram 元数据写入策略（off 关闭后台索引写入）
可选
TG_UPLOAD_NOTIFY
网页上传成功后发送“直链+File ID”通知消息
可选
FILE_URL_SECRET
签名直链密钥
可选
TG_FILE_URL_SECRET
同上（兼容变量名）
可选
BASIC_USER
管理后台用户名
可选
BASIC_PASS
管理后台密码
可选
USE_R2
启用 R2 存储
可选
CHUNK_BACKEND
分片临时存储后端（auto/r2/kv）
可选
S3_ENDPOINT
S3 端点 URL
可选
S3_REGION
S3 区域
可选
S3_ACCESS_KEY_ID
S3 访问密钥
可选
S3_SECRET_ACCESS_KEY
S3 秘密密钥
可选
S3_BUCKET
S3 存储桶名
可选
DISCORD_WEBHOOK_URL
Discord Webhook URL
可选
DISCORD_BOT_TOKEN
Discord Bot Token
可选
DISCORD_CHANNEL_ID
Discord 频道 ID
可选
HF_TOKEN
HuggingFace Token
可选
HF_REPO
HuggingFace 仓库 ID
可选
GUEST_UPLOAD
启用访客上传
可选
GUEST_MAX_FILE_SIZE
访客文件大小限制（字节）
可选
GUEST_DAILY_LIMIT
访客每日上传次数
可选
ModerateContentApiKey
图片审核 API Key
可选
WhiteList_Mode
白名单模式
可选
disable_telemetry
禁用遥测
可选
 
上一篇
MiSub - 部署教程
下一篇
katelya77/K-Vault