# 车牌识别系统 PlateRecApp

> 基于 HyperLPR3 / MNN 的嵌入式 C++ 车牌识别平台，运行于树莓派5 + Ubuntu 24.04  
> 版本: fix27 v44 | 最后更新: 2026-08-30  
> Gogs 仓库: https://git.zhonjin.com:40717/steven_roc/PlateRecApp

## 系统概述

PlateRecApp 是一套面向工业园区/物流场站的全功能车牌识别与称重管理系统，支持多路 RTSP 视频流实时识别、飞书消息推送、MQTT 数据上报、Web 管理后台、登录认证、frpc 内网穿透管理等核心功能。

### 核心能力

| 模块 | 功能说明 |
|------|---------|
| **车牌识别** | HyperLPR3 + MNN 推理引擎，支持低位摄像头 ROI 推理 |
| **视频流** | 4路独立 RTSP 视频流 + Web 端 ROI 手动调整 |
| **飞书推送** | 进出站消息推送，支持携带重量信息，独立开关控制 |
| **MQTT** | 数据上报，独立开关控制，v43 并行模式支持 |
| **称重系统** | 重量调度器（promise/future 异步机制），15秒超时 |
| **Web 管理** | 登录认证、系统监控、日志管理、frpc 管理、SSH 密钥管理 |
| **站点锁** | 交替锁定机制，防止重复抓拍竞态 |
| **日志管理** | logrotate 自动清理，系统指标历史记录 |

## 系统架构

```
┌─────────────────────────────────────────────────────┐
│                    PlateRecApp                       │
├──────────┬──────────┬──────────┬────────────────────┤
│ 车牌识别  │ 重量调度  │ Web服务   │ 飞书/MQTT推送      │
│ HyperLPR3│ 异步引擎  │ 认证+监控 │ 独立开关控制       │
├──────────┴──────────┴──────────┴────────────────────┤
│              统一配置管理 (config.ini)                │
├─────────────────────────────────────────────────────┤
│  SQLite DB  │  MQTT Client  │  RTSP Capture        │
└─────────────────────────────────────────────────────┘
```

## 运行环境

| 项目 | 要求 |
|------|------|
| **硬件** | 树莓派5 8G（兼容 Ubuntu-24.04 / Raspberry Pi OS） |
| **编译器** | GCC 11+, C++17 |
| **核心依赖** | OpenCV 4.x, MNN ≥2.0, HyperLPR3 SDK |
| **其他依赖** | cJSON, cpp-httplib, bcrypt, ini-parser, FFmpeg, FreeType2, mosquitto |
| **数据库** | SQLite3 |
| **网络** | 飞书 API, MQTT Broker, RTSP 视频流, cURL, OpenSSL |

## 项目结构

```
PlateRecApp/
├── src/                          # 源代码
│   ├── main.cpp                  # 主程序入口
│   ├── common.cpp/h              # 公共定义与全局变量
│   ├── config.cpp/h              # 配置文件解析 (config.ini)
│   ├── plate_recognizer.cpp/h    # 车牌识别核心 (HyperLPR3+MNN)
│   ├── rtsp_capture.cpp/h        # RTSP 视频流采集
│   ├── web_server.cpp/h          # Web 管理服务器 (cpp-httplib)
│   ├── database.cpp/h            # SQLite 数据库操作
│   ├── feishu_client.cpp/h       # 飞书消息推送客户端
│   ├── mqtt_client.cpp/h         # MQTT 客户端
│   ├── weight_dispatcher.cpp/h   # 重量调度器 (promise/future)
│   ├── weight_scale.cpp/h        # 称重模块
│   ├── station_lock.cpp/h        # 站点交替锁定机制
│   ├── system_monitor.cpp/h      # 系统监控 (CPU/内存/温度)
│   ├── system_metrics_manager.cpp/h  # 系统指标管理+历史记录
│   ├── log_manager.cpp/h         # 日志管理+logrotate
│   ├── frpc_manager.cpp/h        # frpc 内网穿透管理
│   ├── ssh_manager.cpp/h         # SSH 密钥管理
│   ├── network_client.cpp/h      # 网络客户端 (API上传)
│   ├── utils.cpp/h               # 工具函数
│   ├── auth_api.cpp/h            # 认证 API
│   ├── auth_db.cpp/h             # 认证数据库
│   ├── auth_session.cpp/h        # 会话管理
│   ├── auth_middleware.cpp/h     # 认证中间件
│   ├── auth_crypto.cpp/h         # 加密工具 (bcrypt)
│   ├── auth_rate_limiter.h       # 速率限制
│   └── bcrypt/                   # bcrypt 密码哈希库
├── config/                       # 配置示例
│   ├── config一号门.ini           # 一号门配置模板
│   └── config二号门.ini           # 二号门配置模板
├── scripts/                      # 部署脚本
│   ├── deploy.sh                 # 一键部署脚本
│   ├── reset_passwords.py        # Web 管理密码重置工具
│   └── setup_frpc_sudoers.sh     # frpc sudoers 配置
├── third_party/                  # 第三方依赖源码
│   ├── cJSON.c/h                 # JSON 解析
│   ├── cvxFont.cpp/h             # OpenCV 中文字体
│   ├── httplib.h                 # cpp-httplib 头文件库
│   ├── hyper_lpr_sdk.h           # HyperLPR3 SDK 头文件
│   ├── ini.c/h                   # INI 配置解析
│   └── md5ex1.c/h                # MD5 工具
├── assets/web/                   # Web 前端资源 (HTML/CSS/JS)
├── CMakeLists.txt                # CMake 构建配置
├── CHANGELOG.md                  # 详细变更日志
└── README.md                     # 本文件
```

