# 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**: 9
- **Forks**: 1
- **Created**: 2019-05-24
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: blog

**Tags**: None

## README

# HiBlog Project

## 1. Project Introduction
HiBlog is a full-stack blog management system based on Vue 3 and Spring Boot, supporting blog post management, user management, role permission management, and other features.

### 1.1 Features
- **Blog Post Management**: Support for creating, editing, deleting, publishing, and draft management of articles
- **User Management**: Support for user registration, login, permission assignment, and personal information management
- **Role Permission Management**: Fine-grained permission control based on Spring Security
- **Tag Management**: Support for creating, editing, and deleting article tags
- **File Management**: Support for uploading and managing binary files
- **Internationalization Support**: Built-in multi-language support
- **Responsive Design**: Adapt to devices with different screen sizes
- **API Documentation**: Integrated Swagger UI, providing detailed API documentation
- **System Parameter Configuration**: Support for system-level parameter configuration
- **Server-Side Rendering (SSR)**: SSR support for blog-related pages to improve first-screen loading speed and SEO friendliness

## 2. Technology Stack

### 2.1 Frontend
- Vue 3 + TypeScript: Modern frontend framework with type safety
- Element Plus: UI component library based on Vue 3
- Vite: Fast frontend build tool
- Pinia: State management library for Vue 3
- Vue Router: Official routing manager for Vue
- Playwright: End-to-end testing framework
- Vitest: Unit testing framework

### 2.2 Backend
- Spring Boot 3: Modern Java backend framework
- MyBatis Plus: Enhanced MyBatis ORM framework
- MySQL 8.0+: Relational database
- Spring Security: Security framework providing authentication and authorization
- SpringDoc OpenAPI: Automatically generate API documentation
- Gradle: Build tool

## 3. Project Structure
```
├── backend/           # Backend project directory
│   ├── gradle/        # Gradle wrapper
│   │   └── wrapper/     # Gradle wrapper files
│   ├── gradlew.py      # Gradle wrapper script (Python unified version)
│   ├── src/           # Backend source code
│   │   ├── main/java/      # Java source code
│   │   │   ├── run/yiqi/blog/  # Core code
│   │   │   │   ├── common/      # Common modules
│   │   │   │   │   └── exception/ # Exception handling
│   │   │   │   ├── config/     # Configuration classes
│   │   │   │   ├── controller/ # Controllers
│   │   │   │   ├── model/      # Data models
│   │   │   │   │   └── mapper/ # MyBatis mapping interfaces
│   │   │   │   ├── service/     # Service layer
│   │   │   │   ├── vo/          # View objects
│   │   │   │   ├── BlogApplication.java # Application startup class
│   │   │   │   ├── InitDatabase.java # Database initialization
│   │   │   │   └── run/yiqi/util/  # Utility classes
│   │   ├── main/resources/ # Resource files
│   │   │   ├── mapper/     # MyBatis mapping files
│   │   │   ├── templates/  # Template files
│   │   │   ├── application.yml # Application configuration
│   │   │   ├── create_db_tbl.sql # Database initialization script
│   │   │   └── init.sql    # Data initialization script
│   │   ├── test/java/       # Java test code
│   │   │   ├── run/yiqi/blog/  # Test code
│   │   │   │   ├── common/      # Common modules tests
│   │   │   │   ├── controller/ # Controllers tests
│   │   │   │   ├── model/      # Data models tests
│   │   │   │   └── service/     # Service layer tests
│   │   │   └── run/yiqi/util/  # Utility classes tests
│   │   └── test/resources/  # Test resource files
│   │       └── application-test.yml # Test configuration
│   ├── build.gradle        # Gradle build configuration
│   └── settings.gradle     # Gradle settings file
├── frontend/          # Frontend project directory
│   ├── public/         # Static resources
│   │   └── img/        # Image resources
│   ├── src/            # Source code
│   │   ├── components/ # Vue components
│   │   │   ├── admin/  # Admin backend components
│   │   │   ├── common/ # Common components
│   │   │   └── portal/ # Portal components
│   │   ├── i18n/       # Internationalization configuration
│   │   ├── locales/    # Language packs
│   │   ├── App.vue     # Root component
│   │   ├── entry-server.ts # SSR entry
│   │   ├── main.ts     # Application entry
│   │   ├── router.ts   # Router configuration
│   │   └── store.ts    # State management
│   ├── tests/          # Test directory
│   │   ├── appium/     # Mobile device testing
│   │   ├── components/ # Component testing
│   │   ├── e2e/        # End-to-end testing
│   │   └── setup/      # Test setup
│   ├── .env            # Environment configuration
│   ├── eslint.config.ts # ESLint configuration
│   ├── index.html      # HTML template
│   ├── package.json    # Frontend project configuration
│   ├── playwright.config.ts # Playwright configuration
│   ├── postcss.config.cjs # PostCSS configuration
│   ├── server.ts       # SSR server entry
│   ├── tsconfig.json   # TypeScript configuration
│   ├── vite.config.ts  # Vite configuration
│   └── vitest.config.ts # Vitest configuration
├── scripts/           # Build scripts directory
│   ├── backend-build.py  # Backend build script
│   ├── backend-clean.py  # Backend clean script
│   ├── backend-start.py  # Backend start script
│   ├── backend-test.py   # Backend test script
│   ├── frontend-build.py  # Frontend build script
│   ├── frontend-clean.py  # Frontend shallow clean script
│   ├── frontend-deep-clean.py # Frontend deep clean script
│   ├── frontend-e2e-test.py # Frontend E2E test script
│   ├── frontend-run.py   # Frontend run script
│   └── frontend-test.py  # Frontend unit test script
├── docs/              # Documentation directory
│   └── 01 PRD.md     # Product requirements document
├── .gitignore          # Git ignore file
├── LICENSE             # License file
├── README.MD           # Project documentation
└── README_CN.MD       # Project documentation (Chinese)
```

