常见问题
按频率排序的排查手册。遇到问题先查这里，覆盖 90% 的高频场景。
一、启动类
Q1：MySQL 连接失败，报 Public Key Retrieval is not allowed
原因：MySQL 8 默认关闭了 RSA 公钥检索。
解决：在 JDBC URL 加 allowPublicKeyRetrieval=true：
spring.datasource.dynamic.datasource.master.url:
jdbc:mysql://localhost:3307/mingshang?useSSL=false&allowPublicKeyRetrieval=trueQ2：TDengine JDBC 连接超时 Communications link failure
排查：
# 1. 确认 TDengine 容器运行
docker ps | grep tdengine
# 2. 确认端口可达
curl -u root:taosdata -d "show databases" http://localhost:6042/rest/sql
# 3. 如果 JDBC 不可用，改用 REST Connector（6042 端口）
ms.tdengine.port: 6042 # REST Connector
# 原生驱动端口 6030 不可用时的备选Q3：后端启动报 @ComponentScan 没扫到 Controller
原因：Spring Boot 默认只扫启动类所在包。
解决：启动类加显式扫描：
@SpringBootApplication
@ComponentScan("com.mingshang") // ← 必须加
public class MingShangApplication { ... }Q4：Maven 编译报 package com.mingshang.xxx does not exist
原因：新增子模块未在父 POM 声明坐标。
解决：三处同步登记：
| 位置 | 改什么 |
|---|---|
backend/pom.xml | dependencyManagement 加 ms-xxx 坐标 |
ms-server/pom.xml | modules 加 ms-xxx |
ms-admin/pom.xml | dependencies 加 ms-xxx |
然后 mvn clean install -DskipTests 重新构建。
Q5：MS 保留字冲突 SQLSyntaxErrorException: You have an error in your SQL syntax
原因：MySQL 8 read_write、condition 是保留字。
解决：DDL 中用反引号包裹：
CREATE TABLE ms_alert (
`condition` VARCHAR(255),
`read_write` TINYINT
);二、设备接入类
Q6：MQTT 设备 CONNACK rc=5（认证拒绝）
排查：
# 1. 确认设备存在
mysql -uroot -p -P 3307 -e "SELECT id, serial, auth_code FROM mingshang.ms_device WHERE serial='ESP32-001'"
# 2. 确认 authCode 和设备侧密码一致
# 3. 确认 EMQX Webhook 端点可达
curl -X POST http://localhost:8080/api/emqx/auth \
-H "Content-Type: application/json" \
-d '{"username":"ESP32-001","password":"a1b2c3..."}'
# → {"result":"allow"}Q7：设备上报后 Redis 无数据
排查：
# 1. 确认 Redis 端口
redis-cli -p 6380 ping
# 2. 查 key 是否存在
redis-cli -p 6380 KEYS "ms:tsl:*"
# 3. 查 TouchOnline 是否执行（在线状态）
mysql -uroot -p -P 3307 -e "SELECT online FROM mingshang.ms_device WHERE serial='ESP32-001'"Q8：CoAP 4.01 Unauthorized
原因：CoAP 认证走主库 + tenant_* 全局检索，如果设备在租户库里，主库查不到。
排查：
# 查所有租户库的设备
mysql -uroot -p -P 3307 -e "SELECT schema_name FROM information_schema.schemata WHERE schema_name LIKE 'ms_tenant%'"
mysql -uroot -p -P 3307 ms_tenant_99 -e "SELECT serial, auth_code FROM ms_device WHERE serial='ISO99-SERIAL'"Q9：HTTP Digest 401 重放攻击
原因：Digest nonce 是一次性的，TTL 5 分钟。同 nonce 第二次使用会被拒绝。
解决：每个请求必须从 401 challenge 拿新 nonce。curl --digest 自动处理，手写客户端需注意。
三、前端类
Q10：前端调后端报 CORS Access-Control-Allow-Origin 缺失
解决：SaTokenConfig 已配置通配 CORS。如果是自定义域名，检查 allowedOriginPatterns：
.allowedOriginPatterns("*") // 开发用
// 生产建议限制具体域名Q11：前端登出后仍能访问接口
原因：Sa-Token 过期时间设置。
排查：
sa-token:
timeout: 86400 # Token 有效期（秒）
is-concurrent: true # 同一账号多端同时在线如果需要强制单点登录，设 is-concurrent: false。
四、部署类
Q12：Docker Hub 镜像拉取失败
解决：配置国内加速器。Docker Desktop 设置 → Docker Engine：
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://hub-mirror.c.163.com"
]
}Q13：生产环境 MySQL root 密码
操作：
docker exec -it mysql mysql -uroot -p
ALTER USER 'root'@'%' IDENTIFIED BY 'your-strong-password';
FLUSH PRIVILEGES;同时更新 application-prod.yml 和 docker-compose.yml 中的 MYSQL_PASSWORD。
Q14：Windows PowerShell 向 curl.exe 传 JSON 引号被吞
现象：curl.exe -d '{"foo":"bar"}' 变成空 body。
解决：
# 方法 1：用双引号 + 转义
curl.exe -d "{\"foo\":\"bar\"}" http://localhost:8080/api
# 方法 2：用 @file
Set-Content -Body '{"foo":"bar"}' -Path body.json
curl.exe -d @body.json http://localhost:8080/api
# 方法 3：用 Invoke-RestMethod
Invoke-RestMethod -Uri "http://localhost:8080/api" -Method Post -Body '{"foo":"bar"}' -ContentType "application/json"Q15：Cloudflare Pages 创建报错 8000000
原因：新账号需先在控制台激活 Pages 功能。
解决：打开 https://dash.cloudflare.com → Workers & Pages → 创建 → Pages → 直接上传（随便传一个文件），激活后 API 才能创建。
五、开发类
Q16：新增内部模块后 mvn install 报 version missing
原因：父 POM dependencyManagement 漏登记。
解决：三处同步（见 Q4）。
Q17：ms-admin 产物名不是 ms-admin-1.0.0-SNAPSHOT.jar
实际：产物名是 mingshang-admin.jar（finalName 已自定义）。
# 正确启动
java -jar ms-admin/target/mingshang-admin.jarQ18：Git 仓库 not a git repository
原因：项目从未 git init。
解决：
cd mingshang-iot
git init
git add .
git commit -m "init: 项目基线"
git branch -M master
git remote add origin https://gitee.com/zbzcs/mingshang-iot-ce.git
git push -u origin master六、获取帮助
以上问题仍未解决？发邮件至 support@zbidc.com，请提供：
- 版本信息（后端 jar 包名 / 前端 package.json version）
- 环境（Windows / Linux / Docker）
- 完整错误日志（StackTrace）
- 复现步骤