浪漫色彩下的博客系统

AuroraBlog 系统文档

在代码的星空下，用诗意书写技术的浪漫

---

页面展示：

在这里插入图片描述

目录

1. 项目概述
2. 技术架构
3. 环境要求
4. 快速部署
5. 数据库设计
6. API接口文档
7. 前端页面说明
8. 配置说明
9. 目录结构
10. 常见问题

---

1. 项目概述

1.1 项目简介

Aurora Blog（极光博客）是一款充满浪漫主义色彩的前后端分离博客系统。采用极光(Aurora)主题设计，融合了流动渐变、星光粒子、玻璃拟态等现代视觉元素，为用户提供优雅的写作与阅读体验。

1.2 核心功能

功能模块	描述
用户认证	JWT Token 认证，支持登录/注册
文章管理	支持 Markdown 编辑、分类、标签、置顶
分类管理	文章分类的增删改查
标签管理	自定义标签颜色
文件上传	支持图片上传，本地存储
网站配置	可自定义首页背景、网站标题、作者信息
响应式设计	适配 PC、平板、手机

1.3 设计理念

极光色系：

• 紫罗兰 #8B5CF6
• 兰花紫 #A855F7
• 玫瑰粉 #EC4899
• 绯红 #F43F5E
• 晨曦金 #F59E0B

视觉元素：

• 极光流动渐变背景
• 星光粒子飘浮动画
• 玻璃拟态卡片效果
• 优雅的悬浮动效

---

2. 技术架构

2.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                      客户端                              │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│    │   PC     │  │  平板    │  │   手机   │            │
│    └────┬─────┘  └────┬─────┘  └────┬─────┘            │
└─────────┼─────────────┼─────────────┼──────────────────┘
          │             │             │
          └─────────────┼─────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│                   前端 (Vue 3)                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Vue Router│ │  Pinia  │ │  Axios  │ │Tailwind │       │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTP/REST API
                          ▼
┌─────────────────────────────────────────────────────────┐
│               后端 (Spring Boot 3.x)                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │
│  │   Security  │ │     JPA     │ │     JWT     │       │
│  └─────────────┘ └─────────────┘ └─────────────┘       │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   MySQL 8.0                             │
└─────────────────────────────────────────────────────────┘

2.2 后端技术栈

技术	版本	说明
Spring Boot	3.2.x	核心框架
Spring Security	6.x	安全认证
Spring Data JPA	3.x	ORM 框架
JWT (jjwt)	0.12.x	Token 认证
MySQL	8.0+	数据库
Lombok	1.18.x	简化代码
MapStruct	1.5.x	对象映射
SpringDoc	2.3.x	API 文档

2.3 前端技术栈

技术	版本	说明
Vue	3.4+	核心框架
Vite	5.x	构建工具
Vue Router	4.x	路由管理
Pinia	2.x	状态管理
Axios	1.x	HTTP 请求
Tailwind CSS	3.x	CSS 框架
GSAP	3.x	动画库
Day.js	1.x	日期处理

---

3. 环境要求

3.1 开发环境

软件	版本要求	说明
JDK	17+	后端运行环境
Maven	3.8+	后端构建工具
Node.js	18+	前端运行环境
npm	9+	前端包管理
MySQL	8.0+	数据库

3.2 生产环境

软件	版本要求	说明
JRE	17+	Java 运行环境
Nginx	1.20+	反向代理（可选）
MySQL	8.0+	数据库

---

4. 快速部署

4.1 数据库初始化

# 登录 MySQL
mysql -u root -p

# 执行初始化脚本
source /path/to/aurora-blog.sql

或使用 MySQL 客户端工具导入 aurora-blog.sql 文件。

默认账号信息：

• 用户名：admin
• 密码：admin123

4.2 后端部署

4.2.1 修改配置

编辑 aurora-backend/src/main/resources/application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/aurora_blog?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: your_username    # 修改为你的数据库用户名
    password: your_password    # 修改为你的数据库密码

jwt:
  secret: your_jwt_secret_key  # 建议修改为自定义密钥（至少32位）
  expiration: 86400000         # Token 有效期（毫秒）

file:
  upload:
    path: ./uploads/           # 文件上传路径

4.2.2 开发模式启动

cd aurora-backend
mvn spring-boot:run

4.2.3 生产模式打包

cd aurora-backend
mvn clean package -DskipTests

