系统简介

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

• 多路 RTSP 摄像头实时抓拍识别（进场/出场/侧面进/侧面出）
• 车牌识别结果自动上传至云端 API
• 称重系统对接（TCP 协议），自动关联车牌与称重数据
• MQTT 协议实时推送识别结果
• 飞书群消息通知（异常报警）
• Web 管理界面（监控首页、视频预览、系统配置、锁定管理等）
• frpc 内网穿透管理 + Nginx stream + ssl_preread 协议分流（HTTP 自动跳 HTTPS）
• 登录认证与角色权限控制
• SD 卡写入寿命保护（内存缓冲 + 每日定时写盘）

运行环境

网络架构总览（v2 — nginx stream + ssl_preread 方案）

外网客户端                        frps 服务器                    本机（树莓派5）
─────────                        ─────────                    ─────────────
                                                               ┌─ TLS → nginx stream → C++ HTTPS:8080 (透传)
https://mqtt.zhonjin.com:40963/  ─TCP─→  discover.zhonjin.com:9443  ─TCP─→  frpc ─→ nginx:40963 (stream+ssl_preread)
http://mqtt.zhonjin.com:40963/   ─TCP─→            ↑                ─TCP─→  frpc ─→└─ HTTP → nginx:8081 (301→HTTPS)
https://mqtt.zhonjin.com:40964/  ─TCP─→            ↑                ─TCP─→  frpc ─→ nginx:8082 (HTTPS代理) → ttyd:7681

目录结构

编译部署

1. 解压代码包：tar xzf fix24_vXX.tar.gz
2. 编译：cd fix24/build && cmake .. && make -j4
3. 部署文件到安装目录（如 /opt/openAI/project/003.PlateRecAPP/）
4. 复制 HTML 文件：cp -r assets/web/ /安装目录/assets/web/
5. 配置 sudoers（frpc 管理需要）：sudo bash scripts/setup_frpc_sudoers.sh
6. 安装 nginx stream 模块：sudo apt install libnginx-mod-stream
7. 部署 nginx stream 配置文件（详见第 12 章）
8. 部署 SSL 证书（C++ 应用自管理，详见第 13 章）
9. 修改 config.ini 配置（参考下文各节）
10. 启动服务：sudo systemctl restart nginx && sudo systemctl restart PlateRecApp

systemd 服务配置

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

Unit]
Description=PlateRecApp License Plate Recognition System
After=network.target frpc.service

[Service]
User=stevenroc
Group=stevenroc
WorkingDirectory=/opt/openAI/project/003.PlateRecAPP
ExecStartPre=/bin/sleep 10
ExecStart=/opt/openAI/project/003.PlateRecAPP/PlateRecApp
TimeoutStartSec=30
TimeoutStopSec=10
Restart=on-failure
RestartSec=5
StandardOutput=append:/opt/openAI/project/003.PlateRecAPP/PlateRecApp.log
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

密码重置

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

Nginx 服务配置（v2 — stream 方案）

安装 stream 模块并部署配置：

# 安装 stream 模块（必须）
sudo apt install -y libnginx-mod-stream

# 验证模块
nginx -V 2>&1 | grep stream

# 替换 nginx.conf（详见第 12 章）
sudo cp nginx-stream.conf /etc/nginx/nginx.conf

# 验证配置
sudo nginx -t

# 启动/重载
sudo systemctl enable nginx
sudo systemctl restart nginx

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

[config] 核心识别配置

[server] Web 服务配置

[mqtt] MQTT 上报配置

[auth] 登录认证配置

[ssl] HTTPS 配置（v2 — C++ 应用自管理）

[system] 系统监控配置（v38 内存缓冲）

[frpc] 内网穿透配置

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

摄像头地址格式

标准 RTSP 地址格式：

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

四路摄像头说明

硬件解码（树莓派5推荐配置）

识别流程

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

启用条件

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

配置示例