## 4. Environment Requirements
- JDK 21+
- Node.js 20.19.0+ or 22.12.0+
- npm 9.0.0+ or 10.0.0+
- MySQL 8.0+
- Python 3.8+ (for build scripts)
- Gradle 9.0+ (optional, project includes gradle wrapper)

## 5. Deployment

### 5.1 Prerequisites
- MySQL 8.0+ has been correctly installed and running
- Database and user have been created, and the application can access the database through localhost:3306 (default port)
- Database configuration:
  1. Create database: Execute SQL script `backend/src/main/resources/create_db_tbl.sql` using tools like DBeaver
  2. Database initialization data: The project includes an SQL script `backend/src/main/resources/init.sql` to initialize the database. 

### 5.2 Deployment Architecture
The project uses a separate deployment architecture:
- **Frontend SSR Server**: Runs on Node.js, uses port 3000
- **Backend API Server**: Runs on Java, uses port 9090

### 5.3 Deployment via Source Code
1. **Clone Project**:
   ```bash
   git clone <project-url>
   cd HiBlog
   ```

2. **Frontend Installation and Startup**:
   ```bash  
   # Automatically install dependencies and start SSR development server
   python scripts/frontend-run.py
   ```

3. **Backend Installation and Startup**:
   ```bash
   # Use Python script to build (recommended)
   python scripts/backend-build.py
   
   # Start test server
   python scripts/backend-start.py
   ```

### 5.4 Access
1. **Access Application**:
   - Frontend page: http://localhost:3000
   - Admin backend: http://localhost:3000/admin
   - Blog list: http://localhost:3000/portal/blogs.html
   - Blog detail: http://localhost:3000/portal/blog/blogid/{blogId}.html

2. **Default Accounts**:
   - Admin account: admin / admin
   - Guest account: guest / admin

3. **API Documentation**:
   - Swagger UI: http://localhost:9090/swagger-ui.html
   - API Documentation JSON: http://localhost:9090/v3/api-docs

