VortMall 快速上手指南

本文档帮助您在 30 分钟内完成 VortMall 微服务商城的本地开发环境搭建。

环境要求

必备环境

环境	版本要求	说明
JDK	21+
Maven	3.8+	构建工具
Docker	20.10+	容器运行时
Docker Compose	2.0+	容器编排
Git	2.0+	版本控制

工具	版本	说明
IntelliJ IDEA	2024.1+	推荐 Ultimate 版本
VS Code	最新版	前端开发
Navicat / DBeaver	最新版	数据库管理
Postman / Apifox	最新版	接口调试

硬件要求

配置项	最低配置	推荐配置
CPU	4核	8核+
内存	16GB	32GB
磁盘	50GB SSD	100GB SSD

项目结构

VortMall-Api/
├── vortmall-gateway          # 网关服务 (8000)
├── vortmall-auth             # 认证服务 (8001)
├── vortmall-biz              # 业务服务模块
│   ├── vortmall-biz-product      # 商品服务 (19901)
│   ├── vortmall-biz-payment      # 支付服务 (19902)
│   ├── vortmall-biz-system       # 系统服务 (19903)
│   ├── vortmall-biz-marketing    # 营销服务 (19904)
│   ├── vortmall-biz-order        # 订单服务 (19905)
│   ├── vortmall-biz-content      # 内容服务 (19906)
│   ├── vortmall-biz-organize     # 组织服务 (19907)
│   ├── vortmall-biz-logistics    # 物流服务 (19908)
│   ├── vortmall-biz-aftersales   # 售后服务 (19909)
│   ├── vortmall-biz-distribution # 分销服务 (19910)
│   ├── vortmall-biz-decoration   # 装修服务 (19911)
│   ├── vortmall-biz-message      # 消息服务 (19912)
│   ├── vortmall-biz-user         # 用户服务 (19913)
│   ├── vortmall-biz-file         # 文件服务 (19914)
│   └── vortmall-biz-pos          # POS服务 (19915)
├── vortmall-common           # 公共模块
│   ├── vortmall-common-core      # 核心工具
│   ├── vortmall-common-web       # Web通用配置
│   ├── vortmall-common-cache     # 缓存
│   ├── vortmall-common-datasource# 数据源
│   ├── vortmall-common-mq        # 消息队列
│   ├── vortmall-common-nacos     # Nacos配置
│   └── ...
├── vortmall-feign            # Feign接口定义
├── deployment                # 部署配置
│   └── DockerCompose             # Docker Compose 配置
└── docs                      # 项目文档

快速开始

第一步：克隆项目

# 克隆项目
git clone https://your-git-repo/vortmall-api.git

# 进入项目目录
cd vortmall-api

第二步：启动中间件

# 进入部署目录
cd deployment/DockerCompose

# 修改配置（替换为本机IP）
# Windows PowerShell
$env:PUBLIC_IP = "192.168.x.x"

# Linux/Mac
export PUBLIC_IP=$(hostname -I | awk '{print $1}')

# 启动核心中间件
docker-compose up -d mysql redis nacos

# 等待 MySQL 启动完成（约30秒）
docker-compose logs -f mysql

# 启动消息队列和任务调度
docker-compose up -d namesrv broker xxl-job minio

第三步：初始化数据库

# 进入 MySQL 容器
docker exec -it mysql-8 mysql -uroot -pvortmall666

# 执行初始化脚本（容器内）
source /docker-entrypoint-initdb.d/01-nacos-mysql.sql
source /docker-entrypoint-initdb.d/02-xxl-job.sql

或使用数据库工具导入 db/vortmall_schema.sql

第四步：配置 Nacos

访问 Nacos 控制台：http://localhost:8848/nacos
默认账号密码：nacos / nacos
创建命名空间：dev（开发环境）
导入配置（可选，首次启动使用默认配置即可）

第五步：配置 Host（可选）

# 编辑 hosts 文件
# Windows: C:\Windows\System32\drivers\etc\hosts
# Linux/Mac: /etc/hosts

127.0.0.1 vortmall-mysql
127.0.0.1 vortmall-redis
127.0.0.1 vortmall-nacos

第六步：启动服务

方式一：IDEA 启动（推荐开发使用）

使用 IDEA 打开项目
等待 Maven 依赖下载完成
按以下顺序启动服务：

启动顺序：
1. VortmallGatewayApplication      (网关)
2. VortmallAuthApplication         (认证)
3. VortmallBizSystemApplication    (系统服务)
4. VortmallBizUserApplication      (用户服务)
5. VortmallBizProductApplication   (商品服务)
6. 其他业务服务...

提示：可在 IDEA 中配置 Run Dashboard，批量启动管理服务

方式二：Maven 命令启动

# 编译项目
mvn clean package -DskipTests

# 启动网关
java -jar vortmall-gateway/target/vortmall-gateway-1.0-SNAPSHOT.jar

# 启动认证服务
java -jar vortmall-auth/target/vortmall-auth-1.0-SNAPSHOT.jar

# 启动业务服务
java -jar vortmall-biz/vortmall-biz-system/target/vortmall-biz-system-1.0-SNAPSHOT.jar
java -jar vortmall-biz/vortmall-biz-user/target/vortmall-biz-user-1.0-SNAPSHOT.jar
# ... 其他服务

方式三：Docker Compose 启动

# 构建镜像
mvn clean package -DskipTests
docker-compose -f docker-compose-app.yml build