[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

工作原理

称重系统通过 TCP 协议与称重地磅通信，车牌识别成功后自动读取称重数据并关联上传。

重量判定逻辑

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

配置方式

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

参数说明

机制说明

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

角色定义

默认账号

安全特性

• 密码 bcrypt 加密存储（cost=12）
• 连续登录失败锁定账号
• CSRF Token 防护
• Session 超时自动失效
• 登录速率限制

配置文件位置

frpc 配置文件路径由 config.ini 的 [frpc] config_path 指定，通常为安装目录下的 frpc.toml。

v2 方案 — nginx stream 分流（推荐）

使用 nginx stream + ssl_preread 方案，只需一个公网端口 40963 即可同时处理 HTTP 和 HTTPS：

# frpc.toml — v2 方案（nginx stream 分流）

serverAddr = "discover.zhonjin.com"
serverPort = 9443
auth.method = "token"
auth.token  = "你的frps认证Token"
transport.tls.enable = true
clientID = "ssd_40960"

# frpc Admin HTTP API
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "你的管理密码"

# 隧道1：主服务（外网40963→本机nginx:40963，stream自动分流HTTP/HTTPS）
[[proxies]]
name       = "plate_web"
type       = "tcp"
localIP    = "127.0.0.1"
localPort  = 40963    # ← 转发到 nginx stream，不是 C++ 的 8080
remotePort = 40963

# 隧道2：ttyd终端（外网40964→本机nginx:8082→ttyd:7681）
[[proxies]]
name       = "ttyd_web"
type       = "tcp"
localIP    = "127.0.0.1"
localPort  = 8082     # ← nginx HTTPS 反向代理（SSL 终止 + WebSocket）
remotePort = 40964

隧道说明（v2）

v2 数据流向

HTTP  流量: 公网:40963 → frpc → nginx:40963 (stream) → $ssl_preread=""  → 127.0.0.1:8081 (nginx HTTP) → 301 重定向到 HTTPS
HTTPS 流量: 公网:40963 → frpc → nginx:40963 (stream) → $ssl_preread≠"" → 127.0.0.1:8080 (C++ HTTPS) → 直接处理
Web SSH:  公网:40964 → frpc → nginx:8082 (HTTPS反向代理, SSL终止) → 127.0.0.1:7681 (ttyd HTTP)

参数详解

隧道保护

在 config.ini [frpc] 段配置受保护隧道，防止 Web 界面误删关键隧道：

protected_tunnels = plate_web,ttyd_web

frpc 管理命令

# 查看 frpc 状态
systemctl status frpc

# 重启 frpc
sudo systemctl restart frpc

# 查看 frpc 日志
tail -f /var/log/frpc.log

# 通过 Admin API 查看隧道状态
curl -u admin:密码 http://127.0.0.1:7400/api/status/tcp

架构说明

v2 方案使用 nginx 的 stream 模块 + ssl_preread 功能，在 TCP 层面检测流量类型并自动分流：

• 端口 40963：nginx stream 监听，检测协议类型（TLS / HTTP）
• TLS 流量 → 透传到 C++ HTTPS 服务（127.0.0.1:8080）
• HTTP 流量 → nginx HTTP 模块（127.0.0.1:8081）→ 301 重定向到 HTTPS

nginx.conf 完整配置

文件路径：/etc/nginx/nginx.conf（替换整个文件）

# 加载 stream 动态模块
load_module modules/ngx_stream_module.so;

events {
    worker_connections 1024;
}

# ============================================================
# stream 块 — TCP 层协议分流（在 http 块外面）
# ============================================================
stream {
    # 根据 ssl_preread 检测结果选择后端
    # $ssl_preread_protocol 的可能值：
    #   ""          → HTTP 流量（非 TLS）
    #   "TLSv1.2"   → TLS 1.2
    #   "TLSv1.3"   → TLS 1.3
    map $ssl_preread_protocol $backend {
        ""        http_backend;    # HTTP → nginx HTTP 8081
        default   tls_backend;     # TLS → C++ HTTPS 8080
    }

    # TLS 后端 — C++ HTTPS 服务
    upstream tls_backend {
        server 127.0.0.1:8080;
    }

    # HTTP 后端 — nginx HTTP 301 重定向
    upstream http_backend {
        server 127.0.0.1:8081;
    }

    # 主服务器 — 监听公网端口
    server {
        listen 40963;
        proxy_pass $backend;
        ssl_preread on;          # 启用 SSL 预读检测协议
    }
}

# ============================================================
# http 块 — HTTP → HTTPS 301 重定向
# ============================================================
http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    access_log /var/log/nginx/access.log;
    error_log  /var/log/nginx/error.log;

    # HTTP → HTTPS 301 重定向
    server {
        listen 8081;
        server_name _;
        return 301 https://$host:40963$request_uri;
    }

    # ============================================================
    # ttyd Web 终端 HTTPS 反向代理（端口 8082）
    # ============================================================
    # frpc 隧道：外网 40964 → nginx:8082 → ttyd:7681
    # nginx 做 SSL 终止，再通过 HTTP 代理到 ttyd（含 WebSocket 支持）
    server {
        listen 8082 ssl;
        server_name _;

        ssl_certificate     /etc/nginx/ssl/plate_fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/plate_privkey.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5:!RC4;
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL_Ttyd:5m;
        ssl_session_timeout 1h;

        location / {
            proxy_pass http://127.0.0.1:7681;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # WebSocket 支持（ttyd 核心通信方式）
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            # ttyd 长连接超时
            proxy_read_timeout 86400s;
            proxy_send_timeout 86400s;
        }
    }
}

核心原理

部署步骤

