架构概览
NaviHive 是一个现代化的网站导航管理系统，采用全栈架构部署在 Cloudflare Workers 上。本页面详细介绍系统的技术架构、设计模式和核心实现。
技术栈总览
前端技术栈
- 核心框架: React 19 + TypeScript
- UI 组件库: Material UI 7.0（基于 Emotion 样式引擎）
- 样式方案:
- Tailwind CSS 4.1（实用类样式）
- CSS-in-JS（Emotion，用于动态样式）
- 拖拽功能: DND Kit（实现分组和站点的可拖拽排序）
- 构建工具: Vite 6 + Cloudflare 插件
- API 层: 客户端抽象（支持真实 API 和 Mock 模式）
后端技术栈
- 运行时: Cloudflare Workers（全球边缘计算，无服务器）
- 数据库: Cloudflare D1（基于 SQLite 的分布式数据库）
- 认证方案:
- JWT 令牌（使用 Web Crypto API 的 HMAC-SHA256 签名）
- 密码加密（bcrypt，10轮盐值）
- HttpOnly Cookie 存储（防止 XSS 攻击）
- 入口文件:
worker/index.ts（处理所有 API 路由） - 安全特性: 请求验证、大小限制、CORS、错误处理
系统架构图
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ React 19 │ │ Material UI │ │ Tailwind CSS│ │
│ │ 前端应用 │ │ 组件库 │ │ 样式框架 │ │
│ └──────┬──────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ │ HTTP/HTTPS 请求 │
└─────────┼────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare 全球边缘网络 │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Cloudflare Workers │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ worker/index.ts (API 路由处理器) │ │ │
│ │ │ ┌────────────┐ ┌────────────┐ │ │ │
│ │ │ │ 认证中间件 │ │ 输入验证 │ │ │ │
│ │ │ └────────────┘ └────────────┘ │ │ │
│ │ │ ┌────────────────────────────────────┐ │ │ │
│ │ │ │ API 路由 │ │ │ │
│ │ │ │ - /api/groups (分组管理) │ │ │ │
│ │ │ │ - /api/sites (站点管理) │ │ │ │
│ │ │ │ - /api/configs (配置管理) │ │ │ │
│ │ │ │ - /api/login (用户认证) │ │ │ │
│ │ │ │ - /api/export (数据导出) │ │ │ │
│ │ │ │ - /api/import (数据导入) │ │ │ │
│ │ │ └────────────────────────────────────┘ │ │ │
│ │ └──────────────────┬──────────────────────────┘ │ │
│ └─────────────────────┼─────────────────────────────┘ │
└────────────────────────┼──────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ Cloudflare D1 │
│ (SQLite 数据库) │
│ ┌────────────────┐ │
│ │ groups 表 │ │
│ │ sites 表 │ │
│ │ configs 表 │ │
│ └────────────────┘ │
└──────────────────────┘核心设计模式
1. API 路由结构
所有 API 路由统一使用 /api/ 前缀，在 worker/index.ts 中集中处理：
- 认证中间件: 自动检查 JWT 令牌，验证受保护路由的访问权限
- 输入验证: 在处理前验证所有请求数据，防止恶意输入
- 路由分类:
groups: 分组的 CRUD 操作sites: 站点的 CRUD 操作configs: 全局配置管理login: 用户认证export/import: 数据的导出导入
2. 客户端架构（双模式设计）
系统提供两种 API 客户端实现，通过环境变量切换：
真实 API 客户端 (src/API/client.ts)
- 发送真实 HTTP 请求到 Cloudflare Workers 后端
- 用于生产环境和本地开发（需启动 Workers）
- 通过
VITE_USE_REAL_API=true启用
Mock 客户端 (src/API/mock.ts)
- 内存中的模拟数据和操作
- 用于快速开发和测试，无需后端依赖
- 默认开发模式
优势:
- 前端开发无需依赖后端启动
- 单元测试更加简单
- 统一的接口抽象，易于切换
3. 状态管理策略
采用组件级状态管理，避免全局状态库的复杂性：
- 无全局状态库: 不使用 Redux、Zustand 等
- React Hooks: 使用
useState、useEffect管理组件状态 - 状态缓存: API 响应缓存在组件状态中
- 拖拽状态: 由 DND Kit 自动管理
优势:
- 降低学习成本
- 减少依赖复杂度
- 适合中小型应用
4. 数据库设计（三表结构）
groups 表（分组）
- 存储导航分类
order_num: 排序字段is_public: 公开/私有标识（v1.1.0 新增）
sites 表（站点）
- 存储网站链接
group_id: 关联分组（外键，级联删除）order_num: 排序字段is_public: 公开/私有标识（v1.1.0 新增）
configs 表（配置）
- 键值对存储
- 存储站点标题、名称、自定义 CSS 等全局配置
数据流说明
读取数据流程（访客模式）
- 用户访问页面 → 前端应用加载
- 检查认证状态 → 调用
/api/auth/status - 获取分组和站点 → 调用
/api/groups-with-sites - 后端判断权限:
- 如果有有效令牌 → 返回所有数据
- 如果无令牌且
AUTH_REQUIRED_FOR_READ=false→ 仅返回is_public=1的数据 - 如果无令牌且
AUTH_REQUIRED_FOR_READ=true→ 返回 401 错误
- 前端渲染 → 显示可访问的分组和站点
写入数据流程（需认证）
- 用户操作 → 添加/编辑/删除分组或站点
- 发送请求 → 携带 JWT 令牌（Cookie 或 Authorization 头）
- 认证中间件验证:
- 验证令牌签名和有效期
- 无效 → 返回 401 错误
- 输入验证 → 检查数据格式和内容
- 数据库操作 → 使用参数化查询（防 SQL 注入）
- 返回结果 → 更新成功或错误信息
- 前端更新 → 刷新本地状态
拖拽排序流程
- 用户点击"编辑排序" → 进入排序模式
- 拖拽操作 → DND Kit 提供可视化交互
- 保存排序 → 批量更新
order_num字段 - API 调用:
- 分组排序 →
/api/group-orders - 站点排序 →
/api/site-orders
- 分组排序 →
- 后端事务更新 → 确保数据一致性
- 前端刷新 → 显示新顺序
安全架构
认证与授权流程
用户登录
↓
┌─────────────────────────────────────────┐
│ 1. 提交用户名和密码 │
└─────────────────┬───────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 2. Worker 验证凭证 │
│ - 检查用户名匹配 │
│ - bcrypt 验证密码哈希 │
│ - 检查速率限制（5次/15分钟） │
└─────────────────┬───────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 3. 生成 JWT 令牌 │
│ - 使用 Web Crypto API 签名 │
│ - HMAC-SHA256 算法 │
│ - 有效期：7天（或30天"记住我"） │
└─────────────────┬───────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 4. 令牌存储 │
│ - HttpOnly Cookie（主要，防XSS） │
│ - localStorage（兼容性备用） │
└─────────────────┬───────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 5. 后续请求自动携带令牌 │
│ - Cookie 自动发送 │
│ - 支持 Authorization 头备用 │
└─────────────────────────────────────────┘多层安全防护
1. 认证安全
- JWT 令牌签名（Web Crypto API）
- bcrypt 密码哈希（10轮盐值）
- HttpOnly Cookie（防止 XSS 窃取）
- 速率限制（防暴力破解）
2. 输入验证
- 请求体大小限制：1MB
- 深度验证（结构、类型、格式）
- 字段白名单（防止非法字段注入）
3. SQL 注入防护
- D1 参数化查询（
.bind()方法） - 永不拼接 SQL 字符串
- 字段白名单验证
4. XSS 防护
- React 自动转义输出
- 自定义 CSS 过滤危险模式
- URL 协议白名单
5. SSRF 防护
- URL 验证阻止私有 IP
- 仅允许 HTTPS 和 data:image/ 协议
6. CORS 配置
- 白名单来源验证
- 凭证支持（cookie 认证）
7. 错误处理
- 结构化日志（唯一错误 ID）
- 用户友好错误消息（不泄露细节）
- 服务端详细日志（调试用）
8. 类型安全
- TypeScript 严格模式
- 禁止隐式 any
- 严格空值检查
性能优化
前端优化
代码分割
- Vite 自动分割 chunks
- 动态导入减少初始加载
资源优化
- Tailwind CSS 按需打包
- Material UI 树摇（Tree Shaking）
- 图标使用 Data URL 或外部 CDN
渲染优化
- React 虚拟 DOM 高效更新
- 组件级状态避免全局重渲染
后端优化
边缘计算
- Cloudflare Workers 全球部署
- 就近处理请求，低延迟
数据库优化
- D1 索引（
is_public字段） - 批量操作（排序更新）
- 参数化查询性能优秀
- D1 索引（
缓存策略
- 静态资源 CDN 缓存
- API 响应前端缓存
访客模式性能（v1.1.0）
- 索引优化: 在
groups和sites表的is_public字段上创建索引 - 查询优化: 根据认证状态只查询需要的数据
- 减少数据传输: 访客仅接收公开内容
可扩展性设计
水平扩展
- Cloudflare Workers: 自动全球扩展，无需手动配置
- D1 数据库: Cloudflare 管理的分布式架构
- 无状态设计: Worker 无状态，可任意扩展实例
垂直扩展
- 数据库: D1 支持更大数据集
- Worker: Cloudflare 自动分配资源
- 存储: 可集成 R2 存储大文件（如图标）
功能扩展
- 插件系统: 通过自定义 CSS 和配置扩展
- API 扩展: 易于添加新路由和功能
- 前端扩展: 组件化设计，易于添加新 UI
开发与部署架构
本地开发环境
开发者电脑
│
├─ Vite Dev Server (前端热更新)
│ ↓
│ React 应用 (端口 5173)
│
└─ Wrangler Dev (Workers 本地模拟)
↓
Cloudflare Workers (端口 8787)
↓
本地 D1 数据库 (.wrangler/state/)生产部署架构
GitHub Repository
↓
git push
↓
开发者本地
↓
pnpm deploy
↓
Cloudflare 全球网络
├─ Workers (无服务器函数)
├─ D1 数据库 (分布式 SQLite)
└─ CDN (静态资源缓存)CI/CD 考虑
- 手动部署: 当前使用
pnpm deploy - 未来集成: 可集成 GitHub Actions 自动部署
- 数据库迁移: 需手动执行 SQL 迁移脚本
总结
NaviHive 的架构设计充分利用了 Cloudflare 平台的优势，实现了：
- 高性能: 全球边缘计算，低延迟响应
- 高安全: 多层安全防护，企业级标准
- 易维护: 清晰的代码结构，良好的文档
- 易扩展: 模块化设计，支持功能扩展
- 低成本: 无服务器架构，按需计费
这是一个适合个人、团队和企业使用的现代导航管理系统。