# auth-cloud-base

**Repository Path**: Aaron_qcd/auth-cloud-base

## Basic Information

- **Project Name**: auth-cloud-base
- **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-09-08
- **Last Updated**: 2025-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Auth Cloud Base

基于Spring Cloud Alibaba的微服务认证框架

## 技术栈

| 技术 | 版本 |
|------|------|
| Spring Boot | 3.2.4 |
| Spring Cloud | 2023.0.1 |
| Spring Cloud Alibaba | 2023.0.1.0 |
| Sentinel | 1.8.6 |
| Nacos | 2.3.2 |
| Seata | 2.0.0 |
| JDK | 21 |
| MyBatis Plus | 3.5.7 |
| MySQL | 8.0.42.0 |
| Redis | 3.2.4 |
| RabbitMQ | 5.19.0 |
| MongoDB | 4.11.1 |
| Elasticsearch | 8.10.4 |

## 项目结构

```
auth-cloud-base/
├── auth-common/          # 公共模块
│   ├── src/main/java/com/auth/cloud/common/
│   │   ├── entity/       # 实体类
│   │   ├── result/       # 统一返回结果
│   │   ├── util/         # 工具类
│   │   ├── config/       # 配置类
│   │   └── exception/    # 异常处理
│   └── pom.xml
├── auth-gateway/         # 网关服务
│   ├── src/main/java/com/auth/cloud/gateway/
│   │   ├── filter/       # 过滤器
│   │   └── config/       # 配置类
│   └── pom.xml
├── auth-registry/        # 注册中心配置
│   ├── src/main/java/com/auth/cloud/registry/
│   └── pom.xml
├── auth-service/         # 认证服务
│   ├── src/main/java/com/auth/cloud/auth/
│   │   ├── controller/   # 控制器
│   │   ├── service/      # 服务层
│   │   ├── mapper/       # 数据访问层
│   │   ├── dto/          # 数据传输对象
│   │   └── config/       # 配置类
│   └── pom.xml
├── user-service/         # 用户服务
│   ├── src/main/java/com/auth/cloud/user/
│   │   ├── controller/   # 控制器
│   │   ├── service/      # 服务层
│   │   ├── mapper/       # 数据访问层
│   │   └── dto/          # 数据传输对象
│   └── pom.xml
├── sql/                  # 数据库脚本
│   └── init.sql
├── scripts/              # 启动脚本
│   ├── start.sh         # Linux/Mac启动脚本
│   └── start.bat        # Windows启动脚本
├── pom.xml              # 父级POM文件
└── README.md            # 项目说明
```

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- Nacos 2.3.2+

### 1. 克隆项目

```bash
git clone <repository-url>
cd auth-cloud-base
```

### 2. 数据库初始化

```bash
# 创建数据库
mysql -u root -p < sql/init.sql
```

### 3. 启动Nacos

```bash
# 下载Nacos 2.3.2
# 启动Nacos
sh startup.sh -m standalone
```

### 4. 启动Redis

```bash
# 启动Redis服务
redis-server
```

### 5. 编译项目

```bash
# Linux/Mac
./scripts/start.sh build

# Windows
scripts\start.bat build
```

### 6. 启动服务

```bash
# 启动所有服务
./scripts/start.sh start-all

# 或分别启动
./scripts/start.sh start gateway
./scripts/start.sh start registry
./scripts/start.sh start auth-service
./scripts/start.sh start user-service
```

### 7. 访问服务

- 网关服务: http://localhost:8080
- 认证服务: http://localhost:8082
- 用户服务: http://localhost:8083
- API文档: http://localhost:8080/swagger-ui/index.html

## 服务说明

### 网关服务 (auth-gateway)

- 端口: 8080
- 功能: 统一入口、路由转发、认证过滤、限流熔断
- 技术: Spring Cloud Gateway

### 注册中心服务 (auth-registry)

- 端口: 8081
- 功能: 服务注册与发现、配置管理
- 技术: Nacos

### 认证服务 (auth-service)

- 端口: 8082
- 功能: 用户认证、Token管理、权限验证
- 技术: Spring Security + JWT

### 用户服务 (user-service)

- 端口: 8083
- 功能: 用户管理、用户信息维护
- 技术: MyBatis Plus

## API接口

### 认证接口

#### 用户登录
```http
POST /auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456",
  "captcha": "ABCD",
  "captchaKey": "uuid-key"
}
```

