Zs Admin

Appearance

常见故障及解决办法 ​

本文档汇总了ZsAdmin项目在开发、测试和部署过程中常见的故障及解决办法，帮助开发者快速定位和解决问题。

1. 前端常见故障 ​

1.1 项目启动失败 ​

故障现象：运行 npm run dev 后，项目无法正常启动，控制台报错。

可能原因：

  • 依赖包安装不完整
  • Node.js 版本不符合要求
  • 端口被占用
  • 配置文件错误

解决办法：

  1. 检查 Node.js 版本：node -v，确保版本 >= 18.0.0
  2. 删除 node_modules 目录和 package-lock.json 文件，重新安装依赖：npm install
  3. 检查端口是否被占用：netstat -tlnp | grep 3000（或项目配置的其他端口）
  4. 查看控制台报错信息，根据错误提示修复配置文件

1.2 页面白屏 ​

故障现象：项目启动成功，但浏览器访问页面时白屏。

可能原因：

  • 路由配置错误
  • 权限验证失败
  • 资源加载失败
  • JavaScript 错误

解决办法：

  1. 打开浏览器开发者工具（F12），查看 Console 面板的错误信息
  2. 检查 Network 面板，确认所有资源是否正常加载
  3. 检查路由配置，确认访问路径是否正确
  4. 检查权限配置，确认当前用户是否有访问该页面的权限
  5. 清除浏览器缓存，重新刷新页面

1.3 接口请求失败 ​

故障现象：页面功能无法正常使用，控制台显示 API 请求失败。

可能原因：

  • 后端服务未启动
  • 接口地址配置错误
  • 跨域问题
  • 权限认证失败

解决办法：

  1. 确认后端服务是否正常运行
  2. 检查 .env 文件中的 API 地址配置是否正确
  3. 检查浏览器开发者工具 Network 面板，查看请求的 URL 和状态码
  4. 确认是否有跨域问题，可通过配置 Vite 代理解决
  5. 检查 Token 是否过期，尝试重新登录

1.4 组件样式异常 ​

故障现象：页面组件样式显示异常，或与设计稿不符。

可能原因：

  • CSS 样式冲突
  • 主题配置错误
  • 组件版本不兼容
  • 样式加载顺序问题

解决办法：

  1. 检查浏览器开发者工具 Elements 面板，查看样式应用情况
  2. 确认主题配置是否正确，特别是颜色变量
  3. 检查组件版本是否与项目要求一致
  4. 调整样式加载顺序，确保组件样式被正确应用
  5. 使用 CSS 特异性（specificity）解决样式冲突

1.5 构建失败 ​

故障现象：运行 npm run build 后，构建失败。

可能原因：

  • 代码语法错误
  • TypeScript 类型检查失败
  • 依赖版本不兼容
  • 构建配置错误

解决办法：

  1. 查看控制台报错信息，定位具体错误位置
  2. 修复代码中的语法错误
  3. 解决 TypeScript 类型检查问题
  4. 检查依赖版本，确保兼容性
  5. 检查构建配置文件 vite.config.ts 是否正确

2. 后端常见故障 ​

2.1 项目启动失败 ​

故障现象：运行 mvn spring-boot:run 或启动 JAR 包后，项目无法正常启动。

可能原因：

  • 依赖包缺失
  • JDK 版本不符合要求
  • 端口被占用
  • 数据库连接失败
  • 配置文件错误

解决办法：

  1. 检查 JDK 版本：java -version，确保版本 >= 17
  2. 检查端口是否被占用：netstat -tlnp | grep 8080
  3. 检查数据库是否正常运行，连接信息是否正确
  4. 查看控制台或日志文件的报错信息，定位具体问题
  5. 确认 application.yml 或 application-prod.yml 配置是否正确

2.2 数据库连接失败 ​

故障现象：项目启动时，控制台报错 "Could not get JDBC Connection"

可能原因：

  • 数据库服务未启动
  • 数据库连接信息配置错误
  • 数据库用户权限不足
  • 数据库驱动版本不兼容
  • 防火墙或安全组限制

解决办法：

  1. 确认数据库服务是否正常运行：systemctl status mysql 或 systemctl status redis
  2. 检查 application.yml 中的数据库连接信息（URL、用户名、密码）
  3. 确认数据库用户是否有足够的权限访问目标数据库
  4. 检查数据库驱动版本是否与数据库版本兼容
  5. 检查防火墙或安全组是否允许应用服务器访问数据库

2.3 API 接口返回错误 ​

故障现象：前端请求 API 接口时，返回 4xx 或 5xx 错误。

