# yichao-cloud

**Repository Path**: yulece-application/yichao-cloud

## Basic Information

- **Project Name**: yichao-cloud
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 蚁巢云平台 (Yichao Cloud)

## 项目简介

蚁巢云平台是基于 Spring Cloud 微服务架构的企业级云平台脚手架项目，提供完整的用户权限管理、租户管理等核心功能。

## 技术栈

### 核心框架
- **Java**: 21
- **Spring Boot**: 3.3.4
- **Spring Cloud**: 2023.0.3
- **Spring Cloud Alibaba**: 2023.0.1.2

### 数据层
- **MyBatis Plus**: 3.5.7
- **MySQL**: 8.0+
- **Redis**: 6.0+

### 服务治理
- **Nacos**: 服务注册与配置中心
- **Spring Cloud Gateway**: API 网关
- **Spring Cloud LoadBalancer**: 负载均衡

### 安全认证
- **Spring Security**: 权限框架
- **JWT**: Token 认证

### 其他组件
- **Lombok**: 简化代码
- **MapStruct**: 对象映射
- **SpringDoc OpenAPI**: API 文档
- **Logback**: 日志框架

## 项目结构

```
yichao-cloud
├── yichao-dependencies          # 依赖版本管理
├── yichao-framework             # 框架核心
│   └── yichao-commons          # 公共组件
├── yichao-module-gateway        # API 网关服务
└── yichao-module-system         # 系统管理模块
    ├── yichao-module-system-api    # API 定义
    └── yichao-module-system-server # 服务实现
```

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- Nacos 2.x（可选，本地开发可不启用）

### 配置数据库

1. 创建数据库：
```sql
CREATE DATABASE bookstore_user_center CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

2. 导入初始化脚本：
```bash
mysql -u root -p bookstore_user_center < yichao-module-system/sql/system_module_schema.sql
```

3. 创建数据库用户（可选）：
```sql
CREATE USER 'bookstore_user'@'localhost' IDENTIFIED BY 'user_center!@2025';
GRANT ALL PRIVILEGES ON bookstore_user_center.* TO 'bookstore_user'@'localhost';
FLUSH PRIVILEGES;
```

### 配置 Redis

确保 Redis 服务已启动，默认配置：
- Host: localhost
- Port: 6379
- Database: 10

### 配置 Nacos（可选）

如果使用 Nacos 作为服务注册与配置中心：

1. 下载并启动 Nacos Server
2. 访问 Nacos 控制台：http://localhost:8848/nacos
3. 默认账号密码：nacos/nacos

### 构建项目

```bash
mvn clean install -DskipTests
```

### 启动服务

#### 方式一：使用 Nacos（推荐生产环境）

1. **启动系统服务**
```bash
cd yichao-module-system/yichao-module-system-server
mvn spring-boot:run
```

2. **启动网关服务**
```bash
cd yichao-module-gateway
mvn spring-boot:run
```

#### 方式二：不使用 Nacos（快速本地开发）

修改 `yichao-module-gateway/src/main/resources/application.yaml`：
```yaml
# 将
uri: lb://yichao-module-system
# 改为
uri: http://localhost:8081
```

然后启动服务即可。

### 访问服务

- **系统服务**: http://localhost:8081
- **API 文档**: http://localhost:8081/swagger-ui.html
- **网关服务**: http://localhost
- **通过网关访问**: http://localhost/api/system/xxx

## 核心功能

### 系统管理模块

- **用户管理**: 用户增删改查、密码管理、用户角色分配
- **角色管理**: 角色权限配置、角色菜单分配
- **菜单管理**: 菜单树结构、按钮权限
- **租户管理**: 多租户隔离、租户数据过滤
- **部门管理**: 部门树结构、组织架构
- **认证授权**: JWT Token、验证码、短信登录

### API 网关

- **路由转发**: 基于路径的智能路由
- **负载均衡**: 服务实例负载均衡
- **服务发现**: Nacos 服务自动发现
- **日志追踪**: 请求响应详细日志
- **异常处理**: 统一异常拦截与返回

## 配置说明

### 数据库配置

配置文件：`yichao-module-system-server/src/main/resources/application-local.yaml`

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/bookstore_user_center
    username: bookstore_user
    password: user_center!@2025
```

### Redis 配置

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 10
```

### JWT 配置

```yaml
jwt:
  secret: c2VjcmV0LWtleS1mb3Itand0LXRva2VuLXNpZ25pbmctYW5kLXZlcmlmaWNhdGlvbg==
```

### 日志配置

日志文件位置：`./logs/{应用名}/`

- `info.log`: INFO 级别日志
- `error.log`: ERROR 级别日志
- `all.log`: 所有级别日志
- `sql.log`: SQL 执行日志（仅 system 模块）
- `business.log`: 业务日志（仅 system 模块）

## 开发指南

### 日志使用

```java
@Slf4j
public class YourClass {
    public void yourMethod() {
        log.info("信息日志");
        log.error("错误日志", exception);
    }
}
```

### 权限控制

```java
// 方法级权限控制
@RequiresPermissions("system:user:list")
public Result<?> listUsers() {
    // ...
}

// 角色控制
@RequiresRoles("admin")
public Result<?> adminOnly() {
    // ...
}
```

### 多租户

系统自动根据当前登录用户的租户 ID 进行数据隔离，配置的租户表会自动添加 `tenant_id` 条件。

## 常见问题

### 1. 启动时报 503 错误

**原因**: Gateway 无法找到目标服务

**解决方案**:
- 确保 Nacos 已启动并可访问
- 确保目标服务已注册到 Nacos
- 或者修改 Gateway 配置直接指向服务地址（不使用负载均衡）

### 2. ClassNotFoundException: ContextStorageOverride

**原因**: Spring Cloud Alibaba 版本不兼容

**解决方案**: 确保版本配置正确
- Spring Boot: 3.3.4
- Spring Cloud: 2023.0.3
- Spring Cloud Alibaba: 2023.0.1.2

### 3. Logback 启动报错

**原因**: 使用了已废弃的 `SizeAndTimeBasedFNATP`

**解决方案**: 已更新为 `SizeAndTimeBasedRollingPolicy`

## 许可证

本项目采用 MIT 许可证。

## 联系方式

如有问题或建议，请提交 Issue。