一、OtterHub 是什么

OtterHub 是一个基于 Cloudflare Pages、Cloudflare KV 和 Telegram Bot API 的免费私人云盘项目。它把 Telegram 作为实际文件存储后端，把 Cloudflare KV 用作文件索引和元数据存储，适合个人长期保存、预览和管理文件。

项目地址：

https://github.com/DJChanahCJD/OtterHub

项目定位是“刚好够用、稳定、好维护”的个人云盘，而不是面向多人协作的大型网盘系统。

二、核心功能

三、部署前准备

部署前需要准备以下内容：

生产环境建议准备一个私有 Telegram 频道或群组，专门用于保存 OtterHub 上传的文件。

四、创建 Telegram Bot

1. 创建机器人

1. 打开 Telegram，搜索 @BotFather。
2. 发送 /newbot。
3. 按提示输入机器人名称和用户名。
4. 创建完成后，BotFather 会返回一串 Bot Token。

示例格式：

1234567890:AAExampleExampleExampleExample

这个 Token 后面要填入 Cloudflare Pages 环境变量 TG_BOT_TOKEN。

2. 创建存储频道或群组

建议新建一个私有频道或群组，例如：

OtterHub Storage

然后把刚创建的 Bot 加入该频道或群组，并授予读取消息、发送消息等必要权限。

3. 获取 Chat ID

获取 Chat ID 的常见方式：

1. 先在频道或群组里发送一条消息。
2. 访问 Telegram Bot API：

https://api.telegram.org/bot你的BotToken/getUpdates

3. 在返回结果中找到 chat.id。

频道或群组的 Chat ID 可能是负数，例如：

-1001234567890

这个值后面要填入环境变量 TG_CHAT_ID。

五、Fork OtterHub 仓库

打开项目仓库：

https://github.com/DJChanahCJD/OtterHub

点击右上角 Fork，把项目复制到自己的 GitHub 账号下。

后续 Cloudflare Pages 会从你自己的仓库拉取代码并构建部署。

六、Cloudflare Pages 部署

1. 创建 Pages 项目

进入 Cloudflare Dashboard：

Workers & Pages -> Pages -> Create a project

选择连接 GitHub，然后选择刚刚 Fork 的 OtterHub 仓库。

2. 设置构建配置

按照项目 README 的部署说明填写：

如果 Cloudflare 要求选择框架，可以选择 Next.js 或留空按静态输出构建，关键是输出目录必须是 frontend/out。

3. 添加环境变量

在 Pages 项目设置中添加以下环境变量：

示例：

PASSWORD=your_strong_password
TG_CHAT_ID=-1001234567890
TG_BOT_TOKEN=1234567890:AAExampleExample
API_TOKEN=your_api_token
TG_WEBHOOK_SECRET=your_32_chars_random_secret

PASSWORD 建议使用强密码，不要使用 demo 中的 123456。

4. 创建 Cloudflare KV

进入 Cloudflare Dashboard，创建一个 KV Namespace：

oh_file_url

然后回到 Pages 项目设置，绑定 KV：

注意：变量名也要设置为 oh_file_url，不要随意改名。

5. 可选：绑定 Workers AI

如果你希望启用图片自动分析功能，可以在 Pages 项目中添加 Workers AI Binding：

该功能可在 OtterHub 设置页中关闭。如果你不需要图片 AI 描述，可以暂时不配置。

6. 重新部署

环境变量和 KV 绑定配置完成后，回到 Cloudflare Pages 的 Deployments 页面，重新部署一次。

部署成功后，你会得到一个 Pages 默认域名，例如：

https://your-project.pages.dev

打开该地址，即可进入 OtterHub 登录页面。

七、绑定自定义域名

如果你想用自己的域名访问，例如：

https://drive.example.com

可以在 Cloudflare Pages 项目中进入：

Custom domains -> Set up a custom domain

填写你的子域名，按 Cloudflare 提示完成 DNS 配置。

自定义域名配置完成后，建议在 OtterHub 设置中重新配置 Telegram Webhook，确保回调地址使用正式域名。

八、配置 Telegram 频道/群组上传

OtterHub 支持在 Telegram 频道或群组中直接发送文件，系统自动收录到云盘，并回复文件直链。

前置条件：

• 已配置 TG_WEBHOOK_SECRET
• Bot 已加入目标频道或群组
• Bot 有读取消息和发送消息权限
• Cloudflare Pages 已成功部署

配置步骤：

1. 登录 OtterHub。
2. 进入设置页。
3. 找到常规设置中的上传设置。
4. 点击“配置 Webhook”。
5. 点击“检查状态”，确认 Webhook 已绑定。

如果需要手动配置，可以调用 Telegram API：

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://你的域名/telegram/webhook\",\"secret_token\":\"你的TG_WEBHOOK_SECRET\",\"allowed_updates\":[\"message\",\"channel_post\"]}"

检查 Webhook 状态：

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

注意：Telegram 频道或群组上传仅支持不超过 20MB 的文件。超过 20MB 的文件请使用 OtterHub 网页端上传，网页端会走分片上传。

九、本地开发

如果你想在本地调试项目，需要 Node.js 18+。

1. 克隆仓库

git clone https://github.com/DJChanahCJD/OtterHub
cd OtterHub

2. 安装依赖

npm install

项目使用 Workspaces，根目录执行 npm install 会安装所有子项目依赖。

