1

2026-02-10 08:54:19 +08:00
parent e394f2b51f
commit cc7f00659b
1 changed files with 188 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,188 @@
+# 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 改进本项目。