# user-system

**Repository Path**: Marsfactory/user-system

## Basic Information

- **Project Name**: user-system
- **Description**: 本项目是一个基于 Spring Cloud 微服务架构的用户中心与认证鉴权系统，采用前后端分离设计，实现用户注册、登录、权限管理等核心功能。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-07
- **Last Updated**: 2025-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户中心与认证鉴权系统

## 项目简介

本项目是一个基于 Spring Cloud 微服务架构的用户中心与认证鉴权系统，采用前后端分离设计，实现用户注册、登录、权限管理等核心功能。

## 技术栈

### 后端技术
- **JDK**: 17+
- **Spring Boot**: 3.3.4
- **Spring Cloud**: 2023.0.3
- **Spring Cloud Alibaba**: 2023.0.3.2
- **Sa-Token**: 认证鉴权框架
- **MyBatis-Plus**: ORM 持久层框架
- **MySQL**: 关系型数据库
- **Nacos**: 注册中心与配置中心
- **OpenFeign**: 服务间远程调用
- **Gateway**: 微服务网关

### 前端技术
- **Apifox**: API 文档与接口测试

## 系统架构

### 微服务模块划分

```
user-system
├── user-center-gateway         # 网关服务
├── user-service               # 用户服务
│   ├── 用户信息管理
│   ├── 用户资料维护
│   └── 用户查询服务
└── auth-service               # 认证鉴权服务
    ├── 用户注册
    ├── 用户登录
    ├── Token 管理
    └── 权限验证
```

### 服务职责

#### 1. User Service (用户服务)
负责用户核心业务逻辑：
- 用户信息的增删改查
- 用户资料管理
- 用户状态管理
- 用户列表查询

#### 2. Auth Service (认证鉴权服务)
负责认证与授权：
- 用户注册功能
- 用户登录认证
- Token 生成与验证
- 登录状态管理
- 权限校验
- 登出功能

#### 3. Gateway (网关服务)
统一流量入口：
- 路由转发
- 统一鉴权
- 跨域处理
- 限流熔断
- 日志记录

## 核心功能

### 用户注册
- 用户名、邮箱、手机号唯一性校验
- 密码加密存储
- 参数合法性验证
- 注册成功自动登录（可选）

### 用户登录
- 支持用户名/邮箱/手机号登录
- 密码加密验证
- 基于 Sa-Token 的 Token 生成
- 登录日志记录
- 防暴力破解

### 权限管理
- 基于 Sa-Token 的权限控制
- RBAC 权限模型
- 接口级权限校验
- 动态权限配置

## 数据库设计

### 用户表 (sys_user)

| 字段名 | 类型 | 长度 | 说明 | 备注 |
|-------|------|------|------|------|
| id | BIGINT | - | 用户ID | 主键，自增 |
| username | VARCHAR | 50 | 用户名 | 唯一索引 |
| password | VARCHAR | 255 | 密码 | 加密存储 |
| email | VARCHAR | 100 | 邮箱 | 唯一索引 |
| phone | VARCHAR | 20 | 手机号 | 唯一索引 |
| nickname | VARCHAR | 50 | 昵称 | - |
| avatar | VARCHAR | 255 | 头像URL | - |
| status | TINYINT | - | 状态 | 0:禁用 1:正常 |
| create_time | DATETIME | - | 创建时间 | - |
| update_time | DATETIME | - | 更新时间 | - |
| deleted | TINYINT | - | 删除标记 | 0:未删除 1:已删除 |

### 角色表 (sys_role)

| 字段名 | 类型 | 长度 | 说明 | 备注 |
|-------|------|------|------|------|
| id | BIGINT | - | 角色ID | 主键，自增 |
| role_name | VARCHAR | 50 | 角色名称 | 唯一 |
| role_code | VARCHAR | 50 | 角色编码 | 唯一 |
| description | VARCHAR | 255 | 角色描述 | - |
| status | TINYINT | - | 状态 | 0:禁用 1:正常 |
| create_time | DATETIME | - | 创建时间 | - |
| update_time | DATETIME | - | 更新时间 | - |

