From cc7f00659bfa2a5eefff64bc7895fb8c04e5e13a Mon Sep 17 00:00:00 2001 From: lingxiao865 <1060369102@qq.com> Date: Tue, 10 Feb 2026 08:54:19 +0800 Subject: [PATCH] 1 --- README.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..37a1f6f --- /dev/null +++ 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://:9000` +- **Gateway Service**: `http://:8083` +- **A-Service**: `http://:8091` + +## 配置说明 + +### OpenTelemetry 集成 +项目已配置 OpenTelemetry 日志 appender 和 TraceId 过滤器，用于分布式追踪： +- `InstallOpenTelemetryAppender`: 配置日志与 OpenTelemetry 集成 +- `TraceIdFilter`: 在 HTTP 请求中添加 Trace ID + +### 日志配置 +每个模块包含 `logback-spring.xml` 配置文件，支持结构化日志输出。 + +### 数据库配置 +Auth 模块使用 MySQL 数据库，配置在 `application.properties` 中。 + +## 开发指南 + +### 添加新模块 +1. 在父 `pom.xml` 的 `` 部分添加新模块 +2. 创建模块目录和 `pom.xml` +3. 继承父项目配置，添加所需依赖 + +### 代码风格 +- 使用 Lombok 减少样板代码 +- 遵循 Spring Boot 最佳实践 +- 使用 Java 25 新特性 + +## 故障排除 + +### 常见问题 +1. **服务启动失败**：检查端口是否被占用，数据库连接是否正常 +2. **Kubernetes 部署失败**：检查镜像拉取策略和 Secret 配置 +3. **原生镜像构建失败**：确保 GraalVM 25+ 正确安装 + +### 日志查看 +```bash +# 查看 Kubernetes Pod 日志 +kubectl logs -f +``` + +## 许可证 + +本项目为示例项目，仅供学习参考。 + +## 贡献 + +欢迎提交 Issue 和 Pull Request 改进本项目。 \ No newline at end of file