# klee-blog

**Repository Path**: variable-wing-core/klee-blog

## Basic Information

- **Project Name**: klee-blog
- **Description**: 可变羽翼核心博客系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h1>klee-blog</h1>
  <p>基于 Spring Boot 3 + Vue3 的全栈博客与权限管理系统，包含后台管理（Admin）与门户展示（Portal）。</p>
  <img alt="JDK" src="https://img.shields.io/badge/Java-17-brightgreen">
  <img alt="Spring Boot" src="https://img.shields.io/badge/SpringBoot-3.x-green">
  <img alt="Node" src="https://img.shields.io/badge/Node-20%2B-orange">
  <img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-blue">
</div>

## 🎯 项目简介
klee-blog 旨在快速搭建一个可扩展的博客系统与基础权限管理能力，前后端分离，支持本地与容器化部署。后端采用 Spring Boot 3、MyBatis-Plus、Redis、MySQL、MinIO、XXL-Job 等组件；前端包含 `blog-admin`（后台管理）与 `blog-portal`（门户展示），基于 Vue3 + Vite + TypeScript + Element Plus。

## ✨ 主要特性
- 账户与角色权限：支持菜单、按钮和（可扩展）数据权限
- 内容管理：博客文章、分类、标签（待扩展）
- 系统管理：字典、通知公告、系统配置
- 文件与对象存储：接入 MinIO 可扩展云存储
- 任务调度：集成 XXL-Job 可实现定时/分布式任务
- 代码生成：通过 `codegen.yml` 模板提升开发效率
- 容器编排：Docker Compose 一键拉起 MySQL/Redis/MinIO/XXL-Job
- 前端体验：国际化、多布局、暗黑模式、自动导入、Mock 支持

## 🛠 技术栈
**后端**
- Java 17, Spring Boot 3.x
- MyBatis-Plus, MySQL 8+
- Redis, MinIO
- XXL-Job 调度中心
- Sa-Token/JWT（如后续集成，可扩展认证）
- Logback, Maven

**前端 Admin / Portal**
- Vue 3, Vite, TypeScript
- Element Plus / 组合式 API
- Pinia 状态管理
- Vue Router
- UnoCSS / 可扩展样式体系
- Axios 封装请求
- Mock（开发阶段切换）

## 📂 目录结构
```
klee-blog/
├─ blog-backend/              # 后端工程
│  ├─ src/main/java/com/...   # 业务代码（按模块分包）
│  ├─ src/main/resources/     # 配置与模板
│  │  ├─ application.yml      # 主配置
│  │  ├─ application-dev.yml  # 开发环境配置
│  │  ├─ application-prod.yml # 生产环境配置
│  │  ├─ codegen.yml          # 代码生成配置
│  │  ├─ mapper/              # MyBatis XML
│  │  ├─ templates/           # 代码生成模板
│  ├─ docker/                 # 中间件编排
│  │  ├─ docker-compose.yml
│  │  ├─ mysql/redis/minio/xxljob
│  ├─ sql/                    # 初始化 SQL
│  │  └─ mysql/klee-blog-eva.sql
│  ├─ pom.xml
│
├─ blog-frontend/             # 前端 monorepo
│  ├─ blog-admin/             # 后台管理前端
│  │  ├─ src/api/             # 接口封装
│  │  ├─ src/components/      # 通用组件
│  │  ├─ src/views/           # 业务页面
│  │  ├─ src/store/           # Pinia 模块
│  │  ├─ src/router/          # 路由
│  │  ├─ src/styles/          # 样式
│  │  └─ ...
│  ├─ blog-portal/            # 门户展示前端
│  │  ├─ src/pages/           # 门户页面
│  │  ├─ src/components/
│  │  ├─ src/store/
│  │  ├─ src/router/
│  │  └─ ...
└─ README.md                  # 根 README（当前文件）
```

## 🚀 快速开始
### 环境要求
- JDK 17+
- Maven 3.8+
- Node.js >= 20（或 22 LTS）
- pnpm >= 8（推荐作为前端包管理器）
- Docker & Docker Compose（可选，用于中间件）

### 后端启动（本地）
1. 初始化中间件（可选 Docker Compose）
   ```bash
   docker compose -f blog-backend/docker/docker-compose.yml -p klee-blog up -d
   ```
