troubleshooting.md 10.5 KB

原文件审查历史永久链接



SMF Core 故障排除指南


概述

本文档提供SMF Core系统常见问题的诊断方法和解决方案，帮助用户快速定位和解决系统运行中遇到的问题。


常见问题分类


启动问题


1. 服务无法启动，端口被占用

现象：启动时出现Address already in use错误

解决方法：


检查端口占用情况：
```bash
# Linux/macOS
lsof -i :8080


# Windows
   netstat -ano | findstr :8080


2. 关闭占用端口的进程：
   ```bash
   # Linux/macOS
   kill -9 [PID]

   # Windows
   taskkill /F /PID [PID]


或修改配置文件，使用其他端口：
yaml
# application.yml
server:
 port: 8081


2. 数据库连接失败

现象：启动时出现Connection refused或Cannot create PoolableConnectionFactory错误

解决方法：


检查MySQL服务是否启动：
```bash
# Linux
systemctl status mysql


# Windows
   services.msc  # 检查MySQL服务状态


2. 验证数据库连接参数是否正确：
   - 主机地址
   - 端口号
   - 数据库名称
   - 用户名和密码

3. 确认数据库用户有足够权限：
   ```sql
   GRANT ALL PRIVILEGES ON smf_core.* TO 'smf_user'@'%';
   FLUSH PRIVILEGES;


3. 内存溢出导致启动失败

现象：启动时出现OutOfMemoryError错误

解决方法：


增加JVM内存配置：

java -Xms512m -Xmx1024m -jar smf-core.jar


检查应用是否有内存泄漏问题


登录与认证问题


1. 用户名或密码错误

现象：登录失败，提示"用户名或密码错误"

解决方法：


确认用户名和密码是否正确（默认管理员：admin/admin123）
检查是否开启了大写锁定
尝试重置密码：通过数据库修改用户密码


UPDATE sys_user SET password = '$2a$10$jJfBZ42X1kU2hJt8XtG/6uS5F2mSJyWgXtWjK5CwqZ6bBZ42X1kU2h' WHERE username = 'admin';


2. Token过期

现象：操作时提示"Token已过期"

解决方法：


重新登录获取新的Token
或配置更长的Token过期时间：
yaml
jwt:
 expiration: 7200000  # 2小时


数据操作问题


1. 保存数据失败

现象：保存数据时提示"保存失败"

解决方法：


检查输入数据是否符合验证规则
查看日志中详细错误信息：
bash
tail -f logs/smf.txt | grep ERROR


检查数据库连接状态
验证当前用户是否有操作权限


2. 数据库锁表

现象：操作时系统卡住，无法继续

解决方法：


查看锁表情况：

SELECT * FROM information_schema.innodb_locks;
SELECT * FROM information_schema.innodb_lock_waits;


找到并终止占用锁的进程：

KILL [线程ID];


优化事务处理逻辑，减少长时间持有锁的操作


性能问题


1. 系统响应缓慢

现象：页面加载或操作响应时间过长

解决方法：


检查服务器资源使用情况：

# Linux
top
free -m
df -h


优化数据库查询：


为频繁查询的字段添加索引
检查并优化慢查询


调整JVM内存和GC参数：

java -Xms2g -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar smf-core.jar


启用Redis缓存（如未启用）：

spring:
 redis:
   host: localhost
   port: 6379


2. 高并发下性能下降

解决方法：


调整Tomcat线程池配置：

server:
 tomcat:
   max-threads: 200
   min-spare-threads: 20


使用数据库连接池参数优化：

spring:
 datasource:
   hikari:
     maximum-pool-size: 20
     minimum-idle: 5


考虑启用分布式部署


接口调用问题


1. API请求返回401错误

现象：调用API时返回{"code":"401","message":"未授权"}

解决方法：


检查请求头中是否包含有效的Authorization Token：

Authorization: Bearer {token}


确认Token是否过期
检查API路径是否正确


2. API请求返回403错误

现象：调用API时返回{"code":"403","message":"权限不足"}

解决方法：


确认当前用户是否有操作该接口的权限
检查用户角色配置


3. API请求返回500错误

现象：调用API时返回{"code":"500","message":"服务器内部错误"}

解决方法：


查看服务器日志，定位具体错误原因
根据日志中的异常信息进行修复


设备连接问题


1. AGV连接失败

现象：系统无法连接AGV设备

解决方法：


检查AGV设备是否正常运行

验证AGV连接参数是否正确：

{
 "agv": {
   "host": "192.168.1.100",
   "port": 8000,
   "timeout": 30000
 }
}


检查网络连接状态，确保服务器可以访问AGV设备IP


2. 条码扫描器响应超时

解决方法：


增加条码扫描器超时配置：

{
 "barcode": {
   "timeout": 20000
 }
}


检查条码扫描器硬件连接


日志相关问题


1. 日志文件过大

现象：日志文件占用大量磁盘空间

解决方法：


配置日志滚动策略，限制单个日志文件大小：

