企业官网建设流程全解析

最近在帮别人整理一套“基于Spring Boot + Vue的Web家庭设备维修服务系统”，光是看标题就知道，这不是一个只能跑个登录页的玩具项目，而是包含用户下单、维修工接单、管理员派单、服务评价、维修进度跟踪等完整业务流程的企业级教学项目。很多人拿到源码后第一反应是打开IDEA直接运行，结果被数据库连接失败、前端端口冲突、登录接口404、跨域报错这些问题搞得心态崩掉。这套项目如果只看代码不读文档，确实容易绕晕，但只要把“源码结构、部署配置、接口调用链路”这三条线理顺，一个晚上跑起来是完全可能的。

这篇文章就是我整理这套系统时踩过的坑和梳理出的关键点。我会从项目背景、源码阅读顺序、配置解析、本地联调、服务器部署、常见问题排查这几个角度完整讲一遍。如果你准备拿它做毕业设计、学习前后端分离项目，或者想部署给小型维修公司当内部工具用，照着这篇文章的思路走，基本不会迷路。

1. 这个系统到底在解决什么问题

先说业务。家庭设备维修服务系统的核心，不是“能登录”这么简单，而是把用户报修、维修人员派单、服务评价这三段流程串起来。没有系统的时候，维修订单记在纸质本子上，客户打电话催，维修师傅靠记忆排路线，管理员根本不知道哪个师傅今天到底干了几单。有了这套系统，用户通过手机或电脑提交地址、设备类型、故障描述、期望上门时间，管理员在后台分配维修工，维修工接单后更新状态“已接单、已上门、维修中、已完成”，用户最后评价服务。整个过程有记录、可追溯，维修响应效率和满意度都能明显提升。

这类系统在国内高校的Java课程设计里也特别常见，因为它的业务复杂度刚好够用：有用户、订单、派单、评价、权限管理，涉及多角色、多状态流转，还能扩展支付、消息推送等模块。开发技术上又很主流，Spring Boot负责后端接口，Vue负责前端页面，前后端分离，部署时打成jar包加静态文件，结构清晰。无论你是学生、个人开发者，还是小团队想给物业公司做一套内部维修管理工具，这个项目都很适合作为起点。

1.1 家庭设备维修的核心业务闭环

整个系统可以按照角色拆成三条线：

• 用户端：注册登录、维护常用地址、提交报修单、查看当前进度、对完成的工单进行评价。
• 维修工端：查看被分配到的工单、改变工单状态、填写维修结果和耗材信息。
• 管理员端：管理用户、维修工、设备类别、审核和派单、查看所有工单统计、处理投诉或者异常工单。

这三条线都围绕一个核心对象：维修工单。工单数据贯穿整个项目，所有功能设计本质上是围绕“工单状态”在做流转。状态一般包括：待派单、已派单、维修中、已完成、已评价、已取消。前端页面根据状态显示不同按钮，后端的Service层在不同状态之间做合法性校验。如果状态设计得乱，后面写代码会非常痛苦，所以源码里通常会在repair_order表和order_status_log表上做文章。

order_status_log这个表很多人会忽略，但它很重要。每条工单每次状态变化都记录一条日志，谁在什么时间把工单从什么状态改成了什么状态，全部存下来。这样做的好处是，就算页面没显示，管理员也能通过日志还原当时发生了什么，用户投诉的时候不用看人脸色，直接查记录。

1.2 为什么选Spring Boot + Vue这个组合

后端用Spring Boot，是因为它把Spring生态里那套复杂配置简化到了极致。内嵌Tomcat，打一个jar包就能跑；自动装配机制让数据源、MyBatis、Redis这些组件配置起来非常省事；再加上Spring Security或JWT做登录认证，社区资料多，出问题基本都搜得到。对学习者来说，Spring Boot几乎已经是Java Web项目的默认框架，学它不会白费。

前端用Vue，看重的是组件化和开发效率。页面拆成头部组件、工单卡片组件、状态标签组件，复用起来方便。Vue的双向数据绑定让表单交互写起来很直观，配合Vue Router和Vuex或Pinia，多角色页面之间切换和状态共享也清晰。前端的src/api目录里按模块封装接口，页面里只调用方法，不直接写axios请求，这个习惯很多项目都在用。

前后端分离带来的好处是开发和部署都更灵活。开发时前端用Node跑开发服务器，后端单独启动，通过代理把接口转发过去；部署时前端打包成静态文件交给Nginx，后端只提供一个对外接口服务。任何时候后端升级接口，不需要重新发前端；前端改版，也不影响后端逻辑。这套模式已经是现在Web开发的主流，学这个项目等于把主流工程实践完整走了一遍。