---

## 依赖安装详解（MNN + HyperLPR3）

本项目车牌识别核心依赖 **MNN**（阿里移动神经网络推理框架）和 **HyperLPR3**（中文车牌识别SDK）。以下是在树莓派5（aarch64 / Ubuntu 24.04）上的完整安装流程。

### 依赖关系

```
PlateRecApp
    ├── HyperLPR3 SDK  → libhyperlpr3.so（车牌检测+识别）
    │       └── MNN    → libMNN.so（底层推理引擎）
    ├── OpenCV 4.x     → 图像处理
    ├── FFmpeg         → RTSP流解码（DRM硬解/H.264软解）
    ├── SQLite3        → 数据持久化
    ├── cURL + OpenSSL → API通信 / HTTPS
    ├── mosquitto      → MQTT消息推送
    ├── FreeType2      → 中文字体渲染（水印）
    ├── cJSON          → JSON解析
    └── libcrypt       → bcrypt密码哈希
```

### 第一步：安装系统级依赖

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 编译工具链
sudo apt install -y build-essential cmake git wget pkg-config

# OpenCV 4.x
sudo apt install -y libopencv-dev libopencv-core-dev libopencv-imgproc-dev \
    libopencv-imgcodecs-dev libopencv-highgui-dev libopencv-videoio-dev

# FFmpeg（RTSP视频流解码）
sudo apt install -y libavformat-dev libavcodec-dev libavutil-dev libswscale-dev

# SQLite3
sudo apt install -y libsqlite3-dev

# cURL + OpenSSL
sudo apt install -y libcurl4-openssl-dev libssl-dev

# FreeType2（中文字体渲染）
sudo apt install -y libfreetype-dev

# cJSON
sudo apt install -y libcjson-dev

# MQTT客户端
sudo apt install -y libmosquitto-dev libmosquittopp-dev

# Protobuf（MNN编译需要）
sudo apt install -y libprotobuf-dev protobuf-compiler

# libcrypt（bcrypt认证）
sudo apt install -y libcrypt-dev
```

### 第二步：编译安装 MNN

MNN 是阿里巴巴开源的轻量级深度学习推理引擎，为 HyperLPR3 提供底层模型推理能力。

> 📌 官方仓库：https://github.com/alibaba/MNN

#### 2.1 克隆源码

```bash
cd ~
git clone --depth=1 https://github.com/alibaba/MNN.git
cd MNN
```

#### 2.2 编译（树莓派5 / aarch64 Linux）

```bash
# 生成 schema（首次编译必须执行）
./schema/generate.sh

# 创建构建目录
mkdir build && cd build

# CMake 配置（关键参数说明见下方表格）
cmake .. \
    -DMNN_BUILD_CONVERTER=OFF \
    -DMNN_SEP_BUILD=OFF \
    -DMNN_ARM82=ON \
    -DMNN_OPENMP=ON