# 启动所有服务
docker-compose -f docker-compose-app.yml up -d

服务访问

服务地址一览

服务	地址	说明
API 网关	http://localhost:8000	统一入口
Nacos 控制台	http://localhost:8848/nacos	注册中心
Swagger 文档	http://localhost:8000/swagger-ui.html	API 文档
XXL-JOB 控制台	http://localhost:8082/xxl-job-admin	任务调度
RocketMQ Dashboard	http://localhost:8080	消息队列
MinIO 控制台	http://localhost:9001	文件存储

默认账号密码

服务	账号	密码
Nacos	nacos	nacos
MySQL	root	vortmall666
MinIO	vortmall	vortmall666
XXL-JOB	admin	123456
管理后台	admin	123456

接口测试

# 健康检查
curl http://localhost:8000/actuator/health

# 管理员登录
curl -X POST http://localhost:8000/adminapi/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 获取商品列表（需要 Token）
curl http://localhost:8000/adminapi/product/list \
  -H "satoken: your-token-here"

前端项目

管理后台

# 克隆前端项目
git clone https://your-git-repo/vort-admin.git

# 安装依赖
cd vort-admin
npm install

# 修改 API 地址
# .env.development
VITE_API_URL=http://localhost:8000

# 启动开发服务器
npm run dev

# 访问地址
http://localhost:5173

H5/小程序

# 使用 uni-app 开发
# 修改 API 配置后运行

开发调试

IDEA 配置建议

1. 配置 JVM 参数

-Xms512m
-Xmx512m
-Dfile.encoding=UTF-8
-Dspring.profiles.active=dev

2. 配置环境变量

VORTMALL_HOST=localhost

3. 开启热部署

在 application.yml 中添加：

spring:
  devtools:
    restart:
      enabled: true

日志查看

# 实时查看网关日志
tail -f logs/vortmall-gateway.log

# Docker 容器日志
docker logs -f vortmall-gateway

调试技巧

远程调试：启动时添加 -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
SQL 日志：配置 mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl
Feign 日志：配置 logging.level.com.vortmall.feign=DEBUG

常见问题

Q1: Maven 依赖下载失败

解决方案：配置阿里云镜像

<!-- settings.xml -->
<mirror>
  <id>aliyunmaven</id>
  <mirrorOf>*</mirrorOf>
  <name>阿里云公共仓库</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

Q2: 服务无法注册到 Nacos

排查步骤：

检查 Nacos 是否正常启动：curl http://localhost:8848/nacos/v1/console/health/readiness
检查网络连通性：telnet localhost 8848
检查配置文件中的 Nacos 地址是否正确

Q3: 数据库连接失败

排查步骤：

检查 MySQL 容器状态：docker ps | grep mysql
检查数据库是否创建：docker exec -it mysql-8 mysql -uroot -p -e "show databases;"
检查配置文件中的数据库地址、用户名、密码

Q4: 端口被占用

# Windows 查看端口占用
netstat -ano | findstr :8000

# 结束进程
taskkill /PID <pid> /F

# Linux/Mac 查看端口占用
lsof -i :8000

# 结束进程
kill -9 <pid>

Q5: 内存不足

解决方案：

减少同时启动的服务数量
调整 JVM 参数：-Xms256m -Xmx256m
增加物理内存或使用 Docker Desktop 分配更多内存

Q6: Docker 镜像拉取慢

解决方案：配置 Docker 镜像加速

// ~/.docker/daemon.json
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}

Q7: Windows 下 Docker 网络问题

解决方案：使用 host.docker.internal 替代 localhost

# application.yml
spring:
  datasource:
    url: jdbc:mysql://host.docker.internal:3306/vortmall

核心服务说明

网关服务 (vortmall-gateway)

端口：8000
功能：统一入口、路由转发、鉴权、限流
技术：Spring Cloud Gateway + Sa-Token

认证服务 (vortmall-auth)

端口：8001
功能：用户登录、Token 管理、权限校验
技术：Sa-Token

用户服务 (vortmall-biz-user)

端口：19913
功能：用户管理、角色权限、菜单管理
数据库：vortmall-user

商品服务 (vortmall-biz-product)

端口：19901
功能：商品管理、分类、品牌、规格
数据库：vortmall-product

订单服务 (vortmall-biz-order)

端口：19905
功能：订单管理、购物车、结算
数据库：vortmall-order

VortMall 快速上手指南

环境要求

必备环境

推荐开发工具

硬件要求

项目结构

快速开始

第一步：克隆项目

第二步：启动中间件

第三步：初始化数据库

第四步：配置 Nacos

第五步：配置 Host（可选）

第六步：启动服务

方式一：IDEA 启动（推荐开发使用）

方式二：Maven 命令启动

方式三：Docker Compose 启动

服务访问

服务地址一览

默认账号密码

接口测试

前端项目

管理后台

H5/小程序

开发调试

IDEA 配置建议

1. 配置 JVM 参数

2. 配置环境变量

3. 开启热部署

日志查看

调试技巧

常见问题

Q1: Maven 依赖下载失败

Q2: 服务无法注册到 Nacos

Q3: 数据库连接失败

Q4: 端口被占用

Q5: 内存不足

Q6: Docker 镜像拉取慢

Q7: Windows 下 Docker 网络问题

核心服务说明

网关服务 (vortmall-gateway)

认证服务 (vortmall-auth)

用户服务 (vortmall-biz-user)

商品服务 (vortmall-biz-product)

订单服务 (vortmall-biz-order)