3. 首次构建

首次启动前建议先构建前端：

npm run build

构建后会生成 frontend/out，供 Wrangler Pages Dev 使用。

4. 启动开发环境

npm run dev

默认访问地址：

开发环境默认密码为：

123456

本地开发默认使用 R2 模拟存储，方便直接测试上传。

十、日常使用教程

1. 登录云盘

打开部署后的访问地址，输入环境变量 PASSWORD 中设置的密码登录。

登录后会进入文件管理界面。

2. 上传文件

点击上传按钮，选择本地文件。

OtterHub 支持常见文件类型：

• 图片
• 音频
• 视频
• 文档
• 文本
• PDF
• 压缩包

网页端会根据文件大小自动处理上传。大文件会被拆成不超过 20MB 的分片，再上传到 Telegram。

3. 预览文件

上传完成后，可以直接点击文件进行预览。

常见预览方式：

如果刚上传完文件立即查看时显示不完整，可以稍等片刻再刷新。因为分片上传到 Telegram 的过程是异步处理的。

4. 搜索和标签

OtterHub 支持搜索、收藏、排序和标签。建议给长期保存的文件添加清晰标签，例如：

照片
文档
备份
视频
发票
项目资料

这样后续查找会更方便。

5. 删除和回收站

删除文件后，文件会进入回收站。

你可以在回收站中：

• 恢复文件
• 永久删除文件

项目说明中提到回收站文件 30 天后会自动清除。重要文件删除前请确认是否已有备份。

6. 批量管理

OtterHub 支持批量下载和批量删除。整理大量文件时，可以先通过搜索或标签筛选，再进行批量操作。

7. 图片加载策略

OtterHub 提供图片加载策略：

如果你在移动网络下访问云盘，建议开启省流模式。

十一、大文件机制说明

Telegram Bot API 单文件限制通常是 20MB。OtterHub 通过分片上传解决这个问题：

1. 前端把文件拆成多个不超过 20MB 的分片。
2. 每个分片单独上传到 Telegram。
3. 服务端把每个分片对应的 file_id 写入 KV。
4. 下载或预览时，再按顺序流式拉取并合并。

项目 README 中说明，当前最大支持约 1GB 文件，也就是 50 个 20MB 分片。

实际使用时，不建议同时并发上传多个大文件，因为这会占用较多 Worker 内存和 CPU 资源。

十二、常见问题

登录密码在哪里设置？

登录密码来自 Cloudflare Pages 环境变量：

PASSWORD

修改后需要重新部署 Pages。

上传后文件为什么暂时不完整？

大文件分片会通过 waitUntil 异步上传到 Telegram。分片尚未全部处理完成时，文件可能暂时不完整。一般稍等片刻并刷新即可。

为什么 Telegram 频道上传只能传 20MB？

频道或群组上传直接受 Telegram Bot 单文件限制影响，因此只支持不超过 20MB 的文件。超过 20MB 请使用网页端上传。

Cloudflare 免费版够用吗？

个人云盘场景通常够用。README 中说明，KV 中单文件元数据占用很小，理论可存储大量索引。但大文件上传会消耗 Worker 资源，不建议高并发使用。

可以多人共用吗？

OtterHub 的定位更偏个人私人云盘，不是企业网盘或多人协作系统。如果要多人使用，至少应评估密码共享、安全权限和滥用风险。

文件真的保存在 Cloudflare KV 吗？

不是。生产环境中文件主体保存在 Telegram，Cloudflare KV 主要保存文件索引、元数据和 Telegram file_id 分片信息。

API_TOKEN 有什么用？

API_TOKEN 是可选变量，用于 API 调用鉴权。如果你只通过网页使用 OtterHub，可以暂时不配置。

十三、安全建议

• PASSWORD 使用强密码，不要使用 123456。
• TG_BOT_TOKEN 不要公开到博客、GitHub 或聊天记录。
• Telegram 存储频道或群组建议设置为私有。
• TG_WEBHOOK_SECRET 建议使用 32 位以上随机字符串。
• 定期检查 Cloudflare Pages 环境变量是否泄露。
• 不建议保存极高敏感文件，例如身份证、密码库、私钥、商业合同。
• 如果使用自定义域名，建议开启 Cloudflare 的 HTTPS 和安全规则。

十四、总结

OtterHub 适合个人搭建一个轻量、免费、可预览、可搜索的私人云盘。它的核心架构是：

前端页面 -> Cloudflare Pages Functions -> Cloudflare KV 索引 -> Telegram Bot 文件存储

推荐部署顺序：

1. 创建 Telegram Bot。
2. 创建私有 Telegram 频道或群组。
3. 获取 TG_BOT_TOKEN 和 TG_CHAT_ID。
4. Fork OtterHub 仓库。
5. 在 Cloudflare Pages 中导入仓库。
6. 设置构建命令和输出目录。
7. 配置 PASSWORD、TG_CHAT_ID、TG_BOT_TOKEN、TG_WEBHOOK_SECRET。
8. 创建并绑定 KV Namespace oh_file_url。
9. 重新部署。
10. 登录 OtterHub，测试上传、预览和删除。

按这个流程部署，基本就可以得到一个可长期自用的私人云盘。

参考资料

• OtterHub GitHub 仓库
• OtterHub Demo
• Cloudflare Pages 文档
• Cloudflare KV 文档
• Telegram Bot API 文档