From 140ef4c6849e4f32166eae9949c583786dee7d31 Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Tue, 21 Jul 2026 10:35:58 +0800 Subject: [PATCH] docs: add deployment guide with post-clone and static IP steps --- docs/deployment.md | 541 +++++---------------------------------------- 1 file changed, 52 insertions(+), 489 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 0146f54..8b1949b 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,536 +1,99 @@ -# RK3588 Media Server 部署指南 +# Edge 设备部署指南 -## 架构说明 +## 首次部署（从 SD 卡克隆） -``` -┌─────────────────────────────────────────────────────────────┐ -│ 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程序 │ -└─────────────────────────────────────────────────────────────┘ -``` +### 克隆前准备 -### 设计特点 +在源设备上清理不需要的文件后关机，取出 SD 卡，使用 `dd` 或烧录工具克隆到新卡。 -- **Media Server**: 独立的 systemd 服务，高可用（崩溃自动重启） -- **Agent**: 独立的 systemd 服务，通过 `systemctl` 监控和控制 Media Server -- **两者可独立重启**: 重启 Agent 不会影响 Media Server -- **运行时数据分离**: 程序文件在 `/opt/`，数据在 `/var/lib/` -- **自动清理**: HLS 分片、日志、告警数据自动轮转清理 +### 克隆后配置 ---- +将新 SD 卡插入新设备，开机，执行以下步骤： -## 快速开始 +#### 1. 生成新的设备 ID -### 1. 编译 - -在 RK3588 设备上编译： +管理端通过设备 ID 区分不同设备，克隆后必须更换： ```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 +sudo rm -f /etc/machine-id /var/lib/safesight-edge-agent/device_id +sudo systemd-machine-id-setup ``` -**编译脚本选项：** - -| 选项 | 说明 | -|------|------| -| `-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. 部署 +#### 2. 重新生成 SSH 主机密钥 ```bash -cd ~/apps/OrangePi3588Media -sudo ./scripts/deploy.sh install +sudo rm -f /etc/ssh/ssh_host_*_key* +sudo ssh-keygen -A ``` -部署过程会： -1. 安装 Media Server 和 Agent 到 `/opt/` -2. 创建运行时数据目录 `/var/lib/rk3588-media-server/` -3. 配置日志轮转和自动清理 -4. 启动 systemd 服务 - -### 3. 查看状态 +#### 3. 设置主机名 ```bash -sudo ./scripts/deploy.sh status +sudo hostnamectl set-hostname <新主机名> ``` -### 3.1 DDR 固频排障 +#### 4. 配置静态 IP（生产环境） -当出现 `CPU/NPU` 利用率不高，但 RTSP 输出帧率周期性跌落时，优先检查 DDR devfreq 是否在频繁降频。 - -项目内置了 DDR 模式切换脚本： +编辑 netplan 配置： ```bash -sudo bash ./scripts/ddr_mode.sh status -sudo bash ./scripts/ddr_mode.sh performance -sudo bash ./scripts/ddr_mode.sh restore +sudo nano /etc/netplan/01-network-manager-all.yaml ``` -也可以从运维入口调用： +写入： -```bash -sudo ./scripts/ops.sh ddr-status -sudo ./scripts/ops.sh ddr-performance -sudo ./scripts/ops.sh ddr-restore +```yaml +network: + version: 2 + ethernets: + enP4p65s0: # 网卡名，用 ip addr 确认 + dhcp4: no + addresses: + - 10.0.0.82/24 # 目标 IP + routes: + - to: default + via: 10.0.0.1 # 网关 + nameservers: + addresses: + - 10.0.0.1 # DNS ``` -说明： - -- `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 +sudo netplan apply ``` -如果现场误报仍然偏多，可切换到更严格的对照版： +#### 5. 重启 ```bash -./build/media-server -c configs/person_shoe_two_stage_workshoe_alarm_v8s_shoe640_strict.json +sudo reboot ``` -说明： - -- 输入端：`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 +# 确认服务状态 +systemctl status safesight-edge-server safesight-edge-agent + +# 确认新 IP +ip addr show | grep inet + +# 确认新设备 ID +cat /var/lib/safesight-edge-agent/device_id + +# 管理端发现新设备后，在设备详情页设置别名 ``` --- -## 完整命令参考 +## 更新部署 -### 部署脚本命令 - -| 命令 | 说明 | -|------|------| -| `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. 拉取最新代码 +cd ~/apps/safesight-edge git pull - -# 2. 重新编译（清理后编译确保干净） -./scripts/build.sh -c - -# 3. 执行升级 +bash scripts/build.sh -m -j4 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 -```