本文由 资源共享网 – ziyuan 发布，转载请注明出处，如有问题请联系我们！免费图片文件托管解决方案系统及源码

免费图片/文件托管解决方案，支持 Cloudflare Pages + Docker 双模部署，并兼容多种存储后端

功能特性

• 无限存储 - 不限数量的图片和文件上传

• 完全免费 - 托管于 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 镜像

快速部署

前置要求

• Cloudflare 账户

• Telegram 账户（如使用 Telegram 存储）

• Docker + Docker Compose（可选，用于自托管部署）

第一步：获取 Telegram 凭据

1. 获取 Bot Token

• 向 @BotFather 发送 /newbot

• 按提示创建机器人，获得 BOT_TOKEN

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

• 创建一个新的 Telegram 频道

• 将机器人添加为频道管理员

1. 获取 Chat ID

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

第二步：部署到 Cloudflare

1. Fork 本仓库

2. 创建 Pages 项目

• 登录 Cloudflare Dashboard

• 进入 Workers 和 Pages → 创建应用程序 → Pages → 连接到 Git

• 选择 Fork 的仓库，点击部署

1. 配置环境变量

• 进入项目 设置 → 环境变量

• 添加必需变量：

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

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

第三步：Docker 自托管部署（可选）

如果你希望在自己的 VPS/NAS 上运行（不依赖 Cloudflare Pages 运行时）：

1. 复制环境变量模板：

npm run docker:init-env

该命令会在 .env 不存在时自动创建，并仅在密钥为空或占位符时生成 CONFIG_ENCRYPTION_KEY 与 SESSION_SECRET，不会每次重置已有密钥。

2. 至少填写以下关键变量：

• CONFIG_ENCRYPTION_KEY

• SESSION_SECRET

• 一套默认存储配置（例如 TG_BOT_TOKEN + TG_CHAT_ID）

• 可选设置存储：

• 默认：SETTINGS_STORE=sqlite

• Redis 模式：SETTINGS_STORE=redis 且配置 SETTINGS_REDIS_URL

2. 启动服务：

npm run docker:up

如需启用本地 Redis（用于基础设置存储）：

docker compose --profile redis up -d --build

4. 访问地址：

• 上传首页：http://<host>:8080/

• 管理后台：http://<host>:8080/admin.html

• WebDAV 页面：http://<host>:8080/webdav.html

完整 Docker 说明请查看 README-DOCKER.md。

WebDAV 回归验证（Cloudflare Pages / Docker 通用）

部署完成后，建议至少执行一次 WebDAV 烟测，确认“配置测试 -> 上传 -> 下载 -> 删除”完整闭环。

示例：

BASE_URL=https://你的域名 \
BASIC_USER=admin BASIC_PASS=your_password \
SMOKE_STORAGE_TYPE=webdav \
SMOKE_STORAGE_CONFIG_JSON='{"baseUrl":"https://dav.example.com","username":"u","password":"p","rootPath":"uploads"}' \
node scripts/storage-regression.js

校验标准：

• /api/status 中 webdav.connected 必须为 true

• /api/storage/:id/test 必须返回 connected=true

• 回归脚本中的 WebDAV upload / download / delete 三步必须全部通过

如果是 Docker 部署，只需把 BASE_URL 换成你的自托管地址，例如 http://localhost:8080。

Docker 登录 API（curl 示例）

/api/auth/login 同时兼容两种请求体：

• {"username":"...","password":"..."}

• {"user":"...","pass":"..."}

curl -i -X POST "http://localhost:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

curl -i -X POST "http://localhost:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"user":"admin","pass":"your_password"}'

安全提示：请勿泄露或提交 .env 内 token/secret（如 TG_BOT_TOKEN、DISCORD_BOT_TOKEN、HF_TOKEN、SESSION_SECRET、CONFIG_ENCRYPTION_KEY）；若疑似泄露请立即轮换并重启服务。

存储配置

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 拉进目标频道/群并授予发言权限（频道建议管理员）。

2. 在 Cloudflare Pages 中配置 TG_Bot_Token、PUBLIC_BASE_URL、TG_WEBHOOK_SECRET，然后重新部署。

3. 调用 setWebhook 指向本项目接口：https://你的域名/api/telegram/webhook。