# 编译（-j4 适配树莓派4核）
make -j4

# 安装到系统
sudo make install
sudo ldconfig
```

#### 2.3 关键编译参数说明

| 参数 | 值 | 说明 |
|------|-----|------|
| `MNN_SEP_BUILD` | `OFF` | 关闭分离构建，生成单个 `libMNN.so`（推荐） |
| `MNN_ARM82` | `ON` | **启用 ARMv8.2 半精度浮点(fp16)加速**，树莓派5必开 |
| `MNN_OPENMP` | `ON` | 启用 OpenMP 多线程加速（默认开启） |
| `MNN_BUILD_CONVERTER` | `OFF` | 本项目不需要模型转换工具，关闭减小体积 |
| `MNN_OPENCL` | `OFF` | GPU加速（树莓派无可用OpenCL，保持关闭） |
| `MNN_VULKAN` | `OFF` | Vulkan加速（树莓派支持有限，建议关闭） |

#### 2.4 验证 MNN 安装

```bash
# 检查库文件
ls /usr/local/lib/libMNN*
# 预期输出: libMNN.so  (或 libMNN.a 如果静态编译)

# 检查头文件
ls /usr/local/include/MNN/
# 预期输出: Interpreter.hpp, MNNDefine.h, ...
```

### 第三步：安装 HyperLPR3 SDK

HyperLPR3 是基于深度学习的中文车牌识别框架。本项目使用其 C++ SDK 动态库。

> 📌 官方仓库：https://github.com/HyperInspire/HyperLPR3  
> 📌 国内镜像：https://gitee.com/zeusees/HyperLPR

#### 3.1 方式一：使用预编译 SDK（推荐）

HyperLPR3 官方提供多平台预编译SDK包，包含头文件、动态库和模型文件。

**下载地址**（官方百度网盘）：

| 平台 | 说明 |
|------|------|
| Linux-x86_64 | x86_64 桌面/服务器 |
| **Linux-aarch64** | **树莓派5 / ARM64 开发板（本项目使用）** |
| Linux-armv7l | 32位ARM |
| macOS-x86 | Intel Mac |

下载后解压，目录结构应为：

```
hyperlpr3/                    # 放置于 PlateRecApp 项目根目录
├── include/                  # SDK 头文件
│   └── hyper_lpr_sdk.h      # 核心API头文件
├── lib/                      # 动态库
│   └── libhyperlpr3.so      # 车牌识别SDK
└── resource/                 # 模型文件 + 测试图片
    └── models/               # 检测+识别模型（.mnn格式）
        ├── det/              # 车牌检测模型
        ├── rec/              # 车牌识别模型
        └── ...
```

**安装步骤**：

```bash
# 1. 将SDK解压到项目根目录
cd /path/to/PlateRecApp
# 假设下载的SDK压缩包名为 hyperlpr3-linux-aarch64.zip
unzip hyperlpr3-linux-aarch64.zip -d .

# 2. 确认目录结构正确
ls hyperlpr3/include/hyper_lpr_sdk.h  # 头文件
ls hyperlpr3/lib/libhyperlpr3.so      # 动态库
ls hyperlpr3/resource/models/          # 模型文件

# 3. 设置运行时库搜索路径
echo "/path/to/PlateRecApp/hyperlpr3/lib" | sudo tee /etc/ld.so.conf.d/hyperlpr3.conf
sudo ldconfig
```

#### 3.2 方式二：从源码编译 HyperLPR3 SDK

如果预编译SDK不可用，可自行编译。

```bash
# 1. 克隆源码
cd ~
git clone --depth=1 https://github.com/HyperInspire/HyperLPR3.git
cd HyperLPR3

# 2. 下载第三方依赖包（官方百度网盘，code: eu31）
#    解压后放置到项目根目录，或通过软链接引入
#    依赖包含预编译的 MNN 和 OpenCV 静态库

# 3. 编译动态库
sh command/build_release_linux_share.sh

# 4. 编译产物位于
#    build/linux/install/hyperlpr3/
#    ├── include/    头文件
#    ├── lib/        动态库 (libhyperlpr3.so)
#    └── resource/   模型文件