可能原因：

  • 接口路径错误
  • 参数格式不正确
  • 权限验证失败
  • 业务逻辑错误
  • 服务器内部错误

解决办法：

  1. 检查前端请求的接口路径是否与后端定义一致
  2. 检查请求参数的格式和类型是否符合接口要求
  3. 确认当前用户是否有访问该接口的权限
  4. 查看后端日志，定位具体的业务逻辑错误
  5. 对于 5xx 错误，检查服务器资源使用情况，确认是否存在内存溢出或 CPU 过高问题

2.4 权限验证失败 ​

故障现象：用户登录后，访问某些页面或接口时提示 "权限不足"

可能原因：

  • 用户角色配置错误
  • 权限点配置不完整
  • 接口权限注解缺失
  • Redis 服务异常

解决办法：

  1. 检查用户所属角色是否正确配置
  2. 确认权限点是否已正确分配给用户角色
  3. 检查接口是否添加了正确的权限注解
  4. 确认 Redis 服务是否正常运行
  5. 清除 Redis 缓存，重新登录尝试

2.5 内存溢出 ​

故障现象：项目运行一段时间后，控制台报错 "OutOfMemoryError"

可能原因：

  • JVM 内存配置不足
  • 存在内存泄漏
  • 数据量过大
  • 第三方库内存占用过高

解决办法：

  1. 调整 JVM 内存参数：-Xms1024m -Xmx2048m
  2. 使用内存分析工具（如 VisualVM、YourKit）定位内存泄漏问题
  3. 优化数据库查询，减少一次性加载的数据量
  4. 检查第三方库版本，升级到更稳定的版本
  5. 实现合理的缓存策略，避免缓存过大

3. 数据库常见故障 ​

3.1 数据库连接超时 ​

故障现象：应用程序连接数据库时，出现 "Connection timed out" 错误

可能原因：

  • 数据库服务负载过高
  • 网络不稳定
  • 数据库连接池配置不合理
  • 防火墙限制

解决办法：

  1. 检查数据库服务器的 CPU、内存和磁盘使用情况
  2. 优化数据库连接池配置，调整最大连接数和超时时间
  3. 检查网络连接是否稳定，排除网络故障
  4. 检查防火墙或安全组是否允许应用服务器访问数据库
  5. 考虑使用数据库读写分离或分库分表，减轻主库压力

3.2 SQL 执行缓慢 ​

故障现象：接口响应时间长，数据库查询缓慢

可能原因：

  • SQL 语句优化不足
  • 缺少必要的索引
  • 数据量过大
  • 锁竞争激烈

解决办法：

  1. 开启 MySQL 慢查询日志，定位慢查询 SQL：
    sql
    set global slow_query_log=on;
set global long_query_time=1;
  2. 使用 EXPLAIN 分析 SQL 执行计划，优化查询语句
  3. 为查询条件中的字段添加合适的索引
  4. 考虑使用分页查询，减少一次性返回的数据量
  5. 优化业务逻辑，减少复杂查询
  6. 检查是否存在锁竞争，优化事务处理

3.3 数据库死锁 ​

故障现象：事务执行过程中出现 "Deadlock found when trying to get lock" 错误

可能原因：

  • 事务设计不合理
  • 并发操作同一数据
  • 锁等待超时

解决办法：

  1. 优化事务设计，减少事务持有锁的时间
  2. 统一访问数据的顺序，避免交叉锁
  3. 考虑使用乐观锁替代悲观锁
  4. 增加锁等待超时时间
  5. 分析死锁日志，定位具体的死锁语句：
    sql
    show engine innodb status;

3.4 数据插入失败 ​

故障现象：执行数据插入操作时，出现 "Duplicate entry" 或 "Data too long for column" 错误

可能原因：

  • 违反唯一约束
  • 数据长度超过字段定义
  • 字段类型不匹配
  • 外键约束冲突

解决办法：

  1. 检查插入的数据是否违反了唯一约束
  2. 确认数据长度是否符合字段定义
  3. 检查数据类型是否与字段类型匹配
  4. 确认外键关联的数据是否存在
  5. 查看具体的错误信息，根据提示修复数据

4. 部署常见故障 ​

4.1 Docker 容器启动失败 ​

故障现象：运行 docker-compose up -d 后，部分容器无法正常启动

可能原因：

  • Docker 镜像构建失败
  • 容器配置错误
  • 依赖服务未就绪
  • 端口映射冲突

