环境与启动

1. 项目导入后编译报错、出现各种诡异问题

代码存放路径严禁含有中文、空格、特殊字符。克隆仓库前先确认目标目录路径纯净，这是大量"莫名其妙编译失败"的根因。

详见：项目导入

2. 单体版 worker-server 启动报 serverAddress can't be null

powerjob.worker.enabled 为 true 但没有启动 PowerJob 调度中心。不需要测定时任务时直接设为 false；不要用 allow-lazy-connect-server 代替开关，那只是延迟报错。

详见：单体版启动

3. 微服务版启动报 config dataId not exist / 拉取配置为空

Nacos 上缺少对应 dataId，按序核对三点：

1. 命名空间填的是 ID 而不是名称；
2. group 为 DEFAULT_GROUP；
3. dataId {服务名}.yml 必须与 spring.application.name（即 Maven artifactId，如 console-server）完全一致。

详见：微服务版启动

4. 服务启动报「连接不上 Nacos」

• 检查启动日志中 mdp.nacos.* 的实际生效值：NACOS_IP/NACOS_PORT 环境变量与 config-{env}.properties 编译期值是否指向同一套；
• Nacos 开启鉴权时必须提供 NACOS_USERNAME/NACOS_PASSWORD；
• 最后确认网络连通性。

详见：微服务版启动、后端配置-微服务版

5. 微服务版网关返回 503

• 目标服务没有注册到与网关同一个命名空间与 group；
• 或路由前缀写错：必须是 /api/{workbench|console|open}/**。

详见：微服务版启动

6. 开放接口调用报「找不到服务提供者」/ 时通时不通

两个高频根因：

• 注册中心不一致：api-server 固定使用 Nacos，而 sop-gateway-server 以 dev profile 打包时连的是 ZooKeeper，需按启动文档换依赖并修改 dubbo.registry.address；
• worker-server 漏配 dubbo.enabled: false：导致 worker-server 与 api-server 同时成为 Dubbo provider，请求被路由到没有接口实现的 worker-server 上，表现为间歇性失败。

详见：单体版启动、微服务版启动

7. 接口配好了却调不通、缓存像没生效

检查三个服务的 spring.data.redis.database 是否一致——database 不同等于用了不同的 Redis 库，缓存与 token 互相看不见。

详见：单体版启动

8. 测试/生产环境误用了内置 ZooKeeper

单体版 dev 环境内置的 ZooKeeper 仅供演示。部署到测试/生产时切换 Maven profile 到 test/prod 重新编译，注册中心会自动换成 Nacos，地址由 @config.nacos.*@ 编译期注入。

详见：单体版启动、编译期配置filters

9. 任务在 PowerJob 上创建了但一直不执行

依次检查：是否已在 PowerJob 控制台注册应用 MDP、worker-server 是否启动且在线（worker 列表可见）、server-address 端口是否为 17700。

详见：单体版启动