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 集群 (可选，用于部署)

构建项目

# 编译所有模块
./mvnw clean compile

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

运行单个服务

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

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

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

构建原生镜像 (GraalVM)

# 构建 auth 模块原生镜像
cd auth
../mvnw native:compile -Pnative

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

构建 Docker 镜像

每个模块都包含 Dockerfile，可使用以下命令构建：

# 构建 auth 镜像
cd auth
../mvnw spring-boot:build-image -DskipTests

Kubernetes 部署

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

部署步骤

1. 构建 Docker 镜像并推送到镜像仓库
2. 创建密钥 Secret：

   kubectl apply -f k8s/secrets.yaml
   

3. 部署服务：

   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+ 正确安装

日志查看

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

许可证

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

贡献

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