帮助手册 - 车牌识别系统

📋 目录

系统概述
快速部署指南
config.ini 完整配置说明
RTSP 摄像头配置
车牌识别上传流程
MQTT 数据上报配置
称重系统对接
ROI 区域识别配置
交替锁定机制
登录认证与权限
frpc 内网穿透
SSL/HTTPS 配置
系统监控与日志
Web 管理功能
数据库与备份
常见问题 FAQ

1. 系统概述 ▼

系统简介

车牌识别系统（PlateRecApp）是一款基于 HyperLPR3 的实时车牌识别应用，运行在树莓派 5 (aarch64) 上，支持：

多路 RTSP 摄像头实时抓拍识别（进场/出场/侧面进/侧面出）
车牌识别结果自动上传至云端 API
称重系统对接（TCP 协议），自动关联车牌与称重数据
MQTT 协议实时推送识别结果
飞书群消息通知（异常报警）
Web 管理界面（监控首页、视频预览、系统配置、锁定管理等）
frpc 内网穿透管理
登录认证与角色权限控制

运行环境

项目	要求
硬件	树莓派 5 8GB（推荐）
系统	Debian 13 (trixie) / Ubuntu 24.04 aarch64
依赖	HyperLPR3 SDK、FFmpeg、libcurl、OpenSSL、cJSON、Mosquitto
反向代理	Nginx（HTTPS 对外服务）

目录结构

路径	说明
PlateRecApp	主程序二进制
config.ini	主配置文件
config.txt	MD5 校验配置
hyperlpr3/	HyperLPR3 SDK 模型文件
assets/web/	Web 页面文件（HTML/CSS/JS）
data/	数据库目录（auth.db、upload_records.db）
photos/	抓拍图片存储目录

2. 快速部署指南 ▼

编译部署

解压代码包：tar xzf fix24_vXX.tar.gz
编译：cd fix24/build && cmake .. && make -j4
部署文件到安装目录（如 /opt/openAI/project/003.PlateRecAPP/）
复制 HTML 文件：cp -r assets/web/ /安装目录/assets/web/
配置 sudoers（frpc 管理需要）：sudo bash scripts/setup_frpc_sudoers.sh
修改 config.ini 配置（参考下文各节）
启动服务：sudo systemctl restart PlateRecApp

systemd 服务配置

服务文件路径：/etc/systemd/system/PlateRecApp.service

关键配置：User=stevenroc（非 root 运行），需要 sudoers 授权 frpc 管理权限。WorkingDirectory 应指向安装目录。

密码重置

如忘记管理员密码，运行：python3 reset_passwords.py

3. config.ini 完整配置说明 ▼

配置文件路径：<安装目录>/config.ini，ini 格式，section 和 key 均不区分大小写。

[config] 核心识别配置

参数	类型	默认值	说明
project_name	string	-	项目名称
point_number	string	-	站点编号
throughway	string	-	通道名称
rtsp_url_front_in	string	-	前侧进场摄像头 RTSP 地址
rtsp_url_front_out	string	-	前侧出场摄像头 RTSP 地址
rtsp_url_side_in	string	-	侧面进场摄像头 RTSP 地址
rtsp_url_side_out	string	-	侧面出场摄像头 RTSP 地址
app_api	string	-	云端上传 API 地址
app_key	string	-	API 认证 Key
app_secret	string	-	API 认证 Secret
DEBUG_LOG	int	0	调试日志开关（0=关闭，1=开启）
TestFlag	int	0	测试模式开关
wType	int	0	称重类型（0=禁用，1=启用）
TIME_WINDOW	int	5	识别时间窗口（分钟），同一车牌在窗口内不重复上传
MAX_PHOTO_GROUPS	int	100	最大照片组数缓存
in_out_interval	int	5	⚠️ 单位是分钟！交替锁定间隔（同一车牌进出最短时间），内部转为秒存储
PLATE_CONFIDENCE_THRESHOLD	float	0.7	车牌识别置信度阈值（0~1），低于此值不上传
PLATE_LOG_THRESHOLD	float	0.5	日志记录置信度阈值
AlternatingMerge	int	0	交替合并开关（0=关闭，1=开启）
hw_decode_mode	string	auto	硬件解码模式：auto/soft/drm
hw_decode_device	string	/dev/dri/renderD128	硬件解码设备路径
rtsp_transport	string	tcp	RTSP 传输协议：tcp/udp
PhotoMaxCapacityMB	int	1024	照片目录最大容量（MB），超限自动清理旧照片
LogRetentionDays	int	30	日志保留天数

