RK3588 开发实践-联调诊断指南

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# 期望84xA76 4xA55# 3. 确认内存free-h# 期望总内存 4GB/8GB可用内存 1GB# 4. 确认磁盘df-h/# 期望可用空间 500MB3.2 NPU 驱动与状态RK3588 的 NPU 是 AI 推理的核心NPU 不正常会导致所有算法任务失败。# 1. 确认 NPU 驱动是否加载ls-l/dev/dri/renderD*# 期望/dev/dri/renderD128 存在NPU 设备节点# 2. 确认 NPU 内核模块lsmod|greprknpu# 期望rknpu 模块已加载# 3. 确认 RKNN 运行时库ldd backend/bin/yw_algo_server|greprknn# 期望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 硬解状态MPPMedia Process Platform是 RK3588 的视频硬解模块MPP 不正常会导致视频解码走软解CPU 占用飙升。# 1. 确认 MPP 设备节点ls-l/dev/mpp_service# 期望设备节点存在# 2. 确认 MPP 库ldd backend/bin/yw_core|grepmpp# 期望librockchip_mpp.so 能找到# 3. 硬解 vs 软解判断grep-impp\|hardware decode\|software decodelogs/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 端口连通性timeout2bash-cecho /dev/tcp/192.168.1.32/8554echo端口开放||echo端口不通# 期望端口开放# 2. 用 ffprobe 测试 RTSP 流ffprobe-rtsp_transporttcp-timeout5000000rtsp://192.168.1.32:8554/stream121|head-20# 期望能看到视频流信息分辨率、编码格式、帧率# 3. 查看设备上的 RTSP 拉流日志grep-ERTSP|拉流|打开失败|连接失败|重连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-Edecode|fps|帧率|droplogs/yw_core_*.log|tail-10# 2. 查看 CPU 占用硬解正常时 CPU 应该较低top-b-n1|grepyw_# 期望yw_core CPU 占用 50%8 路 1080P 硬解时# 如果 CPU 占用 80%可能是走了软解五、L4-L5应用服务与通信层诊断5.1 进程状态# 1. 确认两个进程都在运行psaux|grep-Eyw_core|yw_algo_server|grep-vgrep# 期望两个进程都存在且运行时间 0# 2. 确认进程没有频繁重启ps-opid,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-E50051|50052# 期望50051core 管理面和 50052algo 元数据都在监听# 2. 确认 UDS 套接字ls-l/tmp/yw_algo_fd.sock# 期望文件存在类型为 socket# 3. 测试 gRPC 连通性grpcurl-plaintext127.0.0.1:50051 list# 期望能列出 core 的 gRPC 服务5.3 进程间通信诊断两进程之间的通信是边缘 AI 系统的核心纽带通信不正常会导致进程都在但不工作。# 1. 查看 core 连接 algo 的日志grep-Ealgo|推理引擎|UDS|连接|重连|断开logs/yw_core_*.log|tail-20# 2. 查看 algo 接收请求的日志grep-Einfer|推理|request|fd|dmabuflogs/yw_algo_*.log|tail-20# 3. 确认 UDS 零拷贝是否工作grep-Ezero.copy|SCM_RIGHTS|dmabuf|fd.passlogs/yw_algo_*.log|tail-10# 期望有 fd 传递成功的日志没有 fd transfer failed 或 fallback to memcpy常见问题UDS 套接字不存在 → algo 进程未启动或启动失败需要先排查 algogRPC 能连但 UDS 传 fd 失败 → 可能是权限问题或 fd 传递逻辑 bug需要查看 algo 日志core 日志显示 “algo timeout” → algo 推理太慢或卡死需要排查 NPU 状态和模型加载六、L6-L7网络与平台层诊断6.1 网络连通性# 1. 确认设备能上网ping-c38.8.8.8# 期望能 ping 通延迟 100ms# 2. 确认 DNS 正常nslookupplatform.yuewell.com# 期望能解析到 IP 地址# 3. 确认平台端口连通timeout2bash-cecho /dev/tcp/platform.yuewell.com/8080echo平台端口开放||echo平台端口不通6.2 平台连接状态# 1. 查看平台连接日志grep-Eplatform|平台|websocket|ws://|心跳|上线|离线|重连logs/yw_core_*.log|tail-20# 2. 确认设备是否在线# 在平台管理界面查看设备状态或调用平台 API 查询常见问题设备能上网但平台连不上 → 平台地址/端口错误、防火墙拦截、鉴权失败平台连接频繁断连 → 网络不稳定、心跳超时设置过短、平台侧负载过高设备显示在线但数据不上报 → 任务配置问题、算法不工作、数据推送逻辑异常七、端到端打靶测试用已知视频验证全链路分层诊断能确认每一层是否正常但有时候每一层都正常加起来却整体不工作——这时候需要端到端打靶测试。7.1 打靶测试的原理打靶测试的核心思想是用一个已知的、包含明确目标的视频样本输入到系统中验证从拉流→解码→推理→事件融合→报警推送的全链路是否正常。如果打靶视频里有一个明确的人员入侵事件系统应该在预期的时间内产生一条人员入侵报警。如果没有产生说明全链路中某一环有问题。7.2 打靶测试的步骤# 1. 准备打靶视频包含明确目标的 MP4 文件ls-ltest_videos/person_intrusion.mp4# 期望文件存在分辨率 1080P时长 10-30 秒# 2. 用 MediaMTX 或 ffmpeg 将视频推成 RTSP 流ffmpeg-re-stream_loop-1-itest_videos/person_intrusion.mp4-ccopy-frtsp 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支持硬件/算法快速二次开发提供从算法、硬件到产线实机部署的全栈交付。