# service-modelGenerator

**Repository Path**: superjang/service-model-generator

## Basic Information

- **Project Name**: service-modelGenerator
- **Description**: 七牛云25年参赛，Import man团队后端仓库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-22
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Anity3D Service

<div align="center">

![Java](https://img.shields.io/badge/Java-8+-orange.svg)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.18-brightgreen.svg)
![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2021.0.9-blue.svg)
![Docker](https://img.shields.io/badge/Docker-4.0+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

**一个基于微服务架构的文生/图生3D模型AI智能应用服务端**

[项目概览](#项目概览) • [项目优势](#项目优势) • [快速开始](#快速开始) • [架构设计](#架构设计) • [API文档](#api文档)

</div>

---

<div align="center">
  <img src="./docs/pics/logo.png">
</div>

## 📑 目录

- [项目分工](#项目分工)
- [项目概览](#项目概览)
  - [🎯 项目定位](#-项目定位)
  - [🚀 核心功能](#-核心功能)
  - [🏗️ 项目架构](#️-项目架构)
  - [🛠️ 技术栈](#️-技术栈)
- [项目优势](#项目优势)
  - [🎯 技术优势](#-技术优势)
    - [1. 现代化微服务架构](#1-现代化微服务架构)
    - [2. 高性能缓存架构](#2-高性能缓存架构)
    - [3. 企业级安全架构](#3-企业级安全架构)
  - [🚀 业务优势](#-业务优势)
    - [1. 用户体验优化](#1-用户体验优化)
    - [2. 开发效率提升](#2-开发效率提升)
    - [3. 运维管理便捷](#3-运维管理便捷)
- [快速开始](#快速开始)
  - [📋 环境要求](#-环境要求)
    - [系统要求](#系统要求)
    - [软件要求](#软件要求)
  - [🚀 Windows本地部署](#-windows本地部署)
    - [1. 环境准备](#1-环境准备)
    - [2. 配置环境变量](#2-配置环境变量)
    - [3. 构建项目](#3-构建项目)
    - [4. 启动服务](#4-启动服务)
    - [5. 验证部署](#5-验证部署)
    - [6. 访问服务](#6-访问服务)
  - [🐳 Linux Docker容器化部署](#-linux-docker容器化部署)
    - [1. 环境准备](#1-环境准备-1)
    - [2. 配置环境](#2-配置环境)
    - [3. 构建和启动](#3-构建和启动)
    - [4. 服务管理](#4-服务管理)
  - [🔧 开发环境配置](#-开发环境配置)
    - [1. IDE配置](#1-ide配置)
    - [2. 数据库配置](#2-数据库配置)
    - [3. 本地调试](#3-本地调试)
  - [📚 API文档](#-api文档)
    - [Swagger文档](#swagger文档)
    - [主要API接口](#主要api接口)
  - [🐛 故障排除](#-故障排除)
    - [常见问题](#常见问题)
    - [日志查看](#日志查看)
  - [📞 技术支持](#-技术支持)
- [贡献指南](#贡献指南)
  - [🤝 如何贡献](#-如何贡献)
  - [📝 提交规范](#-提交规范)
  - [🔍 代码规范](#-代码规范)
- [许可证](#许可证)
- [致谢](#致谢)

---

## 项目分工
**队伍名称**：Import man 

**前端开发**：张扬  

**后端开发**：黄松江 

**Demo演示视频**：[Anity3D-演示视频](./Anity3D-演示视频.mp4)

**前端仓库地址（优先阅读）**：[Anity 3D - 文生/图生3D模型AI智能应用前端](https://gitee.com/superjang/app-modelGenerator/tree/feature%2Fupgrade/#142-%E6%96%87%E7%94%9F3d%E8%AF%84%E4%BC%B0%E6%96%B9%E6%B3%95%E4%B8%93%E5%AE%B6%E7%89%B9%E5%BE%81%E6%AF%94%E5%AF%B9%E6%B3%95)

**详细设计文档**：[Anity3D服务端系统架构设计文档](./docs/Anity3D服务端系统架构设计文档.md)


## 项目概览

### 🎯 项目定位

Anity3D Service 是一个现代化的微服务架构平台，专注于提供高质量的文本/图像到3D模型生成服务。项目采用Spring Cloud Alibaba技术栈，集成了腾讯云3D服务、火山引擎图像服务和阿里云OSS存储，为用户提供完整的3D模型生成解决方案。

### 🚀 核心功能

- **多模态输入支持**：支持文本描述和图像输入生成3D模型
- **智能图像增强**：基于火山引擎的图像生成和增强功能
- **异步任务处理**：高效的异步任务提交和状态轮询机制
- **用户管理系统**：完整的用户注册、登录、权限管理
- **模型收藏管理**：支持模型收藏、浏览、下载统计
- **高性能缓存**：多级缓存架构，提升系统响应速度
- **容器化部署**：Docker容器化，支持一键部署

### 🏗️ 项目架构

![Anity3D服务端架构图](./docs/pics/anity3d后端架构图.png)

### 🛠️ 技术栈

| 技术分类 | 技术选型 | 版本 | 说明 |
|---------|---------|------|------|
| **后端框架** | Spring Boot | 2.7.18 | 微服务基础框架 |
| **微服务治理** | Spring Cloud Alibaba | 2021.0.5.0 | 服务注册发现、配置管理 |
| **API网关** | Spring Cloud Gateway | 3.1.9 | 路由转发、限流熔断 |
| **数据访问** | MyBatis-Plus | 3.5.3.1 | ORM框架 |
| **数据库** | MySQL | 8.0 | 关系型数据库 |
| **缓存** | Redis | 7.0 | 内存数据库 |
| **消息队列** | - | - | 计划引入RocketMQ |
| **容器化** | Docker | 4.0+ | 容器化部署 |
| **编排工具** | Docker Compose | 2.0+ | 容器编排 |
| **负载均衡** | Nginx | 1.20+ | 反向代理、负载均衡 |
| **监控** | Prometheus + Grafana | - | 监控告警 |
| **文档** | SpringDoc OpenAPI | 1.6.15 | API文档生成 |

---

## 项目优势

### 🎯 技术优势

#### 1. 现代化微服务架构
- **服务拆分合理**：按照业务领域进行服务拆分，确保高内聚低耦合
- **技术栈统一**：采用Spring Cloud Alibaba技术栈，保证技术一致性
- **服务治理完善**：基于Nacos实现服务注册发现、配置管理、负载均衡
- **容错机制健全**：集成熔断器、限流器、重试机制，保证系统稳定性

#### 2. 高性能缓存架构
- **多级缓存设计**：本地缓存+Redis缓存+数据库三层缓存架构
- **智能同步机制**：定时同步+事件同步+手动同步多种同步策略
- **缓存防护体系**：缓存穿透、雪崩、击穿三大问题的完整防护方案
- **性能监控完善**：缓存命中率、响应时间、连接状态全方位监控

#### 3. 企业级安全架构
- **JWT认证体系**：无状态认证，支持分布式部署和水平扩展
- **多层安全防护**：网关层+应用层+数据层三层安全防护
- **数据加密保护**：敏感数据加密存储，传输过程HTTPS保护
- **安全审计机制**：完整的操作日志记录和安全事件监控


### 🚀 业务优势

#### 1. 用户体验优化
- **响应速度快**：通过缓存优化和性能调优，接口响应时间控制在200ms以内
- **功能完整**：支持文本到3D、图像到3D、图像增强等完整功能链路
- **操作简便**：RESTful API设计，支持多种客户端接入
- **状态透明**：实时任务状态查询，用户可随时了解处理进度

#### 2. 开发效率提升
- **开发框架统一**：Spring Boot + Spring Cloud Alibaba技术栈
- **代码规范标准**：统一的编码规范、注释规范、文档规范
- **测试覆盖完整**：单元测试、集成测试、性能测试全覆盖
- **部署流程自动化**：Docker容器化、CI/CD流水线、一键部署

#### 3. 运维管理便捷
- **监控体系完善**：Prometheus + Grafana监控，实时掌握系统状态
- **日志管理集中**：结构化日志、集中收集、快速检索
- **故障处理高效**：健康检查、自动恢复、故障转移机制
- **扩展性良好**：水平扩展支持、负载均衡、弹性伸缩

---

## 快速开始

### 📋 环境要求

#### 系统要求
- **操作系统**：Windows 10/11 (支持WSL2) 或 Linux (Ubuntu 18.04+)
- **内存**：8GB+ (推荐16GB)
- **存储**：20GB+ 可用空间
- **网络**：稳定的互联网连接

#### 软件要求
- **Docker Desktop**：4.0+ (Windows) 或 Docker Engine 20.10+ (Linux)
- **Docker Compose**：2.0+
- **Java**：8+ (用于构建项目)
- **Maven**：3.6+ (用于构建项目)
- **PowerShell**：5.0+ (Windows) 或 Bash (Linux)

### 🚀 Windows本地部署

#### 1. 环境准备

```powershell
# 克隆项目
git clone https://github.com/your-username/model-generate-service.git
cd model-generate-service

# 运行环境设置脚本
.\setup-environment.ps1
```

#### 2. 配置环境变量

```powershell
# 复制环境变量模板
Copy-Item env.example .env

# 编辑 .env 文件，配置以下内容：
# - TENCENTCLOUD_SECRET_ID: 腾讯云Secret ID
# - TENCENTCLOUD_SECRET_KEY: 腾讯云Secret Key
# - OSS_ACCESS_KEY_ID: 阿里云OSS Access Key ID
# - OSS_ACCESS_KEY_SECRET: 阿里云OSS Access Key Secret
# - ARK_API_KEY: 火山引擎API Key
```

#### 3. 构建项目

```powershell
# 构建所有服务
.\build-projects.ps1

# 或者手动构建
mvn clean package -DskipTests
```

#### 4. 启动服务

```powershell
# 启动所有服务（生产环境）
.\start-services.ps1

# 启动开发环境
.\start-services.ps1 -Dev

# 构建并启动
.\start-services.ps1 -Build

# 启动并查看日志
.\start-services.ps1 -Logs
```

#### 5. 验证部署

```powershell
# 检查服务状态
docker-compose ps

# 查看服务日志
.\view-logs.ps1

# 测试API接口
curl http://localhost/api/user/health
curl http://localhost/api/model/health
```

#### 6. 访问服务

| 服务 | 访问地址 | 说明 |
|------|---------|------|
| **API网关** | http://localhost:8080 | 统一API入口 |
| **Nacos控制台** | http://localhost:8848/nacos | 服务注册中心 |
| **用户服务** | http://localhost:8081 | 用户管理服务 |
| **模型服务** | http://localhost:8082/ | 模型生成服务 |
| **健康检查** | http://localhost/health | 系统健康状态 |

### 🐳 Linux Docker容器化部署

#### 1. 环境准备

```bash
# 安装Docker和Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 克隆项目
git clone https://github.com/your-username/model-generate-service.git
cd model-generate-service
```

#### 2. 配置环境

```bash
# 复制环境变量模板
cp env.example .env

# 编辑环境变量
nano .env
```

#### 3. 构建和启动

```bash
# 构建项目
mvn clean package -DskipTests

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

#### 4. 服务管理

```bash
# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 更新服务
docker-compose pull
docker-compose up -d

# 清理资源
docker-compose down -v
docker system prune -a
```

### 🔧 开发环境配置

#### 1. IDE配置

推荐使用IntelliJ IDEA或Eclipse进行开发：

```bash
# 导入项目
File -> Open -> 选择项目根目录

# 配置Maven
Settings -> Build -> Build Tools -> Maven
Maven home directory: 选择Maven安装目录
User settings file: 选择settings.xml文件
```

#### 2. 数据库配置

```sql
-- 创建数据库
CREATE DATABASE db_antiy3d CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE nacos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户
CREATE USER 'model_user'@'%' IDENTIFIED BY 'model_pass123';
GRANT ALL PRIVILEGES ON db_antiy3d.* TO 'model_user'@'%';
GRANT ALL PRIVILEGES ON nacos.* TO 'model_user'@'%';
FLUSH PRIVILEGES;
```

#### 3. 本地调试

```bash
# 启动基础设施服务
docker-compose up -d mysql redis nacos

# 在IDE中启动各个服务
# 1. 启动UserServiceApplication
# 2. 启动ModelServiceApplication
# 3. 启动GatewayServiceApplication
```

### 📚 API文档

#### Swagger文档

启动服务后，访问以下地址查看API文档：

- **用户服务API**：http://localhost:8081/swagger-ui.html
- **模型服务API**：http://localhost:8082/swagger-ui.html

#### 主要API接口

##### 用户管理
```http
POST /api/user/register     # 用户注册
POST /api/user/login        # 用户登录
GET  /api/user/profile      # 获取用户信息
PUT  /api/user/profile      # 更新用户信息
```

##### 模型生成
```http
POST /api/model/generate    # 提交模型生成任务
GET  /api/model/status/{jobId}  # 查询任务状态
GET  /api/model/list        # 获取模型列表
GET  /api/model/{id}        # 获取模型详情
```

##### 模型管理
```http
POST /api/model/favorite    # 收藏模型
DELETE /api/model/favorite  # 取消收藏
GET  /api/model/favorites   # 获取收藏列表
```

### 🐛 故障排除

#### 常见问题

1. **Docker启动失败**
   ```bash
   # 检查Docker状态
   docker info
   
   # 重启Docker服务
   sudo systemctl restart docker
   ```

2. **端口冲突**
   ```bash
   # 检查端口占用
   netstat -tulpn | grep :8080
   
   # 修改docker-compose.yml中的端口映射
   ```

3. **数据库连接失败**
   ```bash
   # 检查数据库状态
   docker-compose logs mysql
   
   # 重启数据库服务
   docker-compose restart mysql
   ```

4. **服务注册失败**
   ```bash
   # 检查Nacos状态
   curl http://localhost:8848/nacos/v1/ns/instance/list?serviceName=user-service
   
   # 重启Nacos服务
   docker-compose restart nacos
   ```

#### 日志查看

```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f model-service-1

# 查看最近100行日志
docker-compose logs --tail=100 -f
```

### 📞 技术支持

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

- **GitHub Issues**：提交问题和建议
- **技术文档**：查看 `Anity3D服务端系统架构设计文档.md` 了解详细架构
- **API文档**：访问Swagger文档了解接口详情

---



## 贡献指南

### 🤝 如何贡献

我们欢迎所有形式的贡献，包括但不限于：

- 🐛 报告Bug
- ✨ 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复
- 🧪 添加测试用例

### 📝 提交规范

请遵循以下提交规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

类型说明：
- `feat`: 新功能
- `fix`: 修复Bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动

### 🔍 代码规范

- 遵循Java编码规范
- 使用统一的代码格式化配置
- 添加必要的注释和文档
- 编写单元测试和集成测试

---

## 许可证

本项目采用 [MIT License](LICENSE) 许可证。

---

## 致谢

感谢以下开源项目和技术服务：

- [Spring Boot](https://spring.io/projects/spring-boot) - 微服务基础框架
- [Spring Cloud Alibaba](https://github.com/alibaba/spring-cloud-alibaba) - 微服务治理
- [MyBatis-Plus](https://baomidou.com/) - ORM框架
- [Docker](https://www.docker.com/) - 容器化技术
- [腾讯云](https://cloud.tencent.com/) - 3D模型生成服务
- [火山引擎](https://www.volcengine.com/) - 图像生成服务
- [阿里云](https://www.aliyun.com/) - 对象存储服务

---

<div align="center">

**如果这个项目对您有帮助，请给我们一个 ⭐ Star！**

Made with ❤️ by Model Generate Service Team

</div>