[config] ROI 区域配置

参数	说明
roi_in_x / roi_in_y	进场 ROI 区域左上角坐标
roi_in_w / roi_in_h	进场 ROI 区域宽高
roi_in_enabled	进场 ROI 开关（0/1）
roi_out_x / roi_out_y	出场 ROI 区域左上角坐标
roi_out_w / roi_out_h	出场 ROI 区域宽高
roi_out_enabled	出场 ROI 开关（0/1）
roi_debug_enabled	ROI 调试模式开关（0/1）

ROI 可通过 Web 首页的可视化工具拖拽设置，也可在 config.ini 中手动填写坐标值。

[server] Web 服务配置

参数	说明
ip	Web 服务监听地址（含端口），如 `0.0.0.0:8080`

[mqtt] MQTT 上报配置

参数	默认值	说明
MQTT_HOST	-	MQTT Broker 地址（填写后自动启用 MQTT）
MQTT_PORT	1883	MQTT Broker 端口
MQTT_USER	-	MQTT 用户名
MQTT_PASS	-	MQTT 密码
MQTT_TOPIC	-	推送主题
MQTT_CLIENT_ID	-	客户端 ID
PLATE_COLOR	-	车牌颜色标识
VEHICLE_TYPE	-	车辆类型标识

[feishu] 飞书通知配置

参数	说明
APP_ID	飞书应用 App ID
APP_SECRET	飞书应用 App Secret
CHAT_ID	飞书群聊 ID
TIMEOUT_SECOND	请求超时时间（秒）
WarningSigns	抑制紧急报警（1=抑制，0=正常）

[weight] 称重系统配置

参数	默认值	说明
flagWeight	0	称重系统开关（0/1）
weight_server_ip	-	称重服务器 IP
weight_server_port	-	称重服务器端口
weight_threshold_in	0	进场称重阈值（吨）
weight_threshold_out	0	出场称重阈值（吨）
default_entry_weight	0	默认进场重量
default_exit_weight	0	默认出场重量
weight_detection_time	5000	称重检测时间（毫秒）
tcp_connect_timeout	3000	TCP 连接超时（毫秒）
MAX_WEIGHT	100	最大称重值（吨）
STABLE_SAMPLE_COUNT	5	稳定采样次数
STABLE_THRESHOLD_KG	50	稳定判定阈值（公斤）
CANDIDATE_DATA_COUNT	3	候选数据次数
MAX_UPLOAD_RETRIES	3	上传最大重试次数
RETRY_DELAY_MS	1000	重试延迟（毫秒）

[auth] 登录认证配置

参数	默认值	说明
enabled	1	认证开关（0=关闭，1=开启）
db_path	data/auth.db	认证数据库路径（相对安装目录）
session_idle_timeout	1800	Session 空闲超时（秒）
session_max_timeout	28800	Session 最大超时（秒）
session_remember_timeout	604800	记住登录超时（秒）
bcrypt_cost	12	bcrypt 加密轮数（10~14）
max_failed_attempts	5	最大登录失败次数
lockout_duration	900	锁定时长（秒）
rate_limit_max	5	速率限制最大请求
rate_limit_window	300	速率限制窗口（秒）

[ssl] HTTPS 配置

参数	说明
enabled	SSL 开关（0/1）
cert_path	SSL 证书路径
key_path	SSL 私钥路径

[system] 系统监控配置（v37 启用历史存储）

