Content
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=180§ion=header&text=Refinex-Cloud&fontSize=52&fontColor=fff&animation=twinkling&fontAlignY=36&desc=Enterprise-Grade%20AI%20Microservices%20%C2%B7%20Spring%20Cloud%20Alibaba%20%2B%20Spring%20AI&descAlignY=58&descSize=16" alt="Refinex-Cloud Banner" width="100%"/>
<br/>
<p>
<img src="https://img.shields.io/badge/Java-21-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white" alt="Java 21"/>
<img src="https://img.shields.io/badge/Spring_Boot-3.5.x-6DB33F?style=for-the-badge&logo=spring-boot&logoColor=white" alt="Spring Boot"/>
<img src="https://img.shields.io/badge/Spring_Cloud-2025.0.x-6DB33F?style=for-the-badge&logo=spring&logoColor=white" alt="Spring Cloud"/>
<img src="https://img.shields.io/badge/Spring_AI-1.1.2-FF6B35?style=for-the-badge&logo=spring&logoColor=white" alt="Spring AI"/>
</p>
<p>
<img src="https://img.shields.io/badge/Spring_Cloud_Alibaba-2025.0.0.0-FF6A00?style=for-the-badge&logo=alibaba-cloud&logoColor=white" alt="Spring Cloud Alibaba"/>
<img src="https://img.shields.io/badge/Sa--Token-1.39.x-007EC6?style=for-the-badge&logo=jsonwebtokens&logoColor=white" alt="Sa-Token"/>
<img src="https://img.shields.io/badge/MyBatis--Plus-3.5.x-1E90FF?style=for-the-badge&logo=databricks&logoColor=white" alt="MyBatis-Plus"/>
</p>
<p>
<img src="https://img.shields.io/github/stars/refinex-lab/Refinex-Cloud?style=for-the-badge&color=FFD700&logo=github" alt="Stars"/>
<img src="https://img.shields.io/github/forks/refinex-lab/Refinex-Cloud?style=for-the-badge&color=1E90FF&logo=git&logoColor=white" alt="Forks"/>
<img src="https://img.shields.io/github/issues/refinex-lab/Refinex-Cloud?style=for-the-badge&color=FF6B6B&logo=github&logoColor=white" alt="Issues"/>
<img src="https://img.shields.io/github/license/refinex-lab/Refinex-Cloud?style=for-the-badge&color=4CAF50" alt="License"/>
<img src="https://img.shields.io/github/last-commit/refinex-lab/Refinex-Cloud?style=for-the-badge&color=9C27B0&logo=git&logoColor=white" alt="Last Commit"/>
</p>
<br/>
**Refinex-Cloud** is Refinex platform's back-end microservice project, built on **Spring Cloud Alibaba 2025**, deeply integrating **Spring AI 1.1.2** to provide production-level AI inference capabilities. The platform covers core AI scenarios such as AI dialogue, RAG knowledge base, Agent orchestration, MCP protocol, text-to-image, text-to-video, TTS, etc., with complete enterprise-level infrastructure - permission control, distributed transactions, full-link tracking, unified file storage, etc., aiming to become the most valuable open-source AI back-end solution.
<br/>
[🌐 Official Documentation](https://www.refinex.cn) · [🚀 Quick Start](#-quick-start) · [📐 System Architecture](#-system-architecture) · [✨ Core Features](#-core-features) · [📦 Project Structure](#-project-structure) · [🛠 Technology Stack](#-technology-stack) · [🗺 Roadmap](#-roadmap) · [🤝 Contribution Guide](#-contribution-guide)
<br/>
</div>
## 🔗 Related Projects
This repository is the **back-end microservice project** of the Refinex platform, which, together with the front-end application, constitutes a complete full-stack AI platform.
<table>
<thead>
<tr>
<th>Project</th>
<th>Repository Address</th>
<th>Description</th>
<th>Core Technology</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>🖥️ Refinex-Agent</b></td>
<td><a href="https://github.com/refinex-lab/Refinex-Agent"><code>refinex-lab/Refinex-Agent</code></a></td>
<td>A modern front-end application designed for AI Agent interaction scenarios, driving dialogue, knowledge base management, Agent orchestration, and multimedia creation with an ultimate visual experience.</td>
<td>shadcn/ui · Tailwind CSS 4.2 · AI Elements</td>
</tr>
<tr>
<td><b>⚙️ Refinex-Cloud</b></td>
<td><a href="https://github.com/refinex-lab/Refinex-Cloud"><code>refinex-lab/Refinex-Cloud</code></a></td>
<td>This repository — Enterprise-grade AI microservice back-end platform.</td>
<td>Spring Cloud Alibaba · Spring AI · Java 21</td>
</tr>
</tbody>
</table>
> 📖 Complete usage documentation, deployment guide, and API reference can be found at **[www.refinex.cn](https://www.refinex.cn)**.
## ✨ Core Features
<table>
<tr>
<td width="50%" valign="top">
<h3>🤖 AI Dialogue</h3>
<ul>
<li>Multi-turn context-aware dialogue, session history persistence management.</li>
<li>Streaming SSE real-time output, based on WebFlux reactive architecture.</li>
<li>Flexible switching of multiple model providers (OpenAI, Ollama, Tongyi Qianwen, etc.).</li>
<li>System Prompt template management, role preset configuration.</li>
</ul>
</td>
<td width="50%" valign="top">
<h3>📚 RAG Knowledge Base</h3>
<ul>
<li>Supports PDF, Word, Markdown, web page multi-format document parsing.</li>
<li>Intelligent text chunking strategy, semantic vectorization storage.</li>
<li>High-performance similarity retrieval based on Milvus / PGVector.</li>
<li>Recall test and relevance score visualization.</li>
</ul>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<h3>🛠 Agent & MCP</h3>
<ul>
<li>Tool call orchestration based on Spring AI Tool Callback.</li>
<li>MCP (Model Context Protocol) Server/Client complete integration.</li>
<li>Agent workflow visual design and execution tracking.</li>
<li>Built-in toolset: network search, code execution, file operation, etc.</li>
</ul>
</td>
<td width="50%" valign="top">
<h3>🎨 Multi-modal Media Generation</h3>
<ul>
<li>Text-to-image: access DALL-E 3, Stable Diffusion, Tongyi Wanxiang.</li>
<li>Text-to-video: access Sora, KeLing, and other mainstream video generation models.</li>
<li>TTS voice synthesis: OpenAI TTS, Alibaba Cloud voice service.</li>
<li>Asynchronous task queue + SSE real-time progress push.</li>
</ul>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<h3>🔐 Permission and Security</h3>
<ul>
<li>JWT stateless authentication system based on Sa-Token.</li>
<li>RBAC role permission model, fine-grained menu and data permission.</li>
<li>Multi-terminal login management, supporting strong kick-off.</li>
<li>Third-party OAuth2 social login integration.</li>
</ul>
</td>
<td width="50%" valign="top">
<h3>⚡ Platform Basic Capabilities</h3>
<ul>
<li>Dynamic routing gateway, Sentinel full-link traffic protection.</li>
<li>Seata AT standard distributed transaction (already implemented in auth registration link and system background user initialization link), Redisson distributed lock.</li>
<li>Idempotence control, Micrometer + OTel full-link tracking.</li>
<li>Unified file storage (MinIO / OSS / local), Office document processing.</li>
</ul>
</td>
</tr>
</table>
## 📐 System Architecture
```mermaid
flowchart TD
Client["🖥️ Client Layer\nBrowser / Mobile App\n(Refinex-Agent Frontend)"]
Gateway["⚡ refinex-gateway\nSpring Cloud Gateway\nToken verification · Dynamic routing · Sentinel current limiting · Gray routing · Log filtering"]
Auth["🔑 refinex-auth\nLogin authentication · Token"]
System["🏢 refinex-system\nUser permission · Menu/dictionary"]
AI["🤖 refinex-ai\nDialogue / Agent\nMCP / RAG\n(WebFlux)"]
Media["🎨 refinex-media\nImage/video · TTS / OSS\n(WebFlux)"]
Knowledge["📚 refinex-knowledge\nVector database / RAG\nDocument parsing"]
Nacos["🧭 Nacos\nRegistration + Configuration"]
RocketMQ["📨 RocketMQ 5.x\nAsynchronous task + Log"]
Redis["⚡ Redis Cluster\nCache + Distributed lock"]
Persistence["🗄️ Persistence Layer\nMySQL (business data) · Milvus / PGVector (vector) · MinIO (file)"]
Observability["🔭 Observability Stack\nPrometheus · Jaeger · ELK\nSpring Boot Admin · XXL-Job"]
Client -->|"HTTPS / WSS / SSE"| Gateway
Gateway --> Auth
Gateway --> System
Gateway --> AI
Gateway --> Media
Gateway --> Knowledge
Auth & System & AI & Media & Knowledge --> Nacos
Auth & System & AI & Media & Knowledge --> RocketMQ
Auth & System & AI & Media & Knowledge --> Redis
Nacos --> Persistence
Persistence --> Observability
style Client fill:#4A90D9,stroke:#2C5F8A,color:#fff
style Gateway fill:#7B68EE,stroke:#4B3BA8,color:#fff
style Auth fill:#E07B54,stroke:#A84C2A,color:#fff
style System fill:#5BA85A,stroke:#2E6B2D,color:#fff
style AI fill:#D4618C,stroke:#9B3060,color:#fff
style Media fill:#D4A017,stroke:#9B6E0A,color:#fff
style Knowledge fill:#4AADAD,stroke:#2A7A7A,color:#fff
style Nacos fill:#FF6A00,stroke:#B84A00,color:#fff
style RocketMQ fill:#C0392B,stroke:#7B1A12,color:#fff
style Redis fill:#C0392B,stroke:#7B1A12,color:#fff
style Persistence fill:#2C3E50,stroke:#1A252F,color:#fff
style Observability fill:#1A6B3C,stroke:#0D3D21,color:#fff
```
## 📦 Project Structure
<details>
<summary><b>🗂 Click to expand the complete project structure</b></summary>
```
refinex-cloud/ # Parent aggregation project (Maven POM)
│
├── refinex-gateway/ # API Gateway (WebFlux kernel, unified entrance)
├── refinex-auth/ # Authentication and authorization service (Sa-Token + JWT)
│
├── refinex-common/ # General capability library (Jar, introduced as needed)
│ ├── refinex-common-core/ # Response body, exception, tool class, Jackson configuration
│ ├── refinex-common-web/ # MVC layer: global exception, idempotence, XSS protection
│ ├── refinex-common-webflux/ # WebFlux layer: reactive exception, MDC propagation
│ ├── refinex-common-security/ # Sa-Token unified security configuration
│ ├── refinex-common-redis/ # Redisson, distributed lock, Bloom filter
│ ├── refinex-common-mybatis/ # MP plugin, multi-data source, data permission, BaseEntity
│ ├── refinex-common-file/ # Unified file storage abstraction (MinIO/OSS/local)
│ ├── refinex-common-office/ # Apache POI, Commons CSV, PDFBox, OpenHTMLToPDF
│ ├── refinex-common-log/ # Operation log annotation, desensitization, asynchronous writing
│ ├── refinex-common-trace/ # Micrometer Tracing, OTel link tracking
│ ├── refinex-common-ratelimit/ # Sentinel + Redis Lua sliding window current limiting
│ ├── refinex-common-mq/ # RocketMQ encapsulation (delayed/transactional/idempotent consumption)
│ ├── refinex-common-sms/ # SMS multi-channel (Alibaba/Tencent) unified encapsulation
│ ├── refinex-common-mail/ # Thymeleaf template mail sending
│ ├── refinex-common-transaction/ # Seata AT/TCC distributed transaction (auth/system/knowledge has been accessed)
│ └── refinex-common-job/ # XXL-Job Executor distributed task
│
├── refinex-api/ # Feign interface SDK (service call contract)
│ ├── refinex-api-system/ # User, permission query interface definition
│ ├── refinex-api-ai/ # AI dialogue interface definition
│ └── refinex-api-knowledge/ # Vector retrieval interface definition
│
└── refinex-modules/ # Business microservices
├── refinex-system/ # System management: user/role/menu/dictionary/department
├── refinex-ai/ # AI core: dialogue/Agent/MCP (WebFlux)
├── refinex-media/ # Media generation: text-to-image/video/TTS (WebFlux)
├── refinex-knowledge/ # Knowledge base: RAG/vectorization/document management
└── refinex-monitor/ # Monitoring and alarm: Boot Admin/indicator/alarm notification
```
</details>
## 🛠 Technical Stack Overview
<table>
<thead>
<tr>
<th>Layer</th>
<th>Technical Components</th>
<th>Version / Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>Runtime</b></td>
<td>Java</td>
<td>21 LTS · Virtual Threads · Record · Pattern Matching</td>
</tr>
<tr>
<td rowspan="5"><b>Core Framework</b></td>
<td>Spring Boot</td>
<td>3.5.x</td>
</tr>
<tr>
<td>Spring Cloud</td>
<td>2025.0.x（Gateway · OpenFeign · LoadBalancer）</td>
</tr>
<tr>
<td>Spring Cloud Alibaba</td>
<td>2025.0.0.0（Nacos · Sentinel · Seata · RocketMQ）</td>
</tr>
<tr>
<td>Spring AI</td>
<td>1.1.2（ChatClient · RAG · MCP · ImageModel · SpeechModel）</td>
</tr>
<tr>
<td>Spring WebFlux</td>
<td>Reactive stack, dedicated to AI streaming inference services</td>
</tr>
<tr>
<td rowspan="2"><b>Authentication and Security</b></td>
<td>Sa-Token</td>
<td>1.39.x · JWT stateless mode · MVC & Reactor dual-stack adaptation</td>
</tr>
<tr>
<td>OAuth2</td>
<td>Social login, supporting GitHub, WeChat and other third-party platform access</td>
</tr>
<tr>
<td rowspan="2"><b>Persistence</b></td>
<td>MyBatis-Plus</td>
<td>3.5.x · Dynamic-Datasource multi-data source · Druid connection pool</td>
</tr>
<tr>
<td>MySQL / PostgreSQL</td>
<td>Business data primary database</td>
</tr>
<tr>
<td rowspan="2"><b>AI Infrastructure</b></td>
<td>Milvus / PGVector</td>
<td>Vector database, RAG semantic retrieval</td>
</tr>
<tr>
<td>OpenAI / Ollama / Tongyi Qianwen</td>
<td>LLM · Embedding · Image · TTS multi-provider unified access</td>
</tr>
<tr>
<td rowspan="2"><b>Cache / Lock</b></td>
<td>Redis</td>
<td>Redisson 3.x · Distributed lock · Bloom filter · Session sharing</td>
</tr>
<tr>
<td>Spring Cache</td>
<td>Annotation-driven, TTL customizable</td>
</tr>
<tr>
<td><b>Message Queue</b></td>
<td>RocketMQ 5.x</td>
<td>Asynchronous task · Log decoupling · Transactional message · Delayed message</td>
</tr>
<tr>
<td><b>Registration / Configuration</b></td>
<td>Nacos</td>
<td>Service registration and discovery · Configuration center · Dynamic routing rules</td>
</tr>
<tr>
<td><b>Current Limiting and Circuit Breaking</b></td>
<td>Sentinel</td>
<td>Gateway traffic control · Resource circuit breaking · Redis Lua sliding window current limiting</td>
</tr>
<tr>
<td><b>Distributed Transaction</b></td>
<td>Seata 2.x</td>
<td>AT mode automatic configuration, TCC interface definition</td>
</tr>
<tr>
<td><b>File Storage</b></td>
<td>MinIO / Alibaba Cloud OSS</td>
<td>Unified FileStorageService abstraction, X-File-Storage adaptation</td>
</tr>
<tr>
<td><b>Office Processing</b></td>
<td>Apache POI · Commons CSV · PDFBox · OpenHTMLToPDF</td>
<td>Excel export · Word template rendering · CSV read and write · PDF parsing and generation</td>
</tr>
<tr>
<td><b>Observability</b></td>
<td>Micrometer + OpenTelemetry</td>
<td>Prometheus indicator · Jaeger link tracking · ELK log aggregation</td>
</tr>
<tr>
<td><b>Timing Task</b></td>
<td>XXL-Job</td>
<td>Distributed task scheduling, sharding execution strategy</td>
</tr>
<tr>
<td><b>Platform Monitoring</b></td>
<td>Spring Boot Admin</td>
<td>Service health dashboard · JVM indicator · Online configuration change</td>
</tr>
</tbody>
</table>
## 🚀 Quick Start
### Environment Requirements
| Dependency | Minimum Version |
|------|---------|
| JDK | 21 |
| Maven | 3.9+ |
| Docker & Docker Compose | 24.x+ |
| Node.js (front-end) | 20.x+ |
### Step 1: Clone the Repository
```bash
# Clone the back-end project
git clone https://github.com/refinex-lab/Refinex-Cloud.git
cd Refinex-Cloud
# If you need to deploy the front-end, clone the front-end project
git clone https://github.com/refinex-lab/Refinex-Agent.git
```
### Step 2: Start the Middleware with One Click
The project provides a complete Docker Compose orchestration, covering all dependent services, without manual installation of any middleware:
```bash
cd docker
docker compose up -d
```
> This command will automatically pull up: **MySQL 8.0** · **Redis 7** · **Nacos 2.x** · **RocketMQ 5.x** · **MinIO** · **Milvus** · **Seata** · **XXL-Job**
### Step 3: Initialize the Database
```bash
mysql -u root -p < sql/refinex_init.sql
```
### Step 4: Import Nacos Configuration
Access `http://localhost:8848/nacos`, batch import the configuration files in the `config/nacos/` directory, and adjust the database connection, Redis address, and AI model API Key according to the local environment:
```yaml
# refinex-ai.yaml key configuration example
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
base-url: https://api.openai.com
vectorstore:
milvus:
uri: http://localhost:19530
```
### Step 5: Compile and Start the Back-end Service
```bash
# Full compilation (skip test)
mvn clean package -DskipTests
# Start each service in the following order
java -jar refinex-gateway/target/refinex-gateway.jar
java -jar refinex-auth/target/refinex-auth.jar
java -jar refinex-modules/refinex-system/target/refinex-system.jar
java -jar refinex-modules/refinex-ai/target/refinex-ai.jar
# Start the knowledge base and media services as needed
java -jar refinex-modules/refinex-knowledge/target/refinex-knowledge.jar
java -jar refinex-modules/refinex-media/target/refinex-media.jar
```
### Step 6: Start the Front-end Application
```bash
cd ../Refinex-Agent
npm install
npm run dev
```
After starting, access `http://localhost:5173` to use the complete platform. For more detailed deployment guidelines, please refer to **[Official Documentation →](https://www.refinex.cn)**
## 🗺 Roadmap
<table>
<tr>
<td align="center" width="33%"><b>✅ Completed</b></td>
<td align="center" width="33%"><b>🚧 In Progress</b></td>
<td align="center" width="33%"><b>📋 Planned</b></td>
</tr>
<tr>
<td valign="top">
✔ Spring Cloud microservice basic architecture<br/>
✔ Sa-Token authentication and authorization system<br/>
✔ AI streaming dialogue (SSE)<br/>
✔ RAG knowledge base basic capability<br/>
✔ Unified file storage abstraction<br/>
✔ Full-link tracking integration<br/>
✔ Operation log and data desensitization
</td>
<td valign="top">
⚙ Agent workflow visual scheduling<br/>
⚙ MCP complete protocol implementation<br/>
⚙ Text-to-image / video asynchronous task<br/>
⚙ Multi-tenancy system complete support<br/>
⚙ Docker Compose one-click deployment<br/>
⚙ Complete unit and integration test coverage
</td>
<td valign="top">
📌 Kubernetes deployment Helm Chart<br/>
📌 Model fine-tuning task management<br/>
📌 AI usage statistics and billing module<br/>
📌 Plugin market and third-party tool integration<br/>
📌 Enterprise SSO / LDAP integration<br/>
📌 Multi-language internationalization support
</td>
</tr>
</table>
## 🤝 Contribution Guide
We warmly welcome any form of contribution from the community, whether it's feature development, bug fixing, documentation improvement, or usage feedback. Before submitting a Pull Request, please read [CONTRIBUTING.md](CONTRIBUTING.md) to understand the detailed specifications.
```bash
# 1. Fork this repository and clone it to local
git clone https://github.com/<your-username>/Refinex-Cloud.git
# 2. Create a feature branch based on the main branch
git checkout -b feat/your-feature-name
# 3. Submit after development (following Conventional Commits specifications)
git commit -m "feat(ai): add multi-model routing support"
# 4. Push the branch and create a Pull Request on GitHub
git push origin feat/your-feature-name
```
**Commit type convention:** `feat` New feature · `fix` Defect fix · `docs` Documentation change · `refactor` Code refactoring · `perf` Performance optimization · `chore` Build / tool change
## 📄 License
This project is released under the [Apache License 2.0](LICENSE) open-source protocol and can be used for free in personal and commercial projects.
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=100§ion=footer" width="100%"/>
<br/>
If Refinex-Cloud is helpful to you, welcome to light up the ⭐ **Star** to support us, which is the most direct encouragement for open source.
<br/>
[](https://star-history.com/#refinex-lab/Refinex-Cloud&refinex-lab/Refinex-Agent&Date)
<br/>
**Made with ❤️ by the [Refinex Team](https://www.refinex.cn)**
</div>