1. 安装 stream 模块：sudo apt install -y libnginx-mod-stream
2. 验证模块：ls -l /usr/lib/nginx/modules/ngx_stream_module.so
3. 备份原配置：sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
4. 替换配置：sudo cp nginx-stream.conf /etc/nginx/nginx.conf
5. 删除默认站点（如有）：sudo rm -f /etc/nginx/sites-enabled/default
6. 验证配置：sudo nginx -t
7. 启动 nginx：sudo systemctl enable nginx && sudo systemctl restart nginx

前置条件

验证方法

# 检查端口监听
ss -tlnp | grep -E '40963|8080|8081'
# 预期输出：
# LISTEN  0.0.0.0:40963  nginx (stream)
# LISTEN  127.0.0.1:8081  nginx (http 301)
# LISTEN  0.0.0.0:8080  PlateRecApp (HTTPS)

# 测试 HTTP 重定向（应返回 301）
curl -I http://localhost:40963/
# 预期：HTTP/1.1 301 Moved Permanently
#       Location: https://localhost:40963/

# 测试 HTTPS（应返回 200）
curl -kI https://localhost:40963/
# 预期：HTTP/1.1 200 OK

# 浏览器测试（清除缓存或用无痕模式）
# 访问 http://mqtt.zhonjin.com:40963/ → 自动跳转到 https://mqtt.zhonjin.com:40963/

端口规划总结

config.ini [ssl] 段配置

[ssl]
enabled=1
cert_path=ssl/plate_fullchain.pem
key_path=ssl/plate_privkey.pem

方式一：Let's Encrypt 证书 — 阿里云 DNS 验证（推荐）

本项目使用 frpc 内网穿透，无公网 80 端口，因此不能使用传统的 HTTP-01 验证。推荐使用 DNS-01 验证，通过阿里云 DNS API 自动完成，不需要任何端口。

方案对比

一键部署

# 1. 安装 certbot + 阿里云 DNS 插件
sudo apt update
sudo apt install -y certbot python3-pip
sudo pip3 install certbot-dns-aliyun

# 2. 配置阿里云 AccessKey（RAM 子账号，需 AliyunDNSFullAccess 权限）
sudo mkdir -p /etc/letsencrypt
sudo vim /etc/letsencrypt/aliyun.ini
# 内容：
#   dns_aliyun_access_key = 你的AccessKeyID
#   dns_aliyun_access_key_secret = 你的AccessKeySecret
sudo chmod 600 /etc/letsencrypt/aliyun.ini

# 3. 一键申请通配符证书（自动通过 DNS API 验证）
sudo certbot certonly \
    --authenticator dns-aliyun \
    --dns-aliyun-credentials /etc/letsencrypt/aliyun.ini \
    --dns-aliyun-propagation-seconds 30 \
    --server https://acme-v02.api.letsencrypt.org/directory \
    --agree-tos --no-eff-email \
    --email admin@zhonjin.com \
    -d mqtt.zhonjin.com \
    -d "*.zhonjin.com"

