跳到主要内容

常见问题诊断

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论

简介​

本指南面向 yudao-cloud 项目的运维与开发人员，聚焦启动失败、连接超时、内存溢出（OOM）、服务启动顺序等常见问题，提供系统化的诊断步骤、日志分析示例与修复建议。文档结合项目实际配置与启动脚本，帮助快速定位并解决问题。

项目结构​

yudao-cloud 采用微服务架构，核心由网关服务与多个业务模块组成。各模块通过 Nacos 注册/配置中心、Redis 缓存、MySQL 与 TDengine 等中间件协同工作。默认端口分布在 48080~48097 区间，便于本地开发与调试。

Mermaid Diagram Code:

graph TB
subgraph "网关层"
GATEWAY[yudao-gateway<br/>端口: 48080]
end
subgraph "核心业务"
SYSTEM[yudao-module-system<br/>端口: 48081]
INFRA[yudao-module-infra<br/>端口: 48082]
end
subgraph "IoT 业务"
DEVICE[yudao-module-device<br/>端口: 48091]
LAUNCHER[yudao-module-launcher<br/>端口: 48097]
BLACKLIST[yudao-module-blacklist<br/>端口: 48096]
TASK[yudao-module-task<br/>端口: 48090+]
REPORT[yudao-module-report<br/>端口: 48088+]
RULE[yudao-module-rule<br/>端口: 48089+]
end
subgraph "中间件"
NACOS[Nacos 2.x]
REDIS[Redis 5.0+]
MYSQL[MySQL 8.0+]
TDENGINE[TDengine]
KAFKA[Kafka]
end
GATEWAY --> SYSTEM
GATEWAY --> INFRA
GATEWAY --> DEVICE
GATEWAY --> LAUNCHER
GATEWAY --> BLACKLIST
GATEWAY --> TASK
GATEWAY --> REPORT
GATEWAY --> RULE
SYSTEM -.-> NACOS
INFRA -.-> NACOS
DEVICE -.-> TDENGINE
TASK -.-> TDENGINE
BLACKLIST -.-> KAFKA
GATEWAY -.-> REDIS

图表来源

章节来源

核心组件​

  • 网关服务：统一入口、路由、鉴权与灰度发布，端口 48080。
  • 核心业务模块：系统管理（48081）、基础设施（48082）。
  • IoT 业务模块：设备管理、Launcher 运营、黑名单、任务与 OTA、报表、规则引擎等。
  • 中间件：Nacos（注册/配置）、Redis（缓存/消息）、MySQL（业务库）、TDengine（时序/日志）、Kafka（异步解耦）。

章节来源

架构总览​

系统采用 Spring Cloud Alibaba 微服务架构，网关统一接入，服务通过 Nacos 注册与配置，Redis 提供缓存与消息能力，MySQL 与 TDengine 分治 OLTP 与 OLAP 数据，Kafka 用于日志上报与事件解耦。

Mermaid Diagram Code:

graph TB
CLIENT[客户端/设备] --> GW[yudao-gateway]
GW --> SVC_SYSTEM[yudao-system]
GW --> SVC_INFRA[yudao-infra]
GW --> SVC_DEVICE[yudao-device]
GW --> SVC_LAUNCHER[yudao-launcher]
GW --> SVC_BLACKLIST[yudao-blacklist]
GW --> SVC_TASK[yudao-task]
GW --> SVC_REPORT[yudao-report]
GW --> SVC_RULE[yudao-rule]
NACOS[Nacos 2.x] -.-> GW
NACOS -.-> SVC_SYSTEM
NACOS -.-> SVC_INFRA
REDIS[Redis 5.0+] -.-> GW
MYSQL[MySQL 8.0+] -.-> SVC_SYSTEM
TDENGINE[TDengine] -.-> SVC_DEVICE
TDENGINE -.-> SVC_TASK
KAFKA[Kafka] -.-> SVC_BLACKLIST

图表来源

章节来源

详细组件分析​

启动顺序与健康检查​

  • 网关优先启动，随后依次启动系统、基础设施、报表、工作流、支付、微信公众号等模块。
  • 基础设施模块提供健康检查（HTTP 48082），系统模块提供健康检查（HTTP 48081）。
  • Docker Compose 使用 host 网络模式，便于服务间通信与端口暴露。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as 开发者
