188 lines
5.1 KiB
Markdown
188 lines
5.1 KiB
Markdown
# 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 改进本项目。 |