4. 频道/群内发送图片或文件，Bot 会自动回复 /file/... 直链。

setWebhook 示例（官方 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\"]}"

setWebhook 示例（自部署 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\"]}"

关于 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

2. 点击 创建命名空间，命名为 k-vault

3. 进入 Pages 项目 → 设置 → 函数 → KV 命名空间绑定

4. 添加绑定：变量名 img_url，选择创建的命名空间

5. 重新部署项目

前端 UI 设计配置（跨端同步）

支持在后台统一设置全站 UI 风格（首页、图库、后台、WebDAV、登录页）。

入口位置：

1. 打开管理后台：/admin.html

2. 点击工具栏中的 前端 UI 设计（滑杆图标）

3. 在弹窗中调整样式并点击 保存设置

可配置项：

• 背景图（全站 / 登录页单独）

• 卡片透明度与模糊强度（毛玻璃效果）

• 动态背景特效类型与强度（含移动端优化）

持久化机制：

• Cloudflare Pages：写入 KV 键 ui_config（通过 img_url 绑定访问）

• Docker 自托管：写入 data/ui_config.json

• 前端会在接口失败时降级到 localStorage（仅本机生效）

接口说明：

• GET /api/ui-config：读取配置（页面初始化自动调用）

• POST /api/ui-config：保存配置（需管理员登录态）

快速排查：

• GET /api/ui-config 返回 source: "default"：表示服务端尚未保存过配置，或写入失败

• Cloudflare 场景请确认：Pages 项目已绑定 KV（变量名必须是 img_url），且变更后已重新部署

• 若保存后跨端未生效，先强制刷新页面缓存（Ctrl+F5 / 无痕窗口），再查看 Functions 日志中的 /api/ui-config 请求记录

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 服务商创建存储桶

2. 获取 Access Key ID 和 Secret Access Key

3. 在 Cloudflare Pages 项目中添加上述环境变量

4. 重新部署，前端将自动显示 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

2. 创建新的 Webhook，复制 Webhook URL

3. 在 Cloudflare Pages 添加环境变量 DISCORD_WEBHOOK_URL

4. （推荐）同时创建 Discord Bot 并添加 DISCORD_BOT_TOKEN，用于文件获取和删除

5. 重新部署

Bot 方式部署：

1. 前往 Discord Developer Portal 创建应用

2. 在 Bot 标签页创建 Bot，获取 Token

3. 在 OAuth2 → URL Generator 中，选择 bot scope，并给 Bot 授予 Administrator 权限

4. 使用生成的 URL 邀请 Bot 到你的服务器

5. 在 Cloudflare Pages 添加 DISCORD_BOT_TOKEN 和 DISCORD_CHANNEL_ID

6. 重新部署

故障排查（File not found on Discord）：

1. 确认 DISCORD_WEBHOOK_URL 指向的频道，Bot 也能访问（频道不一致会导致上传成功但直链失败）。

2. 直接给 Bot 授予 Administrator 权限，避免频道权限遗漏导致读取失败。

3. 修改环境变量后必须重新部署 Cloudflare Pages（仅保存变量不会即时生效）。

4. 打开 /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 账户

2. 创建新的 Dataset 仓库（Settings → New Dataset）

3. 前往 Settings → Access Tokens 创建 Token（需要 Write 权限）

4. 在 Cloudflare Pages 添加 HF_TOKEN 和 HF_REPO 环境变量

5. 重新部署

限制：

• 普通上传（base64）：约 35MB/文件

• LFS 上传：最大 50GB/文件

• 免费用户仓库总大小：约 50GB

WebDAV 存储（可选）

适合对接 alist/openlist、NAS、群晖、坚果云等支持 WebDAV 的存储服务。
你可以把 WebDAV 作为统一挂载入口，后台继续按目录管理文件，已生成的 /file/... 直链不受目录调整影响。 其中 alist/openlist 建议直接填写其 WebDAV 挂载地址（例如 https://example.com/dav），不要填管理后台地址。

环境变量：

