企业官网建设流程全解析

• 电商
• 后端
• 前端
• 移动开发

本文以 mall4j 电商系统的管理后台为对象，给出一条"只跑管理后台"的 30 分钟启动路线：不碰 Docker、Nginx、支付、小程序，仅靠MySQL -> Redis -> yami-shop-admin -> front-end/mall4v四条链路上手。读完本文，你将掌握 mall4j 前后端分离项目的端口与依赖对照、数据库导入与 Redis 准备、后端 Spring Boot 服务与管理后台 Vite 前端的启动方式，以及登录成功后如何验证数据库、Redis、菜单权限与接口地址全部就绪。

为什么第一次启动只跑管理后台

mall4j 是一个前后端分离的多模块项目，后端有两个启动入口，分别服务不同客户端：

管理后台页面只依赖管理端接口8085，与用户端接口8086没有耦合。因此第一次启动只需要跑通yami-shop-admin，用户端接口可以等后台闭环验证完毕后再启动，这样能最快确认数据库、Redis、登录、菜单权限、前端接口地址五件事是否正常，把启动排查面缩到最小。

从源码看，管理端启动入口 WebApplication.java 是一个标准的 Spring Boot 应用：通过@SpringBootApplication开启自动装配，并以@ComponentScan("com.yami.shop")扫描整个业务包；在 IDEA 中直接运行其main方法即可启动8085端口。

最小闭环与端口对照

本地第一次启动只需要四类服务：

MySQL -> Redis -> yami-shop-admin -> front-end/mall4v

对应端口与用途如下：

其中9527是 Vite 开发服务器的端口，并非后端端口。在 vite.config.js 的开发服务器配置中可以确认：

server: { host: true, port: 9527, open: true }

host: true表示允许局域网访问，open: true表示启动后自动打开浏览器。

启动前先核对环境版本，以仓库内配置为准：

Node 与 pnpm 的版本约束写死在 front-end/mall4v/package.json 的engines字段中，同时package.json里的preinstall脚本执行only-allow pnpm，强制使用 pnpm 安装依赖，用 npm/yarn 安装会直接报错。后端关键依赖版本（Spring Boot、MyBatis-Plus、Sa-Token、Redisson、Knife4j 等）以根目录 pom.xml 为准。

七步启动路线

第 1 步：确认版本

用以下命令快速自检：

java -version # 应显示 JDK 17 mvn -v # 确认 Maven 可用 mysql --version # 5.7+ redis-server --version # 4.0+ node -v # 满足 ^20.19.0 || >=22.12.0 pnpm -v # >=7

第 2 步：启动 MySQL

确保本机 MySQL 运行在3306端口。mall4j 的开发环境数据源配置位于 application-dev.yml：

spring: datasource: url: jdbc:mysql://127.0.0.1:3306/yami_shops?allowMultiQueries=true&useSSL=false&useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&zeroDateTimeBehavior=convertToNull&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=GMT%2B8&nullCatalogMeansCurrent=true username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver type: com.zaxxer.hikari.HikariDataSource

连接串中的关键参数值得注意：

• allowMultiQueries=true：允许一次执行多条 SQL，SQL 脚本导入与部分复杂查询依赖此能力；
• characterEncoding=UTF-8与serverTimezone=GMT%2B8：保证中文与时间字段正确；
• 数据库名固定为yami_shops，账号密码默认为root / root——如果你的本机 MySQL 账号密码不同，必须同步修改这里的username/password，否则启动时数据源初始化失败；
• 连接池使用 HikariCP（maximum-pool-size: 20），并通过connection-test-query: SELECT 1做连接可用性探测。

第 3 步：导入db/yami_shop.sql

导入初始化 SQL：

mysql -uroot -proot < db/yami_shop.sql

该脚本位于 db/yami_shop.sql，共约 5898 行，文件开头自带建库语句：

create database IF NOT EXISTS `yami_shops` default character set utf8mb4 collate utf8mb4_general_ci;

也就是说即使本机还没有yami_shops库，导入时也会自动创建（字符集utf8mb4），随后依次创建tz_前缀的业务表并灌入初始化数据，包括地区表tz_area、系统用户表tz_sys_user、菜单权限表tz_sys_menu等。菜单与权限数据是"登录后能看到左侧菜单"的前提，这也是登录失败时首先怀疑"MySQL 是否导入数据"的原因。

第 4 步：启动 Redis

Redis 必须监听6379端口。开发环境 Redis 配置同样在 application-dev.yml：

spring: data: redis: host: 127.0.0.1 port: 6379 database: 0

登录 token 的存储与校验依赖 Redis。若 Redis 未启动或端口不符，管理后台登录接口将直接失败。

第 5 步：启动yami-shop-admin

推荐用 IDEA 导入 Maven 多模块工程后，直接运行：

yami-shop-admin/src/main/java/com/yami/shop/admin/WebApplication.java

命令行方式则在仓库根目录执行：

mvn -pl yami-shop-admin -am spring-boot:run