participant Compose as Docker Compose
participant GW as yudao-gateway
participant SYS as yudao-system
participant INF as yudao-infra
Dev->>Compose : 启动
Compose->>GW : 启动(端口 48080)
Compose->>SYS : 启动(端口 48081)
Compose->>INF : 启动(端口 48082)
INF-->>Compose : 健康检查成功
SYS-->>Compose : 健康检查成功
Compose-->>Dev : 服务就绪

图表来源

章节来源

端口冲突排查​

  • 端口范围：网关 48080、系统 48081、基础设施 48082、设备 48091、黑名单 48096、Launcher 48097。
  • 排查步骤：
    1. 检查宿主机端口占用：使用 netstat/lsof/ps 查找 48080/48081/48082 等进程。
    2. 修改 application.yaml 中 server.port 或使用 JVM 参数 -Dserver.port=XXXX。
    3. 若使用 Docker，调整 -p 映射或容器网络模式。

章节来源

Nacos 注册/配置中心连接问题​

  • 网关与各模块均配置 Nacos 地址、命名空间与认证信息。
  • 常见问题：地址不可达、命名空间不一致、凭据错误、配置导入失败。
  • 排查步骤：
    1. 确认 Nacos 服务可达（telnet 8848）。
    2. 校验命名空间与分组配置一致。
    3. 检查 application-common.yaml 与 datasource.yaml 是否成功拉取。
    4. 查看 Banner 输出的文档地址，确认配置加载顺序。

Mermaid Diagram Code:

flowchart TD
START([开始]) --> CHECK_ADDR["检查 Nacos 地址连通性"]
CHECK_ADDR --> ADDR_OK{"地址可达？"}
ADDR_OK --> |否| FIX_ADDR["修正 server-addr 或网络策略"]
ADDR_OK --> |是| CHECK_NS["核对命名空间与分组"]
CHECK_NS --> NS_OK{"命名空间一致？"}
NS_OK --> |否| FIX_NS["统一命名空间与分组"]
NS_OK --> |是| LOAD_CFG["验证配置文件拉取"]
LOAD_CFG --> CFG_OK{"配置加载成功？"}
CFG_OK --> |否| FIX_CFG["检查配置内容与权限"]
CFG_OK --> |是| END([结束])

图表来源

章节来源

数据库连接问题（MySQL/多数据源）​

  • 数据源配置位于 datasource.yaml，包含 Druid 监控与连接池参数。
  • 多数据源（dynamic）支持主从/影子库切换，需确保 URL、用户名、密码正确。
  • 排查步骤：
    1. 使用 JDBC 工具验证 URL/凭据。
    2. 检查 MySQL 服务状态与防火墙。
    3. 核对多数据源 active-suffix 切换（如影子库）。
    4. 关注慢 SQL 与连接池耗尽问题。

章节来源

Redis 连接与版本要求​

  • Redis 作为缓存与消息中间件，版本需 ≥ 5.0。
  • 框架提供 Redis 版本校验与自定义过期时间的缓存管理器。
  • 排查步骤：
    1. 确认 Redis 服务可达与版本满足要求。
    2. 检查连接池配置（最大连接、等待超时）。
    3. 关注缓存键过期策略与 TTL 设置。

章节来源

Kafka 连接问题​

  • Kafka 用于黑名单回调等异步事件。
  • 排查步骤：
    1. 确认 Kafka 服务可达与主题存在。
    2. 检查生产者/消费者配置（acks、重试、序列化）。
    3. 关注消费者组与分区分配。

章节来源

启动失败的常见原因与修复​

  • 端口冲突：修改 server.port 或容器映射。
  • 依赖缺失：确认 Nacos/Redis/MySQL/TDengine/Kafka 服务可用。
  • 配置错误：核对 Nacos 命名空间、分组与配置文件拉取。
  • 启动顺序：先启动网关与基础设施，再启动业务模块。
  • 端口占用：使用 lsof/ps/netstat 定位并释放。

章节来源

依赖分析​

  • 模块间依赖：网关 → 核心模块 → 业务模块。
  • 外部依赖：Nacos（注册/配置）、Redis（缓存/消息）、MySQL（业务）、TDengine（时序）、Kafka（消息）。
  • 启动依赖：基础设施模块提供健康检查，确保系统模块可正常注册。

Mermaid Diagram Code:

