# 基于 Spring Boot + FastAPI 实现 Java+AI（Python） 分离架构

**Repository Path**: mcb-git/SpringBootFastAPI

## Basic Information

- **Project Name**: 基于 Spring Boot + FastAPI 实现 Java+AI（Python） 分离架构
- **Description**: Java 层负责业务管控（权限、熔断、缓存），AI层通过Python 封装 LangChain RAG 与本地大模型调用；
设计了接口鉴权、全链路日志、降级策略等生产级特性，通过 Docker 容器化实现一键部署，兼顾 AI 能力灵活性与业务系统稳定性。

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-01-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 Spring Boot + FastAPI 实现 Java+AI（Python） 分离架构

## 介绍
Java 层负责业务管控（权限、熔断、缓存），AI层通过Python 封装 LangChain RAG 与本地大模型调用；
设计了接口鉴权、全链路日志、降级策略等生产级特性，通过 Docker 容器化实现一键部署，兼顾 AI 能力灵活性与业务系统稳定性。

## 软件架构
```
java-ai-separated-architecture/
├── java-layer/ (Spring Boot 模块 - 业务管控层)
│   ├── src/main/java/com/ai/mcb/
│   │   ├── config/           # 配置类
│   │   │   ├── CacheConfig.java      # 缓存配置
│   │   │   └── SecurityConfig.java   # 安全配置
│   │   ├── controller/       # 控制器层
│   │   │   ├── AIController.java     # AI服务控制器
│   │   │   └── AuthController.java   # 认证控制器
│   │   ├── service/          # 服务层
│   │   │   └── AIService.java        # AI服务实现
│   │   └── JavaLayerApplication.java # Spring Boot启动类
│   ├── src/main/resources/
│   │   ├── application.yml           # 主配置文件
│   │   ├── application-dev.yml       # 开发环境配置
│   │   ├── application-docker.yml    # Docker环境配置
│   │   └── static/                   # 静态资源
│   ├── pom.xml              # Maven依赖配置
│   └── Dockerfile           # Java层容器化配置
├── ai-service/ (Python FastAPI 模块 - AI层)
│   ├── app/
│   │   ├── db_connector.py  # 数据库连接器
│   │   ├── main.py          # FastAPI主应用
│   │   ├── models.py        # 数据模型定义
│   │   └── rag_manager.py   # RAG管理器
│   ├── travel_docs/         # 旅游文档目录
│   ├── requirements.txt     # Python依赖配置
│   └── Dockerfile           # Python层容器化配置
├── docker-compose.yml       # 多容器编排配置
└── README.md               # 项目说明文档
```


## 功能特性

### Java层 (Spring Boot)
- **接口鉴权**：基于JWT的用户认证和授权
- **服务熔断**：使用Resilience4j实现服务降级和熔断
- **缓存机制**：集成Caffeine缓存提升响应性能
- **全链路日志**：详细的请求追踪和日志记录
- **安全防护**：Spring Security配置，禁用CSRF，实现无状态会话管理

### Python层 (FastAPI)
- **RAG系统**：基于LangChain的检索增强生成
- **向量存储**：使用FAISS进行文档向量化存储
- **大模型集成**：支持通义千问等大模型
- **数据库操作**：MySQL数据库连接和操作
- **API文档**：自动生成的Swagger UI和ReDoc文档

## 环境要求
- **Java层**：JDK 17
- **Python层**：Python 3.12
- **数据库**：MySQL 8.0+
- **容器化**：Docker & Docker Compose

## 安装部署

### 本地开发环境

#### Java层配置
1. 确保已安装JDK 17
2. 配置环境变量
3. 构建项目：
```bash
cd java-layer
mvn clean install
```

4. 启动Java层服务：
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```


#### Python层配置
1. 确保已安装 Python 3.12
2. 创建虚拟环境并激活：
```bash
cd ai-service
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
```

3. 安装依赖：
```bash
pip install -r requirements.txt
```

4. 准备文档
    - 在项目根目录创建`travel_docs`文件夹
    - 将旅游相关的文档（.txt 或.pdf 格式）放入该文件夹

5. 配置环境变量
    - 创建`.env`文件，配置数据库连接和API密钥

6. 启动Python层服务：
```bash
# 开发环境启动
uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload

# 生产环境启动（可使用gunicorn）
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app -b 0.0.0.0:8008
```


### Docker容器化部署

1. **构建单个服务查看进度**（可选）
```bash
docker-compose build ai-service  # 这个可能较慢
docker-compose build java-service  # 这个可能较慢
```


2. **构建完成后，再启动服务**
```bash
docker-compose up -d --build
```


3. **如果之前构建成功过，可直接启动**
```bash
docker-compose up -d --no-build
```


4. **查看构建过程**
```bash
docker-compose logs -f
```


## API接口说明

### Java层接口

#### 认证接口
- `POST /api/v1/auth/token` - 获取JWT令牌

#### AI服务接口
- `GET /api/v1/ai/query` - 调用AI服务生成旅行计划
    - 参数：
        - `userInput`: 用户输入的计划调整需求
        - `userId`: 用户ID
        - `sessionId`: 会话ID
        - [destination](file://E:\MyProject\docker\java-ai-separated-architecture\ai-service\app\models.py#L38-L38): 目的地

### Python层接口

#### 主要功能接口
1. **生成旅游计划**：`POST /api/travel/plan`
    - 接收用户输入和历史对话，返回生成的旅游计划

2. **RAG 知识库查询**：`POST /api/rag/query`
    - 单独提供文档检索功能，返回相关文档片段

3. **保存旅游计划**：`POST /api/travel/save`
    - 将生成的旅游计划保存到数据库

4. **健康检查**：`GET /health`
    - 检查服务状态和 RAG 初始化情况

#### Python层API文档
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 配置说明

### Java层配置
- `application-dev.yml` - 本地开发环境配置
- `application-docker.yml` - Docker环境配置
- `application.yml` - 主配置文件

### Python层配置
- `requirements.txt` - 依赖包列表
- `init.sql` - 数据库初始化脚本
- `.env` - 环境变量配置

## 技术栈

### Java层
- **框架**：Spring Boot 3.2.0
- **安全**：Spring Security + JWT
- **缓存**：Caffeine
- **熔断**：Resilience4j
- **HTTP客户端**：Spring WebFlux WebClient
- **构建工具**：Maven

### Python层
- **框架**：FastAPI
- **AI框架**：LangChain 1.1.3
- **向量存储**：FAISS
- **数据库**：MySQL Connector
- **嵌入模型**：DashScope文本嵌入
- **文档格式**：支持PDF和TXT

## 数据库设计

系统包含以下主要数据表：
- `attractions` - 旅游景点知识库
- `travel_plans` - 旅游计划表
- `itineraries` - 行程安排表
- `travel_tips` - 旅游建议表
- `chat_history` - 对话历史表

## 安全说明

- Java层使用JWT进行身份验证和授权
- 接口访问需要Bearer Token认证
- 遵循最小权限原则，不同角色具有不同访问权限
- 所有敏感信息通过环境变量配置

## 性能优化

- 使用Caffeine缓存减少重复AI调用
- 通过服务熔断机制提升系统稳定性
- 异步处理提升响应速度
- 向量数据库优化文档检索性能

## 故障排查

1. 检查各服务端口是否冲突
2. 确认数据库连接配置正确
3. 验证API密钥是否有效
4. 查看日志输出定位问题
5. 确保Docker资源分配充足

## 扩展建议

- 集成更多AI模型提供服务
- 增加监控和告警机制
- 实现更复杂的缓存策略
- 添加多语言支持
- 集成更多数据源增强RAG能力