5分钟快速上手

作者:唐亚峰 | battcn

字数统计:1.6k 字

适合人群

零基础小白、想快速体验项目功能的开发者

前置条件

⚠️ 小白必读

如果你是第一次接触 Java 微服务项目，请先确保以下软件已正确安装并配置好环境变量！

软件	最低版本	推荐版本	下载地址	验证命令
JDK	17	21	Oracle JDK https://www.oracle.com/java/technologies/downloads/ battcn.com	java -version
Maven	3.8+	3.9+	Maven https://maven.apache.org/download.cgi battcn.com	mvn -v
Node.js	18	20+	Node.js https://nodejs.org/ battcn.com	node -v
pnpm	8+	9+	安装后执行 npm i -g pnpm	pnpm -v
Docker	20+	最新版	Docker Desktop https://www.docker.com/products/docker-desktop/ battcn.com	docker -v
Git	2.0+	最新版	Git https://git-scm.com/ battcn.com	git --version
IDE	-	IDEA Ultimate	JetBrains https://www.jetbrains.com/idea/ battcn.com	-

🔍 如何验证环境是否安装成功？

打开终端（Windows 用 CMD 或 PowerShell，Mac 用 Terminal），依次输入：

java -version    # 应显示 java version "21.x.x" 或 "17.x.x"
mvn -v           # 应显示 Apache Maven 3.x.x
node -v          # 应显示 v20.x.x 或 v18.x.x
pnpm -v          # 应显示 9.x.x 或 8.x.x
docker -v        # 应显示 Docker version 2x.x.x
git --version    # 应显示 git version 2.x.x

如果提示"命令未找到"，说明该软件未安装或环境变量未配置，请参考 环境安装指南

---

第一步：一键启动环境

Docker Compose (推荐)

# 创建项目目录
mkdir wemirr && cd wemirr

# 下载 docker-compose 文件
curl -O https://gitee.com/battcn/wemirr-platform/raw/v4-dev/附件/docker/docker-compose.yml

# 一键启动所有中间件
docker-compose up -d

手动安装

# 创建 Docker 网络
docker network create wemirr

# 启动 Redis
docker run -d --name redis --net wemirr -p 6379:6379 redis:latest

# 启动 MySQL
docker run -d --name mysql --net wemirr -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=123456 mysql:latest

# 启动 Nacos
docker run -d --name nacos --net wemirr -p 8848:8848 -p 9848:9848 \
  -e MODE=standalone nacos/nacos-server:latest

第二步：获取代码

# 克隆后端代码（指定 v4-dev 分支）
git clone -b v4-dev https://gitee.com/battcn/wemirr-platform.git

# 克隆前端代码（指定 v4-dev 分支）
git clone -b v4-dev https://gitee.com/battcn/wemirr-platform-ui.git

🐢 克隆太慢？试试这个

# 使用浅克隆，只拉取最近一次提交
git clone -b v4-dev --depth 1 https://gitee.com/battcn/wemirr-platform.git
git clone -b v4-dev --depth 1 https://gitee.com/battcn/wemirr-platform-ui.git

---

第三步：初始化数据库

📦 需要什么工具？

推荐使用 Navicat、DBeaver（免费）、DataGrip 或 IDEA 自带的 Database 工具

步骤：

1. 连接 MySQL — 地址 localhost:3306，用户 root，密码 123456
2. 创建数据库 — 执行以下 SQL：

CREATE DATABASE IF NOT EXISTS wemirr_platform 
DEFAULT CHARACTER SET utf8mb4 
DEFAULT COLLATE utf8mb4_general_ci;

3. 导入数据 — 选中 wemirr_platform 库，执行 SQL 脚本文件：

wemirr-platform/附件/mysql/wemirr_platform.sql

❌ 常见错误

• 连接失败 — 检查 Docker 容器是否启动：docker ps | grep mysql
• 导入报错 — 确保选中的是 wemirr_platform 数据库再执行 SQL
• 乱码 — 确保创建库时用 utf8mb4 字符集

---

