新手常见问题

作者:唐亚峰 | battcn

字数统计:2k 字

TIP

本页面收集了新手入门时最常遇到的问题和解决方案，包括一些"看起来很蠢但确实会遇到"的问题。

---

概念扫盲

Q: 这个项目为什么有这么多模块？我该启动哪个？

A: 这是微服务架构，不同服务负责不同功能：

服务	作用	必须启动？
Gateway	网关，所有请求的入口	✅ 必须
IAM	认证授权，负责登录	✅ 必须
Suite	核心业务	✅ 必须
Workflow	工作流（可选）	❌ 按需
TMS	运输管理（可选）	❌ 按需
WMS	仓储管理（可选）	❌ 按需

最小启动：Gateway + IAM + Suite

Q: 什么是 Nacos？为什么要装这个？

A: Nacos 是配置中心 + 服务注册中心：

• 配置中心：数据库密码、Redis 地址等配置统一放 Nacos，不用改代码
• 服务注册：各个微服务启动后会注册到 Nacos，网关才知道怎么转发请求

不装 Nacos = 项目跑不起来。

Q: 什么是租户？多租户是什么意思？

A: 简单理解：

• 租户 = 公司/组织
• 多租户 = 一套系统给多个公司用，数据互相隔离

比如 SaaS 软件，A公司和B公司都用这套系统，但 A 看不到 B 的数据。

登录时填的「租户编码」就是区分你属于哪个公司：

• 0000 = 平台管理员（超级管理员，能管所有租户）
• 8888 = 示例租户（普通租户）

Q: 前后端分离是什么意思？

A:

• 后端（wemirr-platform）：提供 API 接口，返回 JSON 数据
• 前端（wemirr-platform-ui）：负责页面展示，调用后端接口获取数据

两个项目独立运行，通过 HTTP 请求通信。

Q: Token 是什么？为什么要 Token？

A: Token 是登录凭证，相当于"门禁卡"：

1. 登录成功 → 后端发一个 Token 给你
2. 之后每次请求 → 带上这个 Token
3. 后端验证 Token → 知道你是谁

Token 过期了就需要重新登录。

---

工具使用

Q: 什么是 Maven？我需要单独安装吗？

A: Maven 是 Java 的包管理工具（类似前端的 npm）：

• 作用：自动下载项目依赖的 jar 包
• 安装：IDEA 自带 Maven，不需要单独安装
• 配置镜像：国内下载慢，需配置阿里云镜像（见下文）

Q: IDEA 怎么打开这个项目？

A:

1. File → Open → 选择 wemirr-platform 文件夹
2. 等待右下角进度条走完（Maven 在下载依赖）
3. 如果报红，等一会儿，或者点击右侧 Maven 图标 → 刷新按钮

Q: pnpm 是什么？和 npm 有什么区别？

A: 都是前端包管理工具：

• npm：Node.js 自带的，但比较慢
• pnpm：更快、更省空间的替代品

本项目用 pnpm，安装命令：

npm install -g pnpm

Q: 我不会用 Git 命令怎么办？

A: 最简单的方式：直接在 Gitee 页面下载 ZIP 压缩包

或者用图形化工具：

• IDEA：自带 Git 功能，VCS → Get from Version Control
• SourceTree：免费的 Git 图形化客户端

Q: Docker 是什么？必须用吗？

A: Docker 是容器技术，可以一键启动 MySQL、Redis、Nacos 等中间件。

必须用吗？ 不是必须，但强烈推荐：

• 用 Docker：一条命令启动所有环境
• 不用 Docker：需要手动安装 MySQL、Redis、Nacos...（很麻烦）

---

环境问题

Q: Docker 启动失败？

A: 常见原因及解决方案：

1. 端口被占用

# 检查端口占用
lsof -i:3306
lsof -i:6379
lsof -i:8848

# 杀掉占用进程或修改 docker-compose 端口映射

2. 内存不足

# Docker Desktop 设置中增加内存限制（建议至少 4GB）

3. 网络问题

# 重新创建 Docker 网络
docker network rm wemirr
docker network create wemirr

Q: Maven 依赖下载失败？

A: 配置国内镜像源：

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

Q: Node 依赖安装缓慢？

A: 配置淘宝镜像：

# 设置镜像源
npm config set registry https://registry.npmmirror.com

# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com

启动问题

Q: Nacos 连接失败？

A: 检查以下几点：

1. 确认 Nacos 已启动

docker ps | grep nacos

2. 确认端口暴露

# Nacos 2.x 需要暴露 8848 和 9848 两个端口
docker run -d --name nacos -p 8848:8848 -p 9848:9848 \
  -e MODE=standalone nacos/nacos-server