1.3 适合哪些场景和学习路径

如果你手头拿到的是带源码、部署文档、代码讲解文档的完整包，你的第一条路是“按文档把系统跑起来”，拿到原始状态再说。第二条路是“修改业务”，加一个预约时间段、加一个材料清单表、把管理员派单改成维修工抢单。第三条路是“学原理”，不看讲稿，自己尝试画一遍系统涉及的表的字段和关系，再看源码对比。第三条路比单纯读代码有用得多。很多人找工作面试时被问到项目经验，不是因为没有做过项目，而是因为只会照着文档念，说不清楚为什么订单表要单独记录状态日志、为什么前端接口要统一封装。这些问题，恰恰是这个项目里最有价值的东西。

2. 源码到手怎么读？先看结构，再跑代码

拿到一个你没有参与开发的项目，最忌讳的事就是打开IDE盲猜。我一般会先看文档，再看目录结构，然后看配置文件，最后才启动项目。这个顺序能省下大量排查时间。

2.1 先分清“源码、部署文档、代码讲解”分别该怎么用

这类完整的项目包通常包含四样东西：源码压缩包、数据库脚本SQL、部署文档（Word或Markdown）、代码讲解文档。部署文档重点告诉你“怎么跑起来”，讲解文档重点告诉你“代码是怎么设计的”。我建议先读部署文档，把环境准备好，让项目能在本机能跑，再回头看代码讲解。如果顺序反了，你连项目长什么样都不知道，读代码时满脑子都是抽象概念。

部署文档里最核心的内容是这几个：JDK版本、MySQL版本、Node版本、数据库创建语句、配置文件改动位置、默认账号密码。很多部署文档是作者在自己电脑上写的，路径和账号密码都是他自己的，你复制的时候不能直接抄，要改成你自己的。比如文档里写spring.datasource.password=123456，你的MySQL密码是root@123，就需要替换，这不算文档错误，是你没读仔细。

2.2 后端工程的目录结构长什么样

典型的Spring Boot后端结构长这样：

repair-server ├── src/main/java/com/repair │ ├── common │ │ ├── Result.java // 统一响应包装 │ │ └── BusinessException.java // 业务异常 │ ├── config │ │ ├── CorsConfig.java // 跨域配置 │ │ ├── MybatisPlusConfig.java // 分页插件 │ │ └── WebMvcConfig.java // 静态资源映射 │ ├── controller │ │ ├── AuthController.java │ │ ├── RepairOrderController.java │ │ └── AdminController.java │ ├── service │ │ ├── RepairOrderService.java │ │ └── impl/RepairOrderServiceImpl.java │ ├── mapper │ │ └── RepairOrderMapper.java │ ├── entity │ │ └── RepairOrder.java │ ├── security │ │ └── JwtUtil.java │ └── utils ├── src/main/resources │ ├── mapper │ │ └── RepairOrderMapper.xml │ ├── application.yml │ └── application-dev.yml └── pom.xml

读后端代码的顺序，我建议从Controller进。Controller是入口，能通过接口定义知道系统对外提供哪些能力。看到Controller之后去Service找业务逻辑，再看Mapper和XML了解SQL是怎么写的。Entity类里的字段对应数据库表，如果某个字段在多个接口里重复出现，很可能是表设计时就已经定好了，不要随便改。

2.3 前端工程的结构和阅读顺序

前端一般叫repair-web目录，典型结构如下：

repair-web ├── src │ ├── api │ │ ├── auth.js │ │ ├── order.js │ │ └── user.js │ ├── assets │ ├── components │ ├── router │ │ └── index.js │ ├── store │ │ └── user.js │ ├── utils │ │ └── request.js │ ├── views │ │ ├── admin │ │ ├── user │ │ └── worker │ ├── App.vue │ └── main.js └── package.json

读前端代码先看utils/request.js，因为所有接口请求都从这里经过。再看router/index.js，理解不同角色如何跳转到不同页面。然后看store里面的用户状态保存逻辑。最后再按页面看api模块和后端接口如何对应。前端如果出现“页面按钮点了没反应”，多半不是后端接口挂了，而是前端记得缓存状态没清理或者接口路径写错。

2.4 数据库设计里的几个关键点

家庭设备维修系统的表数量一般不多，核心表大概有这些：