参数	默认值	说明
monitor_interval	2	监控采集间隔（秒），通过 delta 法计算 CPU 使用率
temp_alert_threshold	70	温度告警阈值（°C）
cpu_alert_threshold	90	CPU 告警阈值（%）
db_path	data/system_metrics.db	监控数据库路径（SQLite）
history_retention_days	7	原始数据保留天数
aggregation_retention_days	365	聚合数据（小时/日）保留天数
flush_time	23:20	每日定时刷盘时间（HH:MM），内存监控数据写入数据库

[frpc] 内网穿透配置

参数	默认值	说明
config_path	-	frpc.toml 配置文件路径
backup_path	-	配置备份路径
protected_tunnels	-	受保护隧道名称（逗号分隔）
restart_check_timeout	3	重启后检查超时（秒）
auto_rollback	1	自动回滚开关（0/1）
web_enabled	1	frpc Web 管理开关
admin_addr	127.0.0.1	frpc Admin API 地址
admin_port	7400	frpc Admin API 端口
admin_user	-	frpc Admin 用户名
admin_password	-	frpc Admin 密码

[terminal] 终端/SSH 配置

参数	默认值	说明
ttyd_port	7681	ttyd Web 终端端口
ttyd_credential	-	ttyd 登录凭据（user:password）
ttyd_max_clients	5	ttyd 最大客户端数
ssh_keys_path	-	SSH 公钥存储路径

[log] 日志配置（v36 内存缓冲）

参数	默认值	说明
enabled	1	内存缓冲模式开关（1=内存缓冲，0=直写文件）
log_file	PlateRecApp.log	日志文件路径
buffer_size_mb	20	内存缓冲区上限（MB），满时丢弃最旧日志
flush_time	23:20	每日定时刷盘时间（HH:MM），内存日志写入磁盘文件
retention_days	30	日志文件保留天数，超期自动清理
redirect_stdout	1	捕获 stdout/stderr 到内存缓冲区（0/1）
auto_flush_on_exit	1	程序退出（SIGTERM/SIGINT）时立即刷盘（0/1）

v36 说明：启用内存缓冲后，所有日志先写入内存环形缓冲区，Web 日志页面直接从内存读取（零磁盘 I/O）。每日到达 flush_time 时批量写入 PlateRecApp_YYYYMMDD.log。设 enabled=0 可回退到传统直写文件模式。

4. RTSP 摄像头配置 ▼

摄像头地址格式

标准 RTSP 地址格式：

rtsp://用户名:密码@摄像头IP:554/stream

四路摄像头说明

参数	方向	说明
rtsp_url_front_in	前→进	前方摄像头，捕捉进场车辆
rtsp_url_front_out	前→出	前方摄像头，捕捉出场车辆
rtsp_url_side_in	侧→进	侧面摄像头，捕捉进场车辆
rtsp_url_side_out	侧→出	侧面摄像头，捕捉出场车辆

共享捕获模式

当 rtsp_url_front_in 与 rtsp_url_front_out 指向同一摄像头时，系统自动启用共享捕获模式，节省解码资源。

硬件解码

模式	值	说明
自动	auto	优先硬件解码，不可用则回退软件
软件解码	soft	CPU 解码，兼容性最好
DRM 硬件	drm	使用 DRM 硬件加速解码（树莓派5推荐）

树莓派 5 推荐配置：hw_decode_mode=drm，hw_decode_device=/dev/dri/renderD128，rtsp_transport=tcp

5. 车牌识别上传完整流程 ▼

识别流程

摄像头抓拍：RTSP 视频流实时解码，检测到车辆运动时触发抓拍
车牌识别：HyperLPR3 引擎识别车牌号，返回车牌文本 + 置信度
置信度过滤：识别结果低于 PLATE_CONFIDENCE_THRESHOLD 则丢弃
时间窗口去重：同一车牌在 TIME_WINDOW 分钟内不重复上传
交替锁定检查：同一车牌进出间隔低于 in_out_interval 分钟则锁定
ROI 过滤：如启用 ROI，只识别指定区域内的车牌
数据上传：通过 HTTP POST 将识别结果 + 抓拍照片上传至 app_api
MQTT 推送：如启用 MQTT，同步推送识别结果
飞书通知：异常情况（识别失败、系统异常）发送飞书群消息

