Wraith 开发介绍文档

项目概述

Wraith 是一个基于 Nuxt.js 4.x 和 Cloudflare D1 构建的现代化博客系统，采用全栈 TypeScript 开发，部署在 Cloudflare Pages 平台。项目设计简洁高效，适合个人博客或小型内容管理系统的开发参考。

技术栈

核心框架

• Nuxt.js 4.x: 基于 Vue 3 的全栈框架，提供 SSR/SSG 能力
• Vue 3: 采用 Composition API 编写组件
• TypeScript: 全面的类型安全支持

样式与 UI

• Tailwind CSS: 原子化 CSS 框架，通过 @nuxtjs/tailwindcss 集成
• Markdown-it: Markdown 渲染引擎

数据库与部署

• Cloudflare D1: 基于 SQLite 的边缘数据库
• Cloudflare Pages: 无服务器部署平台
• Wrangler: Cloudflare 开发工具

开发工具

• Nitro: Nuxt 的服务端引擎，配置为 Cloudflare Pages 预设
• H3: Nitro 的 HTTP 服务器框架

项目架构

目录结构

wraith/
├── components/           # Vue 组件
│   ├── BackButton.vue
│   ├── BackToTop.vue
│   ├── DialogContainer.vue
│   ├── Dropdown.vue
│   ├── Loading.vue
│   ├── MarkdownEditor.vue
│   ├── MarkdownRenderer.vue
│   ├── Modal.vue
│   ├── PostForm.vue
│   ├── PostList.vue
│   ├── Toast.vue
│   └── ToastContainer.vue
├── composables/          # 组合式函数
│   ├── useApi.ts        # API 请求封装
│   ├── useAuth.ts       # 认证状态管理
│   ├── useDate.ts       # 日期工具
│   ├── useDialog.ts     # 对话框管理
│   └── useToast.ts      # 消息提示管理
├── constants/            # 常量定义
│   └── categories.ts    # 文章分类
├── layouts/              # 布局组件
│   └── default.vue      # 默认布局
├── middleware/           # 中间件
│   └── auth.global.ts   # 全局认证中间件
├── pages/                # 页面路由
│   ├── admin/           # 管理后台
│   │   ├── index.vue    # 管理首页
│   │   ├── login.vue    # 登录页
│   │   └── posts/       # 文章管理
│   │       ├── index.vue
│   │       ├── new.vue
│   │       └── edit/[id].vue
│   ├── blog/            # 博客页面
│   │   └── [id].vue     # 文章详情
│   └── index.vue        # 首页
├── server/               # 服务端代码
│   ├── api/             # API 路由
│   │   ├── auth/        # 认证 API
│   │   │   ├── login.post.ts
│   │   │   ├── logout.post.ts
│   │   │   └── me.get.ts
│   │   ├── posts/       # 文章 API
│   │   │   ├── [id].get.ts
│   │   │   ├── [id].put.ts
│   │   │   ├── [id].delete.ts
│   │   │   └── [id].edit.get.ts
│   │   ├── admin/       # 管理员 API
│   │   │   ├── posts.get.ts
│   │   │   ├── posts/[id].get.ts
│   │   │   └── cleanup-tokens.post.ts
│   │   ├── posts.get.ts
│   │   └── encrypt.post.ts
│   └── utils/           # 服务端工具
│       ├── auth.ts      # 认证工具
│       ├── db.ts        # 数据库连接
│       ├── password.ts  # 密码加密
│       └── token.ts     # Token 生成
├── types/                # TypeScript 类型定义
│   └── index.ts
├── public/               # 静态资源
├── schema.sql            # 数据库结构
├── nuxt.config.ts        # Nuxt 配置
├── wrangler.toml         # Cloudflare 配置
└── package.json          # 项目依赖

核心功能模块

1. 认证系统

认证机制

采用 Token + Cookie 混合认证方式：