数据库脚本导入后，重点去看repair_order表的索引和order_status_log表的外键。如果表没有设置合适的索引，等数据量到三万条以上，按状态筛选工单会明显变慢。很多课程设计项目数据量小，这一点平时根本感觉不到，但生产环境很可能被用户“卡爆”，所以这个项目里的索引和联合查询值得当成实战经验来学。

3. 部署文档里没写清楚的配置细节

每套项目的部署文档都不一样，但核心配置差异不大。这里把最通用的部署要点拆开讲，你可以对照自己的项目版本微调。

3.1 本地开发环境版本怎么选

我现在整理这套项目时，后端是Spring Boot 2.7、前端是Vue 2，采用的是一套很稳的经典组合。如果你拿到的是新项目，可能是Spring Boot 3.x配Vue 3，那要注意JDK版本必须是17或更高，MyBatis相关依赖也要换成适配3.x的版本。环境版本参考如下：

这里有个很典型的坑：老项目里用的是javax.servlet，Spring Boot 3.x里变成了jakarta.servlet。如果你的项目依赖是javax，说明它运行在Java 8环境，你偏要用Java 17去跑，大概率启动失败。反过来，Spring Boot 3的项目用Java 8也会报错。所以先看pom.xml再选JDK，别让IDE的自动检查告诉你“版本都不对”时才发现。

3.2 数据库初始化和导入顺序

项目包里的一般是repair_db.sql文件。导入前要确定字符集。如果SQL文件里没有指定，先在Navicat或者命令行创建数据库时指定：

CREATE DATABASE IF NOT EXISTS repair_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE repair_db; SOURCE /你的路径/repair_db.sql;

导入完成后立刻检查三件事：第一，表数量是否和文档说明一致；第二，user表里有没有初始的admin账号；第三，外键是否正常。如果导入时出现重复键或字段长度不够，通常是本机MySQL版本差异导致，不用慌张，查看第一个报错位置，手动调整SQL再导一次就行。

特别注意：不要在导入数据库前直接启动后端。否则Spring Boot在启动时检测不到数据源会直接报错退出。很多项目的部署文档第一句就是“验证环境”，但新手最容易跳过这一句。

3.3 后端配置文件逐行拆解

后端最重要的配置文件是application.yml。我整理过一份比较典型的配置，用来说明每个配置项是干什么的：

server: port: 8080 servlet: context-path: / spring: datasource: url: jdbc:mysql://localhost:3306/repair_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl repair: jwt: secret: your-secret-key expire-days: 7 upload: path: /home/repair/upload

很多项目会把不同环境的配置拆成application-dev.yml和application-prod.yml。本地用dev，生产用prod。切换环境时，只需要启动命令加上--spring.profiles.active=prod。注意repair.upload.path，这个路径决定了上传的维修照片保存在哪里。Windows本地可能是D:/repair-upload，Linux生产环境建议用绝对路径/home/repair/upload，并且在Linux下确认这个目录存在且有写权限。

3.4 前端环境变量与代理配置

前端开发时无法直接把请求发给后端的8080端口，因为浏览器有跨域限制。项目里通常会用Vue CLI的devServer代理规避。在vue.config.js里会有类似的配置：

