# PersonalWeb

**Repository Path**: Sckaro/personal-web

## Basic Information

- **Project Name**: PersonalWeb
- **Description**: Java项目--应用新学技术，如：SaaS、OAuth2.0、SpringSecurity、MinIO、Flyway、动态数据源切换等等
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Personal Web 个人网站平台

一个基于 Spring Boot 3 构建的现代化、安全且功能丰富的个人网站平台，提供博客、笔记、用户管理等功能。

## 🚀 技术栈

| 技术名称           | 版本          | 描述                                     |
|--------------------|--------------|-----------------------------------------|
| Spring Boot        | 3.5.7        | 核心框架                                 |
| Java               | 21           | 编程语言                                 |
| Spring Security    | 6.3.1        | 安全框架                                 |
| JWT                | -            | 无状态认证                               |
| OAuth2.0           | -            | 第三方认证                               |
| MyBatis Plus       | -            | ORM 框架                                 |
| MySQL              | 5.7+         | 数据库                                   |
| MinIO              | -            | 对象存储                                 |
| FastJSON2          | -            | JSON 处理                                |
| Flexmark           | -            | Markdown 渲染                            |
| Flyway             | -            | 数据库迁移                               |

## 📁 项目结构

项目采用标准的 Spring Boot 分层架构：

```
personalweb/
├── controller/          # HTTP 请求处理层
├── service/             # 业务逻辑层（包含 impl 实现子包）
├── mapper/              # 数据访问层（MyBatis Plus）
├── pojo/                # 数据库实体类
├── config/              # 配置类
├── filter/              # JWT 认证过滤器
├── handler/             # 异常和安全处理器
├── intercepter/         # 请求拦截器
├── util/                # 工具类
├── common/              # 通用组件（结果包装器、用户上下文）
├── exception/           # 自定义异常
└── oauth/               # OAuth2 功能模块
```

## ✨ 已完成功能

### 🔐 认证与授权
- **登录/注册**：基础认证，使用 BCrypt 密码哈希
- **OAuth2.0**：第三方授权登录（策略模式实现）
- **JWT**：基于令牌的无状态会话跟踪
- **RBAC**：基于角色的权限控制，支持细粒度权限
- **Spring Security**：完整的安全框架，支持方法级安全

### 🏢 多租户架构支持
- **租户管理**：支持企业和个人租户的创建和管理
- **租户隔离**：用户和内容按租户隔离，确保数据安全性
- **组织架构**：支持企业内部部门、岗位、员工的组织结构
- **租户内权限控制**：不同租户内部独立的权限管理体系
- **认证流程**：用户注册登录后可进行企业或个人认证，自动创建对应租户

### 📝 内容管理
- **个人博客**：完整的博客系统，支持 Markdown
- **笔记**：个人笔记管理，支持富文本
- **标签系统**：内容分类和组织

### 🔄 动态数据源切换
- **数据源配置**：配置多个数据源（主库和从库）
- **路由数据源**：继承`AbstractRoutingDataSource`实现动态路由逻辑
- **上下文管理**：使用`ThreadLocal`维护数据源上下文，确保线程安全
- **AOP拦截**：通过切面拦截带注解的方法，自动切换数据源

### 🗄️ 存储与数据库
- **MinIO 集成**：用于文件和图片的对象存储服务
- **自动数据库初始化**：基于 Flyway 的数据库结构创建
- **默认管理员用户**：自动创建超级管理员 (`admin`/`admin123`)
- **默认角色**：预配置 ADMIN 和 USER 角色
- **动态角色分配**：为新用户配置默认角色

### 🔧 系统功能
- **统一响应格式**：所有 API 端点使用 `Result` 包装器返回一致的 JSON 结构
- **全局异常处理器**：集中处理异常，使用自定义异常
- **请求过滤**：JWT 认证过滤器保护受保护端点
- **请求拦截**：自定义拦截器处理请求
- **首页支持**：允许匿名访问，根据 JWT 令牌显示动态内容

### 🛠️ 管理功能
- **角色管理**：创建和管理用户角色
- **权限管理**：定义和分配权限
- **角色-权限关联**：管理角色与权限的映射
- **用户-角色关联**：动态为用户分配角色

## 📦 快速开始

### 前置要求
- 安装 JDK 21
- 安装 Maven 3.9+
- 运行 MySQL 5.7+ 数据库
- 安装 MinIO 服务器（可选，用于文件存储）

### 安装步骤

1. **克隆仓库**
   ```bash
   git clone https://github.com/your-repo/PersonalWeb.git
   cd PersonalWeb
   ```

2. **配置应用程序**
   编辑 `src/main/resources/application.yaml` 进行配置：
   ```yaml
   # 数据库配置
   spring:
     datasource:
       driver-class-name: com.mysql.cj.jdbc.Driver
       url: jdbc:mysql://localhost:3306/security-demo?useUnicode=true&characterEncoding=utf8
       username: root
       password: root

   # MinIO 配置
   minio:
     endpoint: http://localhost:9000
     access-key: minioadmin
     secret-key: minioadmin
     bucket-name: personalweb

   # JWT 配置
   jwt:
     secret: your-secret-key
     expiration: 7200000

   # 默认角色配置
   auth:
     default-role: USER
   ```

3. **构建项目**
   ```bash
   mvn clean package
   ```

4. **运行应用程序**
   ```bash
   mvn spring-boot:run
   ```

   应用程序默认将在 `http://localhost:8080` 启动。

### 访问应用程序

- **首页**：`http://localhost:8080`（允许匿名访问）
- **登录**：`http://localhost:8080/auth/login`
- **API 文档**：`API_DOCUMENTATION_ZH.md`

## 🛡️ 安全特性

- **密码安全**：BCrypt 密码哈希
- **JWT 保护**：基于令牌的认证
- **授权检查**：使用 `@PreAuthorize` 进行方法级安全
- **CORS 配置**：跨域资源共享
- **XSS 保护**：内置安全头

## 📖 API 文档

API 文档提供两种语言：
- [英文 API 文档](API_DOCUMENTATION.md)
- [中文 API 文档](API_DOCUMENTATION_ZH.md)

Swagger 集成计划中（见 TODO 列表）。

## 🚧 待开发功能

1. **首页内容填充**：完善首页动态内容
2. **Swagger 集成**：添加交互式 API 文档
3. **WebSocket 支持**：实时通信功能

## 📊 数据库结构

由 Flyway 自动创建的关键数据库表：

| 表名                 | 描述                             |
|---------------------|----------------------------------|
| `user`              | 用户信息表                        |
| `role`              | 角色定义表                        |
| `permission`        | 权限定义表                        |
| `user_role`         | 用户-角色关联表                   |
| `role_permission`   | 角色-权限关联表                   |
| `note`              | 笔记内容表                        |
| `blog`              | 博客文章表                        |
| `tag`               | 内容标签表                        |
| `file`              | 文件存储元数据表                  |
| `tenants`           | 租户信息表                        |
| `organizations`     | 组织架构表（部门、岗位、员工）     |

## 🤝 贡献

欢迎贡献！请遵循以下指南：

1. Fork 仓库
2. 创建特性分支 (`git checkout -b feature/your-feature`)
3. 提交更改 (`git commit -m '添加一些功能'`)
4. 推送到分支 (`git push origin feature/your-feature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。详情见 LICENSE 文件。

## 📞 联系

如有问题或疑问，请在 GitHub 上提交 Issue。

---

使用 Spring Boot 构建 ❤️