PocketChest文件共享

一、PocketChest 简介

PocketChest 是一款安全的文件共享应用，旨在提供便捷且安全的文件传输解决方案。其核心架构特点如下：

• 后端：基于 Cloudflare Workers 构建，结合 D1 Database 进行数据存储，R2 Storage 用于文件存储

• 前端：采用 Next.js 14 框架和 Tailwind CSS 开发，部署在 Cloudflare Pages

• 开发语言：全程使用 TypeScript 保证类型安全

主要功能包括文件上传、生成分享链接、TOTP 身份验证保护、文件过期管理等，支持本地开发和云端部署两种模式。

二、前置条件

在开始安装或开发前，请确保满足以下条件：

• 拥有 Cloudflare 账户（免费套餐即可）

• 安装 Wrangler CLI（Cloudflare 开发工具）

• Node.js 环境（推荐 v16+，用于运行 npm 命令）

安装 Wrangler CLI：

npm install -g wrangler
# 登录 Cloudflare 账户
wrangler login

三、本地开发环境搭建

1. 获取代码与配置模板

首先复制项目配置模板文件：

# 复制后端配置模板
cp pocket-chest-backend/wrangler.jsonc.template pocket-chest-backend/wrangler.jsonc
# 复制前端环境变量模板
cp pocket-chest-frontend/.env.local.template pocket-chest-frontend/.env.local

2. 启动后端服务

# 进入后端目录
cd pocket-chest-backend
# 安装依赖
npm install
# 启动开发服务器（默认地址：http://localhost:8787）
npm run dev

3. 启动前端服务

# 进入前端目录
cd pocket-chest-frontend
# 安装依赖
npm install
# 启动开发服务器（默认地址：http://localhost:3000）
npm run dev

启动完成后，可通过 http://localhost:3000 访问前端界面，后端 API 会自动关联到本地服务。

四、部署到 Cloudflare

1. 后端部署（Cloudflare Worker）

# 进入后端目录
cd pocket-chest-backend
# 部署到 Cloudflare Workers
npm run deploy

部署过程中需确保：

• wrangler.jsonc 中已正确配置数据库 ID 和存储桶名称

• 必要的环境变量和密钥已设置（包括 TOTP 密钥等）

2. 前端部署（Cloudflare Pages）

方式 A：通过 Wrangler 直接部署

# 进入前端目录
cd pocket-chest-frontend
# 安装依赖
npm install
# 构建应用
npm run build
# 部署到 Cloudflare Pages（替换为你的项目名）
npx wrangler pages deploy out --project-name your-unique-project-name

方式 B：通过 Git 集成部署

参考 Cloudflare Pages Git 集成文档，将代码仓库与 Cloudflare Pages 关联，实现自动部署。

五、部署后配置与测试

1. 基本测试

1. 访问部署后的前端 URL

2. 尝试上传文件（若启用 TOTP 需进行身份验证）

3. 使用生成的代码测试文件检索功能

4. 验证文件下载是否正常

2. TOTP 配置（可选）

若需要添加或更新 TOTP 密钥，可使用以下方法：

# 生成新的 TOTP 密钥（替换为实际用户名）
cd pocket-chest-backend/scripts
node generate-secrets.js --totp-only admin user1 user2
# 更新 Cloudflare 密钥
cd ..
wrangler secret put TOTP_SECRETS
# 输入生成的完整密钥字符串

六、常见问题排查

• CORS 错误：检查后端的 Access-Control-Allow-Origin 配置

• 数据库错误：确认 D1 数据库已正确绑定到 Worker

• 存储错误：验证 R2 存储桶是否存在且配置正确

• TOTP 问题：确保密钥格式正确且系统时间同步

更多部署细节可参考项目中的 DEPLOYMENT.md 文档。