4. **Swagger Interface Testing Guide**:
   1. **Access Swagger UI**: After starting the service, open http://localhost:9090/swagger-ui.html in the browser
   2. **Select Interface**: Select the corresponding interface on the Swagger UI page and click the "Try it out" button
   3. **Fill in Parameters**: Fill in the test parameters according to the interface requirements
   4. **Execute Test**: Click the "Execute" button to send the request and view the response results

## 6. Environment Variables Configuration
Backend supports configuring sensitive information through environment variables:
- `DB_URL`: Database connection URL
- `DB_USERNAME`: Database username
- `DB_PASSWORD`: Database password
- `ALLOWED_ORIGIN`: Allowed CORS origin (production environment)
- `SERVER_PORT`: Server port (default 9090)

## 7. Security Configuration
- Uses BCryptPasswordEncoder to encrypt stored passwords
- Admin APIs require ADMIN role access
- Enables role-based access control
- Supports JWT token authentication (optional)

## 8. Development and Testing Guide

### 8.1 Build Guide
1. **Build Frontend**:
   ```bash
   python scripts/frontend-build.py
   ```
   
2. **Build Backend**:
   ```bash
   python scripts/backend-build.py
   ```

### 8.2 Frontend Development
1. Modify code under `frontend/src` directory
2. Component development: Create new components in `components` directory
3. Page development: Create new pages in `views` directory
4. Router configuration: Configure routes in `router` directory
5. State management: Create state management modules in `stores` directory
6. Internationalization: Add language packs in `locales` directory

### 8.3 Backend Development
1. Modify code under `backend/src/main/java/run/yiqi/blog` directory
2. Controller development: Create new controllers in `controller` directory
3. Service layer development: Create service implementations in `service` directory
4. Data access: Create mapping interfaces and XML files in `mapper` directory
5. Entity classes: Create entity classes in `entity` directory
6. Configuration classes: Create configuration classes in `config` directory

### 8.4 Database Modification
- Update XML files under `backend/src/main/resources/mapper` directory
- After modifying database structure, update entity classes and mapping files

### 8.5 Frontend Testing
```bash
# Frontend unit tests
python scripts/frontend-test.py

# Frontend end-to-end tests
python scripts/frontend-e2e-test.py

# Frontend Appium tests (mobile device testing)
python scripts/frontend-test.py

```

### 8.6 Backend Testing
```bash
# Run backend unit tests
python scripts/backend-test.py
```

### 8.7 Clean Scripts
Project provides multiple clean scripts for cleaning build artifacts and caches:

**Backend Clean**:
```bash
python scripts/backend-clean.py
```

**Frontend Shallow Clean** (clean build artifacts and test results):
```bash
python scripts/frontend-clean.py
```

**Frontend Deep Clean** (clean build artifacts, test results and dependencies):
```bash
python scripts/frontend-deep-clean.py
```

## 9. License
This project is licensed under the [Mulan Permissive Software License, Version 2 (MulanPSL v2)](LICENSE).

## 10. Contribution Guide
1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 11. FAQ

### 11.1 Q: What to do if frontend build fails?
A: Try deleting `node_modules` directory and reinstalling dependencies:
```bash
python scripts/frontend-deep-clean.py
```

### 11.2 Q: What to do if backend startup fails?
A: Check database connection configuration, ensure MySQL service is running, and database has been created.

### 11.3 Q: How to modify default port?
A: Modify `server.port` configuration in `application.yml` file, or set through environment variable `SERVER_PORT`.

### 11.4 Q: How to add new language support?
A: Add new language pack files in `frontend/src/locales` directory and register them in i18n configuration.

### 11.5 Q: What to do if SSR deployment doesn't render pages?
A: Check the following points:
1. Ensure backend API service is running properly
2. Check if SSR server is started correctly
3. Check browser console for error messages
4. Ensure accessing the correct URL path