521 lines
14 KiB
Markdown
521 lines
14 KiB
Markdown
# 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 设备上编译：
|
||
|
||
```bash
|
||
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. 部署
|
||
|
||
```bash
|
||
cd ~/apps/OrangePi3588Media
|
||
sudo ./scripts/deploy.sh install
|
||
```
|
||
|
||
部署过程会：
|
||
1. 安装 Media Server 和 Agent 到 `/opt/`
|
||
2. 创建运行时数据目录 `/var/lib/rk3588-media-server/`
|
||
3. 配置日志轮转和自动清理
|
||
4. 启动 systemd 服务
|
||
|
||
### 3. 查看状态
|
||
|
||
```bash
|
||
sudo ./scripts/deploy.sh status
|
||
```
|
||
|
||
### 3.1 DDR 固频排障
|
||
|
||
当出现 `CPU/NPU` 利用率不高，但 RTSP 输出帧率周期性跌落时，优先检查 DDR devfreq 是否在频繁降频。
|
||
|
||
项目内置了 DDR 模式切换脚本：
|
||
|
||
```bash
|
||
sudo bash ./scripts/ddr_mode.sh status
|
||
sudo bash ./scripts/ddr_mode.sh performance
|
||
sudo bash ./scripts/ddr_mode.sh restore
|
||
```
|
||
|
||
也可以从运维入口调用：
|
||
|
||
```bash
|
||
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` 组合。
|
||
|
||
推荐配置：
|
||
|
||
```bash
|
||
./build/media-server -c configs/person_shoe_two_stage_recommended.json
|
||
```
|
||
|
||
如需直接启用“缺鞋”判定和按人冷却告警，可使用：
|
||
|
||
```bash
|
||
./build/media-server -c configs/person_shoe_two_stage_recommended_alarm.json
|
||
```
|
||
|
||
如果业务目标是“只关心已检测到的鞋是否为黑色劳保鞋”，可使用：
|
||
|
||
```bash
|
||
./build/media-server -c configs/person_shoe_two_stage_workshoe_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. 卸载
|
||
|
||
```bash
|
||
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 服务管理
|
||
|
||
```bash
|
||
# 启动/停止/重启
|
||
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 服务管理
|
||
|
||
```bash
|
||
# 启动/停止/重启（不影响 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`
|
||
|
||
---
|
||
|
||
## 配置修改
|
||
|
||
编辑配置文件：
|
||
|
||
```bash
|
||
sudo nano /opt/rk3588-media-server/etc/media-server.json
|
||
```
|
||
|
||
修改后重启服务：
|
||
|
||
```bash
|
||
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天
|
||
|
||
查看当前存储使用：
|
||
|
||
```bash
|
||
# 使用部署脚本查看（推荐）
|
||
sudo ./scripts/deploy.sh status
|
||
|
||
# 或直接查看目录大小
|
||
du -sh /var/lib/rk3588-media-server/*/
|
||
```
|
||
|
||
---
|
||
|
||
## 升级
|
||
|
||
升级步骤（保留配置和数据）：
|
||
|
||
```bash
|
||
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 路视频同时播放
|
||
- 自适应布局
|
||
- 实时状态显示
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 服务无法启动
|
||
|
||
```bash
|
||
# 查看详细错误
|
||
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 问题
|
||
|
||
```bash
|
||
# 查看 NPU 状态
|
||
cat /proc/rknpu/load
|
||
cat /proc/rknpu/version
|
||
|
||
# 查看设备节点
|
||
ls -la /dev/rknpu*
|
||
|
||
# 查看温度
|
||
cat /sys/class/thermal/thermal_zone6/temp
|
||
```
|
||
|
||
### HLS 无法播放
|
||
|
||
```bash
|
||
# 检查 HLS 输出目录
|
||
ls -la /var/lib/rk3588-media-server/hls/
|
||
|
||
# 检查分片生成
|
||
ls -la /var/lib/rk3588-media-server/hls/cam1/
|
||
|
||
# 检查服务端口
|
||
ss -tlnp | grep 9000
|
||
```
|
||
|
||
### RTSP 无法连接
|
||
|
||
```bash
|
||
# 本地测试
|
||
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 | 包含系统 |
|
||
|
||
---
|
||
|
||
## 备份与恢复
|
||
|
||
### 备份配置和数据
|
||
|
||
```bash
|
||
# 创建备份
|
||
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"
|
||
```
|
||
|
||
### 恢复
|
||
|
||
```bash
|
||
# 恢复配置
|
||
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
|
||
```
|