### 用户角色关联表 (sys_user_role)

| 字段名 | 类型 | 长度 | 说明 | 备注 |
|-------|------|------|------|------|
| id | BIGINT | - | ID | 主键，自增 |
| user_id | BIGINT | - | 用户ID | 外键 |
| role_id | BIGINT | - | 角色ID | 外键 |
| create_time | DATETIME | - | 创建时间 | - |

## 项目结构

```
user-system/
├── user-service/                      # 用户服务
│   ├── src/main/java/
│   │   └── com/userservice/
│   │       ├── controller/           # 控制器层
│   │       ├── service/              # 服务层
│   │       ├── mapper/               # 数据访问层
│   │       ├── entity/               # 实体类
│   │       ├── dto/                  # 数据传输对象
│   │       ├── vo/                   # 视图对象
│   │       └── config/               # 配置类
│   └── src/main/resources/
│       ├── mapper/                   # MyBatis XML
│       ├── application.yml           # 配置文件
│       └── bootstrap.yml             # 启动配置
│
├── auth-service/                      # 认证服务
│   ├── src/main/java/
│   │   └── com/authservice/
│   │       ├── controller/           # 控制器层
│   │       ├── service/              # 服务层
│   │       ├── dto/                  # 数据传输对象
│   │       ├── vo/                   # 视图对象
│   │       ├── config/               # 配置类
│   │       └── feign/                # Feign 客户端
│   └── src/main/resources/
│       ├── application.yml           # 配置文件
│       └── bootstrap.yml             # 启动配置
│
├── user-center-gateway/               # 网关服务
│   ├── src/main/java/
│   │   └── com/gateway/
│   │       ├── filter/               # 网关过滤器
│   │       └── config/               # 配置类
│   └── src/main/resources/
│       ├── application.yml           # 配置文件
│       └── bootstrap.yml             # 启动配置
│
└── common/                            # 公共模块
    └── src/main/java/
        └── com/common/
            ├── result/               # 统一响应
            ├── exception/            # 异常处理
            ├── constant/             # 常量定义
            └── utils/                # 工具类
```

## API 接口文档

### 认证服务接口 (Auth Service)

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

请求体：
{
  "username": "testuser",
  "password": "123456",
  "email": "test@example.com",
  "phone": "13800138000",
  "nickname": "测试用户"
}

响应：
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "userId": 1,
    "username": "testuser",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

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

请求体：
{
  "username": "testuser",
  "password": "123456"
}

响应：
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "userId": 1,
    "username": "testuser",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenName": "Authorization",
    "tokenTimeout": 7200
  }
}
```

#### 3. 用户登出
```
POST /api/auth/logout
Authorization: Bearer {token}

响应：
{
  "code": 200,
  "message": "登出成功",
  "data": null
}
```

#### 4. Token 验证
```
GET /api/auth/verify
Authorization: Bearer {token}

响应：
{
  "code": 200,
  "message": "Token 有效",
  "data": {
    "userId": 1,
    "username": "testuser",
    "isLogin": true
  }
}
```

### 用户服务接口 (User Service)

#### 1. 获取用户信息
```
GET /api/user/info/{userId}
Authorization: Bearer {token}

响应：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "nickname": "测试用户",
    "avatar": "http://example.com/avatar.jpg",
    "status": 1,
    "createTime": "2025-12-06 10:00:00"
  }
}
```

#### 2. 更新用户信息
```
PUT /api/user/update
Authorization: Bearer {token}
Content-Type: application/json

请求体：
{
  "nickname": "新昵称",
  "avatar": "http://example.com/new-avatar.jpg"
}

响应：
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

#### 3. 查询用户列表
```
GET /api/user/list?page=1&size=10
Authorization: Bearer {token}

响应：
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "pages": 10,
    "records": [...]
  }
}
```

## 环境配置

### 1. 安装 Nacos
```bash
# 下载 Nacos 2.x 版本
# 启动 Nacos (Windows)
startup.cmd -m standalone

# 启动 Nacos (Linux/Mac)
sh startup.sh -m standalone

# 访问 Nacos 控制台
http://localhost:8848/nacos
默认账号密码：nacos/nacos
```