解决办法：

  1. 查看容器日志：docker-compose logs -f <container-name>
  2. 检查 Dockerfile 和 docker-compose.yml 配置是否正确
  3. 确认依赖服务（如 MySQL、Redis）是否正常运行
  4. 检查端口映射是否存在冲突
  5. 尝试重新构建镜像：docker-compose build

4.2 Nginx 404 错误 ​

故障现象：通过域名访问应用时，出现 "404 Not Found" 错误

可能原因：

  • Nginx 配置错误
  • 静态资源路径不正确
  • 路由配置问题
  • 权限不足

解决办法：

  1. 检查 Nginx 配置文件中的 root 和 location 配置
  2. 确认静态资源是否已正确部署到 Nginx 目录
  3. 对于单页应用，确保配置了正确的 fallback 规则：
    nginx
    location / {
    try_files $uri $uri/ /index.html;
}
  4. 检查 Nginx 进程的运行用户是否有访问静态资源的权限
  5. 重启 Nginx 服务：systemctl restart nginx

4.3 HTTPS 证书问题 ​

故障现象：访问 HTTPS 网站时，浏览器提示证书错误

可能原因：

  • 证书已过期
  • 证书配置错误
  • 证书与域名不匹配
  • 中间证书缺失

解决办法：

  1. 检查证书有效期：openssl x509 -in cert.pem -text -noout | grep Validity
  2. 确认 Nginx 配置中证书路径是否正确
  3. 检查证书是否与域名匹配
  4. 确认是否包含完整的证书链（包括中间证书）
  5. 使用 Let's Encrypt 重新申请免费证书：certbot --nginx -d your-domain.com

4.4 文件上传失败 ​

故障现象：用户上传文件时，提示 "上传失败" 或 "文件过大"

可能原因：

  • Nginx 上传文件大小限制
  • 后端配置的文件大小限制
  • 磁盘空间不足
  • 权限不足

解决办法：

  1. 修改 Nginx 配置，增加上传文件大小限制：
    nginx
    client_max_body_size 100m;
  2. 修改 Spring Boot 配置，增加文件大小限制：
    yaml
    spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB
  3. 检查服务器磁盘空间：df -h
  4. 确认上传目录是否存在，且应用程序有写入权限

5. 其他常见故障 ​

5.1 日志查看问题 ​

故障现象：无法查看应用日志，或日志内容不完整

可能原因：

  • 日志配置错误
  • 日志文件权限不足
  • 日志级别设置过高
  • 日志文件过大

解决办法：

  1. 检查日志配置文件 logback-spring.xml 是否正确
  2. 确认日志文件目录是否存在，且应用程序有写入权限
  3. 调整日志级别为 INFO 或 DEBUG，获取更详细的日志信息
  4. 配置日志滚动策略，避免日志文件过大
  5. 使用日志分析工具（如 ELK Stack）集中管理日志

5.2 Git 提交失败 ​

故障现象：执行 git push 时，出现 "Permission denied" 或 "Connection timed out" 错误

可能原因：

  • SSH 密钥配置错误
  • 网络连接问题
  • 分支权限不足
  • 本地分支与远程分支冲突

解决办法：

  1. 检查 SSH 密钥是否已正确配置：ssh -T git@github.com 或 ssh -T git@gitee.com
  2. 确认网络连接是否正常，尝试切换网络环境
  3. 检查当前用户是否有推送权限
  4. 先执行 git pull 合并远程分支的更新，解决冲突后再推送
  5. 检查 Git 配置：git config --list

6. 故障排查建议 ​

  1. 查看日志：日志是排查故障的重要依据，务必养成查看日志的习惯
  2. 定位问题：根据错误信息，逐步缩小问题范围，定位到具体模块或代码行
  3. 谷歌搜索：很多问题都有解决方案，善用搜索引擎
  4. 版本控制：使用 Git 管理代码，便于回滚和对比
  5. 测试环境：在测试环境复现问题，避免直接在生产环境调试
  6. 文档记录：记录遇到的问题和解决方案，便于后续查阅
  7. 团队协作：遇到复杂问题，及时与团队成员沟通

7. 寻求帮助 ​

如果您遇到的问题无法通过本文档解决，可以通过以下方式寻求帮助：

  1. GitHub Issues：https://github.com/zsadmin2025/zs-admin/issues
  2. Gitee Issues：https://gitee.com/zsadmin2025/zs-admin/issues
  3. 交流群：加入官方交流群，与其他开发者讨论
  4. 邮件反馈：发送邮件至 zsadmin@example.com

在寻求帮助时，请提供详细的故障现象、错误日志和操作步骤，以便我们更快地定位和解决问题。