#### 用户注册
```http
POST /auth/register
Content-Type: application/json

{
  "username": "testuser",
  "password": "123456",
  "confirmPassword": "123456",
  "nickname": "测试用户",
  "email": "test@example.com",
  "phone": "13800138000",
  "captcha": "ABCD",
  "captchaKey": "uuid-key"
}
```

#### 刷新Token
```http
POST /auth/refresh
Authorization: Bearer <refresh-token>
```

#### 用户登出
```http
POST /auth/logout
Authorization: Bearer <access-token>
```

### 用户管理接口

#### 分页查询用户
```http
GET /user/page?current=1&size=10&username=admin
Authorization: Bearer <access-token>
```

#### 创建用户
```http
POST /user
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "username": "newuser",
  "password": "123456",
  "nickname": "新用户",
  "email": "new@example.com",
  "phone": "13900139000"
}
```

#### 更新用户
```http
PUT /user/{id}
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "nickname": "更新昵称",
  "email": "updated@example.com"
}
```

#### 删除用户
```http
DELETE /user/{id}
Authorization: Bearer <access-token>
```

## 配置说明

### 数据库配置

修改各服务的 `application.yml` 文件中的数据库连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/auth_cloud?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
    username: root
    password: 123456
```

### Redis配置

```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password:
    database: 0
```

### Nacos配置

```yaml
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: dev
        group: DEFAULT_GROUP
```

## 开发指南

### 添加新服务

1. 在根目录创建新的服务模块
2. 在父级 `pom.xml` 中添加模块
3. 配置服务的基本信息和依赖
4. 实现业务逻辑
5. 在网关中配置路由规则

### 自定义过滤器

在网关服务中添加自定义过滤器：

```java
@Component
public class CustomFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 自定义逻辑
        return chain.filter(exchange);
    }
    
    @Override
    public int getOrder() {
        return -1;
    }
}
```

### 异常处理

使用全局异常处理器统一处理异常：

```java
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        return Result.error(e.getCode(), e.getMessage());
    }
}
```

## 部署说明

### Docker部署

1. 构建镜像
```bash
docker build -t auth-cloud-base .
```

2. 运行容器
```bash
docker run -d -p 8080:8080 auth-cloud-base
```

### 生产环境配置

1. 修改数据库连接为生产环境
2. 配置Redis集群
3. 设置Nacos集群
4. 配置日志级别
5. 设置JVM参数

## 监控和运维

### 健康检查

访问各服务的健康检查端点：

- http://localhost:8080/actuator/health
- http://localhost:8082/actuator/health
- http://localhost:8083/actuator/health

### 日志查看

```bash
# 查看服务日志
tail -f logs/gateway.log
tail -f logs/auth-service.log
tail -f logs/user-service.log
```

### 服务管理

```bash
# 查看服务状态
./scripts/start.sh status

# 停止所有服务
./scripts/start.sh stop-all

# 重启所有服务
./scripts/start.sh restart-all
```

## 常见问题

### 1. 服务启动失败

- 检查端口是否被占用
- 检查数据库连接是否正常
- 检查Redis连接是否正常
- 检查Nacos是否启动

### 2. 认证失败

- 检查JWT密钥配置
- 检查Token是否过期
- 检查用户状态是否正常

### 3. 数据库连接失败

- 检查数据库服务是否启动
- 检查连接字符串是否正确
- 检查用户名密码是否正确

### 4. JWT编译错误

如果遇到 `找不到符号: 方法 parserBuilder()` 等JWT相关编译错误：

- 项目已更新为JWT 0.12.3版本的新API
- 使用 `Jwts.parser()` 替代 `Jwts.parserBuilder()`
- 使用 `parseSignedClaims()` 替代 `parseClaimsJws()`
- 使用 `getPayload()` 替代 `getBody()`

### 5. Lombok编译错误

如果遇到 `java.lang.ExceptionInInitializerError` 错误：

```bash
# 使用清理脚本
./scripts/clean-build.sh all

# 或手动清理
mvn dependency:purge-local-repository -DmanualInclude="org.projectlombok:lombok"
mvn clean compile -DskipTests
```

## 贡献指南

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 联系方式

- 作者: auth-cloud
- 邮箱: auth-cloud@example.com
- 项目地址: https://github.com/auth-cloud/auth-cloud-base