上传 API 请求格式

POST app_api，Headers 包含 app_key 和 app_secret 认证。

上传数据包含：车牌号、置信度、车牌颜色、抓拍时间、摄像头方向、照片文件（Base64 或 multipart）。

照片存储与清理

照片保存在 photos/ 目录下，按日期分目录
当照片总容量超过 PhotoMaxCapacityMB 时，自动清理最旧的照片
清理时优先保留最近的照片，从最旧的日期目录开始删除

6. MQTT 数据上报配置 ▼

启用条件

在 [mqtt] 段中填写 MQTT_HOST 即自动启用 MQTT 推送。

推送内容

每次车牌识别成功后，MQTT 推送 JSON 格式数据，包含：

车牌号、车牌颜色、车辆类型
识别置信度
摄像头方向（进/出）
识别时间戳
站点编号

配置示例

[mqtt]
MQTT_HOST=mqtt.example.com
MQTT_PORT=1883
MQTT_USER=username
MQTT_PASS=password
MQTT_TOPIC=plate/recognition
MQTT_CLIENT_ID=plate_rec_station_01
PLATE_COLOR=yellow
VEHICLE_TYPE=truck

注意：MQTT 连接失败时系统会自动重连，不影响识别和上传功能。

7. 称重系统对接 ▼

工作原理

称重系统通过 TCP 协议与称重地磅通信：

车牌识别成功后，系统连接称重服务器
读取当前称重数据
将车牌与重量数据关联后一起上传

重量判定逻辑

连续 STABLE_SAMPLE_COUNT 次读数变化 < STABLE_THRESHOLD_KG 公斤，视为稳定
稳定后取 CANDIDATE_DATA_COUNT 次读数的中值作为最终重量
重量超过 MAX_WEIGHT 吨视为异常，丢弃

阈值说明

weight_threshold_in：进场最低重量（吨），低于此值可能表示空车
weight_threshold_out：出场最低重量（吨）
default_entry_weight：无法获取称重数据时的默认进场重量
default_exit_weight：无法获取称重数据时的默认出场重量

8. ROI 区域识别配置 ▼

ROI 概念

ROI（Region of Interest）即感兴趣区域，用于限定车牌识别的有效区域，减少误识别。

配置方式

Web 可视化：首页连接状态面板中可拖拽设置 ROI 区域
手动配置：在 config.ini 的 [config] 段填写坐标值

参数说明

参数	说明
roi_in_x, roi_in_y	进场区域左上角坐标（像素）
roi_in_w, roi_in_h	进场区域宽高（像素）
roi_in_enabled	1=启用进场 ROI，0=关闭
roi_out_x, roi_out_y	出场区域左上角坐标
roi_out_w, roi_out_h	出场区域宽高
roi_out_enabled	1=启用出场 ROI
roi_debug_enabled	1=在抓拍图上绘制 ROI 框（调试用）

开启 roi_debug_enabled=1 后，抓拍照片上会显示红色 ROI 框线，便于确认区域位置是否准确。

9. 交替锁定机制 ▼

机制说明

交替锁定防止同一车牌短时间内进出频繁触发（如车辆在门口调头）。同一车牌从"进"切换到"出"（或反之），必须间隔 in_out_interval 分钟以上。

工作流程

车牌 A 被识别为"进"方向
5 分钟内（默认）车牌 A 再次被识别为"出"方向
系统判定为异常，创建交替锁定记录
锁定期间该车牌不会被上传
超过 2 小时锁定自动清零，或手动在"锁定管理"页面清除

配置

参数	默认值	说明
in_out_interval	5	交替锁定间隔（⚠️ 单位分钟），小于此间隔的进/出切换会被锁定
AlternatingMerge	0	交替合并开关

in_out_interval 单位是分钟，不是秒！config.ini 填 5 表示 5 分钟 = 300 秒。系统内部会自动 ×60 转换。

10. 登录认证与权限 ▼

角色定义

角色	Role值	可访问页面
普通用户	0	首页、视频、称重、锁定管理
管理员	1	普通用户 + 系统配置
超级管理员	2	所有页面（含系统监控、frpc管理、SSH密钥、日志）