| 变量名 | 说明 | 示例 | | :--- | :--- | :--- | | WEBDAV_BASE_URL | WebDAV 基础地址（不带结尾 /） | https://dav.example.com/dav | | WEBDAV_USERNAME | WebDAV 用户名（Basic 认证） | alice | | WEBDAV_PASSWORD | WebDAV 密码（Basic 认证） | your-password | | WEBDAV_BEARER_TOKEN | Bearer Token（与用户名/密码二选一） | eyJhbGciOi... | | WEBDAV_TOKEN | Bearer Token 兼容变量名（可选） | eyJhbGciOi... | | WEBDAV_ROOT_PATH | 可选，WebDAV 根目录前缀 | k-vault/uploads |

部署步骤：

1. 在你的 WebDAV 服务端准备一个可写目录，并确认具备 PUT/GET/DELETE/MKCOL 权限。

2. 在 Cloudflare Pages 项目中添加上述 WEBDAV_* 变量（认证方式二选一：用户名+密码 或 Bearer Token）。

3. 重新部署后，访问 /api/status 检查 webdav.connected 与 webdav.enabled，或直接打开 /webdav.html 测试上传。

4. Docker 自托管场景下，在 .env 填写相同变量后重启容器（npm run docker:up 或 docker compose up -d --build）。

常见问题：

• Not configured：通常是 WEBDAV_BASE_URL 为空，或认证变量未正确填写。

• 401/403：认证失败，请检查账号密码或 Token。

• 上传失败且提示 MKCOL：说明服务端不允许建目录或路径权限不足，请调整 WebDAV 权限。

GitHub 存储（可选）

支持将文件存到 GitHub 仓库，提供两种模式：

• releases：更适合二进制文件，默认模式

• contents：更适合小文件/文本文件（单文件建议不超过 20MB）

环境变量：

| 变量名 | 说明 | 示例 | | :--- | :--- | :--- | | GITHUB_TOKEN | GitHub Token（需要仓库写入权限） | ghp_xxxxxxxxxxxx | | GITHUB_REPO | 目标仓库（owner/repo） | yourname/kvault-files | | GITHUB_MODE | 存储模式：releases / contents | releases | | GITHUB_PREFIX | 可选，仓库内路径前缀 | uploads | | GITHUB_RELEASE_TAG | 可选，releases 模式固定标签 | k-vault-storage | | GITHUB_BRANCH | 可选，contents 模式目标分支 | main | | GITHUB_API_BASE | 可选，GitHub API 基址（企业版时可改） | https://api.github.com |

部署步骤：

1. 准备一个 GitHub 仓库（建议专门用于存储文件）。

2. 在 GitHub Settings -> Developer settings -> Personal access tokens 创建 Token（Classic 或 Fine-grained 均可），确保对目标仓库有写权限。

3. 在 Cloudflare Pages 项目中添加 GITHUB_TOKEN、GITHUB_REPO，可按需补充 GITHUB_MODE 等可选变量。

4. 重新部署后，首页会出现 GitHub 存储选项（未连通时为禁用态）。

5. 可访问 /api/status 确认 github.connected 与 github.enabled 状态。

建议：

• 大文件优先使用 releases 模式。

• 需要目录化管理和频繁覆盖时可使用 contents 模式。

访客上传功能

允许未登录用户上传文件，站长可自行配置是否开启及限制规则。

| 变量名 | 说明 | 默认值 | | :--- | :--- | :--- | | GUEST_UPLOAD | 启用访客上传 | false | | GUEST_MAX_FILE_SIZE | 访客单文件最大大小（字节） | 5242880（5MB） | | GUEST_DAILY_LIMIT | 访客每日上传次数限制（按 IP 计） | 10 |

启用方式：

1. 在环境变量中设置 GUEST_UPLOAD = true

2. 按需调整 GUEST_MAX_FILE_SIZE 和 GUEST_DAILY_LIMIT

3. 确保已配置 BASIC_USER 和 BASIC_PASS（否则无访客/管理员区分）

4. 重新部署

功能说明：

• 访客可在首页直接上传文件，无需登录

• 访客有单文件大小限制和每日上传次数限制

• 访客不能使用分片上传和高级存储选项（S3/Discord/HuggingFace/GitHub）

• 访客不能访问管理后台和图片浏览页

• 限制基于访客 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 | 禁用遥测 | - |

Docker 运行时变量（自托管模式）