# 5. 将产物拷贝到 PlateRecApp 项目目录
cp -r build/linux/install/hyperlpr3 /path/to/PlateRecApp/
```

#### 3.3 模型文件说明

HyperLPR3 需要以下模型文件（`.mnn` 格式，由 MNN 推理引擎加载）：

| 模型 | 功能 | 位置 |
|------|------|------|
| 车牌检测模型 (det) | 定位图片中的车牌区域 | `resource/models/det/` |
| 车牌识别模型 (rec) | 识别车牌字符 | `resource/models/rec/` |
| 车牌分割模型 (seg) | 分割粘连车牌字符 | `resource/models/seg/`（可选） |

> ⚠️ **模型文件必须与可执行文件在同一路径或配置路径下**，否则运行时会报模型加载失败。

### 第四步：验证完整编译环境

安装完所有依赖后，执行以下检查：

```bash
cd /path/to/PlateRecApp

# 检查所有依赖是否就绪
echo "=== 依赖检查 ==="
echo -n "OpenCV:     " && pkg-config --modversion opencv4 2>/dev/null || echo "❌ 未安装"
echo -n "SQLite3:    " && pkg-config --modversion sqlite3 2>/dev/null || echo "❌ 未安装"
echo -n "cURL:       " && curl --version | head -1 || echo "❌ 未安装"
echo -n "OpenSSL:    " && openssl version || echo "❌ 未安装"
echo -n "FFmpeg:     " && pkg-config --modversion libavformat 2>/dev/null || echo "❌ 未安装"
echo -n "FreeType2:  " && pkg-config --modversion freetype2 2>/dev/null || echo "❌ 未安装"
echo -n "cJSON:      " && pkg-config --modversion libcjson 2>/dev/null || echo "❌ 未安装"
echo -n "Mosquitto:  " && dpkg -l | grep libmosquitto-dev | awk '{print $3}' || echo "❌ 未安装"
echo -n "MNN:        " && ls /usr/local/lib/libMNN.so >/dev/null 2>&1 && echo "✅ 已安装" || echo "❌ 未安装"
echo -n "HyperLPR3:  " && ls hyperlpr3/lib/libhyperlpr3.so >/dev/null 2>&1 && echo "✅ 已安装" || echo "❌ 未安装"
echo -n "HyperLPR3头文件: " && ls hyperlpr3/include/hyper_lpr_sdk.h >/dev/null 2>&1 && echo "✅ 存在" || echo "❌ 缺失"
echo -n "模型文件:   " && ls hyperlpr3/resource/models/ >/dev/null 2>&1 && echo "✅ 存在" || echo "❌ 缺失"
```

### 第五步：编译 PlateRecApp

```bash
cd /path/to/PlateRecApp

# 创建构建目录
mkdir -p build && cd build

# CMake 配置
cmake .. \
    -DCMAKE_BUILD_TYPE=Release

# 编译（-j4 适配树莓派4核）
make -j4

# 编译产物
ls -la PlateRecApp
# 可执行文件约 2-5 MB（Release 模式 strip 后）
```

### 常见问题排查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| `fatal error: MNN/Interpreter.hpp: No such file` | MNN 头文件路径未配置 | `sudo make install` 后 `sudo ldconfig` |
| `undefined reference to hyperlpr3_xxx` | HyperLPR3 库未链接 | 确认 `hyperlpr3/lib/libhyperlpr3.so` 存在 |
| `libhyperlpr3.so: cannot open shared object` | 运行时找不到动态库 | `echo "路径" > /etc/ld.so.conf.d/hyperlpr3.conf && sudo ldconfig` |
| `模型加载失败` | 模型文件路径不正确 | 确认 `hyperlpr3/resource/models/` 目录存在且包含 .mnn 文件 |
| `OpenCV 版本不匹配` | 系统安装多版本 OpenCV | `pkg-config --modversion opencv4` 确认版本 ≥ 4.0 |
| `MNN ARM82 编译报错` | 汇编宏嵌套过深 | 参考 MNN Issue，手动展开 `FMAX`/`FMIN` 宏调用 |
| `cJSON 找不到` | 未安装或 pkg-config 缺失 | `sudo apt install libcjson-dev` |
| `mosquittopp 找不到` | MQTT C++ 库未安装 | `sudo apt install libmosquittopp-dev` |

---

## 快速开始

### 1. 克隆仓库

```bash
git clone https://git.zhonjin.com:40717/steven_roc/PlateRecApp.git
cd PlateRecApp
```

### 2. 编译

```bash
mkdir build && cd build
cmake ..
make -j4
```

### 3. 配置

```bash
# 复制配置模板并修改
cp config/config一号门.ini config.ini
# 编辑 config.ini 填入实际参数
```

### 4. 部署

```bash
sudo bash scripts/deploy.sh
```

### 5. 验证

```bash
sudo systemctl status PlateRecApp
# 访问 Web 管理: http://<设备IP>:8080
```

## 配置文件说明

核心配置通过 `config.ini` 管理：

```ini
[rtsp]
# RTSP 视频流地址（支持4路）
URL_1 = rtsp://...
URL_2 = rtsp://...