# 运行 JAR 包
java -jar target/aurora-blog-1.0.0.jar

后端服务默认运行在：http://localhost:8080

4.3 前端部署

4.3.1 安装依赖

cd aurora-frontend
npm install

4.3.2 开发模式启动

npm run dev

前端开发服务器运行在：http://localhost:5173

4.3.3 生产模式打包

npm run build

打包后的文件位于 dist 目录，可部署到 Nginx 等 Web 服务器。

4.4 Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/aurora-frontend/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 上传文件访问
    location /uploads {
        alias /path/to/uploads;
    }
}

---

5. 数据库设计

5.1 ER 图

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│   sys_user   │       │ blog_article │       │ blog_category│
├──────────────┤       ├──────────────┤       ├──────────────┤
│ id           │◄──────│ author_id    │       │ id           │
│ username     │       │ category_id  │──────►│ name         │
│ password     │       │ title        │       │ description  │
│ nickname     │       │ summary      │       │ sort_order   │
│ avatar       │       │ content      │       │ created_at   │
│ email        │       │ cover_image  │       └──────────────┘
│ role         │       │ view_count   │
│ created_at   │       │ like_count   │       ┌──────────────┐
│ updated_at   │       │ is_top       │       │   blog_tag   │
└──────────────┘       │ is_published │       ├──────────────┤
                       │ created_at   │       │ id           │
                       │ updated_at   │       │ name         │
                       └──────┬───────┘       │ color        │
                              │               └──────┬───────┘
                              │                      │
                       ┌──────▼──────────────────────▼───────┐
                       │         blog_article_tag            │
                       ├─────────────────────────────────────┤
                       │ article_id                          │
                       │ tag_id                              │
                       └─────────────────────────────────────┘

┌──────────────┐       ┌──────────────┐
│  sys_config  │       │sys_attachment│
├──────────────┤       ├──────────────┤
│ id           │       │ id           │
│ config_key   │       │ original_name│
│ config_value │       │ stored_name  │
│ description  │       │ file_path    │
└──────────────┘       │ file_type    │
                       │ file_size    │
                       │ uploader_id  │
                       │ created_at   │
                       └──────────────┘

5.2 表结构说明

5.2.1 sys_user（用户表）

字段	类型	说明
id	BIGINT	主键
username	VARCHAR(50)	用户名（唯一）
password	VARCHAR(255)	密码（BCrypt 加密）
nickname	VARCHAR(100)	昵称
avatar	VARCHAR(500)	头像 URL
email	VARCHAR(100)	邮箱
role	VARCHAR(20)	角色：USER/ADMIN
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

5.2.2 blog_article（文章表）

字段	类型	说明
id	BIGINT	主键
title	VARCHAR(200)	文章标题
summary	VARCHAR(500)	文章摘要
content	LONGTEXT	文章内容（Markdown）
cover_image	VARCHAR(500)	封面图片 URL
category_id	BIGINT	分类 ID
author_id	BIGINT	作者 ID
view_count	INT	浏览量
like_count	INT	点赞数
is_top	TINYINT	是否置顶
is_published	TINYINT	是否发布
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

5.2.3 blog_category（分类表）

字段	类型	说明
id	BIGINT	主键
name	VARCHAR(50)	分类名称
description	VARCHAR(200)	分类描述
sort_order	INT	排序序号
created_at	DATETIME	创建时间

5.2.4 blog_tag（标签表）

字段	类型	说明
id	BIGINT	主键
name	VARCHAR(50)	标签名称
color	VARCHAR(20)	标签颜色（HEX）

5.2.5 sys_config（系统配置表）

字段	类型	说明
id	BIGINT	主键
config_key	VARCHAR(100)	配置键（唯一）
config_value	TEXT	配置值
description	VARCHAR(200)	配置描述

预置配置项：

配置键	说明	默认值
site_title	网站标题	Aurora Blog
site_subtitle	网站副标题	在代码的星空下...
site_description	网站描述	一个充满浪漫主义...
site_keywords	SEO 关键词	博客,技术,生活...
home_background	首页背景图	空（使用极光动画）
author_name	作者名称	Aurora
author_signature	作者签名	愿你的代码如诗...
author_avatar	作者头像	空

---

6. API接口文档

6.1 接口概览