graph LR
GW["yudao-gateway"] --> SYS["yudao-system"]
GW --> INF["yudao-infra"]
GW --> DEV["yudao-device"]
GW --> LCH["yudao-launcher"]
GW --> BLK["yudao-blacklist"]
GW --> TSK["yudao-task"]
GW --> RPT["yudao-report"]
GW --> RUL["yudao-rule"]
NACOS["Nacos"] -.-> GW
NACOS -.-> SYS
NACOS -.-> INF
REDIS["Redis"] -.-> GW
MYSQL["MySQL"] -.-> SYS
TDENGINE["TDengine"] -.-> DEV
TDENGINE -.-> TSK
KAFKA["Kafka"] -.-> BLK

图表来源

章节来源

性能考虑​

  • 连接池与超时：合理设置 Druid 连接池参数（初始/最小/最大连接、最大等待、空闲检测）。
  • 缓存策略：使用自定义 TTL 的 Redis 缓存管理器，避免缓存穿透与击穿。
  • 监控与可观测性：启用 SkyWalking 与 Prometheus，关注慢 SQL 与热点接口。
  • 日志滚动：容器日志使用 json-file 并限制单文件大小与历史数量。

章节来源

故障排查指南​

启动失败排查​

  • 现象：服务启动后立即退出或卡住。
  • 步骤：
    1. 查看 Banner 输出（启动成功后打印文档地址），确认配置加载顺序。
    2. 检查 Nacos 配置拉取日志与命名空间一致性。
    3. 核对端口占用与容器映射。
    4. 关注健康检查失败（基础设施/系统模块）。

章节来源

连接超时问题排查​

  • 数据库连接超时：
    1. 检查 datasource.yaml 中 URL/凭据与 MySQL 服务状态。
    2. 调整 Druid 最大等待时间与连接池上限。
  • Redis 连接超时：
    1. 确认 Redis 版本 ≥ 5.0。
    2. 检查连接池参数与网络策略。
  • Nacos 连接超时：
    1. 校验 server-addr 与命名空间。
    2. 检查网络连通性与防火墙。

章节来源

内存溢出（OOM）诊断与修复​

  • 现象：服务频繁 Full GC、堆内存不足、容器被 OOM Killer 终止。
  • 诊断步骤：
    1. 查看容器日志滚动与大小限制（json-file + max-size/max-file）。
    2. 检查 JVM 参数（堆大小、GC 策略）与容器内存限制。
    3. 关注大对象与集合（如 CircularFifoQueue）内存占用。
  • 修复建议：
    1. 调整容器内存限制与 JVM 堆参数。
    2. 优化缓存与集合容量，避免无限增长。
    3. 启用 GC 日志与内存分析工具（Arthas/Heap Dump）。

章节来源

服务启动顺序问题​

  • 现象：业务模块启动早于基础设施，导致注册失败或配置拉取失败。
  • 修复：
    1. 使用 Docker Compose 的 depends_on 与健康检查。
    2. 确保网关先启动，再启动系统/基础设施。
    3. 核对各模块的健康检查端口与路径。

章节来源

错误日志分析示例​

  • 全局异常处理：
    • 未导入表结构时，返回 NOT_IMPLEMENTED 并提示对应模块的开启文档。
    • 默认异常兜底返回 INTERNAL_SERVER_ERROR，并异步记录错误日志。
  • 排查要点：
    1. 关注异常日志中的 traceId，串联链路日志。
    2. 检查请求 URL、参数与用户信息。
    3. 结合 Banner 输出的文档地址，定位模块启用与配置问题。

Mermaid Diagram Code:

sequenceDiagram
participant Client as 客户端
participant Handler as GlobalExceptionHandler
participant Log as 错误日志API
Client->>Handler : 发起请求
Handler->>Handler : 捕获异常
alt 表未导入
Handler-->>Client : 返回 NOT_IMPLEMENTED + 文档指引
else 默认异常
Handler->>Log : 异步记录错误日志(含traceId/URL/参数)
Handler-->>Client : 返回 INTERNAL_SERVER_ERROR
end

图表来源

章节来源

结论​

通过梳理 yudao-cloud 的启动流程、配置加载与依赖关系，可将常见问题归纳为：端口冲突、依赖缺失、配置错误、连接超时与启动顺序不当。结合本文提供的诊断步骤、日志分析与修复建议，可快速定位并解决启动与运行中的问题。建议在生产环境进一步完善健康检查、日志滚动与监控告警，保障系统稳定运行。

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答