How vikiboss/r2-web works
项目类型与目的(先定“画什么层级”)
从 README + 文件树判断:这是一个纯前端(零后端)的 Cloudflare R2(S3 API 兼容)文件管理器/图床工具,运行在浏览器里,直接用用户填写的凭证调用 R2 API。
因此系统设计图不要画“后端服务/数据库”,核心应该画清楚:
• 静态站点/PWA如何交付到浏览器
• 浏览器端的模块分层(UI / 业务 / R2 API 适配 / 缓存 / 配置)
• 与 Cloudflare R2(S3 API) 的交互(含 AWS4 签名、CORS)
• 本地能力:localStorage、WASM 图片压缩、请求缓存、预览渲染
• 外部可选服务:比如 README 提到的 Tinify(如果代码里实现了“云压缩”开关,也要作为可选外部依赖画出来)
顶层交付/工程与部署
• src/index.html:入口 HTML(大概率含 import maps / 脚本入口)
• src/main.js:主入口(启动应用、初始化 UI/配置/i18n 等)
• src/manifest.json:PWA 清单
• wrangler.jsonc:强烈暗示部署在 Cloudflare 生态(Pages/Workers 静态资源或相关配置)
• package.json、pnpm-lock.yaml:依赖只用于开发/类型提示,但也能用来标注关键第三方库(aws4fetch/dayjs/jsquash/qrcode)
• .github/workflows/release.yaml + scripts/release.mts + bump.config.ts:发布流水线(如果你要画“DevOps/Release 架构图”可单独一张)
前端模块(src/js 是你画“组件图”的依据)
按文件名几乎可以直接抽象出模块职责:
• src/js/app.js:应用总控/路由式状态机(主协调者)
• src/js/ui-manager.js:UI 组件装配、对话框、提示、主题等
• src/js/file-explorer.js:目录浏览/列表分页/排序/懒加载缩略图(核心交互之一)
• src/js/file-operations.js:重命名/移动/复制/删除等操作编排(业务层)
• src/js/upload-manager.js:拖拽/粘贴/选择上传 + 进度/队列(业务层)
• src/js/file-preview.js:图片/音视频/文本预览与渲染(本地渲染能力)
• src/js/r2-client.js:R2(S3) API 访问层(HTTP + AWS4 签名 + 请求封装)
• src/js/config-manager.js:凭证/桶配置管理、localStorage 持久化、配置分享(链接/二维码)
• src/js/i18n.js:多语言资源与切换
• src/js/constants.js、src/js/utils.js:公共常量与工具(节流、防抖、缓存 key、格式化等)
样式与静态资源
• src/css/* + src/style.css:CSS layers / tokens / layout / components
• 这些一般不用在系统图里细画,但可在“前端内部”标注为 UI Assets。
建议你画 3 张图(最准确且不会丢信息)
必须包含这些框与箭头:
• User(Browser)
• R2 Web(Static Site + PWA, runs in browser)
• Cloudflare R2(S3-compatible API)
• Optional External Services(如果有:Tinify;如果没有实现就不要硬画)
• Local Browser Storage(localStorage / Cache)
关键箭头(要标注协议/关键约束):
• Browser App → R2: HTTPS (S3 API) + AWS4 Signature + CORS required
• Browser App → localStorage: store credentials/config (local only)
• Browser App ↔ WASM codecs: in-browser image compression
• Browser App → (optional) Tinify: HTTPS upload image for compression(可选路径)
> 这张图的目的:澄清“零后端”,数据直连 R2,安全边界在浏览器与 R2。
这张图强调“站点如何被交付到浏览器”:
• Static Hosting(Cloudflare Pages / 任意静态托管;由 wrangler.jsonc 暗示 Cloudflare)
• delivers: index.html, main.js, src/js/*, css/*, manifest.json, WASM assets(如果存在)
• Client Runtime (Browser)
• PWA install / offline(如果有 service worker 文件,树里没看到;若实际用浏览器缓存策略也可标“PWA manifest only”)
• Fetch to R2
> 这张图可以把“CI/CD release”作为旁路:GitHub Actions → Static Hosting(可选)。
用 src/js/* 直接作为组件盒子(越细越好,按你的要求“尽量多拆组件”):
推荐分 4 个泳道/颜色:
Application/Orchestration
• app.js(初始化、事件总线/状态流、把 UI 与业务串起来)
• i18n.js(语言资源、切换触发 UI 刷新)
Domain/Business
• upload-manager.js(拖拽/粘贴上传、队列、进度、命名模板、压缩策略选择)
• file-operations.js(rename/move/copy/delete recursive、批量操作)
Infrastructure/Adapters
• r2-client.js(list/get/put/delete/head, presigned url, copy object;内部用 aws4fetch)
• config-manager.js(credentials, bucket, endpoint; localStorage; 分享链接/二维码)
• utils.js / constants.js(缓存、格式化、节流、防抖等)
• WASM codecs(来自 @jsquash/*:mozjpeg/oxipng/webp/avif)
• Browser APIs:Fetch, Clipboard, Drag&Drop, localStorage, <dialog>
数据流建议画成“命令链”:
• UI event → app.js → (upload/file-ops) → r2-client.js → R2
• config-manager.js 提供签名所需配置给 r2-client.js
• upload-manager.js → (optional) WASM compression → r2-client.putObject
• file-explorer.js → r2-client.list → 渲染
• file-preview.js → r2-client.get/signedUrl → <img>/<video>/<audio>/<pre>
必须强调的架构事实
• 无后端:不存在你方服务器处理数据;所有操作发生在浏览器与 R2 之间
• 安全边界:凭证只在 localStorage;风险点是“配置分享链接/二维码”携带敏感信息
• AWS4 签名:aws4fetch 作为关键依赖,建议在 r2-client 旁边显式标注
• CORS 是前置条件:README 里明确需要配置 R2 桶 CORS;在 Context 图用醒目注释
• WASM 本地压缩:图里把“压缩发生在客户端”画成独立节点,避免被误解为服务器处理
建议标注的运行时“状态/缓存”
• Request Cache(README 提到请求缓存;可能在 utils.js 或 r2-client.js 做了缓存)
• Pagination/Lazy loading(file-explorer 的核心性能策略)
• Throttling/debouncing(性能策略)
针对该项目类型(纯前端工具)的“画图要点”
与常见全栈不同,本项目的重点不是 API Gateway / DB schema,而是:
• 浏览器端分层:UI/业务/适配器要清晰
• 外部依赖的协议细节:S3 API + AWS4 + CORS
• 本地能力:WASM、localStorage、剪贴板、拖拽、PWA manifest
• 风险点:凭证与分享链接(可以在图上加 Security Notes)
画图规范(让它“可读且可审”)
• 每个组件框写:名称 + 文件名(例如:R2 Client (src/js/r2-client.js))
• 每条箭头写:动作/协议(ListObjectsV2 / PutObject / DeleteObject / presigned URL / localStorage read/write)
形状与颜色(强制你区分类型)
• 蓝色:Browser internal modules(src/js)
• 灰色:Browser APIs(Fetch/localStorage/Clipboard/WASM runtime)
• 橙色:External systems(Cloudflare R2、Tinify)
• 紫色:Delivery/Hosting(Static host, GitHub Actions)
方向与层次
• 从左到右:User → Browser App → External R2
• 从上到下:UI → Orchestration → Domain → Infrastructure
结合当前仓库,建议你在图里“点名”的技术/文件
• r2-client.js + aws4fetch:签名与请求封装(这是系统成立的关键)
• config-manager.js + localStorage:凭证与配置生命周期(安全重点)
• upload-manager.js + @jsquash/* (WASM):本地压缩(性能/隐私卖点)
• file-explorer.js / file-operations.js:主要业务能力
• manifest.json:PWA(安装体验)
• wrangler.jsonc:部署与 Cloudflare 生态关联(容器图/交付图里体现)
最后给你一个“可直接照着画”的组件清单(按边界拆到最大)
Browser App(R2 Web)
• Entry
• index.html
• main.js
• Orchestration
• app.js
• UI / Views
• ui-manager.js
• file-explorer.js
• file-preview.js
• CSS: src/css/*, style.css
• Domain
• upload-manager.js
• file-operations.js
• Infra
• r2-client.js (uses aws4fetch)
• config-manager.js (uses localStorage)
• i18n.js
• utils.js
• constants.js
• Local execution deps
• WASM image codecs (@jsquash/*)
• Browser APIs: Fetch/Clipboard/DragDrop/Dialog
External
• Cloudflare R2 (S3 API endpoints)
• Optional: Tinify (cloud compression) — only if实际实现
• Static hosting (Cloudflare Pages/Vercel/Netlify)
• GitHub Actions release workflow → deploy static assets