默认账号

用户名	密码	角色
admin	zhongjin188A	超级管理员
zhonjin	zhonjin	普通用户

安全特性

密码使用 bcrypt 加密存储（cost=12）
连续 max_failed_attempts 次登录失败后锁定账号
CSRF Token 防护所有状态变更请求
Session 超时自动失效
登录速率限制

密码重置

运行 python3 reset_passwords.py，脚本会自动查找 data/auth.db 并重置所有用户密码为默认值。

11. frpc 内网穿透 ▼

功能说明

系统内置 frpc 管理，支持：

查看 frpc 运行状态和隧道列表
在线编辑 frpc.toml 配置（自动备份）
一键重启 frpc 服务（需 sudoers 配置）
重启失败自动回滚配置
受保护隧道标记，防止误删

sudoers 配置

PlateRecApp 以非 root 用户运行时，需要配置 sudoers 授权 frpc 管理权限：

sudo bash scripts/setup_frpc_sudoers.sh [运行用户名]

12. SSL/HTTPS 配置 ▼

两种方式

应用内置 SSL：在 [ssl] 段配置证书和私钥路径，PlateRecApp 直接提供 HTTPS
Nginx 反向代理（推荐）：PlateRecApp 监听 HTTP，Nginx 处理 SSL 终止

config.ini 配置

[ssl]
enabled=1
cert_path=/path/to/cert.pem
key_path=/path/to/key.pem

13. 系统监控与日志 ▼

系统监控（实时）

CPU 使用率（含每核使用率、1/5/15分钟负载均值）
内存使用率（总量/已用/可用）
磁盘使用率（根分区容量/已用/可用）
CPU 温度监控，超阈值告警（阈值由 temp_alert_threshold 配置）
CPU 使用率告警（阈值由 cpu_alert_threshold 配置）
PlateRecApp 进程资源占用（RSS 内存、CPU 占用）
frpc 运行状态
MQTT 连接状态
称重系统连接状态

数据来源：通过读取 /proc、/sys、statvfs 等系统接口实时采集，页面每 2 秒自动刷新。

历史监控数据（v37 新增）

系统自动采集并存储监控数据到 SQLite 数据库（data/system_metrics.db），支持历史趋势查询。

采集间隔：monitor_interval（默认 2 秒），通过 delta 法计算 CPU 使用率，不阻塞采集线程
定时刷盘：每日 flush_time（默认 23:20）将内存监控数据批量写入 system_metrics.db，减少 SD 卡写入次数（v38 起）
三级存储：原始数据（2秒间隔）→ 小时聚合 → 日聚合，自动降采样
自动清理：全量数据保留 history_retention_days 天（默认 7 天），聚合数据保留 aggregation_retention_days 天（默认 365 天）
历史查询 API：/api/monitor/history?range=1h|6h|24h|7d|30d，自动选择合适的数据粒度
统计接口：/api/monitor/stats 返回数据库记录数和运行状态

💡 历史数据页面路径：/history，可查看 CPU、内存、温度、磁盘等指标的趋势图表。

SD 卡写入保护策略（v38）

系统针对树莓派 SD 卡/eMMC 写入寿命问题，统一采用"内存缓冲 + 每日定时写盘"策略：

系统监控：采集数据全部缓存在内存（~5MB），每天 23:20 一次性写入 system_metrics.db。相比每 30 秒写盘，每日写入从 2880 次降至 1 次
运行日志：stdout/stderr 通过 pipe 重定向到内存环形缓冲区，Web 日志页面实时从内存读取。每天 23:20 写入 PlateRecApp_YYYYMMDD.log
旧版日志清理自动禁用：内存模式启用时，凌晨 2 点的旧版 daily_log_cleanup()（copytruncate）自动跳过，避免无意义的 SD 卡读写
退出安全刷盘：程序退出（SIGTERM/SIGINT）时自动执行最后一次刷盘，防止数据丢失

💡 两个子系统的 flush_time 均配置为 23:20，分别在 [log] 和 [system] 段中设置，可独立调整。