第四步：导入 Nacos 配置

步骤：

1. 打开 Nacos — 浏览器访问 http://localhost:8848/nacos
2. 登录 — 账号 nacos，密码 nacos
3. 创建命名空间：
   • 点击左侧菜单「命名空间」→「新建命名空间」
   • 命名空间ID：v4-dev（必须完全一致）
   • 命名空间名：v4-dev
4. 导入配置：
   • 点击「配置管理」→「配置列表」
   • 右上角切换命名空间到 v4-dev
   • 点击「导入配置」→ 选择文件 wemirr-platform/附件/nacos/nacos_config_export.zip

❌ 常见错误

• 命名空间 ID 不对 — 必须是 v4-dev，不是随机生成的 UUID
• 导入后配置为空 — 检查是否切换到了 v4-dev 命名空间
• 配置中的 IP 不对 — 如果用 Docker，MySQL/Redis 地址应该是 host.docker.internal 或容器名

第五步：启动后端服务

步骤：

1. 用 IDEA 打开项目 — 菜单 File → Open → 选择 wemirr-platform 文件夹
2. 等待索引完成 — 右下角进度条跑完（首次约 3-5 分钟）
3. 依次启动服务：

顺序	服务	启动类位置	端口
①	网关服务	wemirr-platform-gateway → GatewayApplication	9000
②	认证服务	wemirr-platform-iam → IamApplication	5001
③	业务服务	wemirr-platform-suite → SuiteApplication	5002

💡 如何启动？

在 IDEA 中找到对应模块的 Application.java 文件，右键 → Run 'xxxApplication'

❌ 常见错误

Maven 依赖报错（红色波浪线）

cd wemirr-platform
mvn clean install -DskipTests

端口被占用

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

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

连接 Nacos 失败

• 检查 Nacos 是否启动：docker ps | grep nacos
• 检查 bootstrap.yml 中的 Nacos 地址是否正确

连接 MySQL/Redis 失败

• 检查 Docker 容器是否运行：docker ps
• 检查 Nacos 配置中的连接地址和密码是否正确

第六步：启动前端项目

步骤：

# 1. 进入前端目录
cd wemirr-platform-ui

# 2. 安装 pnpm（如果没有）
npm install -g pnpm

# 3. 安装依赖（首次需要，约 2-3 分钟）
pnpm install

# 4. 启动开发服务器
pnpm run dev:antd

启动成功后会显示：

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5666/
  ➜  Network: http://192.168.x.x:5666/

❌ 常见错误

pnpm: command not found

npm install -g pnpm

安装依赖报错 / 卡住

# 清除缓存重试
pnpm store prune
rm -rf node_modules
pnpm install

启动后页面空白 / 报错

• 检查后端服务是否全部启动
• 检查浏览器控制台（F12）报错信息
• 确认 .env.development 中的 API 地址配置正确

---

第七步：访问系统

🎉 恭喜！项目已成功运行，现在可以访问：

地址	说明
http://localhost:5666	前端界面
http://localhost:9000	后端 API
http://localhost:8848/nacos	Nacos 控制台

默认登录账号：

• 平台管理员：租户编码 0000，账号 admin，密码 123456
• 租户管理员：租户编码 8888，账号 admin，密码 123456

快速体验

登录后您可以体验以下核心功能：

• 🏢 租户管理 - 创建和管理多租户
• 👥 用户管理 - 用户、角色、权限配置
• 📋 菜单管理 - 动态菜单配置
• 🔐 权限控制 - RBAC 权限模型
• 📊 系统监控 - 日志、操作记录

遇到问题？

• 📖 查看 常见问题
• 💬 加入技术交流群：789517089
• 🐛 提交
  Issue

  https://gitee.com/battcn/wemirr-platform/issues

  battcn.com

下一步

• 核心概念 - 了解 SaaS、多租户等基础概念
• Docker 部署 - 深入学习 Docker 部署方案
• 前端开发 - 学习前端组件和页面开发
• 后端开发 - 学习后端 API 和服务开发