module.exports = { devServer: { port: 8081, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/api': '' } } } } }

这个配置的意思是，前端页面里所有以/api开头的请求，都会被Node开发服务器转发到http://localhost:8080，并且把/api前缀去掉。所以后端接口实际是/login，前端只需要请求/api/login。有的人会问：为什么生产环境没有Node？生产环境我们把代理这件事交给Nginx做，到时候也是反向代理同一个道理。理解这一点，后面部署就不会觉得怪。

4. 本地联调流程与核心功能实现思路

4.1 启动后端和前端的具体顺序

本地联调的标准顺序是：

1. 导入数据库脚本。
2. 修改application.yml里的数据库账号密码。
3. 启动后端，等待Spring Boot日志出现Started。
4. 启动前端，执行npm install，再执行npm run serve。
5. 打开浏览器访问http://localhost:8081。

后端启动时如果日志里只有Tomcat started on port(s): 8080，说明后端没问题；前端启动时如果提示App running at，说明前端载体已经就绪。此时试试登录默认管理员的账号密码。登录成功后在浏览器开发者工具里看Network面板，Requests中能看到请求路径、响应耗时、状态码。这一步是联调时最推荐的调试习惯，比盲猜靠谱得多。

4.2 维修工单状态机的代码实现

这个系统里最值得讲的业务逻辑是状态机。要时刻防止“已完成”的工单被改回“维修中”之类的非法操作。很多老代码只在按钮上做了状态判断，后端接口没有校验，结果用户在页面点一下请求，服务端照样接收了，数据直接乱套。

我建议在后端Service层显式判断状态：

public void updateOrderStatus(RepairOrder order, RepairOrderStatus targetStatus, Long operatorId) { RepairOrderStatus current = RepairOrderStatus.valueOf(order.getStatus()); boolean allowed = current.canTransitTo(targetStatus); if (!allowed) { throw new BusinessException("当前状态不允许变更为：" + targetStatus.getDesc()); } order.setStatus(targetStatus.getCode()); repairOrderMapper.updateById(order); OrderStatusLog log = new OrderStatusLog(); log.setOrderId(order.getId()); log.setFromStatus(current.getCode()); log.setToStatus(targetStatus.getCode()); log.setOperatorId(operatorId); statusLogMapper.insert(log); }

配合一个枚举来维护合法的状态转移关系：

public enum RepairOrderStatus { PENDING("PENDING", "待派单"), ACCEPTED("ACCEPTED", "已接单"), IN_PROGRESS("IN_PROGRESS", "维修中"), COMPLETED("COMPLETED", "已完成"), EVALUATED("EVALUATED", "已评价"), CANCELLED("CANCELLED", "已取消"); public boolean canTransitTo(RepairOrderStatus target) { switch (this) { case PENDING: return target == ACCEPTED || target == CANCELLED; case ACCEPTED: return target == IN_PROGRESS || target == CANCELLED; case IN_PROGRESS: return target == COMPLETED; case COMPLETED: return target == EVALUATED; default: return false; } } }

这样写的最大好处是，以后改业务规则只改枚举，不需要翻遍所有Controller。比如要加一个“客户取消后管理员可以重新派单”的规则，在枚举里增加一个从CANCELLED到PENDING的合法路径即可。代码量少，还不容易漏改状态判断。

4.3 前端请求封装和登录鉴权

前端utils/request.js通常会对axios做统一封装，核心逻辑是：每次请求前从localStorage取token，加到请求头；拿到响应后统一处理业务码，比如后端返回Result.success或Result.fail；遇到401就跳回登录页。

import axios from 'axios' import router from '@/router' const request = axios.create({ baseURL: '/api', timeout: 10000 }) request.interceptors.request.use(config => { const token = localStorage.getItem('repair_token') if (token) { config.headers['Authorization'] = 'Bearer ' + token } return config }) request.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { if (res.code === 401) { router.push('/login') } return Promise.reject(new Error(res.message || '请求失败')) } return res.data }, error => { return Promise.reject(error) } ) export default request

在页面里调用就非常简洁了：

import request from '@/utils/request' export function submitOrder(data) { return request({ url: '/repair/order', method: 'post', data }) }

这里有一个经验：不要把接口地址写死在页面里。后端路径一旦改，或者要统一拼接前缀，你去每个页面里找接口字符串，能找一晚上。统一封装在api/order.js这种模块里，所有人看代码都舒服，维护也简单。

5. 生产部署实操：Linux + Nginx + Jar

本地跑通只能算第一步，真正考验人的是生产部署。部署方式有很多，Docker、系统服务、普通jar后台运行。这里讲最常见的Linux + Nginx + jar组合，适合项目体量不大、未来想平滑扩展的情况。

5.1 后端打包与后台运行

先在本地执行Maven打包命令：

mvn clean package -DskipTests

打包成功后，target目录下会生成一个jar包，比如repair-server-0.0.1-SNAPSHOT.jar。把这个jar上传到服务器的/home/repair/目录，然后使用如下命令启动：

cd /home/repair nohup java -jar repair-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod > app.log 2>&1 &

这里nohup命令的意思是让程序挂后台运行，日志输出到app.log。启动后立刻执行tail -f app.log，观察有没有异常。很多新手在这里犯错：命令运行后再按Ctrl+C，session结束，程序也停了。用nohup ... &之后，正常关掉终端不会影响它，但是如果你的部署过程还有别的后台任务，还是建议用systemd管理服务，那样更规范。

如果你要在服务器上更新版本，先停掉旧进程，再启动新进程。找进程方式：

ps -ef | grep repair-server kill 进程ID

5.2 前端打包与Nginx静态资源配置

前端打包命令是：

npm run build

执行完成后，项目根目录下会多一个dist文件夹。把dist里的所有文件上传到服务器的/home/repair/web目录。然后在Nginx配置里添加一个Server块：

