# 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_workshoe_alarm_v8s_shoe640.json
```

如果现场误报仍然偏多，可切换到更严格的对照版：

```bash
./build/media-server -c configs/person_shoe_two_stage_workshoe_alarm_v8s_shoe640_strict.json
```

说明：

- 输入端：`use_ffmpeg: true`、`use_mpp: false`
- 输出端：仍然使用 `MPP` 编码
- 鞋检测：使用 `shoe_det_yolov8s_workshoe_640_rk3588.rknn`
- 适用场景：源流在 VLC 中播放正常，但项目内 `ffmpeg demux + mpp decode` 会出现固定画面卡顿
- 当前业务目标：只对“检测到鞋，但颜色不符合黑色劳保鞋要求”的目标告警

现场实施时，优先修改这些参数：

- 鞋漏报多：
  - `shoe_det.conf`
  - `shoe_assoc.person_shoe_check.min_shoe_score`
  - `dynamic_roi.min_person_height`
- 蓝框误报多：
  - `shoe_det.conf`
  - `shoe_assoc.person_shoe_check.min_shoe_score`
  - `dynamic_roi.max_box_area_ratio`
- 黑鞋被误报：
  - `shoe_color.color_check.dark_threshold`
- 告警太频繁：
  - `alarm.rules[].min_duration_ms`
  - `alarm.rules[].cooldown_ms`
- 完整流程 FPS 不够：
  - `face_det.infer_fps`
  - `face_recog.infer_fps`
  - `dynamic_roi.max_rois`

排障建议：

- 若 VLC 直接拉原始 RTSP 源不卡，而项目内画面会在固定位置卡顿，优先切到 `use_ffmpeg: true`、`use_mpp: false`
- 若 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模型文件
│   ├── ppe_det_yolov8_ppe11_768_rk3588.rknn
│   ├── object_det_yolov8n_coco_640_rk3588.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
```