Spring-cloud-2025.1.1/README.md

# Lingxiao 微服务项目

## 概述

Lingxiao 是一个基于 Spring Boot 4.0.2 构建的微服务示例项目，采用多模块 Maven 结构，包含认证服务、网关服务和业务服务。项目集成了 OpenTelemetry 分布式追踪、Spring Cloud 微服务组件、Kubernetes 服务发现与部署支持。

## 技术栈

- **Java 25** (使用 Maven 编译)
- **Spring Boot 4.0.2**
- **Spring Cloud 2025.1.1** (微服务基础设施)
- **Spring Security OAuth2** (认证与授权)
- **OpenTelemetry** (分布式追踪与日志)
- **Spring Cloud Gateway** (反应式网关)
- **Spring Cloud Kubernetes Fabric8** (Kubernetes 集成)
- **Caffeine** (本地缓存)
- **MySQL** (关系数据库)
- **Redis** (会话与缓存存储)
- **GraalVM Native Image** (原生镜像支持)
- **Kubernetes** (容器编排)

## 项目结构

```
lingxiao/
├── auth/                    # 认证服务模块
│   ├── src/main/java/com/example/springboot4/
│   │   └── Springboot4Application.java
│   ├── pom.xml
│   └── HELP.md
├── gateway/                # 网关服务模块
│   ├── src/main/java/com/example/geteway/
│   │   └── GatewayApplication.java
│   ├── pom.xml
│   └── HELP.md
├── a-service/              # 业务服务模块
│   ├── src/main/java/com/example/demo001/
│   │   └── Demo001Application.java
│   ├── pom.xml
│   └── HELP.md
├── k8s/                    # Kubernetes 部署配置
│   ├── auth-deployment.yaml
│   ├── gateway-deployment.yaml
│   ├── a-service-deployment.yaml
│   └── secrets.yaml
├── keys/                   # 密钥文件（非版本控制）
├── pom.xml                 # 父项目配置
├── mvnw                    # Maven 包装器
└── mvnw.cmd
```

## 模块说明

### 1. Auth (认证服务)
- 基于 Spring Security OAuth2 Authorization Server 实现认证与授权
- 使用 Jetty 作为内嵌 Web 容器（替换默认 Tomcat）
- 集成 MySQL 数据库与 Redis 会话存储
- 支持 GraalVM 原生镜像构建
- 服务端口：9000

### 2. Gateway (网关服务)
- 基于 Spring Cloud Gateway 的反应式 API 网关
- 集成 OAuth2 Resource Server 进行请求鉴权
- 服务端口：8083

### 3. A-Service (业务服务)
- 基于 WebFlux 的反应式业务服务
- 使用 HTTP 服务客户端 (`HttpServiceGroup`) 调用外部 API
- 服务端口：8091

## 构建与运行

### 前提条件
- JDK 25+
- Maven 3.6+
- Docker (用于容器化构建)
- Kubernetes 集群 (可选，用于部署)

### 构建项目
```bash
# 编译所有模块
./mvnw clean compile

# 打包所有模块（跳过测试）
./mvnw clean package -DskipTests
```

### 运行单个服务
```bash
# 运行认证服务
cd auth
../mvnw spring-boot:run

# 运行网关服务
cd gateway
../mvnw spring-boot:run

# 运行业务服务
cd a-service
../mvnw spring-boot:run
```

### 构建原生镜像 (GraalVM)
```bash
# 构建 auth 模块原生镜像
cd auth
../mvnw native:compile -Pnative

# 运行原生镜像
./target/springboot4
```

### 构建 Docker 镜像
每个模块都包含 Dockerfile，可使用以下命令构建：
```bash
# 构建 auth 镜像
cd auth
../mvnw spring-boot:build-image -DskipTests
```

## Kubernetes 部署

项目包含完整的 Kubernetes 部署配置，位于 `k8s/` 目录：

### 部署步骤
1. 构建 Docker 镜像并推送到镜像仓库
2. 创建密钥 Secret：
   ```bash
   kubectl apply -f k8s/secrets.yaml
   ```
3. 部署服务：
   ```bash
   kubectl apply -f k8s/auth-deployment.yaml
   kubectl apply -f k8s/gateway-deployment.yaml
   kubectl apply -f k8s/a-service-deployment.yaml
   ```

### 服务访问
部署后，服务将通过 LoadBalancer 类型暴露：
- **Auth Service**: `http://<cluster-ip>:9000`
- **Gateway Service**: `http://<cluster-ip>:8083`
- **A-Service**: `http://<cluster-ip>:8091`

## 配置说明

### OpenTelemetry 集成
项目已配置 OpenTelemetry 日志 appender 和 TraceId 过滤器，用于分布式追踪：
- `InstallOpenTelemetryAppender`: 配置日志与 OpenTelemetry 集成
- `TraceIdFilter`: 在 HTTP 请求中添加 Trace ID

### 日志配置
每个模块包含 `logback-spring.xml` 配置文件，支持结构化日志输出。

### 数据库配置
Auth 模块使用 MySQL 数据库，配置在 `application.properties` 中。

## 开发指南

### 添加新模块
1. 在父 `pom.xml` 的 `<modules>` 部分添加新模块
2. 创建模块目录和 `pom.xml`
3. 继承父项目配置，添加所需依赖

### 代码风格
- 使用 Lombok 减少样板代码
- 遵循 Spring Boot 最佳实践
- 使用 Java 25 新特性

## 故障排除

### 常见问题
1. **服务启动失败**：检查端口是否被占用，数据库连接是否正常
2. **Kubernetes 部署失败**：检查镜像拉取策略和 Secret 配置
3. **原生镜像构建失败**：确保 GraalVM 25+ 正确安装

### 日志查看
```bash
# 查看 Kubernetes Pod 日志
kubectl logs -f <pod-name>
```

## 许可证

本项目为示例项目，仅供学习参考。

## 贡献

欢迎提交 Issue 和 Pull Request 改进本项目。