<RollingFile name="RollingFile" fileName="logs/smf.txt" 
            filePattern="logs/smf-%d{yyyy-MM-dd}-%i.txt.gz">
   <Policies>
       <SizeBasedTriggeringPolicy size="100 MB"/>
       <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
   </Policies>
   <DefaultRolloverStrategy max="10"/>
</RollingFile>


清理历史日志文件：

# Linux/macOS
find logs/ -name "smf-*.txt.gz" -mtime +30 -delete


2. 日志级别配置不合理

解决方法：


调整日志级别配置，生产环境建议使用INFO级别：

<Logger name="com.neotel.smfcore" level="INFO" additivity="false">


或通过Spring Boot Actuator动态调整日志级别：

curl -X POST "http://localhost:8080/smf-core/actuator/loggers/com.neotel.smfcore" \
-H "Content-Type: application/json" \
-d '{"configuredLevel": "INFO"}'


错误码对照表


错误码
描述
可能原因


200
成功
操作正常完成


400
请求参数错误
请求参数格式不正确或缺少必要参数


401
未授权
Token缺失或已过期


403
权限不足
用户无操作权限


404
资源不存在
请求的资源不存在


500
服务器内部错误
服务器处理请求时发生异常


1001
用户不存在
登录时用户名不存在


1002
密码错误
登录密码不正确


2001
物料不存在
操作的物料不存在


2002
物料编码重复
添加物料时编码已存在


3001
库存不足
出库操作时库存不足


3002
库位不存在
指定的库位不存在


4001
订单不存在
操作的订单不存在


4002
订单状态错误
订单状态不允许当前操作


5001
AGV连接失败
AGV设备连接异常


5002
数据库操作失败
数据库连接或操作错误


日志分析技巧


1. 关键日志搜索

# Linux/macOS

# 搜索ERROR级别日志
grep "ERROR" logs/smf.txt

# 搜索特定时间范围的日志
grep "2024-05-15 10:" logs/smf.txt

# 搜索特定模块的日志
grep "com.neotel.smfcore.core.order" logs/smf.txt

# 搜索异常栈信息
grep -A 20 "Exception" logs/smf.txt


2. 分析系统启动日志

# 查找启动失败原因
grep -i "fail\|error\|exception" logs/smf.txt | head -n 50


3. 监控实时日志

# Linux/macOS
tail -f logs/smf.txt

# 过滤ERROR日志实时查看
tail -f logs/smf.txt | grep "ERROR"


系统诊断工具


1. Spring Boot Actuator端点

SMF Core提供了多个内置诊断端点：


健康检查: http://localhost:8080/smf-core/actuator/health


环境信息: http://localhost:8080/smf-core/actuator/env


配置属性: http://localhost:8080/smf-core/actuator/configprops


日志配置: http://localhost:8080/smf-core/actuator/loggers


线程信息: http://localhost:8080/smf-core/actuator/threaddump


2. 系统监控接口

# 查询系统状态
curl http://localhost:8080/smf-core/api/v1/system/status

# 查询连接池状态
curl http://localhost:8080/smf-core/api/v1/system/connection-pool


数据库排查


1. 数据库连接状态检查

-- 查看当前连接数
SHOW STATUS LIKE 'Threads_connected';

-- 查看最大连接数
SHOW VARIABLES LIKE 'max_connections';

-- 查看连接详情
SHOW PROCESSLIST;


2. 慢查询分析

-- 开启慢查询日志
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 1;  -- 1秒以上的查询记录为慢查询

-- 查看慢查询日志路径
SHOW VARIABLES LIKE 'slow_query_log_file';


3. 表空间使用情况

-- 查看数据库表大小
SELECT table_schema AS '数据库',
       table_name AS '表名',
       round(((data_length + index_length) / 1024 / 1024), 2) AS '表大小(MB)'
FROM information_schema.TABLES
WHERE table_schema = 'smf_core'
ORDER BY (data_length + index_length) DESC;


Docker部署问题排查


1. 容器无法启动

# 查看容器日志
docker logs smf-core

# 查看容器状态
docker ps -a | grep smf-core


2. 容器间网络连接问题

# 查看容器网络配置
docker network inspect bridge

# 测试容器间连接
docker exec -it smf-core ping mysql


3. 卷挂载问题

# 检查卷挂载状态
docker inspect smf-core | grep -A 10 "Mounts"

# 检查权限
ls -la /opt/smf/config/


备份与恢复指南


数据丢失情况处理


尝试从备份恢复：

# 恢复MySQL数据库
mysql -u smf_user -p smf_core < backup_20240101.sql


检查数据库日志，尝试恢复事务日志
联系技术支持寻求帮助


联系支持

如果遇到无法解决的问题，请收集以下信息后联系技术支持：


系统版本信息
问题复现步骤
错误日志文件
相关配置文件
服务器环境信息


最佳实践


定期备份数据，防止数据丢失

定期检查日志，及时发现和解决问题

监控系统资源，避免资源耗尽

保持系统更新，获取最新补丁和功能

记录问题处理过程，形成知识库

定期进行压力测试，确保系统稳定性