StoneFish.blog

现代化全栈博客系统

📋 目录

• 项目简介
• 技术栈
• 项目结构
• 快速开始
• 开发指南
• API 文档
• 测试
• 部署
• 贡献指南
• 许可证

🎯 项目简介

StoneFish.blog 是一个基于 Monorepo 架构的现代化全栈博客系统，采用前后端分离设计，提供优雅的公共博客界面和完善的管理后台功能。

核心特性

• ✨ 现代化技术栈: Vue 3 + Express 5 + TypeScript
• 🎨 优雅 UI: Nuxt UI v4 + Tailwind CSS v4
• 🚀 高性能: Vite 7 + 服务端缓存
• 🔐 安全认证: Better Auth 认证框架
• 📝 丰富内容: Markdown 支持、代码高亮、富文本编辑
• 🌍 国际化: 多语言支持 (i18n)
• 📦 Monorepo: pnpm workspaces 统一管理
• 🧪 测试覆盖: Vitest 单元测试 (覆盖率 80%+)

🛠 技术栈

前端

技术	版本	说明
Vue	3.5	渐进式 JavaScript 框架
Vite	7.1	下一代前端构建工具
Nuxt UI	4.1	Vue 3 UI 组件库
Tailwind CSS	4.1	实用优先的 CSS 框架
Pinia	3.0	Vue 状态管理
Vue Query	5.9	服务端状态缓存
Vue Router	4.6	官方路由管理器

后端

技术	版本	说明
Express	5.1	Node.js Web 框架
Drizzle ORM	0.44	轻量级 TypeScript ORM
PostgreSQL	-	关系型数据库
Redis	-	内存缓存数据库
Better Auth	1.3	认证框架
Zod	4.1	TypeScript 优先的验证库

开发工具

• 包管理器: pnpm 10.20 (Workspaces)
• 代码规范: @antfu/eslint-config
• 测试框架: Vitest 4.0
• Git 工作流: Husky + lint-staged + commitlint
• 类型检查: TypeScript 5.9

📁 项目结构

StoneFish.blog/
├── apps/
│   ├── client/          # 公共博客前端
│   │   ├── src/
│   │   │   ├── assets/      # 静态资源
│   │   │   ├── components/  # Vue 组件
│   │   │   ├── composables/ # 组合式函数
│   │   │   ├── layouts/     # 布局组件
│   │   │   ├── router/     # 路由配置
│   │   │   ├── stores/      # Pinia 状态
│   │   │   ├── views/       # 页面视图
│   │   │   └── types/       # 类型定义
│   │   └── package.json
│   │
│   ├── admin/           # 管理后台
│   │   ├── src/
│   │   │   └── ...         # 类似 client 结构
│   │   └── package.json
│   │
│   └── server/          # 后端 API 服务
│       ├── bin/            # 启动脚本
│       ├── config/         # 配置文件
│       ├── db/             # 数据库
│       │   ├── drizzle/    # 迁移文件
│       │   └── schema.ts   # Schema 定义
│       ├── middlewares/    # Express 中间件
│       ├── routes/         # 路由层
│       ├── services/       # 服务层
│       ├── utils/          # 工具函数
│       ├── validations/    # Zod 验证
│       └── package.json
│
└── packages/            # 共享包
    ├── api-client/      # API 请求封装
    ├── shared/         # 共享类型和工具
    ├── i18n/           # 国际化配置
    ├── tsconfig/       # TypeScript 配置
    └── eslint-config-custom/  # ESLint 配置

🚀 快速开始

前置要求

• Node.js: >= 20.0.0
• pnpm: >= 9.0.0
• PostgreSQL: >= 14.0
• Redis: >= 6.0

安装步骤

1. 克隆项目

git clone https://github.com/your-username/StoneFish.blog.git
cd StoneFish.blog

2. 安装依赖

pnpm install

3. 配置环境变量

# 复制环境变量模板
cp apps/server/.env.example apps/server/.env
cp apps/client/.env.example apps/client/.env
cp apps/admin/.env.example apps/admin/.env

编辑 apps/server/.env:

# 应用配置
NODE_ENV=development
PORT=3000
HOST=http://localhost:3000

# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/stonefish

# Redis
REDIS_URL=redis://localhost:6379

# Better Auth
BETTER_AUTH_SECRET=your-secret-key-min-32-chars-long-please-change-this
BETTER_AUTH_URL=http://localhost:3000

# CORS
CLIENT_URL=http://localhost:5173
ADMIN_URL=http://localhost:5174

编辑 apps/client/.env:

VITE_API_BASE_URL=http://localhost:3000
VITE_APP_TITLE=StoneFish.blog
VITE_APP_DESCRIPTION=现代化博客系统

4. 初始化数据库

cd apps/server

# 生成数据库迁移
pnpm db:generate

# 执行迁移
pnpm db:migrate

# 生成 Better Auth 表
pnpm auth:generate

5. 启动开发服务器

# 返回项目根目录
cd ../..