| 变量名 | 说明 | 默认值 | | :--- | :--- | :--- | | PORT | 容器内 API 服务端口 | 8787 | | DATA_DIR | 数据目录 | /app/data | | DB_PATH | SQLite 数据库路径 | /app/data/k-vault.db | | CHUNK_DIR | 分片临时目录 | /app/data/chunks | | CONFIG_ENCRYPTION_KEY | 用于加密存储配置密钥（必填） | - | | SESSION_SECRET | 会话/签名密钥（建议与加密密钥不同） | - | | UPLOAD_MAX_SIZE | 最大上传大小（字节） | 104857600 | | UPLOAD_SMALL_FILE_THRESHOLD | 直传/分片策略阈值（字节） | 20971520 | | CHUNK_SIZE | 分片大小（字节） | 5242880 | | DEFAULT_STORAGE_TYPE | 启动时默认存储类型（telegram/r2/s3/discord/huggingface/webdav/github） | telegram | | SETTINGS_STORE | 基础设置存储后端（sqlite 或 redis） | sqlite | | SETTINGS_REDIS_URL | Redis URL（Upstash/Redis/KVrocks，SETTINGS_STORE=redis 时必填） | - | | SETTINGS_REDIS_PREFIX | Redis 键前缀 | k-vault | | SETTINGS_REDIS_CONNECT_TIMEOUT_MS | Redis 连接/心跳超时（毫秒） | 5000 | | WEB_PORT | docker compose 对外 Web 端口 | 8080 |

页面说明

| 页面 | 路径 | 说明 |

 | :--- | :--- | :--- |

 | 首页/上传 | / | 批量上传、拖拽、粘贴上传 | | WebDAV 独立页 | /webdav.html | WebDAV 上传/状态检查/URL 上传 | | 图片浏览 | /gallery.html | 图片网格浏览 | | 管理后台 | /admin.html | 文件管理、黑白名单 | | 文件预览 | /preview.html | 多格式文件预览 | | 登录页 | /login.html | 后台登录 |

使用限制

Cloudflare 免费额度：

• 每日 100,000 次请求

• KV 每日 1,000 次写入、100,000 次读取、1,000 次列出

• 超出后需升级付费计划（$5/月起）

• 建议 Telegram 场景开启签名直链或低 KV 写入模式以降低额度压力

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

各存储后端文件大小限制：

| 存储后端 | 单文件最大大小 |

 | :--- | :--- |

 | 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 | ✅ |

| `TG_BOT_TOKEN` | Telegram Bot Token（Docker/自托管命名） | 可选 |

| `TG_CHAT_ID` | Telegram 频道 ID（Docker/自托管命名） | 可选 |