server { listen 80; server_name repair.example.com; root /home/repair/web; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /upload/ { alias /home/repair/upload/; } location / { try_files $uri $uri/ /index.html; } }

这个配置里最关键的是try_files $uri $uri/ /index.html;。因为Vue Router默认使用History模式，用户访问/user/order/123时，Nginx在静态目录里找不到这个文件，如果没有try_files回退，就会返回404。加上try_files后，请求会被重新落到index.html，Vue路由再接管页面渲染。

location /api/的代理也比较讲究。我这里的后端接口路径是/api/xxx，所以proxy_pass http://127.0.0.1:8080;不带URI。如果后端接口本身没有/api前缀，要在Nginx这层做路径重写，具体写法要看你的项目约定，不要照抄网上模板就完事。

5.3 文件上传路径和图片访问的配置

维修系统一定会涉及上传故障照片，所以Nginx和Spring Boot都要处理好上传路径。Spring Boot这边通常已经做了静态资源映射：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/upload/**") .addResourceHandler("file:" + uploadPath + "/"); } }

这样上传后的文件，比如/home/repair/upload/2025/abc.jpg，可以通过http://服务器IP/upload/2025/abc.jpg访问。Nginx里的location /upload/会先拦截请求，直接交给静态文件目录，不走后端。如果没有这层Nginx配置，用户访问图片会走Spring Boot，虽然也能显示，但性能差不少。

部署到生产环境后，一定要检查上传目录的权限。很多Linux服务器上，Java进程运行在tomcat用户或root用户下，如果目录是755权限，进程没有写权限，上传接口会报“无法创建目录”。最简单的方式：

mkdir -p /home/repair/upload chmod -R 755 /home/repair/upload

6. 常见问题与排查技巧实录

这一部分是我在实际踩坑过程中总结出来的，不一定每一个项目都会遇到，但命中率极高。

6.1 启动报错速查表

6.2 几个容易忽略但特别影响体验的细节

第一，MyBatis的resultMap不要滥用。如果你的表字段和实体类字段能用map-underscore-to-camel-case自动映射，就不用每个查询写一长串resultMap。但如果碰到带有order_no这种下划线字段，还需要确认驼峰转换配置是否开启，否则查出来的对象orderNo一直为null，排查起来会很费劲。

第二，不要在生产环境开启SQL日志。开发环境常用的:

configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

在正式生产环境建议去掉，因为控制台打印的SQL会非常频繁，容易把日志文件撑爆，还会泄露表结构信息。如果你需要排错，可以设置Spring Boot的logging.level只打印某个Mapper包下的SQL，不要全局打印。

第三，数据库时间字段要留意时区。在连接串上加上serverTimezone=Asia/Shanghai是一个简单又省事的方法。项目里的create_time如果全部用数据库now()生成，不同时区服务器之间会观察到好几个小时的时间偏差。如果前端页面显示的时间和实际差8小时，基本就是时区问题。

第四，修改前端代码后没有重新打包。很多部署现场是：前端改了页面，问为什么线上没变化，最后发现根本没执行npm run build，还一直在用老旧的dist文件。这不算技术问题，但是最容易出错的流程问题。

6.3 如果只有jar包没有源码，怎么定位问题

有时候拿到手的是一个可运行的jar包，没有源码。想排查接口返回的逻辑，可以用反编译工具把jar包里的class反编译成Java源码，结合部署文档里的接口说明去对照。比如JD-GUI这类工具，能直接打开jar文件浏览类结构。不过这是辅助手段，反编译出来的代码可读性参差不齐，变量名、注释全都会丢，真正能用来修改项目并重新打包，工程量很大。

我更推荐的做法是：先用java -jar启动，然后通过接口调用和日志来观察行为。开启--debug或者打印请求日志，不一定需要源码就能定位大部分问题。比如接口返回500，日志会直接告诉你异常发生在哪一行，哪个MyBatis的XML文件写法不对，再看对应的表结构就能推断出问题逻辑。能不动一个线上正在运行的项目，就别去动它，这是运维的基本心态。

最后再分享一个我个人的习惯。每次拿到一个像样的全栈项目，我一定会在跑通之后重新看一遍数据库表关系，手动把表名、字段名、业务含义画成表格记下来。因为代码可以重构，文档可以过期，但表结构里的业务设计往往是最稳定的一层。这个维修系统的核心，就是从一张维修工单开始，把人和设备、服务流程、评价反馈全部串起来。把这件事想明白了，不管你是用它交作业、改造上线，还是面试时被问到项目细节，都能讲得有理有据，比死记硬背源码强得多。