13 KiB
13 KiB
RK3588 Media Server 部署指南
架构说明
┌─────────────────────────────────────────────────────────────┐
│ RK3588 Device │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Media Server │ │ RK3588 Agent │ │
│ │ (systemd) │◄────│ (systemd) │ │
│ │ │ │ │ │
│ │ - RTSP输出 │ │ - Web管理界面 │ │
│ │ - HLS输出 │ │ - 服务监控 │ │
│ │ - NPU推理 │ │ - 远程配置 │ │
│ └─────────┬───────────┘ └─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ 运行时数据目录 │ │
│ │ /var/lib/rk3588-media-server/ │ │
│ │ ├── hls/ - HLS分片输出 (root) │ │
│ │ ├── logs/ - 应用日志 (orangepi) │ │
│ │ ├── alarms/ - 告警截图 (orangepi) │ │
│ │ └── clips/ - 告警视频片段 (orangepi) │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ /opt/rk3588-media-server/ # 程序文件 │
│ /opt/rk3588-agent/ # Agent程序 │
└─────────────────────────────────────────────────────────────┘
设计特点
- Media Server: 独立的 systemd 服务，高可用（崩溃自动重启）
- Agent: 独立的 systemd 服务，通过
systemctl监控和控制 Media Server - 两者可独立重启: 重启 Agent 不会影响 Media Server
- 运行时数据分离: 程序文件在
/opt/，数据在/var/lib/ - 自动清理: HLS 分片、日志、告警数据自动轮转清理
快速开始
1. 编译
在 RK3588 设备上编译：
cd ~/apps/OrangePi3588Media
# 一键编译（推荐）
./scripts/build.sh
# 或使用完整 cmake 命令
cmake -S . -B build \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTS=OFF \
-DBUILD_SAMPLES=ON \
-DRK3588_ENABLE_FFMPEG=ON \
-DRK3588_ENABLE_MPP=ON \
-DRK3588_ENABLE_RGA=ON \
-DRK3588_ENABLE_ZLMEDIAKIT=ON \
-DRK3588_ENABLE_RKNN=ON \
-DRK_ZLMK_API_LIB_PATH=$PWD/third_party/rknpu2/examples/3rdparty/zlmediakit/aarch64/libmk_api.so \
-DRK_ZLMEDIAKIT_INCLUDE_DIR=$PWD/third_party/rknpu2/examples/3rdparty/zlmediakit/include
cmake --build build -j$(nproc)
# 仅编译 Media Server
./scripts/build.sh -m
# 仅编译 Agent
./scripts/build.sh -a
# Debug 模式编译
./scripts/build.sh -d
# 清理后重新编译
./scripts/build.sh -c
编译脚本选项：
| 选项 | 说明 |
|---|---|
-h, --help |
显示帮助 |
-c, --clean |
清理构建目录后编译 |
-j N |
指定并行编译线程数 |
-m, --media-only |
仅编译 Media Server |
-a, --agent-only |
仅编译 Agent |
-d, --debug |
Debug 模式编译 |
环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
BUILD_TYPE |
Release | 编译类型 |
BUILD_TESTS |
OFF | 是否编译测试 |
BUILD_SAMPLES |
ON | 是否编译示例 |
ENABLE_FFMPEG |
ON | 启用 FFmpeg |
ENABLE_MPP |
ON | 启用 MPP |
ENABLE_RGA |
ON | 启用 RGA |
ENABLE_ZLMEDIAKIT |
ON | 启用 ZLMediaKit |
ENABLE_RKNN |
ON | 启用 RKNN |
2. 部署
cd ~/apps/OrangePi3588Media
sudo ./scripts/deploy.sh install
部署过程会：
- 安装 Media Server 和 Agent 到
/opt/ - 创建运行时数据目录
/var/lib/rk3588-media-server/ - 配置日志轮转和自动清理
- 启动 systemd 服务
3. 查看状态
sudo ./scripts/deploy.sh status
3.1 DDR 固频排障
当出现 CPU/NPU 利用率不高，但 RTSP 输出帧率周期性跌落时，优先检查 DDR devfreq 是否在频繁降频。
项目内置了 DDR 模式切换脚本：
sudo bash ./scripts/ddr_mode.sh status
sudo bash ./scripts/ddr_mode.sh performance
sudo bash ./scripts/ddr_mode.sh restore
也可以从运维入口调用：
sudo ./scripts/ops.sh ddr-status
sudo ./scripts/ops.sh ddr-performance
sudo ./scripts/ops.sh ddr-restore
说明：
performance：保存当前 governor/min/max 后，将 DDR 切到高性能模式restore：恢复到切换前保存的 governor/min/max- 默认节点为
/sys/class/devfreq/dmc
3.2 RTSP 解码推荐
对高位监控、烟雾多、偶发 H.264 参考帧异常的 RTSP 源，优先使用 FFmpeg CPU decode + MPP encode 组合。
推荐配置：
./build/media-server -c configs/person_shoe_two_stage_recommended.json
如需直接启用“缺鞋”判定和按人冷却告警，可使用：
./build/media-server -c configs/person_shoe_two_stage_recommended_alarm.json
说明：
- 输入端：
use_ffmpeg: true、use_mpp: false - 输出端：仍然使用
MPP编码 - 适用场景：源流在 VLC 中播放正常，但项目内
ffmpeg demux + mpp decode会出现固定画面卡顿
排障建议：
- 若
configs/sample_rtsp_publish_only.json会卡，但 VLC 直接拉原始 RTSP 源不卡，优先切到 FFmpeg 解码版验证 - 若 FFmpeg 解码版不卡，则说明问题主要在 MPP 解码兼容性，而不是 AI 链路或发布链路
4. 卸载
sudo ./scripts/deploy.sh uninstall
完整命令参考
部署脚本命令
| 命令 | 说明 |
|---|---|
sudo ./deploy.sh install |
安装/部署服务 |
sudo ./deploy.sh upgrade |
升级服务（保留配置和数据） |
sudo ./deploy.sh status |
查看详细运行状态 |
sudo ./deploy.sh logs |
查看实时日志 |
sudo ./deploy.sh clean-hls [天数] |
清理 HLS 旧分片 |
sudo ./deploy.sh uninstall |
卸载服务 |
Media Server 服务管理
# 启动/停止/重启
sudo systemctl start media-server
sudo systemctl stop media-server
sudo systemctl restart media-server
# 查看状态
sudo systemctl status media-server
# 查看日志 (systemd)
sudo journalctl -u media-server -f
sudo journalctl -u media-server --since "1 hour ago"
# 直接查看日志文件 (无需 sudo)
ls -la /var/lib/rk3588-media-server/logs/
cat /var/lib/rk3588-media-server/logs/media-server.log
Agent 服务管理
# 启动/停止/重启（不影响 Media Server）
sudo systemctl start rk3588-agent
sudo systemctl stop rk3588-agent
sudo systemctl restart rk3588-agent
# 查看状态
sudo systemctl status rk3588-agent
# 查看日志 (systemd)
sudo journalctl -u rk3588-agent -f
# Agent 日志文件位置
cat /var/lib/rk3588-agent/agent.log
目录结构
程序目录 (/opt/)
/opt/rk3588-media-server/
├── bin/
│ ├── media-server # 主程序
│ ├── cleanup-hls.sh # HLS清理脚本
│ └── plugins/ # 插件目录
│ ├── libinput_rtsp.so
│ ├── libai_yolo.so
│ ├── libosd.so
│ ├── libtracker.so
│ └── ...
├── lib/ # 依赖库
├── etc/
│ └── media-server.json # 配置文件
├── models/ # AI模型文件
│ ├── best-640.rknn
│ ├── yolov5s-640-640.rknn
│ └── ...
└── web/ # Web静态文件
├── index.html
├── graph.html
├── hls_player.html # HLS播放器
└── hls/ # HLS输出(符号链接)
/opt/rk3588-agent/
├── rk3588-agent # Agent程序
└── agent.config.json # Agent配置
运行时数据目录 (/var/lib/)
/var/lib/rk3588-media-server/
├── hls/ # HLS直播分片 (root:root, 755)
│ ├── cam1/
│ │ ├── index.m3u8
│ │ ├── index0.ts
│ │ └── ...
│ ├── cam2/
│ └── ...
├── logs/ # 应用日志 (orangepi:orangepi, 755)
├── alarms/ # 告警截图 (orangepi:orangepi, 755)
└── clips/ # 告警视频片段 (orangepi:orangepi, 755)
/var/lib/rk3588-agent/
└── device_id # 设备唯一标识 (orangepi:orangepi)
权限说明：
logs/,alarms/,clips/目录归属于orangepi:orangepi，方便默认用户查看和管理hls/目录归属于root:root，但权限 755 允许 orangepi 组读取- Agent 相关目录归属于
orangepi:orangepi
配置修改
编辑配置文件：
sudo nano /opt/rk3588-media-server/etc/media-server.json
修改后重启服务：
sudo systemctl restart media-server
数据管理
HLS 分片清理
HLS 分片自动清理策略：
- 默认保留: 3天
- 自动执行: 每天凌晨3点
- 手动执行:
sudo /opt/rk3588-media-server/bin/cleanup-hls.sh [天数]
日志轮转
日志自动轮转策略：
- 保留周期: 7天
- 压缩: 启用
- 位置:
/var/lib/rk3588-media-server/logs/ - 文件归属:
orangepi:orangepi（方便默认用户查看）
告警数据清理
自动清理策略（通过 cron）：
- 告警视频 (clips): 保留30天
- 告警图片 (alarms): 保留90天
查看当前存储使用：
# 使用部署脚本查看（推荐）
sudo ./scripts/deploy.sh status
# 或直接查看目录大小
du -sh /var/lib/rk3588-media-server/*/
升级
升级步骤（保留配置和数据）：
cd ~/apps/OrangePi3588Media
# 1. 拉取最新代码
git pull
# 2. 重新编译（清理后编译确保干净）
./scripts/build.sh -c
# 3. 执行升级
sudo ./scripts/deploy.sh upgrade
Web 管理界面
Agent 管理界面
http://<设备IP>:9100
功能：
- 查看 Media Server 运行状态
- 启动/停止/重启 Media Server
- 查看配置信息
HLS 播放器
http://<设备IP>:9000/hls_player.html
功能：
- 5 路视频同时播放
- 自适应布局
- 实时状态显示
故障排查
服务无法启动
# 查看详细错误
sudo journalctl -u media-server -n 50
# 检查配置文件语法
sudo cat /opt/rk3588-media-server/etc/media-server.json | python3 -m json.tool
# 检查目录权限
ls -la /var/lib/rk3588-media-server/
ls -la /opt/rk3588-media-server/
# 修复日志目录权限（如需要）
sudo chown orangepi:orangepi /var/lib/rk3588-media-server/logs
sudo chown orangepi:orangepi /var/lib/rk3588-media-server/alarms
sudo chown orangepi:orangepi /var/lib/rk3588-media-server/clips
NPU 问题
# 查看 NPU 状态
cat /proc/rknpu/load
cat /proc/rknpu/version
# 查看设备节点
ls -la /dev/rknpu*
# 查看温度
cat /sys/class/thermal/thermal_zone6/temp
HLS 无法播放
# 检查 HLS 输出目录
ls -la /var/lib/rk3588-media-server/hls/
# 检查分片生成
ls -la /var/lib/rk3588-media-server/hls/cam1/
# 检查服务端口
ss -tlnp | grep 9000
RTSP 无法连接
# 本地测试
ffplay rtsp://localhost:8555/live/cam1
# 检查端口
ss -tlnp | grep 8555
# 查看编码器状态
grep "RKVENC" /proc/mpp_service/sessions-summary
系统要求
- 硬件: Orange Pi 5 Plus (RK3588) 或其他 RK3588 设备
- 系统: Ubuntu 22.04 LTS (ARM64) 或 Debian 11
- 内存: 建议 4GB 以上
- 存储: 建议 32GB 以上（HLS 分片占用空间）
- 依赖: RKNN Runtime, MPP, FFmpeg
性能参考
5 路 720p@30fps 并发处理：
| 资源 | 使用率 | 备注 |
|---|---|---|
| NPU Core0 | 70-80% | YOLO 推理 |
| CPU | 20-30% | 预处理、编码 |
| 编码器 | 5 路 720p | H264 CBR 2Mbps |
| 温度 | 50-60°C | 正常范围 |
| 内存 | 3-4GB | 包含系统 |
备份与恢复
备份配置和数据
# 创建备份
BACKUP_DIR="/root/rk3588-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"
# 备份配置
cp /opt/rk3588-media-server/etc/media-server.json "$BACKUP_DIR/"
# 备份模型
cp -r /opt/rk3588-media-server/models "$BACKUP_DIR/"
# 备份 HLS（可选，占用空间大）
cp -r /var/lib/rk3588-media-server/hls "$BACKUP_DIR/"
echo "备份完成: $BACKUP_DIR"
恢复
# 恢复配置
cp "$BACKUP_DIR/media-server.json" /opt/rk3588-media-server/etc/
# 恢复模型
cp -r "$BACKUP_DIR/models"/* /opt/rk3588-media-server/models/
# 重启服务
sudo systemctl restart media-server