系统简介

车牌识别系统（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

一键部署脚本（推荐）

代码包内置 scripts/deploy.sh，覆盖编译→备份→部署→服务安装→启动→健康检查全流程，默认部署目录 /opt/openAI/project/003.PlateRecAPP、运行用户 stevenroc、服务名 PlateRecApp（均可用环境变量 APP_DIR/RUN_USER/SVC_NAME 覆盖）：

# 首次：安装编译/运行依赖（需 root）
sudo bash scripts/deploy.sh deps

# 一键编译+部署+重启（部署前自动备份当前版本到 backup/，保留最近 5 个）
sudo bash scripts/deploy.sh deploy      # 或直接 sudo bash scripts/deploy.sh

# 日常运维
bash scripts/deploy.sh status           # 服务状态 + 8080/8079 端口 + 进程 + 磁盘
bash scripts/deploy.sh logs             # 跟踪 PlateRecApp.log
bash scripts/deploy.sh journal          # 跟踪 systemd journal
bash scripts/deploy.sh restart          # 重启服务
sudo bash scripts/deploy.sh rollback    # 回滚到上一次备份
sudo bash scripts/deploy.sh sudoers     # 配置 frpc 管理 sudoers 权限

systemd 服务配置

PlateRecApp 服务文件路径：/etc/systemd/system/PlateRecApp.service（由 deploy.sh 自动生成，内容等价于）：

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++ 应用自管理）

[sync] 车牌称重并行同步配置（v43 新增）

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

[frpc] 内网穿透配置

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

[feishu] 飞书通知配置

[weight] 称重系统配置

[terminal] 终端/SSH 配置

摄像头地址格式

标准 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. 飞书通知：异常报警发送飞书群消息

照片存储与自动清理

• 照片保存在 PlateJPG/ 目录下，文件名格式：车牌号_时间戳_方向.jpg（如 沪FQ7108_1787365677_side_out.jpg）
• 系统每日凌晨 2:00 自动执行照片清理任务（间隔 24 小时）
• 清理策略：当 PlateJPG/ 目录下所有 .jpg 文件总大小超过 PhotoMaxCapacityMB（默认 1024MB）时，按文件修改时间从旧到新逐个删除，直到总大小降至阈值以下
• 删除照片后递归清理空子目录
• 清理日志输出示例：

  [照片清理] PlateJPG/ 当前 1156 MB / 1024 MB 阈值，共 8234 个文件
  [照片清理] 删除 1523 张照片(按时间从旧到新)，释放 156 MB，当前 1000 MB
  [照片清理] 同步清空DB路径字段: 2847 个字段已更新

照片清理与数据库同步（v41 修复）

照片被物理删除后，系统同步清空 upload_records 表中对应的 lo_photo_path / hi_photo_path 字段（设为 NULL）：

• 业务记录（车牌号、联单编号、抓拍时间、上传状态等）完整保留，仅清空路径字段
• Web 前端路径为 NULL 时显示灰色斜体「已清理」占位，不再显示 broken image
• 即使 DB 清理与页面加载存在竞态，<img onerror> 也会自动替换为「已清理」
• 程序启动时自动执行一次孤儿路径扫描（db_purge_missing_photo_paths），修复历史遗留数据

启用条件

在 [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 吨视为异常，丢弃

阈值说明

• weight_threshold_in：进场最低重量（吨），低于此值可能表示空车
• weight_threshold_out：出场最低重量（吨）
• default_entry_weight：无法获取称重数据时的默认进场重量
• default_exit_weight：无法获取称重数据时的默认出场重量
• weight_detection_time：称重检测时间（毫秒，默认 5000）
• tcp_connect_timeout：TCP 连接超时（毫秒，默认 3000）
• MAX_UPLOAD_RETRIES：上传最大重试次数（默认 3）
• RETRY_DELAY_MS：重试延迟（毫秒，默认 1000）

配置方式

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

参数说明

机制说明

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

工作流程

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

角色定义

默认账号

安全特性

• 密码 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 温度监控，超阈值告警（阈值由 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 返回数据库记录数和运行状态

SD 卡写入保护策略（v38）

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

日志管理（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 控制），支持手动触发刷盘

Tab 分离：实时数据 + 历史查询（v41 新增）

首页和称重页均改为 Tab 分离结构，自动刷新与手动查询完全独立：

两个 Tab 使用独立的状态和函数，互不干扰。切换 Tab 时自动加载对应数据；重试操作后根据当前 Tab 智能刷新对应数据源。

分类查询筛选条件（v41）

历史查询 Tab 支持多维度组合筛选（所有条件 AND 组合）：

分页控件（v41）

• 每页条数：可选 20 / 50 / 100 条
• 页码导航：首页 / 上一页 / 页码（当前页前后各 2 页，含首末页和省略号）/ 下一页 / 末页
• 跳转：输入页码 + GO 按钮快速跳转
• 信息栏：显示"第 X/Y 页 · 共 Z 条"

数据库文件

upload_records 表结构

备份建议

• 定期备份 data/ 目录和 config.ini
• nginx SSL 证书和配置文件备份：/etc/nginx/ssl/、/etc/nginx/conf.d/
• frpc 配置修改时系统自动备份
• 照片数据在 PhotoMaxCapacityMB 限制内自动管理，重要照片建议另行备份

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: 照片被自动清理后，Web 页面看到"已清理"怎么办？

A: 这是正常现象。当 PlateJPG/ 目录总大小超过 PhotoMaxCapacityMB（默认 1024MB）时，系统每日凌晨 2:00 自动删除最旧的照片释放空间。被删除照片对应的数据库记录仍保留（业务数据不丢失），Web 页面显示灰色「已清理」占位。如需保留更多照片，调大该配置值。

Q: 日志中出现 [路径校验] 转换绝对路径失败 错误？

A: 此错误在旧版本（v41 修复前）出现，原因是照片被物理删除后 DB 路径字段未同步清空，前端仍请求已删除文件。v41 已修复：删除照片时通过 basename 匹配同步清空 DB 路径字段，启动时自动扫描孤儿路径，且 /photo 接口对缺失文件静默返回 404 不再打 ERROR 日志。升级后此错误不再出现。

Q: 如何调整照片存储上限？

A: 修改 config.ini 的 [config] 段中 PhotoMaxCapacityMB 值并重启服务。例如：

[config]
PhotoMaxCapacityMB=2048   # 调整为 2GB

Q: 称重页的"待上传"状态是什么意思？

A: 称重记录上传状态筛选比首页多一个「待上传」选项，对应数据库中 upload_status = 0 的记录，即称重数据尚未成功上传到云端 API，可通过此筛选快速定位需重试的记录。

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

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