# 启动所有应用（并行）
pnpm dev

应用将在以下地址运行：

• 🌐 公共博客: http://localhost:5173
• 🔧 管理后台: http://localhost:5174
• 🚀 API 服务: http://localhost:3000

📚 开发指南

常用命令

全局命令（项目根目录）

# 开发模式（并行启动所有应用）
pnpm dev

# 构建所有包和应用
pnpm build

# 代码检查
pnpm lint

# 自动修复代码问题
pnpm lint:fix

# 代码格式化
pnpm format

# 运行所有测试
pnpm test

# 测试监听模式
pnpm test:watch

# 生成测试覆盖率报告
pnpm test:coverage

应用特定命令

Client App (apps/client):

cd apps/client

pnpm dev          # 启动开发服务器 (端口 5173)
pnpm build        # 构建生产版本
pnpm preview      # 预览生产构建
pnpm test         # 运行测试

Admin App (apps/admin):

cd apps/admin

pnpm dev          # 启动开发服务器 (端口 5174)
pnpm build        # 构建生产版本
pnpm preview      # 预览生产构建
pnpm test         # 运行测试

Server App (apps/server):

cd apps/server

pnpm dev          # 启动开发服务器 (tsx 热重载)
pnpm build        # 构建生产版本
pnpm start        # 启动生产服务器

# 数据库命令
pnpm db:generate  # 生成数据库迁移
pnpm db:migrate   # 执行数据库迁移
pnpm db:push      # 推送 Schema 到数据库
pnpm db:studio    # 打开 Drizzle Studio
pnpm db:seed      # 填充种子数据

# 认证
pnpm auth:generate  # 生成 Better Auth 表

# 测试
pnpm test         # 运行测试
pnpm test:watch   # 测试监听模式
pnpm test:coverage # 测试覆盖率

代码规范

TypeScript

• 严格类型检查，避免使用 any
• 优先使用类型推导
• 遵循项目配置的 TypeScript 规则

Vue 组件

• 使用 <script setup> 语法
• Props 和 Emits 需明确类型定义
• 遵循组合式 API 最佳实践

CSS 与样式

• ✅ 优先使用 Tailwind CSS 工具类
• ❌ 不在空文件夹中添加 .gitkeep 文件
• 使用 Tab 缩进（Vue 文件除外）

Git 工作流

项目使用 Conventional Commits 规范：

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

提交前会自动运行：

• ESLint 检查
• Prettier 格式化
• Commitlint 验证

📡 API 文档

文章 API

方法	端点	说明	鉴权
GET	/api/posts	获取文章列表	❌
GET	/api/posts/:slug	获取文章详情	❌
POST	/api/posts	创建文章	✅
PUT	/api/posts/:id	更新文章	✅
DELETE	/api/posts/:id	删除文章	✅

分类 API

方法	端点	说明	鉴权
GET	/api/categories	获取分类列表	❌
POST	/api/categories	创建分类	✅
PUT	/api/categories/:id	更新分类	✅
DELETE	/api/categories/:id	删除分类	✅

标签 API

方法	端点	说明	鉴权
GET	/api/tags	获取标签列表	❌
POST	/api/tags	创建标签	✅
PUT	/api/tags/:id	更新标签	✅
DELETE	/api/tags/:id	删除标签	✅

认证 API

方法	端点	说明
POST	/api/auth/signin	用户登录
POST	/api/auth/signout	用户登出
GET	/api/auth/session	获取会话信息

🧪 测试

测试覆盖率

项目要求测试覆盖率 >= 80%

运行测试

# 运行所有测试
pnpm test

# 监听模式
pnpm test:watch

# 生成覆盖率报告
pnpm test:coverage

测试类型

• 单元测试: 工具函数、服务层
• 集成测试: API 端点
• 组件测试: Vue 组件

🚢 部署

构建生产版本

# 构建所有包和应用
pnpm build

环境变量

确保生产环境配置了正确的环境变量：

• NODE_ENV=production
• DATABASE_URL (PostgreSQL 连接字符串)
• REDIS_URL (Redis 连接字符串)
• BETTER_AUTH_SECRET (至少 32 字符)
• CLIENT_URL / ADMIN_URL (前端地址)

数据库迁移

cd apps/server
pnpm db:migrate

启动生产服务器

cd apps/server
pnpm start

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献流程

1. Fork 本项目
2. 创建功能分支 (git checkout -b feat/AmazingFeature)
3. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
4. 推送到分支 (git push origin feat/AmazingFeature)
5. 开启 Pull Request

开发规范

• 遵循项目的代码风格和规范
• 确保所有测试通过
• 保持测试覆盖率 >= 80%
• 更新相关文档

📄 许可证

本项目采用 MIT License 许可证。

📞 联系方式

• 项目文档: /docs/项目蓝图与启动指南.md
• 开发指南: /docs/新项目开发指南.md
• 问题反馈: GitHub Issues

---

Made with ❤️ by StoneFish