RK3588 边缘 AI 系统联调诊断指南
RK3588 边缘 AI 系统联调诊断指南：从"设备不工作"到"5 分钟定位根因"
越微智能（Yuewell）工业边缘 AI 工程实践系列 · 第 7 篇
关键词：联调诊断、系统自检、端到端打靶、诊断日志、NPU 状态、MPP 硬解、RTSP 拉流
一、为什么需要一套标准化的联调诊断流程
做边缘 AI 设备的团队，几乎都遇到过这样的场景：
客户："设备不工作了，你们赶紧看看。"
工程师："具体是什么不工作？是连不上？还是不报警？还是预览黑屏？"
客户："就是不工作了，你们过来看看吧。"
工程师：（远程登录，花了 2 小时排查，最后发现是摄像头网线松了）
这种"客户说不工作，工程师远程排查半天"的场景，在边缘设备的运维中非常常见。根本原因是：没有一套标准化的联调诊断流程，每次排查都是从零开始，靠工程师的经验和运气。
我们在早期项目中，一次现场排障平均需要 2-4 小时，其中大部分时间花在"确认问题是什么"上。后来我们沉淀了一套标准化的联调诊断流程，把平均排障时间降到了 15 分钟以内。
本文分享这套诊断流程的设计思路和具体方法。
二、诊断的核心原则：分层定位，从外到内
边缘 AI 系统的故障，本质上是一个分层架构的问题。诊断的核心原则是：从外到内，逐层排查，先确认哪一层有问题，再深入该层的具体原因。
┌─────────────────────────────────────────┐
│ L7 平台/客户端层 │ 平台能否连上设备？客户端能否预览？
├─────────────────────────────────────────┤
│ L6 网络层 │ 设备能否上网？DNS 是否正常？
├─────────────────────────────────────────┤
│ L5 应用服务层 │ yw_core / yw_algo_server 进程是否在跑？
├─────────────────────────────────────────┤
│ L4 通信层 │ gRPC 端口是否监听？UDS 套接字是否存在？
├─────────────────────────────────────────┤
│ L3 视频流层 │ RTSP 能否拉流？MPP 硬解是否正常？
├─────────────────────────────────────────┤
│ L2 AI 推理层 │ NPU 是否可用？模型是否加载成功？
├─────────────────────────────────────────┤
│ L1 硬件/驱动层 │ RK3588 设备是否正常？驱动是否加载？
└─────────────────────────────────────────┘
诊断顺序：L7 → L6 → L5 → L4 → L3 → L2 → L1，从最外层的"平台能不能连上"开始，逐层深入到最内层的"硬件驱动是否正常"。
为什么从外到内？因为：
- 外层问题（网络、平台连接）最常见，也最容易确认
- 如果外层就有问题，内层再正常也没用（比如设备断网了，AI 推理再准也传不出去）
- 从外到内排查，可以快速缩小范围，避免一上来就查最复杂的内层
三、L1-L2：硬件与 NPU 状态诊断
3.1 RK3588 设备基本状态
# 1. 确认设备型号和系统
cat /proc/device-tree/model
# 期望：Rockchip RK3588 EVB 或类似
# 2. 确认 CPU 核心
nproc
# 期望：8（4xA76 + 4xA55）
# 3. 确认内存
free -h
# 期望：总内存 4GB/8GB，可用内存 > 1GB
# 4. 确认磁盘
df -h /
# 期望：可用空间 > 500MB
3.2 NPU 驱动与状态
RK3588 的 NPU 是 AI 推理的核心，NPU 不正常会导致所有算法任务失败。
# 1. 确认 NPU 驱动是否加载
ls -l /dev/dri/renderD*
# 期望：/dev/dri/renderD128 存在（NPU 设备节点）
# 2. 确认 NPU 内核模块
lsmod | grep rknpu
# 期望：rknpu 模块已加载
# 3. 确认 RKNN 运行时库
ldd backend/bin/yw_algo_server | grep rknn
# 期望：librknnrt.so 能找到（不是 not found）
# 4. NPU 利用率（推理时）
cat /sys/kernel/debug/rknpu/load
# 期望：推理时有 NPU 负载数据，不是全 0
常见问题：
/dev/dri/renderD128不存在 → NPU 驱动未加载，需要检查内核配置或重新烧录 BSPlibrknnrt.so not found→ RKNN 运行时库缺失，需要从 RKNPU2 SDK 中拷贝- NPU 利用率全 0 → 推理任务没有真正在 NPU 上执行，可能走了 CPU 推理或模型加载失败
3.3 MPP 硬解状态
MPP（Media Process Platform）是 RK3588 的视频硬解模块，MPP 不正常会导致视频解码走软解，CPU 占用飙升。
# 1. 确认 MPP 设备节点
ls -l /dev/mpp_service
# 期望：设备节点存在
# 2. 确认 MPP 库
ldd backend/bin/yw_core | grep mpp
# 期望：librockchip_mpp.so 能找到
# 3. 硬解 vs 软解判断
grep -i 'mpp\|hardware decode\|software decode' logs/yw_core_*.log | tail -10
# 期望：日志显示 MPP 硬解初始化成功，没有 "no_mpp" 或 "fallback to software"
常见问题：
/dev/mpp_service不存在 → MPP 驱动未加载- 日志出现
no_mpp→ MPP 初始化失败，视频解码走软解，CPU 占用会很高 - 客户端预览长期黑屏 → 可能是 MPP 硬解失败，需要排查驱动版本
四、L3：视频流层诊断
4.1 RTSP 拉流诊断
RTSP 拉流是边缘 AI 视觉的"数据源"，拉流不正常会导致所有算法任务没有输入。
# 1. 测试 RTSP 端口连通性
timeout 2 bash -c 'echo >/dev/tcp/192.168.1.32/8554' && echo "端口开放" || echo "端口不通"
# 期望：端口开放
# 2. 用 ffprobe 测试 RTSP 流
ffprobe -rtsp_transport tcp -timeout 5000000 rtsp://192.168.1.32:8554/stream1 2>&1 | head -20
# 期望：能看到视频流信息（分辨率、编码格式、帧率）
# 3. 查看设备上的 RTSP 拉流日志
grep -E 'RTSP|拉流|打开失败|连接失败|重连' logs/yw_core_*.log | tail -20
常见问题：
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 端口不通 | 相机离线 / 网络不通 / IP 变更 | ping 相机 IP，检查网线，确认相机 IP |
| 端口通但 ffprobe 失败 | RTSP 路径错误 / 鉴权失败 / 编码不支持 | 确认 RTSP URL 路径，检查用户名密码，确认相机编码格式 |
| 拉流成功但频繁断连 | 网络不稳定 / 相机码流异常 / 带宽不足 | 检查网络丢包率，降低相机码率，切换 TCP 传输 |
| 拉流日志显示 "Connection refused" | 相机 RTSP 服务未启动 / 端口错误 | 登录相机 Web 界面确认 RTSP 服务状态 |
4.2 视频解码诊断
RTSP 拉流成功后，还需要确认视频解码正常。
# 1. 查看解码帧率
grep -E 'decode|fps|帧率|drop' logs/yw_core_*.log | tail -10
# 2. 查看 CPU 占用（硬解正常时 CPU 应该较低）
top -b -n 1 | grep yw_
# 期望：yw_core CPU 占用 < 50%（8 路 1080P 硬解时）
# 如果 CPU 占用 > 80%，可能是走了软解
五、L4-L5：应用服务与通信层诊断
5.1 进程状态
# 1. 确认两个进程都在运行
ps aux | grep -E 'yw_core|yw_algo_server' | grep -v grep
# 期望：两个进程都存在，且运行时间 > 0
# 2. 确认进程没有频繁重启
ps -o pid,etime,cmd -p $(pgrep yw_core)
# 期望：etime（运行时间）较长，如果只有几分钟，说明进程在频繁重启
# 3. 查看 systemd 状态
systemctl status yw-core yw-algo-server
# 期望：active (running)，没有 failed 状态
5.2 端口与 UDS 套接字
# 1. 确认 gRPC 端口监听
ss -tlnp | grep -E '50051|50052'
# 期望：50051（core 管理面）和 50052（algo 元数据）都在监听
# 2. 确认 UDS 套接字
ls -l /tmp/yw_algo_fd.sock
# 期望：文件存在，类型为 socket
# 3. 测试 gRPC 连通性
grpcurl -plaintext 127.0.0.1:50051 list
# 期望：能列出 core 的 gRPC 服务
5.3 进程间通信诊断
两进程之间的通信是边缘 AI 系统的核心纽带，通信不正常会导致"进程都在但不工作"。
# 1. 查看 core 连接 algo 的日志
grep -E 'algo|推理引擎|UDS|连接|重连|断开' logs/yw_core_*.log | tail -20
# 2. 查看 algo 接收请求的日志
grep -E 'infer|推理|request|fd|dmabuf' logs/yw_algo_*.log | tail -20
# 3. 确认 UDS 零拷贝是否工作
grep -E 'zero.copy|SCM_RIGHTS|dmabuf|fd.pass' logs/yw_algo_*.log | tail -10
# 期望：有 fd 传递成功的日志，没有 "fd transfer failed" 或 "fallback to memcpy"
常见问题：
- UDS 套接字不存在 → algo 进程未启动或启动失败，需要先排查 algo
- gRPC 能连但 UDS 传 fd 失败 → 可能是权限问题或 fd 传递逻辑 bug，需要查看 algo 日志
- core 日志显示 "algo timeout" → algo 推理太慢或卡死，需要排查 NPU 状态和模型加载
六、L6-L7：网络与平台层诊断
6.1 网络连通性
# 1. 确认设备能上网
ping -c 3 8.8.8.8
# 期望：能 ping 通，延迟 < 100ms
# 2. 确认 DNS 正常
nslookup platform.yuewell.com
# 期望：能解析到 IP 地址
# 3. 确认平台端口连通
timeout 2 bash -c 'echo >/dev/tcp/platform.yuewell.com/8080' && echo "平台端口开放" || echo "平台端口不通"
6.2 平台连接状态
# 1. 查看平台连接日志
grep -E 'platform|平台|websocket|ws://|心跳|上线|离线|重连' logs/yw_core_*.log | tail -20
# 2. 确认设备是否在线
# 在平台管理界面查看设备状态，或调用平台 API 查询
常见问题：
- 设备能上网但平台连不上 → 平台地址/端口错误、防火墙拦截、鉴权失败
- 平台连接频繁断连 → 网络不稳定、心跳超时设置过短、平台侧负载过高
- 设备显示在线但数据不上报 → 任务配置问题、算法不工作、数据推送逻辑异常
七、端到端打靶测试：用已知视频验证全链路
分层诊断能确认每一层是否正常，但有时候"每一层都正常"加起来却"整体不工作"——这时候需要端到端打靶测试。
7.1 打靶测试的原理
打靶测试的核心思想是：用一个已知的、包含明确目标的视频样本，输入到系统中，验证从拉流→解码→推理→事件融合→报警推送的全链路是否正常。
如果打靶视频里有一个明确的"人员入侵"事件，系统应该在预期的时间内产生一条"人员入侵"报警。如果没有产生，说明全链路中某一环有问题。
7.2 打靶测试的步骤
# 1. 准备打靶视频（包含明确目标的 MP4 文件）
ls -l test_videos/person_intrusion.mp4
# 期望：文件存在，分辨率 1080P，时长 10-30 秒
# 2. 用 MediaMTX 或 ffmpeg 将视频推成 RTSP 流
ffmpeg -re -stream_loop -1 -i test_videos/person_intrusion.mp4 -c copy -f rtsp rtsp://localhost:8554/test
# 3. 在设备上配置一个相机，RTSP URL 指向打靶流
# 通过管理 API 或配置文件添加相机
# 4. 配置一个"人员入侵"算法任务，ROI 覆盖打靶视频中的目标区域
# 5. 观察报警输出
grep -E '报警|alarm|intrusion|人员入侵' logs/yw_core_*.log | tail -10
# 期望：在目标进入 ROI 后，经过蓄力时间，产生一条人员入侵报警
7.3 打靶测试的诊断价值
打靶测试能快速定位问题在哪一环：
| 打靶结果 | 问题定位 |
|---|---|
| RTSP 拉流失败 | L3 视频流层问题 |
| 拉流成功但推理日志为空 | L4 通信层或 L2 推理层问题 |
| 推理有结果但无报警 | L5 应用层（事件融合/防误报/ROI 配置）问题 |
| 有报警但平台收不到 | L6-L7 网络/平台层问题 |
| 全链路正常，报警如期产生 | 系统正常，问题可能在客户现场的相机/网络/配置 |
八、诊断日志体系：让设备自己"说话"
标准化诊断的基础是完善的日志体系。如果日志不够详细，再标准的诊断流程也无从下手。
8.1 三类日志的分工
| 日志类型 | 文件 | 内容 | 用途 |
|---|---|---|---|
| 业务日志 | yw_core_YYYYMMDD.log |
任务调度、事件融合、报警推送 | 排查业务逻辑问题 |
| 推理日志 | yw_algo_YYYYMMDD.log |
模型加载、推理执行、NPU 状态 | 排查 AI 推理问题 |
| 运维日志 | yw_ops.log |
启动/停止、Preflight、崩溃、重启、OOM、维护锁 | 排查系统运维问题 |
8.2 关键事件的日志规范
每个关键事件都必须有明确的日志输出，包含时间戳、事件类型、关键参数：
[2026-06-08 10:23:15] [INFO] [PlatformClient] 平台心跳超时，开始重连...
[2026-06-08 10:23:15] [WARN] [RTSP] 相机 cam01 拉流断开，开始重连（第 3 次）
[2026-06-08 10:23:16] [ERROR] [AlgoClient] 推理引擎 UDS 连接失败：Connection refused
[2026-06-08 10:23:17] [INFO] [Guardian] Preflight Check: PASS (12/12)
[2026-06-08 10:23:18] [WARN] [Memory] RSS 达到 350MB (warn 阈值 300MB)，触发软降级
[2026-06-08 10:23:18] [ERROR] [System] OOM Killer 杀掉 yw_core 进程，准备自动重启
8.3 日志的可检索性
日志必须是可检索的——通过关键词就能快速定位问题。我们的日志规范要求：
- 每个模块有明确的标签（如
[PlatformClient]、[RTSP]、[AlgoClient]） - 每个事件有明确的级别（INFO/WARN/ERROR/FATAL）
- 错误日志必须包含错误原因和上下文（不能只写 "error"）
- 关键参数必须打印（如相机 ID、任务 ID、算法类型、帧率）
九、越微自研：Yuewell-Diag 联调诊断工具集
以上所有诊断方法，我们沉淀为越微智能内部的 Yuewell-Diag 联调诊断工具集，核心包括：
- 一键健康检查脚本：自动执行 L1-L7 全层诊断，输出健康报告（PASS/WARN/FAIL）
- 端到端打靶框架：内置 10+ 种标准打靶视频，一键启动 RTSP 推流 + 任务配置 + 报警验证
- 日志聚合分析工具：自动分析三类日志，提取异常事件，生成诊断摘要
- NPU/MPP 状态探针：实时监控 NPU 利用率、MPP 硬解状态、内存使用，异常时自动告警
- 网络质量监控：持续检测 ping 延迟、丢包率、DNS 解析时间，网络质量差时自动记录
- 诊断报告生成：一键导出设备状态、日志摘要、诊断结果，便于远程支持和问题归档
这套工具集让我们的现场排障从"靠工程师经验花 2 小时"，变成了"一键诊断 5 分钟出报告"。在多个项目中，客户现场人员甚至可以自己运行诊断脚本，把报告发给我们，我们远程就能定位 80% 的问题。
十、写在最后
边缘 AI 系统的联调诊断，看似是"出了问题再排查"的被动工作，实则是工程化能力的综合体现。一套标准化的诊断流程、完善的日志体系、自动化的诊断工具，能把排障时间从小时级降到分钟级，把"靠专家经验"变成"靠标准流程"。
越微智能在 RK3588 边缘 AI 视觉设备的量产交付中，把这些踩过的坑沉淀成了 Yuewell-Diag 联调诊断工具集，并集成到了我们的工业级边缘 AI 视觉基座（Yuewell Edge Framework）中。我们相信，诊断和运维能力是边缘 AI 产品从"能交付"到"能长期服务"的核心竞争力。
如果你也在做边缘 AI 系统的联调和运维，欢迎交流。
关于越微智能（Yuewell）
上海越微信息技术有限公司是一支专注具身智能与工业 AI 视觉落地的技术团队，以自研 VLA 具身智能、视觉与语言大模型及 RK3588 边缘算力为底座，为工业与服务场景提供从算法、硬件到机器人集成的全栈交付。
我们将边缘 AI 视觉设备的部署、守护、算法集成、防误报、性能调优、故障诊断、远程升级等全链路工程经验，封装为了工业级边缘 AI 视觉基座（Yuewell Edge Framework），支持硬件/算法快速二次开发，提供从算法、硬件到产线实机部署的全栈交付。
浙公网安备 33010602011771号