K-Vault访客上传配置指南:如何安全开放匿名上传并设置大小与次数限制
K-Vault访客上传配置指南:如何安全开放匿名上传并设置大小与次数限制
K-Vault 是一款基于 Cloudflare 的 Serverless 聚合云盘,以 Telegram 为核心并兼容 R2、S3、WebDAV 等存储后端。它内置了「访客上传」(Guest Upload)功能:允许未登录的访客匿名上传文件,同时由站长通过 3 个环境变量控制单文件大小与每日上传次数。本指南带你 5 分钟完成 K-Vault 访客上传的安全配置与验证。
访客上传是什么:不登录也能传文件的安全边界
开启访客上传后,普通用户打开你的 K-Vault 站点即可直接上传文件,无需注册、无需登录。为防止滥用,系统内置了多层安全边界:
| 维度 | 默认限制 | 说明 |
|---|---|---|
| 单文件大小 | 5MB | 由 GUEST_MAX_FILE_SIZE 控制 |
| 每日上传次数 | 10 次 | 按访客 IP 统计,由 GUEST_DAILY_LIMIT 控制,每日自动重置 |
| 存储后端 | Telegram / R2 | 访客不可用 S3、Discord、HuggingFace、WebDAV、GitHub |
| 分片上传 | ❌ 不可用 | 访客只能走普通直传链路 |
| 页面访问 | 仅首页 | 访客无法访问管理后台、图片浏览页、WebDAV 页 |
当访客进入首页时,页面顶部会显示「访客模式 - 单文件最大 X,每日上限 Y 次」的提示条,让使用限制一目了然。
开启访客上传前的 3 个前置条件
在配置环境变量之前,请先确认以下三点,否则访客上传不会生效:
- 站点已正常部署:Cloudflare Pages 或 Docker 任一方式均可,两种模式的配置变量名完全一致。
- 已配置后台账号
BASIC_USER和BASIC_PASS⚠️ 这是最关键的一步。「访客」身份是相对于「管理员」而言的——如果没设置后台账号,系统无法区分身份,所有请求都会按管理员放行,大小与次数限制全部失效。 - 已配置至少一个存储后端(如 Telegram)。Cloudflare Pages 部署时,每日次数统计依赖 KV 命名空间(变量名
img_url);未绑定 KV 时,每日次数限制会被跳过(大小限制仍生效)。
核心配置:3 个环境变量打开 K-Vault 访客上传
进入 Cloudflare Pages 项目 → 设置 → 环境变量(Docker 则写入 .env),添加以下变量:
| 变量名 | 作用 | 默认值 | 示例 |
|---|---|---|---|
GUEST_UPLOAD |
访客上传总开关 | false |
true |
GUEST_MAX_FILE_SIZE |
访客单文件上限,单位:字节 | 5242880(5MB) |
10485760(10MB) |
GUEST_DAILY_LIMIT |
每个 IP 每日上传次数 | 10 |
5 |
两个容易踩的坑:
- ⚠️
GUEST_UPLOAD的值必须是字符串true,写True或1都不会启用(Docker 模式则支持布尔解析)。 - ⚠️
GUEST_MAX_FILE_SIZE以字节为单位:10MB =10485760,20MB =20971520,别直接填10。
修改环境变量后必须重新部署(Docker 为重启容器),运行中的实例不会自动读取新配置。
💡 权限校验的核心逻辑位于 functions/utils/guest.js(Pages 模式)与 server/lib/utils/guest.js(Docker 模式),每日计数分别存储在 KV 和 SQLite 的 guest_upload_counters 表中,到期自动清零。
访客文件大小与每日次数限制怎么设
限制值没有标准答案,可按站点的开放程度选择:
| 场景 | GUEST_MAX_FILE_SIZE |
GUEST_DAILY_LIMIT |
思路 |
|---|---|---|---|
| 公开图床/分享站 | 5242880(5MB) |
5 |
收紧,防刷防滥用 |
| 小圈子互助群 | 10485760(10MB) |
10 |
平衡体验与安全 |
| 内部协作场景 | 20971520(20MB) |
20 |
放宽,配合内容审核 |
设置时的两点建议:
- 访客大小上限应小于等于所选用存储后端的网页上传上限(如 Cloudflare Pages 上 Telegram 网页直传为 20MB),否则会收到 413 错误。
- 访客每日次数是按 IP 计的,同一出口 IP 下的多个用户共享额度;面向公网时建议搭配 README.md 中提到的图片审核(
ModerateContentApiKey)一起使用。
验证步骤:3 步确认匿名上传已生效
配置完成后,建议按顺序验证,确保访客上传链路完整可用:
第 1 步:检查状态接口
访问 https://你的域名/api/status,确认返回中包含:
"guestUpload": {
"enabled": true,
"maxFileSize": 10485760,
"dailyLimit": 10
}
第 2 步:无痕模式体验访客模式
用浏览器无痕窗口打开首页,未登录状态下应看到访客提示条与上传区,且导航栏不会出现「管理后台 / 图片浏览 / WebDAV」入口。
第 3 步:实测上传并观察报错
上传一个 1MB 小文件应成功;再分别上传超限大文件、连续上传超次数的请求,前端会收到清晰提示:
| HTTP 状态码 | 提示内容 | 含义 |
|---|---|---|
| 401 | 未启用访客上传,请登录后操作 | 开关未生效或后台账号未配置 |
| 413 | 访客上传限制:文件大小不能超过 XMB | 超过 GUEST_MAX_FILE_SIZE |
| 429 | 访客每日上传上限 N 次,今日已用完 | 超过 GUEST_DAILY_LIMIT |
访客上传的文件会进入你的管理后台,可与登录用户上传的内容一样统一管理、使用黑白名单与标签功能。
常见问题:访客上传不生效怎么排查
Q1:配置了 GUEST_UPLOAD=true,访客仍被跳转到登录页?
按顺序检查:① GUEST_UPLOAD 是否恰好为 true;② BASIC_USER / BASIC_PASS 是否已配置(这是访客身份成立的前提);③ 修改环境变量后是否重新部署。
Q2:每日次数限制不生效?
Cloudflare Pages 模式下,每日计数依赖 KV 绑定 img_url。请确认 Pages 项目已绑定 KV 命名空间并重新部署;Docker 模式下计数写入本地 SQLite,无需额外配置。
Q3:想让访客传大文件(如 50MB+)?
访客目前只能使用 Telegram / R2 直传链路。R2 网页直传上限为 20MB,若需要更大文件,建议访客场景以图片/小文件为主,大文件引导用户登录后使用分片上传或 API Token 上传。
Q4:如何关闭访客上传?
将 GUEST_UPLOAD 改为 false(或直接删除该变量)并重新部署即可,已有文件不受影响。
相关源码与文档位置
- 访客权限与限流(Pages):functions/utils/guest.js
- 上传入口与访客拦截逻辑:functions/upload.js
- 状态接口(含
guestUpload字段):functions/api/status.js - 访客模式前端提示条:index.html
- Docker 模式访客服务:server/lib/utils/guest.js
- Docker 环境变量解析:server/lib/config.js
- 完整环境变量参考:README.md
配置完成后,你的 K-Vault 就同时具备了「零门槛的匿名上传」与「可控的大小和次数边界」——欢迎把这份私有云盘开放给更多人使用 🚀