模块	基础路径	说明
认证	/api/auth	登录、注册、用户信息
文章	/api/blog/articles	文章 CRUD
分类	/api/blog/categories	分类管理
标签	/api/blog/tags	标签管理
配置	/api/config	网站配置
上传	/api/upload	文件上传

6.2 认证接口

6.2.1 用户登录

POST /api/auth/login

请求体：

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 86400000,
    "user": {
      "id": 1,
      "username": "admin",
      "nickname": "管理员",
      "role": "ADMIN"
    }
  }
}

6.2.2 用户注册

POST /api/auth/register

请求体：

{
  "username": "newuser",
  "password": "password123",
  "nickname": "新用户",
  "email": "user@example.com"
}

6.2.3 获取当前用户

GET /api/auth/profile
Authorization: Bearer {token}

6.3 文章接口

6.3.1 获取文章列表

GET /api/blog/articles?page=0&size=10&categoryId=1&keyword=搜索词

参数说明：

参数	类型	必填	说明
page	int	否	页码（从 0 开始）
size	int	否	每页数量（默认 10）
categoryId	long	否	分类 ID
keyword	string	否	搜索关键词

6.3.2 获取文章详情

GET /api/blog/articles/{id}

6.3.3 创建文章

POST /api/blog/articles
Authorization: Bearer {token}

请求体：

{
  "title": "文章标题",
  "summary": "文章摘要",
  "content": "Markdown 内容",
  "coverImage": "/api/upload/xxx.jpg",
  "categoryId": 1,
  "tagIds": [1, 2, 3],
  "isTop": false,
  "isPublished": true
}

6.3.4 更新文章

PUT /api/blog/articles/{id}
Authorization: Bearer {token}

6.3.5 删除文章

DELETE /api/blog/articles/{id}
Authorization: Bearer {token}

6.3.6 点赞文章

POST /api/blog/articles/{id}/like

6.4 分类接口

6.4.1 获取分类列表

GET /api/blog/categories

6.4.2 创建分类

POST /api/blog/categories
Authorization: Bearer {token}

请求体：

{
  "name": "分类名称",
  "description": "分类描述",
  "sortOrder": 1
}

6.5 标签接口

6.5.1 获取标签列表

GET /api/blog/tags

6.5.2 创建标签

POST /api/blog/tags
Authorization: Bearer {token}

请求体：

{
  "name": "标签名称",
  "color": "#8B5CF6"
}

6.6 配置接口

6.6.1 获取网站配置

GET /api/config

6.6.2 更新网站配置

PUT /api/config
Authorization: Bearer {token}

请求体：

{
  "site_title": "我的博客",
  "site_subtitle": "副标题",
  "author_name": "作者名",
  "home_background": "/api/upload/bg.jpg"
}

6.7 上传接口

6.7.1 上传图片

POST /api/upload/image
Authorization: Bearer {token}
Content-Type: multipart/form-data

参数：

• file: 图片文件

响应：

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "/api/upload/uuid-filename.jpg",
    "filename": "original-name.jpg"
  }
}

6.7.2 获取文件

GET /api/upload/{filename}

6.8 通用响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

状态码说明：

状态码	说明
200	成功
400	请求参数错误
401	未授权
403	无权限
404	资源不存在
500	服务器错误

---

7. 前端页面说明

7.1 页面路由

路径	页面	权限	说明
/	首页	公开	极光动画背景，展示最新文章
/articles	文章列表	公开	分页展示、分类筛选、搜索
/article/:id	文章详情	公开	Markdown 渲染、点赞分享
/login	登录页	公开	登录/注册表单
/admin	后台首页	需登录	仪表盘统计
/admin/articles	文章管理	需登录	文章列表、删除
/admin/articles/create	写文章	需登录	创建文章
/admin/articles/edit/:id	编辑文章	需登录	修改文章
/admin/categories	分类管理	需登录	分类 CRUD
/admin/tags	标签管理	需登录	标签 CRUD
/admin/config	网站配置	需登录	配置管理、预览

7.2 组件说明

