# cloud-nacos

**Repository Path**: wangpanA/cloud-nacos

## Basic Information

- **Project Name**: cloud-nacos
- **Description**: Demo Spring Cloud Doctor
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Cloud Nacos Demo

<div align="center">

![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.1-6DB33F)
![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2023.0.0-0A84FF)
![Spring Cloud Alibaba](https://img.shields.io/badge/Spring%20Cloud%20Alibaba-2023.0.1.2-1677FF)
![Nacos](https://img.shields.io/badge/Nacos-2.3.0-EF4E4E)
![License](https://img.shields.io/badge/License-MIT-F4B400)

一个面向实战的 Spring Cloud Alibaba 微服务示例项目。  
围绕 `Nacos 注册/配置中心`、`Gateway 网关`、`JWT 认证`、`RBAC 权限`、`Sentinel 限流熔断`、`RocketMQ 消息` 等能力，提供一套可运行、可扩展、可演示的完整工程。

</div>

---

## 项目定位

这个仓库不是单一功能 Demo，而是一个适合学习和二次开发的微服务脚手架，重点解决下面几类场景：

- 想快速搭建一套基于 Nacos 的 Spring Cloud 微服务基础工程
- 想把认证、鉴权、网关、服务调用、限流熔断串成一条完整链路
- 想拿一个能直接跑起来的项目，用于课程演示、毕设、内部 PoC 或个人练手
- 想在现有基础上继续扩展业务模块、前端页面、消息队列和部署方案

---

## 核心能力

- 统一网关入口：基于 Spring Cloud Gateway 做统一路由、跨域和安全拦截
- 认证鉴权：基于 JWT 的登录、刷新、校验、退出能力
- 权限控制：支持 RBAC 思路，可继续扩展菜单、按钮、接口级权限
- 服务治理：基于 Nacos 实现服务注册发现与配置集中管理
- 服务调用：基于 OpenFeign 实现服务间远程调用
- 稳定性治理：集成 Sentinel，支持限流、熔断、规则持久化
- 消息能力：集成 RocketMQ，覆盖生产、消费与部分测试场景
- 文档能力：集成 Knife4j，支持通过网关聚合查看接口文档
- 安全增强：包含接口安全、防重放、防刷、XSS/SQL 注入防护等扩展文档
- 容器部署：提供 `docker-compose.yml`，可一键拉起基础环境与核心服务

---

## 架构概览

```text
Client / Frontend
        |
        v
+----------------------+
|    nacos-gateway     |  统一入口 / 路由转发 / JWT 校验 / 文档聚合
+----------------------+
        |
        +---------------------> auth-service       (认证服务)
        |
        +---------------------> provider-service   (核心提供者服务)
        |
        +---------------------> consumer-service   (Feign 调用示例)
        |
        +---------------------> more business APIs...

Infrastructure:
- Nacos      : 注册中心 + 配置中心
- MySQL      : 业务数据存储
- Redis      : 缓存/状态支持
- RocketMQ   : 异步消息
- Sentinel   : 限流 / 熔断 / 降级
```

---

## 模块说明

| 模块 | 说明 | 默认本地端口 |
| --- | --- | --- |
| `nacos-gateway` | 网关层，统一入口、路由转发、JWT 校验、Knife4j 聚合 | `8080` |
| `nacos-auth` | 认证服务，负责登录、注册、Token 刷新与校验 | `8085` |
| `nacos-provider` | 提供者服务，承载用户与部分业务接口 | 由配置中心控制 |
| `nacos-consumer` | 消费者服务，演示 Feign 调用与服务协作 | 由配置中心控制 |
| `nacos-common` | 公共模块，封装 DTO、统一返回、异常处理、工具类等 | - |
| `nacos-frontend` | 前端工程，基于 Vue 3 + Element Plus | 前端开发端口由 Vite 决定 |

说明：

- `provider` 和 `consumer` 的具体端口可由 Nacos 配置中心或运行环境决定
- Docker 场景下暴露端口与本地开发端口不同，见下方“Docker 启动”

---

## 技术栈

| 类别 | 选型 |
| --- | --- |
| 基础框架 | Spring Boot 3.2.1、Spring Cloud 2023.0.0 |
| 微服务生态 | Spring Cloud Alibaba 2023.0.1.2、Nacos |
| 网关与调用 | Spring Cloud Gateway、OpenFeign、LoadBalancer |
| 安全认证 | Spring Security、JWT |
| 数据访问 | MySQL、MyBatis-Plus、Redis |
| 稳定性 | Sentinel |
| 消息队列 | RocketMQ |
| 接口文档 | Knife4j / OpenAPI 3 |
| 前端 | Vue 3、Vite、Element Plus、Pinia、Vue Router、ECharts |
| 构建工具 | Maven、Docker Compose |

---

## 仓库结构

```text
springcloud-nacos-demo
├── docs/                 项目文档
├── sql/                  初始化与业务 SQL
├── scripts/              辅助脚本
├── data/                 数据目录
├── nacos-auth/           认证服务
├── nacos-common/         公共模块
├── nacos-consumer/       消费者服务
├── nacos-gateway/        网关服务
├── nacos-provider/       提供者服务
├── nacos-frontend/       前端工程
├── docker-compose.yml    容器编排
└── pom.xml               Maven 父工程
```

---

## 快速开始

### 方式一：本地开发启动

适合需要调试代码、逐个模块启动的场景。

#### 1. 环境准备

- JDK `17+`
- Maven `3.8+`
- MySQL `8.0+`
- Redis `6+` 或 `7+`
- Nacos `2.3+`
- RocketMQ `4.x` 或与当前配置兼容的版本

#### 2. 初始化数据库

本仓库 `sql/` 目录下已经提供多份脚本，可按你的业务需要导入，例如：

- `sql/02_init.sql`
- `sql/03_rbac_init.sql`
- `sql/04_business_schema.sql`
- `sql/05_doctor_schema.sql`

如果你只是做最小化演示，建议先导入基础初始化脚本和 RBAC 相关脚本，再逐步补充业务表。

#### 3. 配置 Nacos

需要在 Nacos 中准备对应配置，通常包括：

- `nacos-auth`
- `nacos-gateway`
- `nacos-provider`
- `nacos-consumer`

至少要保证这些配置项正确：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_db
    username: your_username
    password: your_password

jwt:
  secret: your-jwt-secret
  expiration: 86400
```

注意：

- `auth` 与 `gateway` 中的 `jwt.secret` 必须保持一致
- `provider`、`consumer` 的数据库、Redis、Nacos 地址应与你本地环境一致

#### 4. 启动顺序

建议按下面顺序启动：

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

```bash
# 1. provider
cd nacos-provider
mvn spring-boot:run
```

```bash
# 2. auth
cd nacos-auth
mvn spring-boot:run
```

```bash
# 3. consumer
cd nacos-consumer
mvn spring-boot:run
```

```bash
# 4. gateway
cd nacos-gateway
mvn spring-boot:run
```

#### 5. 验证是否启动成功

```bash
curl http://localhost:8080/actuator/health
```

```bash
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"123456\"}"
```

---

### 方式二：Docker Compose 启动

适合快速体验整套环境。

```bash
docker compose up -d --build
```

默认会拉起这些容器：

- `mysql`
- `redis`
- `nacos`
- `rocketmq-namesrv`
- `rocketmq-broker`
- `rocketmq-dashboard`
- `nacos-provider`
- `nacos-auth`
- `nacos-consumer`
- `nacos-gateway`

Docker 默认端口映射如下：

| 服务 | 端口 |
| --- | --- |
| Gateway | `8000` |
| Provider | `8001` |
| Consumer | `8002` |
| Auth | `8003` |
| Nacos | `8848` |
| MySQL | `3306` |
| Redis | `6379` |
| RocketMQ Dashboard | `8081` |

说明：

- 本地开发常见端口是 `8080/8085/...`
- Docker 编排中对外暴露的是 `8000/8001/8002/8003`
- 首页展示时建议优先写明这两套端口差异，避免使用者混淆

---

## 常用访问入口

| 名称 | 地址 |
| --- | --- |
| 网关入口 | `http://localhost:8080` |
| 网关入口（Docker） | `http://localhost:8000` |
| Nacos 控制台 | `http://localhost:8848/nacos` |
| Knife4j 聚合文档 | `http://localhost:8080/doc.html` |
| RocketMQ Dashboard | `http://localhost:8081` |

---

## 接口示例

### 认证接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/auth/login` | 用户登录 |
| `POST` | `/auth/register` | 用户注册 |
| `POST` | `/auth/refresh` | 刷新 Token |
| `POST` | `/auth/verify` | 校验 Token |
| `POST` | `/auth/logout` | 用户退出 |
| `GET` | `/auth/me` | 获取当前用户信息 |

### Provider 接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/provider-service/provider/user/list` | 查询用户列表 |
| `GET` | `/provider-service/provider/user/{id}` | 根据 ID 查询用户 |
| `POST` | `/provider-service/provider/user/save` | 新增用户 |
| `PUT` | `/provider-service/provider/user/update` | 更新用户 |
| `DELETE` | `/provider-service/provider/user/{id}` | 删除用户 |

### Consumer 接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/consumer-service/consumer/hello` | Feign 调用演示 |
| `GET` | `/consumer-service/consumer/echo` | 本地测试接口 |
| `GET` | `/consumer-service/consumer/user/{id}` | 通过 Feign 查询用户 |

---

## 文档导航

如果你不是只想“跑起来”，而是想继续深入，建议直接看这些文档：

- [Docker 部署说明](docs/DOCKER_DEPLOY.md)
- [API 测试指南](docs/API_TEST_GUIDE.md)
- [RBAC 权限说明](docs/RBAC_GUIDE.md)
- [配置加密说明](docs/CONFIG_ENCRYPTION.md)
- [接口安全说明](docs/API_SECURITY.md)
- [Sentinel 使用说明](docs/SENTINEL.md)
- [RocketMQ 使用说明](docs/ROCKETMQ_GUIDE.md)

---

## 适合怎么用这个项目

- 作为 Spring Cloud Alibaba 学习样例
- 作为校招/毕设/课程设计的基础工程
- 作为中后台项目的微服务起步模板
- 作为认证鉴权、网关治理、服务调用、消息集成的演示仓库

---

## 后续可扩展方向

- Kubernetes 部署与 Helm 编排
- 链路追踪与可观测性接入
- 分布式事务支持
- 更完整的前后端联调示例
- CI/CD、自动化测试与发布流程

---

## 说明

- 当前仓库内部分配置与文档已经具备业务扩展痕迹，不再是最初的纯净最小 Demo
- 如果你打算对外展示，建议把业务场景、演示账号、默认密码、部署方式继续按你的目标受众再收敛一次
- 如果你需要，我可以继续帮你把 README 再细分成“Gitee 首页精简版 + docs/README-DEV 开发版”双文档结构

---

## License

本项目基于 [MIT License](LICENSE) 开源。