K-Vault访客上传配置指南:如何安全开放匿名上传并设置大小与次数限制

原创2026-10-26 23:36:212,298 阅读

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 页

K-Vault访客上传首页界面:未登录访客可直接拖拽上传文件

当访客进入首页时,页面顶部会显示「访客模式 - 单文件最大 X,每日上限 Y 次」的提示条,让使用限制一目了然。

开启访客上传前的 3 个前置条件

在配置环境变量之前,请先确认以下三点,否则访客上传不会生效:

  1. 站点已正常部署:Cloudflare Pages 或 Docker 任一方式均可,两种模式的配置变量名完全一致。
  2. 已配置后台账号 BASIC_USER 和 BASIC_PASS ⚠️ 这是最关键的一步。「访客」身份是相对于「管理员」而言的——如果没设置后台账号,系统无法区分身份,所有请求都会按管理员放行,大小与次数限制全部失效。
  3. 已配置至少一个存储后端(如 Telegram)。Cloudflare Pages 部署时,每日次数统计依赖 KV 命名空间(变量名 img_url);未绑定 KV 时,每日次数限制会被跳过(大小限制仍生效)。

K-Vault登录页面:设置后台账号后访客上传限制才会生效

核心配置: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

访客上传的文件会进入你的管理后台,可与登录用户上传的内容一样统一管理、使用黑白名单与标签功能。

K-Vault后台管理页面:访客上传的文件统一在此管理

常见问题:访客上传不生效怎么排查

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(或直接删除该变量)并重新部署即可,已有文件不受影响。

相关源码与文档位置

配置完成后,你的 K-Vault 就同时具备了「零门槛的匿名上传」与「可控的大小和次数边界」——欢迎把这份私有云盘开放给更多人使用 🚀

登录后查看全文
K-Vault