# lumin-cloud

**Repository Path**: xfcode-projects/lumin-cloud

## Basic Information

- **Project Name**: lumin-cloud
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lumin Cloud 微服务平台

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.java.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.0-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2023.0.0-brightgreen.svg)](https://spring.io/projects/spring-cloud)
[![Production Ready](https://img.shields.io/badge/status-production%20ready-success.svg)]()

> 🚀 基于 Spring Cloud 的企业级微服务平台，集成 Nacos、OAuth2、Sentinel、Zipkin 等核心组件

---

## 📖 项目简介

Lumin Cloud （鹿鸣）是一个功能完整的微服务平台，提供企业级微服务架构所需的核心能力：

**核心功能**：
- ✅ **服务注册与发现** - 基于 Nacos 的服务治理
- ✅ **配置中心** - 集中式配置管理，支持动态刷新
- ✅ **API网关** - Spring Cloud Gateway，统一入口
- ✅ **认证授权** - OAuth2 + JWT，标准化身份认证
- ✅ **限流熔断** - Sentinel，智能流量控制
- ✅ **链路追踪** - Sleuth + Zipkin，全链路监控

**核心价值**：
- 🎯 **开箱即用** - 预集成主流微服务组件
- 🔒 **安全可靠** - OAuth2 + JWT 标准化认证
- ⚡ **高性能** - 响应式网关，支持高并发
- 🔍 **可观测** - 全链路追踪，实时监控
- 📦 **易扩展** - 模块化设计，支持水平扩展

**详细文档**: [📚 cloud-doc/README.md](./cloud-doc/README.md)

---

## 🏗️ 项目结构

```
lumin-cloud/
├── cloud-doc/                  # 📚 完整文档中心
│   ├── README.md              # 文档导航索引
│   ├── FEATURES.md            # 功能说明文档
│   ├── QUICK_START_GUIDE.md   # 快速开始指南
│   ├── API_REFERENCE.md       # API接口文档
│   ├── OAUTH2_GUIDE.md        # OAuth2认证指南
│   ├── CONFIGURATION_GUIDE.md # 配置管理指南
│   ├── MICROSERVICES_USAGE.md # 详细使用指南
│   ├── PRODUCTION_DEPLOYMENT_CHECKLIST.md  # 生产部署清单
│   ├── PRODUCTION_SECURITY_CHECKLIST.md    # 安全检查清单
│   └── README_MICROSERVICES.md             # 项目说明文档
│
├── lumin-gateway/             # 🔀 API网关服务 (8080)
│   ├── src/main/java/
│   ├── src/main/resources/
│   ├── pom.xml
│   └── Dockerfile
│
├── lumin-auth/                # 🔐 认证授权服务 (9001)
│   ├── src/main/java/
│   ├── src/main/resources/
│   ├── pom.xml
│   └── Dockerfile
│
├── lumin-user/                # 👤 用户服务 (9002)
│   ├── src/main/java/
│   ├── src/main/resources/
│   ├── pom.xml
│   └── Dockerfile
│
├── lumin-common/              # 📦 公共模块
├── docker-compose.yml         # 🐳 Docker编排配置
├── pom.xml                    # Maven父项目
├── start-services.bat         # Windows启动脚本
├── start-services-prod.bat    # 生产环境启动脚本
└── README.md                  # 本文件
```

### 模块说明

| 模块 | 说明 | 端口 | 状态 |
|------|------|------|------|
| **lumin-gateway** | API网关，路由转发、负载均衡、限流 | 8080 | ✅ 已完成 |
| **lumin-auth** | OAuth2认证授权、JWT令牌管理 | 9001 | ✅ 已完成 |
| **lumin-user** | 用户服务、业务逻辑处理 | 9002 | ✅ 已完成 |
| **lumin-common** | 公共工具类、通用组件 | - | ✅ 已完成 |

---

## 🚀 快速开始

**推荐阅读**: [📖 cloud-doc/QUICK_START_GUIDE.md](./cloud-doc/QUICK_START_GUIDE.md) - 完整快速开始指南

### 前置要求

- **JDK**: 17+
- **Maven**: 3.6+
- **Docker**: 20.10+（可选，用于容器化部署）
- **Git**: 2.x

### 方式一：Docker Compose（推荐）⭐

```bash
# 1. 克隆项目
git clone <repository-url>
cd lumin-cloud

# 2. 启动基础设施（Nacos, Sentinel, Zipkin）
docker-compose up -d nacos sentinel zipkin

# 等待1-2分钟，确保基础设施完全启动

# 3. 构建并启动应用服务
docker-compose build
docker-compose up -d lumin-gateway lumin-auth lumin-user

# 4. 验证服务
curl http://127.0.0.1:8080/health
```

### 方式二：本地开发环境

#### Step 1: 启动基础设施

```bash
# 使用 Docker 启动 Nacos, Sentinel, Zipkin
docker-compose up -d nacos sentinel zipkin
```

#### Step 2: 启动应用服务

**Windows:**
```bash
start-services.bat
```

**Linux/Mac:**
```bash
# 需要打开三个终端分别启动

# 终端1 - Gateway
cd lumin-gateway && mvn spring-boot:run

# 终端2 - Auth
cd lumin-auth && mvn spring-boot:run

# 终端3 - User
cd lumin-user && mvn spring-boot:run
```

### 验证服务

访问以下地址确认服务正常运行：

| 服务 | 地址 | 说明 |
|------|------|------|
| **API网关** | http://127.0.0.1:8080 | 统一API入口 |
| **健康检查** | http://127.0.0.1:8080/health | 网关健康状态 |
| **Nacos控制台** | http://127.0.0.1:8848/nacos | 服务注册中心 (nacos/nacos) |
| **Sentinel控制台** | http://127.0.0.1:8858 | 限流熔断监控 (sentinel/sentinel) |
| **Zipkin链路追踪** | http://127.0.0.1:9411 | 分布式追踪UI |

---

## 📋 核心功能

详细说明请参考：[📖 cloud-doc/FEATURES.md](./cloud-doc/FEATURES.md)

### 1. 服务注册与发现 🔍

- ✅ 自动服务注册与注销
- ✅ 服务实例健康检查
- ✅ 负载均衡（Ribbon）
- ✅ 命名空间隔离
- ✅ 多环境支持

**技术**: Nacos Discovery

### 2. 配置中心 ⚙️

- ✅ 集中式配置管理
- ✅ 配置动态刷新（@RefreshScope）
- ✅ 配置版本管理
- ✅ 多环境配置隔离
- ✅ 配置变更历史

**技术**: Nacos Config

### 3. API网关 🚪

- ✅ 统一入口路由
- ✅ 请求转发与负载均衡
- ✅ 全局过滤器链
- ✅ 跨域配置（CORS）
- ✅ 限流熔断集成
- ✅ 路径重写

**技术**: Spring Cloud Gateway

### 4. 认证授权 🔐

- ✅ OAuth2.0 标准协议
- ✅ JWT 令牌生成与验证
- ✅ RSA 密钥对签名
- ✅ 四种授权模式
  - 密码模式（Password）
  - 授权码模式（Authorization Code）
  - 客户端凭证模式（Client Credentials）
  - 刷新令牌模式（Refresh Token）
- ✅ Scope 权限控制

**技术**: Spring Authorization Server + JWT

### 5. 限流熔断 🛡️

- ✅ QPS 流量控制
- ✅ 线程数控制
- ✅ 熔断降级
- ✅ 系统自适应保护
- ✅ 实时监控面板

**技术**: Alibaba Sentinel

### 6. 链路追踪 🔗

- ✅ 自动生成 TraceId 和 SpanId
- ✅ 跨服务链路追踪
- ✅ 请求耗时统计
- ✅ 依赖关系分析
- ✅ 采样率控制

**技术**: Spring Cloud Sleuth + Zipkin

---

## 🔧 技术栈

**详细技术栈**: [📖 cloud-doc/FEATURES.md#技术架构](./cloud-doc/FEATURES.md#技术架构)

### 核心技术

| 技术 | 版本 | 说明 |
|------|------|------|
| **Java** | 17 | LTS版本 |
| **Spring Boot** | 3.2.0 | 应用框架 |
| **Spring Cloud** | 2023.0.0 | 微服务框架 |
| **Spring Cloud Alibaba** | 2022.0.0.0 | 阿里云微服务套件 |
| **Spring Cloud Gateway** | 4.1.0 | API网关 |
| **Spring Authorization Server** | 1.2.0 | OAuth2认证服务器 |

### 中间件

| 中间件 | 版本 | 用途 |
|--------|------|------|
| **Nacos** | 2.3.0 | 服务注册与配置中心 |
| **Sentinel** | 1.8.6 | 流量控制与熔断降级 |
| **Sleuth** | 3.1.7 | 分布式链路追踪 |
| **Zipkin** | Latest | 链路追踪UI |
| **JWT (jjwt)** | 0.12.3 | JSON Web Token |

### 工具库

- **Lombok** - 简化代码
- **Hutool** - Java工具类库
- **Logback** - 日志框架
- **Maven** - 项目管理

---

## 📚 文档中心

所有文档位于 `cloud-doc/` 目录：

### 🚀 新手入门
- [📖 文档导航](./cloud-doc/README.md) - 文档中心索引
- [⚡ 快速开始](./cloud-doc/QUICK_START_GUIDE.md) - 5分钟快速启动 ⭐
- [🎯 功能说明](./cloud-doc/FEATURES.md) - 平台功能详解

### 💻 开发参考
- [📡 API文档](./cloud-doc/API_REFERENCE.md) - 完整API接口
- [🔐 OAuth2指南](./cloud-doc/OAUTH2_GUIDE.md) - 认证授权详解
- [⚙️ 配置管理](./cloud-doc/CONFIGURATION_GUIDE.md) - Nacos配置中心

### 🏗️ 部署运维
- [📋 部署清单](./cloud-doc/PRODUCTION_DEPLOYMENT_CHECKLIST.md) - 生产部署步骤
- [🔒 安全检查](./cloud-doc/PRODUCTION_SECURITY_CHECKLIST.md) - 安全加固措施
- [📖 使用指南](./cloud-doc/MICROSERVICES_USAGE.md) - 详细使用说明

---

## 🧪 API测试

### 1. 获取OAuth2令牌

```bash
curl -X POST http://127.0.0.1:8080/auth/oauth2/token \
  -H "Authorization: Basic bHVtaW4tY2xpZW50OnNlY3JldA==" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=admin&password=admin123&scope=read write"
```

**响应示例**:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7199,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}
```

### 2. 使用令牌访问资源

```bash
# 将 YOUR_TOKEN 替换为上面获取的 access_token
curl http://127.0.0.1:8080/user/api/user/info \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": 1,
    "username": "admin",
    "nickname": "管理员",
    "email": "admin@lumin.cloud"
  },
  "timestamp": 1716242400000
}
```

### 3. 健康检查

```bash
curl http://127.0.0.1:8080/health
```

更多API请参考：[📡 cloud-doc/API_REFERENCE.md](./cloud-doc/API_REFERENCE.md)

---

## 🐳 Docker部署

### 构建镜像

```bash
# 构建所有服务镜像
docker-compose build

# 或单独构建某个服务
docker-compose build lumin-gateway
```

### 启动服务

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 生产环境部署

```bash
# 设置环境变量
export JWT_SECRET="your-production-jwt-secret"
export OAUTH2_CLIENT_SECRET="$2a$10$..."

# 使用生产配置启动
docker-compose -f docker-compose.yml up -d
```

详细部署指南：[📋 cloud-doc/PRODUCTION_DEPLOYMENT_CHECKLIST.md](./cloud-doc/PRODUCTION_DEPLOYMENT_CHECKLIST.md)

---

## 📊 监控与管理

### Actuator 端点

| 端点 | 路径 | 说明 |
|------|------|------|
| health | /actuator/health | 健康检查 |
| info | /actuator/info | 应用信息 |
| metrics | /actuator/metrics | 性能指标 |
| gateway | /actuator/gateway/routes | 网关路由（仅Gateway） |

### 日志管理

日志文件位于各模块的 `logs/` 目录：
- `lumin-gateway.log` - 网关日志
- `lumin-auth.log` - 认证服务日志
- `lumin-user.log` - 用户服务日志

**日志特性**:
- ✅ 包含 TraceId 和 SpanId
- ✅ 自动滚动（单文件100MB，保留30天）
- ✅ 分级输出（INFO/WARN/ERROR）

---

## 🤝 贡献指南

欢迎贡献代码和文档！

### 贡献流程

1. **Fork** 本仓库
2. **创建分支** (`git checkout -b feature/amazing-feature`)
3. **提交更改** (`git commit -m 'Add amazing feature'`)
4. **推送分支** (`git push origin feature/amazing-feature`)
5. **开启 Pull Request**

### 开发规范

- 遵循 Java 代码规范
- 编写单元测试
- 更新相关文档
- 保持commit信息清晰

---

## 📄 许可证

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

---

## 📞 联系方式

- **项目主页**: [GitHub Repository](repository-url)
- **问题反馈**: [Issues](repository-url/issues)
- **文档中心**: [cloud-doc/README.md](./cloud-doc/README.md)

---

## 🎯 后续规划

- [ ] 集成数据库（MyBatis Plus + MySQL）
- [ ] 集成Redis缓存
- [ ] 消息队列集成（RabbitMQ/Kafka）
- [ ] 分布式事务（Seata）
- [ ] API文档聚合（Knife4j/Swagger）
- [ ] 容器化部署优化（Kubernetes）
- [ ] CI/CD流程搭建

---

## 🌟 Star History

如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！

---

**Version**: 1.0.0  
**Last Updated**: 2026-05-20  
**Status**: 🟢 Production Ready  
**Documentation**: [📚 cloud-doc/README.md](./cloud-doc/README.md)

---

<div align="center">

**Made with ❤️ by Lumin Cloud Team**

[⬆ Back to Top](#lumin-cloud-微服务平台)

</div>