# next-blog

**Repository Path**: jacklon_66/next-blog

## Basic Information

- **Project Name**: next-blog
- **Description**: nextjs  博客项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-07
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 我的博客系统

一个基于 Next.js 15 构建的现代化全栈博客系统，支持文章管理、用户认证、评论系统、数据统计等完整功能。

## 📋 目录

- [项目概述](#项目概述)
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [API 文档](#api-文档)
- [数据库设计](#数据库设计)
- [部署指南](#部署指南)
- [开发指南](#开发指南)
- [贡献指南](#贡献指南)

## 🎯 项目概述

这是一个功能完整的现代化博客系统，采用 Next.js 15 和 TypeScript 构建，提供了从内容创作到数据统计的全套解决方案。系统支持多用户、角色权限、实时统计等企业级功能。

### 核心亮点

- 🚀 **现代化技术栈**：Next.js 15 + React 19 + TypeScript
- 🎨 **美观的 UI**：基于 Radix UI 和 Tailwind CSS
- 📝 **强大的编辑器**：集成 ByteMD Markdown 编辑器
- 🔐 **安全认证**：JWT + 密码加密 + 角色权限
- 📊 **数据统计**：实时浏览量统计和数据分析
- 🗄️ **类型安全**：Prisma ORM + Zod 验证

## ✨ 功能特性

### 🏠 前端功能

#### 博客展示
- **响应式首页**：展示最新文章和网站信息
- **文章详情页**：支持 Markdown 渲染和语法高亮
- **标签系统**：文章分类和标签筛选
- **搜索功能**：快速查找文章内容
- **评论系统**：用户互动和内容讨论

#### 用户体验
- **移动端适配**：完全响应式设计
- **加载优化**：服务端渲染和静态生成
- **SEO 友好**：元数据优化和结构化数据
- **无障碍支持**：符合 WCAG 标准

### 🔧 管理后台

#### 内容管理
- **文章管理**：创建、编辑、删除、发布文章
- **Markdown 编辑器**：实时预览、语法高亮、数学公式
- **媒体管理**：图片上传和管理
- **标签管理**：创建和管理文章标签
- **评论审核**：管理用户评论

#### 数据统计
- **概览仪表板**：关键指标一目了然
- **文章统计**：发布数量、浏览量、热门文章
- **用户统计**：注册用户、活跃度分析
- **评论统计**：评论数量、审核状态
- **标签分析**：热门标签和使用频率

#### 系统设置
- **网站配置**：基本信息、Logo、描述
- **用户权限**：注册设置、角色管理
- **内容策略**：评论规则、标签限制
- **系统维护**：维护模式、缓存设置

### 🔐 用户系统

#### 认证授权
- **JWT 认证**：安全的令牌机制
- **密码加密**：bcrypt 加密存储
- **角色权限**：用户和管理员角色
- **会话管理**：自动登录和登出

#### 用户管理
- **用户注册**：邮箱验证和账号创建
- **个人资料**：用户信息管理
- **权限控制**：基于角色的访问控制

## 🏗️ 技术架构

### 前端技术栈

```mermaid
graph TB
    A[Next.js 15] --> B[React 19]
    A --> C[TypeScript]
    A --> D[App Router]
    
    E[UI 组件] --> F[Radix UI]
    E --> G[Tailwind CSS]
    E --> H[Lucide Icons]
    
    I[编辑器] --> J[ByteMD]
    I --> K[Markdown 渲染]
    I --> L[语法高亮]
    
    M[状态管理] --> N[React Hooks]
    M --> O[Context API]
```

### 后端技术栈

```mermaid
graph TB
    A[Next.js API Routes] --> B[Prisma ORM]
    A --> C[JWT 认证]
    A --> D[Zod 验证]
    
    B --> E[SQLite 数据库]
    B --> F[数据模型]
    
    G[中间件] --> H[路由保护]
    G --> I[认证检查]
    
    J[文件处理] --> K[Multer]
    J --> L[图片上传]
```

### 数据库设计

```mermaid
erDiagram
    User ||--o{ Post : "creates"
    User ||--o{ Comment : "writes"
    Post ||--o{ Comment : "has"
    Post ||--o{ PostTag : "tagged"
    Tag ||--o{ PostTag : "categorizes"
    
    User {
        string id PK
        string email UK
        string name
        string password
        enum role
        datetime createdAt
        datetime updatedAt
    }
    
    Post {
        string id PK
        string title
        text content
        string excerpt
        string slug UK
        enum status
        string coverImage
        int viewCount
        string authorId FK
        datetime createdAt
        datetime updatedAt
        datetime publishedAt
    }
    
    Tag {
        string id PK
        string name UK
        datetime createdAt
    }
    
    Comment {
        string id PK
        text content
        string author
        string email
        string postId FK
        enum status
        datetime createdAt
        datetime updatedAt
    }
    
    PostTag {
        string id PK
        string postId FK
        string tagId FK
    }
```

## 🚀 快速开始

### 环境要求

- Node.js 18+ 
- npm 或 yarn
- Git

### 1. 克隆项目

```bash
git clone <repository-url>
cd my-app
```

### 2. 安装依赖

```bash
npm install
```

### 3. 环境配置

创建 `.env.local` 文件：

```env
# 数据库
DATABASE_URL="file:./dev.db"

# JWT 密钥
JWT_SECRET="your-super-secret-jwt-key-here"

# 应用配置
NEXT_PUBLIC_APP_URL="http://localhost:3000"
```

### 4. 初始化数据库

```bash
# 推送数据库模式
npx prisma db push

# 生成 Prisma 客户端
npx prisma generate

# 运行种子数据（可选）
npx prisma db seed
```

### 5. 启动开发服务器

```bash
npm run dev
```

访问 [http://localhost:3000](http://localhost:3000) 查看应用。

### 6. 默认账号

- **管理员账号**：admin@example.com / admin123
- **普通用户**：user@example.com / user123

## 📁 项目结构

```
my-app/
├── app/                          # Next.js App Router
│   ├── admin/                    # 管理后台
│   │   ├── layout.tsx           # 管理后台布局
│   │   ├── page.tsx             # 仪表板
│   │   ├── posts/               # 文章管理
│   │   │   ├── page.tsx         # 文章列表
│   │   │   ├── new/             # 新建文章
│   │   │   └── [id]/edit/       # 编辑文章
│   │   ├── stats/               # 数据统计
│   │   └── settings/            # 系统设置
│   ├── api/                     # API 路由
│   │   ├── auth/                # 认证相关
│   │   ├── posts/               # 文章相关
│   │   ├── comments/            # 评论相关
│   │   ├── stats/               # 统计数据
│   │   └── upload/              # 文件上传
│   ├── blog/                    # 博客展示
│   │   └── [slug]/              # 文章详情页
│   ├── login/                   # 登录页面
│   ├── globals.css              # 全局样式
│   ├── layout.tsx               # 根布局
│   └── page.tsx                 # 首页
├── components/                   # 可复用组件
│   ├── ui/                      # UI 组件库
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── input.tsx
│   │   └── ...
│   ├── BlogCard.tsx             # 博客卡片
│   ├── Header.tsx               # 网站头部
│   ├── MarkdownEditor.tsx       # Markdown 编辑器
│   ├── MarkdownViewer.tsx       # Markdown 查看器
│   └── ViewTracker.tsx          # 浏览量跟踪
├── lib/                         # 工具库
│   ├── auth.ts                  # 认证工具
│   ├── data.ts                  # 数据访问层
│   ├── prisma.ts                # Prisma 客户端
│   ├── types.ts                 # 类型定义
│   ├── utils.ts                 # 工具函数
│   └── validations.ts           # 数据验证
├── prisma/                      # 数据库相关
│   ├── schema.prisma            # 数据库模式
│   └── seed.ts                  # 种子数据
├── public/                      # 静态资源
├── middleware.ts                # Next.js 中间件
├── next.config.ts               # Next.js 配置
├── tailwind.config.ts           # Tailwind 配置
├── tsconfig.json                # TypeScript 配置
└── package.json                 # 项目依赖
```

## 📚 API 文档

### 认证相关

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "admin123"
}
```

**响应：**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_id",
    "email": "admin@example.com",
    "name": "Admin",
    "role": "ADMIN"
  }
}
```

#### 用户注册
```http
POST /api/auth/register
Content-Type: application/json

{
  "name": "用户名",
  "email": "user@example.com",
  "password": "password123"
}
```

### 文章管理

#### 获取文章列表
```http
GET /api/posts?status=published&page=1&limit=10
Authorization: Bearer <token>
```

#### 创建文章
```http
POST /api/posts
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "文章标题",
  "content": "文章内容（Markdown）",
  "excerpt": "文章摘要",
  "tags": ["标签1", "标签2"],
  "status": "DRAFT"
}
```

#### 更新文章
```http
PUT /api/posts/[id]
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "更新后的标题",
  "content": "更新后的内容",
  "status": "PUBLISHED"
}
```

#### 删除文章
```http
DELETE /api/posts/[id]
Authorization: Bearer <token>
```

#### 增加浏览量
```http
POST /api/posts/[id]/view
```

### 评论管理

#### 获取评论
```http
GET /api/comments?postId=xxx&status=approved
```

#### 创建评论
```http
POST /api/comments
Content-Type: application/json

{
  "content": "评论内容",
  "author": "评论者姓名",
  "email": "commenter@example.com",
  "postId": "post_id"
}
```

#### 审核评论
```http
PUT /api/comments/[id]
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "APPROVED"
}
```

### 统计数据

#### 获取统计数据
```http
GET /api/stats
Authorization: Bearer <token>
```

**响应：**
```json
{
  "overview": {
    "totalPosts": 25,
    "publishedPosts": 20,
    "draftPosts": 5,
    "totalComments": 150,
    "pendingComments": 3,
    "totalUsers": 10,
    "totalViews": 2500
  },
  "recentPosts": [...],
  "popularTags": [...]
}
```

## 🗄️ 数据库设计

### 用户表 (User)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键，CUID |
| email | String | 邮箱，唯一 |
| name | String | 用户姓名 |
| password | String | 加密密码 |
| role | Enum | 用户角色 (USER/ADMIN) |
| createdAt | DateTime | 创建时间 |
| updatedAt | DateTime | 更新时间 |

### 文章表 (Post)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键，CUID |
| title | String | 文章标题 |
| content | Text | 文章内容（Markdown） |
| excerpt | String | 文章摘要 |
| slug | String | URL 别名，唯一 |
| status | Enum | 文章状态 (DRAFT/PUBLISHED/ARCHIVED) |
| coverImage | String | 封面图片 URL |
| viewCount | Int | 浏览量，默认 0 |
| authorId | String | 作者 ID，外键 |
| createdAt | DateTime | 创建时间 |
| updatedAt | DateTime | 更新时间 |
| publishedAt | DateTime | 发布时间 |

### 标签表 (Tag)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键，CUID |
| name | String | 标签名称，唯一 |
| createdAt | DateTime | 创建时间 |

### 评论表 (Comment)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键，CUID |
| content | Text | 评论内容 |
| author | String | 评论者姓名 |
| email | String | 评论者邮箱 |
| postId | String | 文章 ID，外键 |
| status | Enum | 评论状态 (PENDING/APPROVED/REJECTED) |
| createdAt | DateTime | 创建时间 |
| updatedAt | DateTime | 更新时间 |

### 文章标签关联表 (PostTag)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键，CUID |
| postId | String | 文章 ID，外键 |
| tagId | String | 标签 ID，外键 |

## 🚀 部署指南

### Vercel 部署（推荐）

1. **连接 GitHub**
   - 将代码推送到 GitHub 仓库
   - 在 Vercel 中导入项目

2. **环境变量配置**
   ```env
   DATABASE_URL="your-production-database-url"
   JWT_SECRET="your-production-jwt-secret"
   NEXT_PUBLIC_APP_URL="https://your-domain.vercel.app"
   ```

3. **数据库设置**
   - 使用 Vercel Postgres 或 PlanetScale
   - 运行数据库迁移

4. **部署**
   - Vercel 会自动构建和部署
   - 支持自动 HTTPS 和 CDN

### Docker 部署

1. **创建 Dockerfile**
   ```dockerfile
   FROM node:18-alpine
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   COPY . .
   RUN npm run build
   EXPOSE 3000
   CMD ["npm", "start"]
   ```

2. **构建和运行**
   ```bash
   docker build -t my-blog .
   docker run -p 3000:3000 my-blog
   ```

### 传统服务器部署

1. **服务器要求**
   - Node.js 18+
   - PM2 进程管理
   - Nginx 反向代理

2. **部署步骤**
   ```bash
   # 克隆代码
   git clone <repository-url>
   cd my-app
   
   # 安装依赖
   npm ci --production
   
   # 构建应用
   npm run build
   
   # 使用 PM2 启动
   pm2 start npm --name "my-blog" -- start
   ```

## 🛠️ 开发指南

### 开发环境设置

1. **安装开发依赖**
   ```bash
   npm install
   ```

2. **启动开发服务器**
   ```bash
   npm run dev
   ```

3. **数据库管理**
   ```bash
   # 查看数据库
   npx prisma studio
   
   # 重置数据库
   npx prisma db push --force-reset
   ```

### 代码规范

- **TypeScript**：严格类型检查
- **ESLint**：代码质量检查
- **Prettier**：代码格式化
- **命名规范**：camelCase 变量，PascalCase 组件

### 提交规范

```bash
# 功能开发
git commit -m "feat: 添加文章搜索功能"

# 问题修复
git commit -m "fix: 修复登录页面样式问题"

# 文档更新
git commit -m "docs: 更新 API 文档"

# 样式调整
git commit -m "style: 优化移动端响应式布局"
```

### 测试

```bash
# 运行类型检查
npm run type-check

# 运行代码检查
npm run lint

# 构建测试
npm run build
```

## 🤝 贡献指南

### 如何贡献

1. **Fork 项目**
2. **创建功能分支**：`git checkout -b feature/AmazingFeature`
3. **提交更改**：`git commit -m 'Add some AmazingFeature'`
4. **推送分支**：`git push origin feature/AmazingFeature`
5. **创建 Pull Request**

### 贡献类型

- 🐛 Bug 修复
- ✨ 新功能开发
- 📚 文档改进
- 🎨 UI/UX 优化
- ⚡ 性能优化
- 🔒 安全性改进

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

感谢以下开源项目的支持：

- [Next.js](https://nextjs.org/) - React 全栈框架
- [Prisma](https://prisma.io/) - 现代数据库 ORM
- [Radix UI](https://www.radix-ui.com/) - 无样式组件库
- [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架
- [ByteMD](https://bytemd.js.org/) - Markdown 编辑器
- [Lucide](https://lucide.dev/) - 美观的图标库

## 📞 联系方式

- **项目维护者**：Your Name
- **邮箱**：your.email@example.com
- **GitHub**：[@yourusername](https://github.com/yourusername)

---

⭐ 如果这个项目对你有帮助，请给它一个星标！