| `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 | 可选 |

| `WEBDAV_BASE_URL` | WebDAV 基础地址 | 可选 |

| `WEBDAV_USERNAME` | WebDAV 用户名（Basic 认证） | 可选 |

| `WEBDAV_PASSWORD` | WebDAV 密码（Basic 认证） | 可选 |

| `WEBDAV_BEARER_TOKEN` | WebDAV Bearer Token（与用户名/密码二选一） | 可选 |

| `WEBDAV_TOKEN` | WebDAV Bearer Token 兼容变量名 | 可选 |

| `WEBDAV_ROOT_PATH` | WebDAV 根目录前缀 | 可选 |

| `GITHUB_TOKEN` | GitHub Token（仓库写权限） | 可选 |

| `GITHUB_REPO` | GitHub 仓库（`owner/repo`） | 可选 |

| `GITHUB_MODE` | GitHub 存储模式（`releases`/`contents`） | 可选 |

| `GITHUB_PREFIX` | GitHub 存储路径前缀 | 可选 |

| `GITHUB_RELEASE_TAG` | GitHub Release 标签（releases 模式） | 可选 |

| `GITHUB_BRANCH` | GitHub 分支（contents 模式） | 可选 |

| `GITHUB_API_BASE` | GitHub API 基址 | 可选 |

| `GUEST_UPLOAD` | 启用访客上传 | 可选 |

| `GUEST_MAX_FILE_SIZE` | 访客文件大小限制（字节） | 可选 |

| `GUEST_DAILY_LIMIT` | 访客每日上传次数 | 可选 |

| `ModerateContentApiKey` | 图片审核 API Key | 可选 |

| `WhiteList_Mode` | 白名单模式 | 可选 |

| `disable_telemetry` | 禁用遥测 | 可选 |

| `PORT` | Docker 自托管模式 API 端口 | 可选 |

| `DATA_DIR` | Docker 自托管模式数据目录 | 可选 |

| `DB_PATH` | Docker 自托管模式 SQLite 路径 | 可选 |

| `CHUNK_DIR` | Docker 自托管模式分片目录 | 可选 |

| `CONFIG_ENCRYPTION_KEY` | Docker 自托管模式存储配置加密密钥（必填） | 可选 |

| `SESSION_SECRET` | Docker 自托管模式会话/签名密钥 | 可选 |

| `UPLOAD_MAX_SIZE` | Docker 自托管模式最大上传大小（字节） | 可选 |

| `UPLOAD_SMALL_FILE_THRESHOLD` | Docker 自托管模式直传阈值（字节） | 可选 |

| `CHUNK_SIZE` | Docker 自托管模式分片大小（字节） | 可选 |

| `DEFAULT_STORAGE_TYPE` | Docker 自托管模式默认存储类型 | 可选 |

| `SETTINGS_STORE` | Docker 自托管基础设置存储后端（`sqlite`/`redis`） | 可选 |

| `SETTINGS_REDIS_URL` | Docker 自托管 Redis URL（Upstash/Redis/KVrocks） | 可选 |

| `SETTINGS_REDIS_PREFIX` | Docker 自托管设置存储 Redis 键前缀 | 可选 |

| `SETTINGS_REDIS_CONNECT_TIMEOUT_MS` | Docker 自托管 Redis 连接/心跳超时（毫秒） | 可选 |

| `WEB_PORT` | `docker compose` 对外 Web 端口 | 可选 |

API 使用指南

1. 创建 API Token

1. 打开管理面板 /admin.html

2. 点击工具箱菜单中的 API Token 管理

3. 创建 Token 时按需选择权限：upload / read / delete / paste，并设置过期时间

2. 常用示例

curl 上传文件：

curl -X POST https://your-kvault.com/api/v1/upload \
  -H "Authorization: Bearer kvault_xxxxxxxxxxxx" \
  -F "file=@/path/to/file.png"

curl 上传并设置过期和密码：

curl -X POST https://your-kvault.com/api/v1/upload \
  -H "Authorization: Bearer kvault_xxxxxxxxxxxx" \
  -F "file=@backup.tar.gz" \
  -F "expires_in=86400" \
  -F "password=mypassword"

curl 创建文本粘贴：

curl -X POST https://your-kvault.com/api/v1/paste \
  -H "Authorization: Bearer kvault_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello World","language":"text"}'

Shell 快捷函数（可加入 .bashrc / .zshrc）：

kvault() {
  curl -s -X POST "https://your-kvault.com/api/v1/upload" \
    -H "Authorization: Bearer $KVAULT_TOKEN" \
    -F "file=@$1" | jq -r '.links.share'
}
# 使用: kvault screenshot.png

3. ShareX 配置

• 目标类型（Destination type）：Image uploader / File uploader

• 请求地址（Request URL）：https://your-kvault.com/api/v1/upload

• 请求头（Headers）：Authorization: Bearer kvault_xxxxxxxxxxxx

• 请求体（Body）：Form data（multipart/form-data）

• 文件字段名（File form name）：file

• 返回 URL 路径（URL path）：$.links.download（或 $.links.share）

4. API 端点速查

| 方法 | 端点 | 权限 | 说明 |

 | :--- | :--- | :--- | :--- | 

| POST | /api/v1/upload | upload | 上传文件（multipart/form-data，字段 file） | 

| GET | /api/v1/files | read | 列出文件（支持分页） |

 | GET | /api/v1/file/:id | read | 下载文件 | 

| GET | /api/v1/file/:id/info | read | 获取文件元信息 |

 | DELETE | /api/v1/file/:id | delete | 删除文件 |

 | POST | /api/v1/paste | paste | 创建文本粘贴 |

 | GET | /api/v1/pastes | read | 列出粘贴（支持分页） |

 | GET | /api/v1/paste/:id | read | 获取粘贴内容 |

 | DELETE | /api/v1/paste/:id | delete | 删除粘贴 |