-am（also make）会先把依赖的兄弟模块（如yami-shop-bean、yami-shop-common、yami-shop-service、yami-shop-sys、yami-shop-security-*）一起构建。启动完成后，管理端接口文档应可访问：

http://127.0.0.1:8085/doc.html

doc.html由 Knife4j（当前依赖版本4.5.0）提供，Swagger 配置类位于 SwaggerConfiguration.java。管理端默认激活的开发 profile 在 application.yml 中声明（spring.profiles.active: dev），因此实际加载的就是application-dev.yml。

第 6 步：启动front-end/mall4v

管理后台前端位于front-end/mall4v，启动命令：

cd front-end\mall4v pnpm i pnpm run dev

pnpm i安装依赖（仓库使用 pnpm 工作区与锁文件），pnpm run dev拉起 Vite 开发服务器，按终端输出访问本地地址（默认http://localhost:9527）。

开发环境的接口地址配置在 .env.development：

VITE_APP_ENV = 'development' VITE_APP_BASE_API = 'http://127.0.0.1:8085' VITE_APP_RESOURCES_URL = 'https://img.mall4j.com/'

• VITE_APP_BASE_API：所有接口请求的基地址，默认指向管理端后端8085；
• VITE_APP_RESOURCES_URL：静态资源 URL；
• 若后端端口被修改，必须同步修改VITE_APP_BASE_API，否则登录请求会发往错误地址。

第 7 步：登录管理后台

打开管理后台页面，使用初始化账号登录：

admin / 123456

登录接口的完整链路可以在 AdminLoginController.java 中看到，顺序为：

1. 校验图形验证码（captchaService.verification，失败直接返回"验证码有误或已过期"）；
2. 按用户名查询tz_sys_user（查不到返回"账号或密码不正确"）；
3. 解密前端提交的密码并交给PasswordCheckManager.checkPassword校验（含半小时内密码错误十次锁定 30 分钟的规则）；
4. 校验用户状态（status == 0的禁用账号无法登录）；
5. 加载用户权限集合：超级管理员（Constant.SUPER_ADMIN_ID）直接取全部菜单权限，普通用户走queryAllPerms；
6. 组装UserInfoInTokenBO后调用TokenStore.storeAndGetVo将 token 写入 Redis 并返回。

token 的生成规则在 application.yml 的sa-token配置中定义：token-name: Authorization、token-style: uuid、is-concurrent: true（同一账号允许并发登录）。

先不要做的事

第一次启动请克制住扩展范围的冲动，先不要做这些：

• 不要先改 Docker；
• 不要先配 Nginx；
• 不要先接支付；
• 不要先启动小程序和 uni-app；
• 不要先写二开功能。

先跑通管理后台，再逐层叠加其他模块，理解成本会低很多。仓库虽然提供了 docker-compose.yml 与各模块的 Dockerfile 等容器化方案，但那属于后续部署阶段的事，与"最小闭环"目标无关。

完成后应该看到

按上述步骤操作后，应能同时确认四点：

• http://127.0.0.1:8085/doc.html能打开管理端接口文档；
• 管理后台本地页面能打开（默认http://localhost:9527）；
• 登录接口请求的是http://127.0.0.1:8085（浏览器 Network 面板可见）；
• 登录成功后能看到左侧菜单。

登录失败排查速查

登录失败时不要先怀疑业务代码，按依赖链路自下而上排查：

检查题-含答案

问题：第一次启动为什么只跑yami-shop-admin，不一定要跑yami-shop-api？

答案：管理后台只依赖管理端接口8085。先跑通后台管理闭环，可以最快确认数据库、Redis、登录、菜单权限、前端接口地址都正常。

问题：管理后台页面端口是8085吗？

答案：不是。8085是管理端后端接口；管理后台前端由 Vite 启动，当前端口是9527。项目是前后端分离架构，前端端口与后端端口天然不同。

问题：登录失败时应该先怀疑业务代码吗？

答案：不应该。先查 MySQL 是否导入数据、Redis 是否启动、管理后台是否连8085、Token 是否过期。

延伸阅读

• 环境要求：JDK、MySQL、Redis、Node、pnpm 版本明细与后端依赖版本清单
• 数据库初始化：db/yami_shop.sql的完整导入说明
• 后端本地启动：管理端 / 用户端双启动入口详解
• 管理后台本地启动：Vite 前端启动细节
• 前端接口地址配置：多环境接口地址切换
• 启动失败排查：启动类问题诊断
• 登录与验证码问题：登录链路专项排查
• 接口地址与 401 问题：接口连通性与鉴权问题

本文依据

• doc/2-环境搭建/1-30分钟启动路线.md
• front-end/mall4v/vite.config.js
• front-end/mall4v/.env.development
• front-end/mall4v/package.json
• yami-shop-admin/src/main/resources/application-dev.yml
• yami-shop-admin/src/main/resources/application.yml
• yami-shop-admin/src/main/java/com/yami/shop/admin/WebApplication.java
• yami-shop-admin/src/main/java/com/yami/shop/admin/controller/AdminLoginController.java
• db/yami_shop.sql

• 电商
• 后端
• 前端
• 移动开发