• Token: 存储在 HTTP-only Cookie 中，由浏览器自动发送
• 用户信息: 存储在 localStorage 中，方便前端访问
• 有效期: 7 天自动过期
• 安全性: 每次登录自动删除该用户的旧 token

认证流程

登录流程 ([login.post.ts](file:///c:/code/wraith/server/api/auth/login.post.ts)):

1. 用户提交邮箱和密码
2. 后端验证用户凭证
3. 生成随机 token 并存储到数据库
4. 设置 Cookie（7 天有效期）
5. 返回用户信息

认证验证 ([auth.ts](file:///c:/code/wraith/server/utils/auth.ts)):

• verifyToken(): 验证 token 有效性
• requireAuth(): 要求用户已登录
• requireAdmin(): 要求管理员权限
• requireResourceOwnership(): 验证资源所有权

前端状态管理 ([useAuth.ts](file:///c:/code/wraith/composables/useAuth.ts)):

• currentUser: 当前用户信息
• getToken(): 获取 token
• setToken(): 设置 token
• fetchCurrentUser(): 获取当前用户信息
• getUserFromStorage(): 从 localStorage 读取用户信息

路由保护 ([auth.global.ts](file:///c:/code/wraith/middleware/auth.global.ts)):

• 保护所有 /admin 路由（除登录页）
• 验证 token 有效性
• 未认证用户重定向到登录页

2. 文章管理系统

数据模型

Post 接口 ([types/index.ts](file:///c:/code/wraith/types/index.ts#L1-L10)):

interface Post {
  id: number;
  user_id?: number;
  title: string;
  excerpt: string;
  content?: string;
  category?: string;
  tags?: string[];
  published?: number;
  created_at: string;
  updated_at?: string;
}

API 端点

公开文章列表 ([posts.get.ts](file:///c:/code/wraith/server/api/posts.get.ts)):

• 支持分页（page, limit）
• 支持排序（latest, oldest, title-asc, title-desc）
• 支持搜索（title, excerpt）
• 支持分类筛选
• 支持按作者筛选
• 支持包含草稿（include_unpublished）

文章详情 ([posts/[id].get.ts](file:///c:/code/wraith/server/api/posts/[id].get.ts)):

• 只返回已发布的文章
• 包含作者邮箱信息
• 解析 JSON 格式的 tags

文章更新 ([posts/[id].put.ts](file:///c:/code/wraith/server/api/posts/[id].put.ts)):

• 验证资源所有权
• 支持部分更新
• 自动更新 updated_at 字段

文章删除 ([posts/[id].delete.ts](file:///c:/code/wraith/server/api/posts/[id].delete.ts)):

• 验证资源所有权
• 软删除或硬删除

3. API 请求封装

useApi ([composables/useApi.ts](file:///c:/code/wraith/composables/useApi.ts)):

• 统一的 API 请求封装
• 自动处理认证错误（401/403）
• 支持查询参数、请求体
• 提供便捷方法：get, post, put, del, patch

4. UI 组件系统

基础组件

• Loading: 加载状态指示器
• Modal: 模态框组件
• Dropdown: 下拉选择器
• Toast: 消息提示
• Dialog: 对话框

业务组件

• PostForm: 文章表单（支持 Markdown 编辑）
• PostList: 文章列表
• MarkdownEditor: Markdown 编辑器
• MarkdownRenderer: Markdown 渲染器

状态管理

• useToast: Toast 消息管理
• useDialog: 对话框管理

数据库设计

表结构

users 表:

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  role TEXT DEFAULT 'user',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

tokens 表:

CREATE TABLE tokens (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id INTEGER NOT NULL,
  token TEXT UNIQUE NOT NULL,
  expires_at DATETIME NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

posts 表:

CREATE TABLE posts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id INTEGER NOT NULL,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  excerpt TEXT,
  category TEXT,
  tags TEXT,
  published INTEGER DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

默认数据

• 管理员账号：admin@wraith.com / admin123
• 普通用户：editor@wraith.com / admin123

配置说明

Nuxt 配置 ([nuxt.config.ts](file:///c:/code/wraith/nuxt.config.ts))

export default defineNuxtConfig({
  compatibilityDate: "2025-07-15",
  devtools: { enabled: true },
  modules: ["@nuxtjs/tailwindcss"],
  nitro: {
    preset: "cloudflare-pages",
    experimental: {
      asyncContext: true,
    },
  },
  runtimeConfig: {
    jwtSecret: process.env.JWT_SECRET || "change-me-to-a-strong-secret",
    adminEmail: process.env.ADMIN_EMAIL || "",
    adminPasswordHash: process.env.ADMIN_PASSWORD_HASH || "",
  },
});

Cloudflare 配置 ([wrangler.toml](file:///c:/code/wraith/wrangler.toml))

配置 D1 数据库绑定和 Pages 部署设置。

开发工作流

本地开发

1. 安装依赖:

npm install

2. 初始化数据库:

npx wrangler d1 execute wraith_db --local --file=schema.sql

3. 启动开发服务器:

npm run dev

应用将在 http://localhost:3000 启动

数据库管理

本地数据库:

• 位置：.wrangler/state/v3/d1/miniflare-D1DatabaseObject/
• 查询：npx wrangler d1 execute wraith_db --local --command="SQL"
• 导出：npx wrangler d1 export wraith_db --local --output=backup.sql

远程数据库:

• 查询：npx wrangler d1 execute wraith_db --remote --command="SQL"
• 导出：npx wrangler d1 export wraith_db --remote --output=backup.sql
• 同步：npx wrangler d1 execute wraith_db --remote --file=schema.sql

构建与部署

构建:

npm run build

部署到 Cloudflare Pages:

npx wrangler pages deploy .output/public

安全特性

1. 密码加密: 使用 SHA-256 哈希算法
2. Token 验证: 服务端验证 token 有效性和过期时间
3. 权限控制: 基于角色的访问控制（RBAC）
4. 资源所有权: 用户只能访问自己的资源（管理员除外）
5. SQL 注入防护: 使用参数化查询
6. XSS 防护: Markdown 渲染时进行转义

扩展建议

功能扩展

• [ ] 文章评论系统
• [ ] 文章点赞/收藏
• [ ] 用户头像上传
• [ ] 富文本编辑器
• [ ] 图片上传与管理
• [ ] SEO 优化
• [ ] RSS 订阅
• [ ] 多语言支持

技术优化

• [ ] 添加单元测试
• [ ] 添加 E2E 测试
• [ ] 性能监控
• [ ] 错误日志收集
• [ ] CDN 集成
• [ ] 缓存策略优化

常见问题

登录时出现 “no such table: users” 错误

数据库表未创建，运行：

npx wrangler d1 execute wraith_db --local --file=schema.sql

Token 过期处理

系统自动处理 token 过期：

• 前端检测到 401 错误自动跳转登录页
• 每次登录自动删除旧 token
• 可通过 API 清理过期 token

本地开发数据库位置

本地数据库文件位于： .wrangler/state/v3/d1/miniflare-D1DatabaseObject/

开发规范

代码风格

• 使用 TypeScript 进行类型检查
• 遵循 Vue 3 Composition API 最佳实践
• 组件使用 PascalCase 命名
• 文件名使用 kebab-case 命名

API 设计

• RESTful 风格
• 统一的错误处理
• 使用 HTTP 状态码表示请求状态
• 返回 JSON 格式数据

提交规范

建议使用 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构
• test: 测试相关
• chore: 构建/工具相关

相关资源

• Nuxt.js 官方文档
• Vue 3 官方文档
• Cloudflare D1 文档
• Cloudflare Pages 文档
• Tailwind CSS 文档

许可证

MIT