### 2. 配置 MySQL
```sql
-- 创建数据库
CREATE DATABASE user_center DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 使用数据库
USE user_center;

-- 创建用户表
CREATE TABLE `sys_user` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '用户ID',
  `username` VARCHAR(50) NOT NULL COMMENT '用户名',
  `password` VARCHAR(255) NOT NULL COMMENT '密码',
  `email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
  `phone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
  `nickname` VARCHAR(50) DEFAULT NULL COMMENT '昵称',
  `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
  `status` TINYINT DEFAULT 1 COMMENT '状态 0:禁用 1:正常',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记 0:未删除 1:已删除',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`),
  UNIQUE KEY `uk_email` (`email`),
  UNIQUE KEY `uk_phone` (`phone`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

-- 创建角色表
CREATE TABLE `sys_role` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '角色ID',
  `role_name` VARCHAR(50) NOT NULL COMMENT '角色名称',
  `role_code` VARCHAR(50) NOT NULL COMMENT '角色编码',
  `description` VARCHAR(255) DEFAULT NULL COMMENT '角色描述',
  `status` TINYINT DEFAULT 1 COMMENT '状态 0:禁用 1:正常',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_role_name` (`role_name`),
  UNIQUE KEY `uk_role_code` (`role_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色表';

-- 创建用户角色关联表
CREATE TABLE `sys_user_role` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT 'ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `role_id` BIGINT NOT NULL COMMENT '角色ID',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_role` (`user_id`, `role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联表';
```

### 3. Nacos 配置

在 Nacos 控制台创建以下配置：

**user-service.yml**
```yaml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/user_center?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
```

**auth-service.yml**
```yaml
sa-token:
  token-name: Authorization
  timeout: 7200
  active-timeout: -1
  is-concurrent: true
  is-share: false
  token-style: uuid
  is-log: true
```

## 快速开始

### 1. 克隆项目
```bash
git clone https://github.com/your-repo/user-system.git
cd user-system
```

### 2. 启动基础服务
```bash
# 启动 Nacos
# 启动 MySQL
```

### 3. 启动微服务
```bash
# 按顺序启动以下服务：
# 1. 启动网关服务
cd user-center-gateway
mvn spring-boot:run

# 2. 启动用户服务
cd user-service
mvn spring-boot:run

# 3. 启动认证服务
cd auth-service
mvn spring-boot:run
```

### 4. 访问服务
- Nacos 控制台：http://localhost:8848/nacos
- 网关地址：http://localhost:8080
- 用户服务：http://localhost:8081
- 认证服务：http://localhost:8082

## 开发规范

### 代码规范
- 遵循阿里巴巴 Java 开发手册
- 使用 Lombok 简化代码
- 统一使用 Restful API 风格
- 使用 Swagger/Apifox 文档

### 分支管理
- master：主分支，稳定版本
- develop：开发分支
- feature/*：功能分支
- hotfix/*：热修复分支

### 提交规范
- feat：新功能
- fix：修复bug
- docs：文档更新
- style：代码格式调整
- refactor：重构
- test：测试相关
- chore：构建/工具变动

## 常见问题

### 1. Nacos 连接失败
- 检查 Nacos 是否正常启动
- 确认配置文件中的 Nacos 地址正确
- 检查网络连接

### 2. 数据库连接异常
- 确认 MySQL 服务已启动
- 检查数据库配置信息
- 验证数据库用户权限

### 3. Token 验证失败
- 检查 Token 是否过期
- 确认请求头格式正确
- 验证 Sa-Token 配置

## 后续规划

- [ ] 集成 Sentinel 流量控制
- [ ] 增加 OAuth2.0 第三方登录
- [ ] 实现分布式 Session
- [ ] 添加操作日志记录
- [ ] 完善单元测试
- [ ] Docker 容器化部署
- [ ] K8s 编排支持

## 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进项目。

## 许可证

[MIT License](LICENSE)

## 联系方式

- 项目负责人：
- 邮箱：
- 技术支持：

---

**最后更新时间：2025-12-06**