3. 检查命名空间配置
   • 确保 Nacos 中创建了 v4-dev 命名空间
   • 或注释掉 application.yml 中的 namespace 配置

Q: 后端启动报 "无法找到数据源"？

A: 按以下步骤检查：

1. 确认 MySQL 已启动并可连接
2. 确认数据库 wemirr_platform 已创建
3. 确认 Nacos 配置已导入且配置正确
4. 检查 Nacos 中数据库连接信息

# 检查 Nacos 配置中的数据库连接
spring.datasource.dynamic.datasource.master.url=jdbc:mysql://localhost:3306/wemirr_platform?...
spring.datasource.dynamic.datasource.master.username=root
spring.datasource.dynamic.datasource.master.password=123456

Q: 前端启动后页面空白？

A: 检查以下几点：

1. 确认后端服务已启动

   • Gateway (9000)
   • IAM (5001)
   • Suite (5002)

2. 检查代理配置

// vite.config.ts 中检查代理目标
proxy: {
  '/api': {
    target: 'http://localhost:9000', // 确保指向本地网关
    changeOrigin: true,
  }
}

3. 清除缓存重试

rm -rf node_modules/.vite
pnpm dev:antd

登录问题

Q: 登录提示租户不存在？

A: 确认输入了正确的租户编码：

租户类型	租户编码	账号	密码
平台管理员	0000	admin	123456
租户管理员	8888	admin	123456

Q: 登录提示验证码错误？

A: 可能原因：

1. Redis 未启动 - 验证码存储在 Redis 中
2. Redis 连接配置错误 - 检查 Nacos 中 Redis 配置

# 检查 Redis 是否正常
docker exec -it redis redis-cli ping
# 应返回 PONG

Q: 登录后权限不足？

A: 检查用户角色配置：

1. 登录平台管理员账号（租户 0000）
2. 进入「系统管理」-「角色管理」
3. 确认角色已分配相应菜单权限

调试排错

Q: 控制台一堆红色报错，看不懂怎么办？

A: 看报错的关键技巧：

1. 找 Caused by - 真正的错误原因通常在这行
2. 找你写的代码 - 堆栈里找 com.wemirr 开头的行
3. 看第一个错 - 后面的错误可能是连锁反应

常见错误关键词：

• Connection refused → 连不上数据库/Redis/Nacos
• NullPointerException → 空指针，某个对象是 null
• Access denied → 数据库密码错了
• Table doesn't exist → 表不存在，SQL 脚本没执行

Q: 怎么知道后端服务有没有启动成功？

A: 看控制台日志最后几行：

Started GatewayApplication in 5.xxx seconds

如果看到 Started xxx 就是启动成功了。

也可以访问 Nacos 控制台 → 服务列表，看服务有没有注册上去。

Q: 接口报错怎么调试？

A:

1. 浏览器 F12 → Network 标签 → 找到报错的请求
2. 看 Response 里的错误信息
3. 后端 IDEA 控制台看详细报错

Q: 前端页面改了代码没效果？

A:

1. 先看有没有保存文件（Ctrl+S）
2. 清浏览器缓存（Ctrl+Shift+Delete）
3. 重启前端服务（Ctrl+C 停止，再 pnpm dev:antd）

---

开发问题

Q: 如何新增一个菜单？

A: 步骤如下：

1. 后端 - 编写 Controller、Service、Mapper
2. 前端 - 在 views/wemirr/ 下创建页面组件
3. 配置 - 在「菜单管理」中添加菜单项，配置路由地址和组件路径

Q: 如何获取当前登录用户信息？

A:

// 后端获取
@Autowired
private AuthenticationContext context;

public void example() {
    Long userId = context.userId();
    Long tenantId = context.tenantId();
    String username = context.username();
}

// 前端获取
import { useUserStore } from '@/store/modules/user';

const userStore = useUserStore();
const userInfo = userStore.getUserInfo;

Q: 如何忽略某个接口的租户过滤？

A: 使用 @TenantIgnore 注解：

@TenantIgnore
@GetMapping("/public/data")
public Result<List<Data>> getPublicData() {
    // 此接口不会添加租户过滤条件
}

部署问题

Q: 生产环境如何配置？

A: 参考 生产部署 文档

Q: 如何配置 HTTPS？

A: 在 Nginx 中配置 SSL：

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:5666;
    }
    
    location /api {
        proxy_pass http://localhost:9000;
    }
}

获取帮助

如果以上内容没有解决您的问题：

• 📖 查看 完整 FAQ
• 💬 加入技术交流群：789517089
• 🐛 提交
  Issue

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

  battcn.com
• 💰 付费技术支持：微信 battcn2022