2. 创建数据库并执行初始化脚本：`sql/mysql/klee-blog-eva.sql`
3. 修改 `application-dev.yml` 中数据库、Redis、MinIO 等连接配置
4. IDE 运行主启动类（如 `KleeBlogApplication`，名称按实际工程为准）或：
   ```bash
   mvn spring-boot:run
   ```

### 前端启动（Admin）
```bash
cd blog-frontend/blog-admin
pnpm install
pnpm run dev
```
开发接口地址配置：在 `.env.development` 中设置 `VITE_APP_API_URL` 指向后端，例如 `http://localhost:8080`。

### 前端启动（Portal）
```bash
cd blog-frontend/blog-portal
pnpm install
pnpm run dev
```

### 关闭中间件
```bash
docker compose -f blog-backend/docker/docker-compose.yml -p klee-blog down
```

## ⚙️ 配置说明
| 配置文件 | 作用 |
|----------|------|
| `application.yml` | 基础公共配置入口 |
| `application-dev.yml` | 开发环境差异配置 |
| `application-prod.yml` | 生产环境配置 |
| `codegen.yml` | 代码生成器数据源与模板路径定义 |
| `logback-spring.xml` | 日志级别与输出策略 |
| `.env.development` (前端) | 开发环境变量，接口、Mock 开关 |

## 🧬 代码生成（后端）
`templates/` 与 `codegen.yml` 配合，可自定义实体、Mapper、Service、Controller 等模板。典型流程：
1. 在 `codegen.yml` 中配置数据源与生成参数（表名、作者等）
2. 编写或调整 `templates/` 下的 FreeMarker/Velocity 模板
3. 执行内部工具类/启动器（需在工程内补充调用脚本）生成代码

> 可扩展：新增前端 CRUD 页面脚本以实现全链路快速生成。

## 🐳 Docker 说明
已提供 `docker-compose.yml` 快速拉起：MySQL、Redis、MinIO、XXL-Job。示例：
```bash
docker compose -f blog-backend/docker/docker-compose.yml -p klee-blog up -d
```
自定义端口及持久化目录请在对应服务段落内修改。

## 📦 构建与部署
### 后端 Jar 构建
```bash
cd blog-backend
mvn clean package -DskipTests
java -jar target/*.jar --spring.profiles.active=prod
```

### 前端打包（Admin / Portal）
```bash
cd blog-frontend/blog-admin
pnpm run build
# dist 产物部署至 Nginx / 静态服务器

cd ../blog-portal
pnpm run build
```
Nginx 示例：
```nginx
server {
  listen 80;
  server_name your-domain.com;
  location / { root /usr/share/nginx/html; index index.html; }
  location /api/ { proxy_pass http://backend-host/; }
}
```

## ❓ 常见问题
| 问题 | 解决方案 |
|------|----------|
| 前端访问空白页 | 升级浏览器，确保支持 ES2022（如可选链 `?.`） |
| 组件类型/导入报红 | 重启 VSCode 或重新安装依赖 `pnpm install` |
| 接口 404 | 检查 `VITE_APP_API_URL` 是否正确指向后端以及反向代理设置 |
| Docker 服务启动失败 | 查看端口占用、磁盘权限或内存限制；使用 `docker compose logs` 排查 |
| MinIO 上传失败 | 确认访问密钥、endpoint 与 bucket 是否存在 |

## 🤝 贡献指南
欢迎提交 Issue 与 PR：
1. Fork 本仓库并创建特性分支
2. 保持代码风格一致，遵循前端 ESLint + Prettier，后端 Checkstyle（如后续集成）
3. 提交信息遵循 Conventional Commits（示例：`feat: 支持标签多选`）
4. 关联 Issue（如存在）

## 📄 License
本项目采用 Apache License 2.0。

## 🗺️ 后续规划（Roadmap）
- ✅ 初始后端/前端结构化 README
- ⏳ 博客文章/分类/标签模块落地
- ⏳ 前端代码生成适配后端模型
- ⏳ 单元测试与集成测试用例补充
- ⏳ CI/CD（GitHub Actions / Jenkins）流水线

> 欢迎 Star ⭐ 与反馈，帮助项目持续完善！