OtterHub

OtterHub 是一款专为个人用户设计的轻量级、免费且私密的云存储解决方案。它巧妙地结合了 Cloudflare Pages/KV 的元数据管理能力与 Telegram Bot API 的大文件存储能力，实现了像水獭藏宝一样安全、隐蔽的文件存储体验。

不同于复杂的自建网盘或仅支持图片的图床，OtterHub 专注于“刚好够用”的核心需求：支持大文件分片上传、视频流式播放、回收站机制以及 AI 图片分析，同时保持极低的维护成本和零服务器费用（基于 Cloudflare 免费额度）。

核心亮点

1. 突破限制的大文件支持

• 分片上传技术：通过前端将大文件拆分为 ≤20MB 的分片，绕过 Telegram 单文件限制。
• 流式合并下载：后端记录每个分片的 file_id，下载时按序从 Telegram 拉取并流式返回给客户端，支持 HTTP Range 请求。
• 实测性能：已稳定支持 100MB+ 文件上传与预览，理论最大支持 1GB 单文件。
• 断点续传：利用 HTTP Range 头，支持视频/音频的按需加载和断点续传，节省流量。

2. 架构克制，长期可维护

• 无状态后端：基于 Cloudflare Workers/Pages Functions，无需维护传统服务器。
• 混合存储策略：
  • 元数据 (KV)：存储文件名、大小、分片索引等关键信息，查询极速。
  • 实际文件 (Telegram)：利用 Telegram 无限的免费存储空间作为实际文件载体。
  • 本地开发兼容：开发环境下自动切换至本地 R2 模拟，方便调试。
• 缓存优化：非 Range 请求走 Cloudflare 边缘缓存，Range 请求直出以避免缓存污染，平衡速度与成本。

3. 安全与私密

• JWT 认证：基于密码登录，使用 JWT + Cookie 保护会话。
• NSFW 检测：集成 nsfw.js，在客户端自动检测并遮罩敏感图片，提供“安全模式”。
• 回收站机制：删除文件进入回收站，30天后自动清除，支持手动恢复或永久删除，防止误操作。

4. AI 赋能与智能管理

• AI 图片分析：可选绑定 Cloudflare Workers AI，上传图片后自动生成简要描述，便于后续通过自然语言检索图片。
• 智能预览：支持图片、音频、视频、PDF/TXT 文本的直接在线预览，无需下载。
• 分类管理：KV Key 按 img:, audio:, video:, doc: 前缀划分，提升查询效率。支持标签、收藏、排序及批量操作。

快速开始

前置要求

• Node.js 18+
• Cloudflare 账号
• Telegram Bot Token & Chat ID

本地开发

git clone https://github.com/otterhub/otterhub.git # 假设仓库地址
cd otterhub
npm install
npm run dev

• 前端: http://localhost:3000
• 后端: http://localhost:8080
• 默认密码: 123456
• 存储: 本地 R2 模拟

Cloudflare 部署

1. 创建 Pages 项目：
   • Fork 项目并在 Cloudflare Dashboard 连接 GitHub 仓库。
   • 构建命令: npm install && npm run build
   • 输出目录: frontend/out
2. 配置环境变量：
   • PASSWORD: 登录密码
   • TG_CHAT_ID: 你的 Telegram Chat ID
   • TG_BOT_TOKEN: 你的 Bot Token
   • API_TOKEN: (可选) API 调用令牌
3. 绑定 KV Namespace：
   • 创建 KV 命名空间 oh_file_url。
   • 在 Pages 设置中将其绑定为变量名 oh_file_url。
4. (可选) 绑定 Workers AI：
   • 如需 AI 图片描述功能，在 Functions 设置中绑定 AI 资源，变量名为 AI。
5. 重新部署即可生效。

技术原理详解

文件上传流程

1. 初始化：前端发送 GET /upload/chunk，后端生成唯一 Key 并创建元数据占位。
2. 分片上传：前端将文件切片（≤20MB），逐个发送 POST /upload/chunk。后端将分片暂存至临时 KV (TTL 1小时)。
3. 异步上云：后端使用 waitUntil 异步将分片上传至 Telegram，获取 file_id。
4. 合并元数据：所有分片上传完成后，将 file_id 数组写入最终 KV，清理临时数据。

文件下载流程

1. 读取元数据：从 KV 获取文件分片信息及对应的 file_id 列表。
2. 流式拉取：根据客户端请求的 Range，后端按序从 Telegram API 拉取对应分片。
3. 实时响应：边拉取边向客户端推送数据，实现低延迟播放和下载。

存储容量估算

• 元数据占用：单个文件元数据约 < 500 字节。
• KV 容量：Cloudflare 免费版提供 1GB KV 存储。
• 理论文件数：$1GB / 500B \approx 200万$ 个文件索引。
• 实际文件存储：依赖 Telegram，理论上无限（受限于 Telegram 单账号总容量限制，但极大）。

常见问题

Q: 为什么上传后文件显示不完整？
A: 由于使用了异步上传 (waitUntil)，分片可能尚未全部同步到 Telegram。请稍等片刻并刷新页面，通常几秒内即可正常显示。

Q: 免费版 Cloudflare Workers 够用吗？
A: 对于个人日常使用完全足够。但请注意，大文件处理会消耗较多 CPU 时间和内存，建议避免极高并发的大文件上传。

Q: 如何获取 Telegram Bot Token 和 Chat ID？
A:

• Token: 搜索 @BotFather，发送 /newbot 创建机器人并保存 Token。
• Chat ID: 搜索 @userinfobot 发送任意消息，或访问 https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates 查看。