src/
├── views/
│   ├── HomeView.vue          # 首页（极光背景+粒子效果）
│   ├── ArticleList.vue       # 文章列表
│   ├── ArticleDetail.vue     # 文章详情
│   ├── LoginView.vue         # 登录/注册
│   └── admin/
│       ├── AdminLayout.vue   # 后台布局
│       ├── Dashboard.vue     # 仪表盘
│       ├── ArticleManage.vue # 文章管理
│       ├── ArticleEdit.vue   # 文章编辑
│       ├── CategoryManage.vue# 分类管理
│       ├── TagManage.vue     # 标签管理
│       └── ConfigManage.vue  # 网站配置
├── stores/
│   ├── auth.js               # 认证状态
│   └── config.js             # 网站配置状态
├── api/
│   └── index.js              # API 封装
├── router/
│   └── index.js              # 路由配置
└── styles/
    └── main.css              # 全局样式（极光动画等）

---

8. 配置说明

8.1 后端配置 (application.yml)

server:
  port: 8080                    # 服务端口

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/aurora_blog
    username: root              # 数据库用户名
    password: root              # 数据库密码

  jpa:
    hibernate:
      ddl-auto: update          # 自动更新表结构
    show-sql: true              # 显示 SQL 日志

  servlet:
    multipart:
      max-file-size: 10MB       # 单文件最大
      max-request-size: 50MB    # 请求最大

jwt:
  secret: your-secret-key       # JWT 密钥（生产环境必须修改）
  expiration: 86400000          # Token 有效期（24小时）

file:
  upload:
    path: ./uploads/            # 上传目录
    allowed-types: image/jpeg,image/png,image/gif,image/webp,application/pdf
    max-size: 10485760          # 10MB

cors:
  allowed-origins: http://localhost:5173,http://localhost:3000

8.2 前端配置 (vite.config.js)

export default defineConfig({
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',  // 后端地址
        changeOrigin: true
      }
    }
  }
})

---

9. 目录结构

aurora-blog/
├── aurora-backend/                 # 后端项目
│   ├── pom.xml                     # Maven 配置
│   └── src/
│       └── main/
│           ├── java/com/aurora/blog/
│           │   ├── AuroraBlogApplication.java  # 启动类
│           │   ├── controller/     # 控制器
│           │   │   ├── AuthController.java
│           │   │   ├── ArticleController.java
│           │   │   ├── CategoryController.java
│           │   │   ├── TagController.java
│           │   │   ├── ConfigController.java
│           │   │   └── FileUploadController.java
│           │   ├── service/        # 服务层
│           │   ├── repository/     # 数据访问层
│           │   ├── entity/         # 实体类
│           │   ├── dto/            # 数据传输对象
│           │   ├── config/         # 配置类
│           │   ├── security/       # 安全相关
│           │   └── util/           # 工具类
│           └── resources/
│               ├── application.yml # 应用配置
│               ├── schema.sql      # 数据库结构
│               └── data.sql        # 初始数据
│
├── aurora-frontend/                # 前端项目
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── index.html
│   └── src/
│       ├── main.js                 # 入口文件
│       ├── App.vue                 # 根组件
│       ├── views/                  # 页面视图
│       ├── components/             # 公共组件
│       ├── api/                    # API 接口
│       ├── stores/                 # 状态管理
│       ├── router/                 # 路由配置
│       └── styles/                 # 样式文件
│
├── docs/                           # 文档
│   └── 系统文档.md
├── aurora-blog.sql                 # 数据库脚本
└── README.md                       # 项目说明

---

10. 常见问题

10.1 后端启动失败

问题： 数据库连接失败

解决方案：

1. 确认 MySQL 服务已启动
2. 检查 application.yml 中的数据库配置
3. 确认数据库 aurora_blog 已创建
4. 检查用户名密码是否正确

10.2 前端无法访问 API

问题： 请求返回 CORS 错误

解决方案：

1. 确认后端已启动
2. 检查 vite.config.js 中的代理配置
3. 确认后端 CORS 配置允许前端域名

10.3 上传图片失败

问题： 文件上传返回 401

解决方案：

1. 确认已登录并携带有效 Token
2. 检查文件类型是否在允许列表中
3. 检查文件大小是否超过限制

10.4 登录后无法跳转

问题： 登录成功但页面不跳转

解决方案：

1. 清除浏览器 LocalStorage
2. 检查 Token 是否正确保存
3. 查看浏览器控制台错误信息

10.5 修改默认密码

-- 生成新密码的 BCrypt 哈希
-- 可使用在线工具或 Java 代码生成

UPDATE sys_user
SET password = '$2a$10$新的BCrypt哈希'
WHERE username = 'admin';

---

结尾

Aurora Blog - 愿你的代码如诗，愿你的生活如画