# HiBlog **Repository Path**: wuxianfeicn/HiBlog ## Basic Information - **Project Name**: HiBlog - **Description**: 练手的个人小博客，基于SpringBoot+Vue3js+ElementPlus开发。 - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 1 - **Created**: 2019-05-24 - **Last Updated**: 2026-02-16 ## Categories & Tags **Categories**: blog **Tags**: None ## README # HiBlog 项目 ## 1. 项目简介 HiBlog是一个基于Vue 3和Spring Boot的全栈博客管理系统，支持博客文章管理、用户管理、角色权限管理等功能。 ### 1.1 功能特性 - **博客文章管理**：支持文章的创建、编辑、删除、发布和草稿管理 - **用户管理**：支持用户注册、登录、权限分配和个人信息管理 - **角色权限管理**：基于Spring Security的细粒度权限控制 - **标签管理**：支持文章标签的创建、编辑和删除 - **文件管理**：支持上传和管理二进制文件 - **国际化支持**：内置多语言支持 - **响应式设计**：适配不同屏幕尺寸的设备 - **API文档**：集成Swagger UI，提供详细的API文档 - **系统参数配置**：支持系统级别的参数配置 - **服务端渲染(SSR)**：对博客相关页面提供SSR支持，提高首屏加载速度和SEO友好性 ## 2. 技术栈 ### 2.1 前端 - Vue 3 + TypeScript：现代前端框架，提供类型安全 - Element Plus：基于Vue 3的UI组件库 - Vite：快速的前端构建工具 - Pinia：Vue 3的状态管理库 - Vue Router：Vue的官方路由管理器 - Playwright：端到端测试框架 - Vitest：单元测试框架 ### 2.2 后端 - Spring Boot 3：现代化的Java后端框架 - MyBatis Plus：增强的MyBatis ORM框架 - MySQL 8.0+：关系型数据库 - Spring Security：安全框架，提供认证和授权 - SpringDoc OpenAPI：自动生成API文档 - Gradle：构建工具 ## 3. 项目结构 ``` ├── HiBlogVue/ # 前端项目目录 │ ├── public/ # 静态资源 │ │ ├── img/ # 图片资源 │ ├── src/ # 源代码 │ │ ├── components/ # Vue组件 │ │ │ ├── admin/ # 管理后台组件 │ │ │ ├── common/ # 通用组件 │ │ │ ├── portal/ # 前台组件 │ │ ├── i18n/ # 国际化配置 │ │ ├── locales/ # 语言包 │ │ ├── App.vue # 根组件 │ │ ├── entry-server.ts # SSR入口 │ │ ├── main.ts # 应用入口 │ │ ├── router.ts # 路由配置 │ │ ├── store.ts # 状态管理 │ ├── tests/ # 测试目录 │ │ ├── appium/ # 移动设备测试 │ │ ├── components/ # 组件测试 │ │ ├── setup/ # 测试设置 │ ├── .env # 环境配置 │ ├── eslint.config.ts # ESLint配置 │ ├── index.html # HTML模板 │ ├── package.json # 前端项目配置 │ ├── postcss.config.cjs # PostCSS配置 │ ├── server.ts # SSR服务器入口 │ ├── tsconfig.json # TypeScript配置 │ ├── vite.config.ts # Vite配置 │ ├── vitest.config.ts # Vitest配置 ├── gradle/ # Gradle包装器 │ ├── wrapper/ # Gradle包装器文件 ├── src/ # 后端项目目录 │ ├── main/java/ # Java源代码 │ │ ├── run/yiqi/blog/ # 核心代码 │ │ │ ├── common/ # 公共模块 │ │ │ │ └── exception/ # 异常处理 │ │ │ ├── config/ # 配置类 │ │ │ ├── controller/ # 控制器 │ │ │ ├── model/ # 数据模型 │ │ │ │ └── mapper/ # MyBatis映射接口 │ │ │ ├── service/ # 服务层 │ │ │ ├── vo/ # 视图对象 │ │ │ ├── BlogApplication.java # 应用启动类 │ │ │ ├── InitDatabase.java # 数据库初始化 │ │ └── run/yiqi/util/ # 工具类 │ ├── main/resources/ # 资源文件 │ │ ├── mapper/ # MyBatis映射文件 │ │ ├── templates/ # 模板文件 │ │ ├── application.yml # 应用配置 │ │ ├── create_db_tbl.sql # 数据库初始化脚本 │ │ └── init.sql # 数据初始化脚本 │ ├── test/java/ # Java测试代码 │ │ ├── run/yiqi/blog/ # 测试代码 │ │ │ ├── common/ # 公共模块测试 │ │ │ ├── controller/ # 控制器测试 │ │ │ ├── model/ # 数据模型测试 │ │ │ └── service/ # 服务层测试 │ │ └── run/yiqi/util/ # 工具类测试 │ ├── test/resources/ # 测试资源文件 │ │ └── application-test.yml # 测试配置 ├── .gitignore # Git忽略文件 ├── LICENSE # 许可证文件 ├── README.MD # 项目说明文档 ├── build.gradle # Gradle构建配置 ├── gradlew # Gradle包装器脚本（Linux/Mac） ├── gradlew.bat # Gradle包装器脚本（Windows） ├── settings.gradle # Gradle设置文件 ``` ## 4. 环境要求 - JDK 21+ - Node.js 20.19.0+ 或 22.12.0+ - npm 9.0.0+ 或 10.0.0+ - MySQL 8.0+ - Gradle 9.0+（可选，项目包含gradle wrapper） ## 5. 部署 ### 5.1 前提 - MySQL 8.0+ 已正确安装并运行 - 已创建数据库和用户，应用能通过 localhost:3306 访问数据库（默认端口） - 数据库配置： 1. 创建数据库：通过 DBeaver 等工具执行 SQL 脚本 `src/main/resources/create_db_tbl.sql` 2. 数据库初始化数据无需手工操作，jar 包启动后自动插入初始化数据 ### 5.2 部署架构 项目采用分开部署的架构： - **前端SSR服务器**：基于Node.js运行，使用3000端口 - **后端API服务器**：基于Java运行，使用9090端口 ### 5.3 通过源代码部署 1. **克隆项目**： ```bash git clone <项目地址> cd HiBlog ``` 2. **前端安装和启动**： ```bash # 进入前端目录 cd HiBlogVue # 安装依赖 npm install # 开发环境启动 npm run dev # 启动SSR开发服务器 npm run dev:ssr ``` 3. **后端安装和启动**： ```bash # 回到项目根目录 cd .. # 清理项目 ./gradlew.bat clean # 构建项目 ./gradlew.bat build # 启动测试服务器 ./gradlew.bat bootRun ``` ### 5.4 访问 1. **访问应用**： - 前端页面：http://localhost:3000 - 管理后台：http://localhost:3000/admin - 博客列表：http://localhost:3000/portal/blogs.html - 博客详情：http://localhost:3000/portal/blog/blogid/{blogId}.html 2. **默认账户**： - 管理员账户：admin / admin - 访客账户：guest / admin 3. **API文档**： - Swagger UI：http://localhost:9090/swagger-ui.html - API文档JSON：http://localhost:9090/v3/api-docs 4. **Swagger接口测试指南**： 1. **访问Swagger UI**：启动服务后，浏览器打开 http://localhost:9090/swagger-ui.html 2. **选择接口**：在Swagger UI页面选择对应接口，点击"Try it out"按钮 3. **填写参数**：根据接口要求填写测试参数 4. **执行测试**：点击"Execute"按钮发送请求并查看响应结果 ## 6. 环境变量配置 后端支持通过环境变量配置敏感信息： - `DB_URL`：数据库连接URL - `DB_USERNAME`：数据库用户名 - `DB_PASSWORD`：数据库密码 - `ALLOWED_ORIGIN`：允许的跨域来源（生产环境） - `SERVER_PORT`：服务器端口（默认9090） ## 7. 安全配置 - 使用BCryptPasswordEncoder加密存储密码 - 管理员API需要ADMIN角色才能访问 - 启用了基于角色的访问控制 - 支持JWT令牌认证（可选） ## 8. 开发和测试指导 ### 8.1 构建指南 1. **构建前端**： ```bash cd HiBlogVue ; npm run build:ssr ``` 2. **构建后端**： ```bash cd .. ; ./gradlew build ``` ### 8.2 前端开发 1. 修改 `HiBlogVue/src` 目录下的代码 2. 组件开发：在 `components` 目录下创建新组件 3. 页面开发：在 `views` 目录下创建新页面 4. 路由配置：在 `router` 目录下配置路由 5. 状态管理：在 `stores` 目录下创建状态管理模块 6. 国际化：在 `locales` 目录下添加语言包 ### 8.3 后端开发 1. 修改 `src/main/java/run/yiqi/blog` 目录下的代码 2. 控制器开发：在 `controller` 目录下创建新的控制器 3. 服务层开发：在 `service` 目录下创建服务实现 4. 数据访问：在 `mapper` 目录下创建映射接口和XML文件 5. 实体类：在 `entity` 目录下创建实体类 6. 配置类：在 `config` 目录下创建配置类 ### 8.4 数据库修改 - 更新 `src/main/resources/mapper` 目录下的XML文件 - 修改数据库结构后，需要更新实体类和映射文件 ### 8.5 前端测试 ```bash # 前端单元测试 npm run test:unit # 前端端到端测试 npm run test:e2e ``` ### 8.6 后端测试 ```bash # 运行后端单元测试 ./gradlew.bat test ``` ## 9. 许可证 本项目采用 [木兰宽松许可证第二版（Mulan PSL v2）](LICENSE)。 ## 10. 贡献指南 1. Fork 本项目 2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 打开 Pull Request ## 11. 常见问题 ### 11.1 Q: 前端构建失败怎么办？ A: 尝试删除 `node_modules` 目录并重新安装依赖： ```bash rm -rf node_modules rm package-lock.json npm install ``` ### 11.2 Q: 后端启动失败怎么办？ A: 检查数据库连接配置，确保MySQL服务正在运行，并且数据库已创建。 ### 11.3 Q: 如何修改默认端口？ A: 在 `application.yml` 文件中修改 `server.port` 配置，或通过环境变量 `SERVER_PORT` 设置。 ### 11.4 Q: 如何添加新的语言支持？ A: 在 `HiBlogVue/src/locales` 目录下添加新的语言包文件，并在 `i18n` 配置中注册。 ### 11.5 Q: SSR部署后页面没有渲染怎么办？ A: 检查以下几点： 1. 确保后端API服务正常运行 2. 检查SSR服务器是否正确启动 3. 查看浏览器控制台是否有错误信息 4. 确保访问的是正确的URL路径