[feishu]
ENABLED = 1              # 1=启用飞书消息推送，0=禁用
WEBHOOK_URL = https://open.feishu.cn/open-apis/bot/v2/hook/xxx

[MQTT]
MQTT_ENABLED = 1         # 1=启用MQTT消息推送，0=禁用
MQTT_HOST = xxx
MQTT_PORT = 1883

[weight]
flagWeight = 1           # 飞书消息是否携带重量信息 (1=是)

[web]
PORT = 8080              # Web 管理端口
```

## Web 管理功能

| 功能 | 路径 | 说明 |
|------|------|------|
| 首页仪表盘 | `/` | 系统概览、最新抓拍 |
| 登录认证 | `/login` | 超级管理员/普通用户双角色 |
| 系统监控 | `/monitor` | CPU/内存/磁盘/温度实时监控 |
| frpc 管理 | `/frpc` | 内网穿透服务管理 |
| SSH 密钥 | `/ssh` | Web 端 SSH 密钥管理 |
| 日志管理 | `/logs` | 在线查看 + logrotate |
| ROI 调整 | `/roi` | Web 端 4 路视频 ROI 手动调整 |
| 视频预览 | `/video` | 实时视频流预览 |
| 称重记录 | `/weight` | 称重数据查询 |

## 账号说明

| 角色 | 用户名 | 密码 | 权限 |
|------|--------|------|------|
| 超级管理员 | admin | zhonjin188A | 所有页面 |
| 普通用户 | zhonjin | zhonjin | 基础页面 |

> 首次部署后建议通过 `scripts/reset_passwords.py` 修改默认密码

## 安全规则

- ✅ 所有管理操作必须经过超级管理员登录认证
- ✅ frpc admin API 仅允许本机 127.0.0.1 调用，禁止通过 frp 隧道暴露到公网
- ✅ 永久失败告警受飞书开关 (`g_feishu_enabled`) 控制
- ✅ 认证系统使用 bcrypt 密码哈希 + 速率限制

## 版本历史

| 版本 | 日期 | 主要内容 |
|------|------|---------|
| fix27 v44 | 2026-08-30 | 飞书消息携带重量、水印居中、MQTT修复、内存泄漏修复 |
| fix26 v44 | 2026-08-30 | 飞书/MQTT独立开关 |
| fix25 v44 | 2026-08-30 | P0 prelock 优化 |
| fix24 v43 | 2026-08-30 | 系统指标历史、日志管理 |
| fix24 v32-v41 | 2026-07~08 | Web管理、认证系统、frpc管理 |
| fix24 v21 | 2026-07-03 | P0 时间对齐 bug 修复 |
| fix18 | 2026-07-06 | 重复抓拍竞态、4路视频流、MQTT合并 |
| V5 fix19 | 2026-06-25 | 基础版本 |

详细变更记录请查看 [CHANGELOG.md](CHANGELOG.md)

## 自动同步

项目包含 `sync_to_gogs.sh` 脚本，每次代码更新后执行即可自动同步到 Gogs 仓库：

```bash
bash sync_to_gogs.sh
```

## 许可证

本项目为内部使用项目。

## 联系方式

- **作者**: steven_roc
- **邮箱**: steven_roc@126.com
- **Gogs**: https://git.zhonjin.com:40717/steven_roc/PlateRecApp