diff --git a/README.md b/README.md
new file mode 100644
index 0000000..57fc2de
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+# LingXiao 项目
+
+基于 Spring Boot 4 和 Spring Cloud 2025 的微服务架构示例，包含认证授权、API 网关和业务服务模块，支持 Kubernetes 原生部署。
+
+## 技术栈
+
+- **Java**: 25
+- **Spring Boot**: 4.0.2
+- **Spring Cloud**: 2025.1.1
+- **构建工具**: Maven
+- **数据库**: MySQL, Redis
+- **容器编排**: Kubernetes (Fabric8)
+- **Web 服务器**: Jetty (auth 模块), Netty (网关和业务服务)
+- **模板引擎**: Thymeleaf
+- **安全**: Spring Security OAuth2
+
+## 项目结构
+
+```
+lingxiao/
+├── auth/                    # 认证授权服务
+├── geteway/                 # API 网关
+├── a-service/               # 业务服务
+├── k8s/                     # Kubernetes 部署配置
+├── keys/                    # 密钥文件
+├── pom.xml                  # 父 POM
+└── mvnw, mvnw.cmd           # Maven Wrapper
+```
+
+### 模块说明
+
+#### auth (认证授权服务)
+- 基于 Spring Boot + Jetty
+- 集成 Spring Security OAuth2 Authorization Server
+- 使用 Redis 存储会话和缓存
+- 支持 MySQL 数据库存储用户信息
+- 启用 Kubernetes 服务发现 (`@EnableDiscoveryClient`)
+- 提供 Thymeleaf 模板页面
+
+#### geteway (API 网关)
+- 基于 Spring Cloud Gateway (WebFlux)
+- 集成 OAuth2 资源服务器和客户端
+- 作为微服务架构的入口点，负责路由、安全认证等
+
+#### a-service (业务服务)
+- 基于 Spring Boot WebFlux (响应式)
+- 使用 `@ImportHttpServices` 导入 HTTP 服务客户端
+- 示例业务逻辑服务
+
+## 快速开始
+
+### 环境要求
+- JDK 25+
+- Maven 3.9+
+- Docker & Kubernetes (可选，用于容器化部署)
+- MySQL 8.0+ 和 Redis 7.0+ (用于 auth 模块)
+
+### 构建项目
+```bash
+# 使用 Maven Wrapper (推荐)
+./mvnw clean package -DskipTests
+
+# 或直接使用 Maven
+mvn clean package -DskipTests
+```
+
+### 运行单个服务
+```bash
+# 运行认证服务
+cd auth
+../mvnw spring-boot:run
+
+# 运行网关
+cd geteway
+../mvnw spring-boot:run
+
+# 运行业务服务
+cd a-service
+../mvnw spring-boot:run
+```
+
+### 使用 Docker 运行
+```bash
+# 构建 Docker 镜像
+docker build -t lingxiao-auth ./auth
+docker build -t lingxiao-gateway ./geteway
+docker build -t lingxiao-a-service ./a-service
+```
+
+## Kubernetes 部署
+
+项目已包含 Kubernetes 部署配置 (`k8s/` 目录)：
+
+- `auth-deployment.yaml` - 认证服务部署
+- `gateway-deployment.yaml` - 网关部署
+- `a-service-deployment.yaml` - 业务服务部署
+- `secrets.yaml` - 密钥配置
+
+### 部署步骤
+1. 确保已安装 kubectl 并配置 Kubernetes 集群
+2. 应用配置文件：
+   ```bash
+   kubectl apply -f k8s/
+   ```
+
+## 配置说明
+
+### 数据库配置
+auth 模块需要 MySQL 和 Redis，配置位于 `auth/src/main/resources/application.properties` (或 application.yml)。
+
+### 服务发现
+项目使用 Spring Cloud Kubernetes Fabric8 进行服务发现，各服务会自动注册到 Kubernetes。
+
+### 安全配置
+- OAuth2 授权服务器运行在 auth 服务
+- 网关作为资源服务器验证令牌
+- 业务服务通过 HTTP 服务客户端调用认证服务
+
+## 开发指南
+
+### 添加新模块
+1. 在父 `pom.xml` 的 `<modules>` 中添加新模块
+2. 创建模块目录，包含自己的 `pom.xml`
+3. 继承父 POM：`<parent>` 指向 `com:lingxiao`
+
+### 代码风格
+- 使用 Lombok 减少样板代码
+- 遵循 Spring Boot 最佳实践
+- 响应式编程使用 WebFlux (网关和业务服务)
+
+### 测试
+```bash
+# 运行所有测试
+./mvnw test
+
+# 跳过测试
+./mvnw clean package -DskipTests
+```
+
+## 许可证
+
+本项目仅供学习参考，请根据实际需求调整使用。
\ No newline at end of file