文档二维码中心（Cloudflare Workers + TypeScript + pnpm）

一个单用户文档二维码工具：

• 上传文件（PDF、图片、Office、文本等）或粘贴 URL
• 生成不可猜测的分享链接与高对比二维码
• 手机扫码后打开分享页：预览 / 下载 / 跳转
• 历史文档库：重新打开、复制链接、下载二维码 PNG、删除
• 每条分享可设置有效期（默认 7 天），过期自动清理
• 全中文界面，移动端友好

---

技术栈

• 运行时：Cloudflare Workers
• 存储：
  • R2：保存上传文件
  • D1：保存文档元数据（名称、分享 ID、类型、时间等）
• 语言：TypeScript（应用代码全部为 .ts）
• 包管理器：pnpm

---

1) 本地安装与开发（pnpm）

需要 Node.js 20+（建议 20/22 LTS）

pnpm install
pnpm typegen
pnpm dev

• pnpm dev 使用 wrangler dev
• 本地地址通常是 http://127.0.0.1:8787

---

2) Cloudflare 首次准备（登录与资源）

先登录 Wrangler（不会在代码里保存你的账号密钥）：

pnpm wrangler login

自动资源创建（推荐）

本项目 wrangler.jsonc 只声明了绑定名（不写死资源 ID），利用 Wrangler 的自动资源创建能力：

• d1_databases: [{ "binding": "DB" }]
• r2_buckets: [{ "binding": "DOCS_BUCKET" }]

首次 pnpm deploy 时，Wrangler 会在你的账号中创建并绑定所需 D1/R2（需 Wrangler 版本支持自动创建）。

手动创建（如果你的环境关闭自动创建）

如需手动创建，可执行：

pnpm wrangler d1 create document-qr-db
pnpm wrangler r2 bucket create document-qr-files

然后把命令输出里的数据库/桶信息填回 wrangler.jsonc 对应绑定。

---

3) 构建与部署

本地构建检查（不真正发布）

pnpm build

pnpm build 实际执行的是 wrangler deploy --dry-run，用于检查 Worker 打包与配置。

正式部署

pnpm deploy

部署成功后会得到 Worker 的公网地址（*.workers.dev 或你绑定的自定义域名）。

---

4) 二维码可扫码访问的关键说明

二维码里编码的是分享链接 URL。
手机蜂窝网络能否打开，取决于这个 URL 是否公网可达。

• 本地 wrangler dev 地址仅用于本地开发调试
• 生产请使用 pnpm deploy 后的 Worker 公网地址
• 也就是说，扫码应指向部署后的 Worker URL

---

5) 分享有效期与自动删除机制

• 创建文档时可设置有效期：
  • 1 小时 / 1 天 / 7 天（默认）/ 30 天 / 自定义日期时间 / 永不过期
• 到期后行为：
  • /s/<shareId> 不再返回文档内容，而是显示“已过期/不可用”页面
  • 不再允许下载、预览、重定向
  • 元数据会从 D1 删除，上传文件会从 R2 删除（不可恢复）
• 清理策略：
  • 懒清理：访问到过期记录时立刻删除
  • 定时清理：Worker Cron（wrangler.jsonc 中 triggers.crons）每 15 分钟清理一次，避免无人访问时文件滞留

本地可手动触发 scheduled 处理器测试：

curl "http://127.0.0.1:8787/cdn-cgi/handler/scheduled?cron=*/15+*+*+*+*"

---

6) 常用命令（pnpm-only）

pnpm install
pnpm typegen
pnpm typecheck
pnpm dev
pnpm build
pnpm deploy
pnpm check

---

7) 功能行为说明

• 上传文件后：
  • 文件写入 R2
  • 元数据写入 D1
  • 生成随机分享链接 /s/<shareId>
  • 记录该分享的到期时间
• 粘贴 URL 后：
  • 元数据写入 D1
  • 分享链接 /s/<shareId> 访问时 302 跳转（未过期）
• 分享页：
  • PDF / 图片：浏览器内预览
  • 其他文件：展示下载入口
• 文档库：
  • 历史记录持久化
  • 一键复制链接
  • 下载二维码 PNG
  • 删除（同步删除 D1 记录；上传文件同时删除 R2 对象）