# 4. 部署证书到 PlateRecApp
mkdir -p ssl/
sudo cp /etc/letsencrypt/live/mqtt.zhonjin.com/fullchain.pem ssl/plate_fullchain.pem
sudo cp /etc/letsencrypt/live/mqtt.zhonjin.com/privkey.pem   ssl/plate_privkey.pem
sudo chown stevenroc:stevenroc ssl/*.pem
chmod 644 ssl/plate_fullchain.pem
chmod 600 ssl/plate_privkey.pem

# 5. 配置自动续期（每天 3:00 检查，续期后自动部署）
(crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet --deploy-hook /opt/openAI/project/003.PlateRecAPP/scripts/renew_ssl.sh") | crontab -

# 6. 重启 PlateRecApp
sudo systemctl restart PlateRecApp

续期部署脚本 renew_ssl.sh

#!/bin/bash
# /opt/openAI/project/003.PlateRecAPP/scripts/renew_ssl.sh
DOMAIN="mqtt.zhonjin.com"
SSL_DIR="/opt/openAI/project/003.PlateRecAPP/ssl"

cp /etc/letsencrypt/live/${DOMAIN}/fullchain.pem ${SSL_DIR}/plate_fullchain.pem
cp /etc/letsencrypt/live/${DOMAIN}/privkey.pem   ${SSL_DIR}/plate_privkey.pem
chown stevenroc:stevenroc ${SSL_DIR}/*.pem
chmod 644 ${SSL_DIR}/plate_fullchain.pem
chmod 600 ${SSL_DIR}/plate_privkey.pem
systemctl restart PlateRecApp
echo "$(date) SSL 证书续期部署成功" >> /opt/openAI/project/003.PlateRecAPP/ssl_renew.log

阿里云 RAM 权限配置

1. 登录 RAM 控制台 → 用户 → 创建用户
2. 勾选 OpenAPI 调用访问，保存 AccessKey ID 和 Secret
3. 添加权限：AliyunDNSFullAccess（云解析 DNS 管理）

方式二：自签名证书

无公网域名时使用自签名证书，浏览器会显示警告但加密通信正常：

# 创建证书目录
mkdir -p ssl/

# 生成自签名证书（10年有效期）
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ssl/plate_privkey.pem \
  -out    ssl/plate_fullchain.pem \
  -days   3650 \
  -subj   "/CN=mqtt.zhonjin.com/O=PlateRecApp/C=CN"

# 设置权限
chmod 600 ssl/plate_privkey.pem
chmod 644 ssl/plate_fullchain.pem

# 重启 PlateRecApp 加载证书
sudo systemctl restart PlateRecApp

证书文件说明

v1→v2 迁移说明

系统监控（实时）

• CPU 使用率（delta 法，含每核使用率、负载均值）
• 内存使用率（总量/已用/可用）
• 磁盘使用率（根分区）
• CPU 温度，超阈值告警
• PlateRecApp 进程资源占用
• frpc/MQTT/称重连接状态

历史监控数据（v37+）

• 采集间隔：monitor_interval（默认 2 秒）
• 定时刷盘：每日 flush_time（默认 23:20）写入 system_metrics.db
• 三级存储：原始数据 → 小时聚合 → 日聚合
• 自动清理：原始数据保留 7 天，聚合数据保留 365 天
• 历史查询 API：/api/monitor/history?range=1h|6h|24h|7d|30d

SD 卡写入保护策略（v38）

• 系统监控：内存缓冲，每日 23:20 一次写入，SD 卡写入从 2880 次/天降至 1 次
• 运行日志：内存环形缓冲区，Web 日志页面零磁盘 I/O，每日 23:20 写入 PlateRecApp_YYYYMMDD.log
• 旧版日志清理：内存模式启用时自动跳过旧版 copytruncate，避免无意义读写
• 退出安全刷盘：SIGTERM/SIGINT 时立即执行最后一次刷盘

日志管理（v36 内存缓冲）

• 内存缓冲模式（默认）：所有日志写入内存，Web 页面实时读取
• 直写文件模式（enabled=0）：传统模式回退
• 支持手动触发刷盘（Web 页面操作）

数据库文件

备份建议

• 定期备份 data/ 目录和 config.ini
• nginx SSL 证书和配置文件备份：/etc/nginx/ssl/、/etc/nginx/conf.d/
• frpc 配置修改时系统自动备份

Q: HTTP 访问没有跳转到 HTTPS？

A: 检查以下几点：

• 确认 nginx stream 模块已安装：nginx -V 2>&1 | grep stream
• 确认 nginx 配置正确：sudo nginx -t
• 确认 8081 端口正在监听：ss -tlnp | grep 8081
• 确认 frpc 隧道 plate_web 正常运行（localPort 为 40963）
• 浏览器可能缓存了旧的重定向，尝试清除缓存或无痕模式
• 测试本机重定向：curl -I http://localhost:40963/，应返回 301

Q: HTTPS 访问返回错误？

A: v2 方案下 TLS 由 C++ 应用处理，检查：

• PlateRecApp 是否正在运行：systemctl status PlateRecApp
• PlateRecApp 是否启用了 HTTPS：config.ini [ssl] enabled=1
• SSL 证书文件是否存在：ls -l ssl/plate_fullchain.pem ssl/plate_privkey.pem
• nginx stream 是否正常监听：ss -tlnp | grep 40963
• nginx 错误日志：sudo tail -f /var/log/nginx/error.log

Q: unknown directive "stream"？

A: stream 模块未加载。执行：sudo apt install -y libnginx-mod-stream，确认 nginx.conf 顶部有 load_module modules/ngx_stream_module.so;

Q: frpc 重启后隧道不生效？

A: 检查 frpc.toml 配置语法：

frpc verify -c /path/to/frpc.toml

常见错误：TOML 格式问题（缺少引号、缩进错误）。通过 Web 管理界面编辑配置时系统会自动校验。

Q: 自签名证书浏览器警告怎么消除？

A: 自签名证书无法消除浏览器警告（这是正常安全行为）。解决方案：

• 方式1：使用 Let's Encrypt 免费证书（需域名解析到公网 IP）
• 方式2：在客户端将自签名 CA 证书添加到受信任的根证书列表
• 方式3：忽略警告，继续使用（加密通信正常，仅证书不受信任）

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

A: 确认 RTSP 地址格式正确，在 VLC 中测试播放。尝试 rtsp_transport=tcp。

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

A: 5 分钟。单位是分钟，系统内部自动 ×60 转为秒。

Q: 如何重置管理员密码？

cd /opt/openAI/project/003.PlateRecAPP
python3 reset_passwords.py