日志管理（v36 内存缓冲）

内存缓冲模式（enabled=1，默认）：所有日志写入内存环形缓冲区，Web 日志页面直接从内存读取，零磁盘 I/O
直写文件模式（enabled=0）：传统模式，日志直接写入文件
定时刷盘：每日 flush_time（默认 23:20）自动将内存日志批量写入 PlateRecApp_YYYYMMDD.log
退出刷盘：auto_flush_on_exit=1 时，收到 SIGTERM/SIGINT 信号立即刷盘，防止日志丢失
stdout 捕获：redirect_stdout=1 时，stdout/stderr 通过 pipe 重定向到内存缓冲区，统一收集
Web 界面实时查看日志（支持 Tail 模式），显示内存使用率和缓冲状态
超期日志文件自动清理（由 retention_days 控制）
支持手动触发刷盘（Web 页面操作）

14. Web 管理功能 ▼

页面列表

页面	路径	权限	说明
监控首页	/	所有用户	实时监控、识别记录、连接状态、ROI设置
视频预览	/video	所有用户	实时视频流预览
称重记录	/weight	所有用户	称重数据查看
锁定管理	/locks	所有用户	交替锁定记录查看和清除
帮助手册	/help	超级管理员	系统配置文档
系统配置	/config	管理员+	config.ini 在线编辑
系统监控	/system	超级管理员	CPU/内存/温度/磁盘监控
frpc 管理	/frpc	超级管理员	内网穿透状态和配置
SSH 密钥	/ssh-keys	超级管理员	SSH 公钥管理
日志管理	/logs	超级管理员	系统日志查看
登录	/login	公开	用户登录页面

15. 数据库与备份 ▼

数据库文件

文件	路径	说明
认证数据库	data/auth.db	用户账号、密码、Session
识别记录	data/upload_records.db	车牌识别上传记录
系统监控	data/system_metrics.db	性能监控时序数据（原始+小时聚合+日聚合）

v29 版本起，所有数据库统一存放在 data/ 目录下。系统首次启动时会自动将旧路径数据库迁移到新位置（旧文件保留为备份）。

备份建议

定期备份 data/ 目录和 config.ini
frpc 配置修改时会自动备份到 backup_path 指定位置
照片数据在 PhotoMaxCapacityMB 限制内自动管理

16. 常见问题 FAQ ▼

Q: 摄像头连接失败怎么办？

A: 检查以下几点：

确认 RTSP 地址格式正确，在 VLC 中测试能否播放
检查网络连通性：ping 摄像头IP
尝试修改 rtsp_transport=tcp（比 UDP 更稳定）
查看日志：tail -f PlateRecApp.log

Q: 识别率低怎么办？

A: 优化建议：

启用 ROI 区域，缩小识别范围到车道区域
调整 PLATE_CONFIDENCE_THRESHOLD（适当降低可增加识别率，但可能增加误识别）
确保摄像头角度和光照条件良好
开启 roi_debug_enabled=1 确认 ROI 区域位置

Q: frpc 重启失败？

A: 检查：

确认已配置 sudoers：sudo bash scripts/setup_frpc_sudoers.sh
检查 frpc.toml 配置语法是否正确
查看 frpc 服务状态：systemctl status frpc
查看 frpc 日志：journalctl -u frpc -n 50

Q: 登录后页面显示 403？

A: 这是因为当前用户角色没有该页面的访问权限。普通用户无法访问配置和管理页面，需要管理员或超级管理员账号。

Q: 如何修改密码？

A: 目前通过命令行重置：

python3 reset_passwords.py

Q: 数据库路径错误怎么办？

A: v29 版本起数据库统一在 data/ 目录。如果是从旧版升级，启动时会自动迁移。如迁移失败，手动将 upload_records.db 和 upload_records_auth.db 复制到 data/ 目录并重命名。

Q: in_out_interval 填 5 是 5 秒还是 5 分钟？

A: 5 分钟。这个参数的单位是分钟，不是秒。系统内部会自动乘以 60 转换为秒。填 5 = 300 秒。