Home Explore Help
Register Sign In
steven_roc
/
PlateRecApp
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: db052aa98c
Branches Tags
PlateRecApp
/
assets
/
web
/
help20260828.html

help20260828.html 60 KB
History Raw

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156 
  1. <!DOCTYPE html>
    2. 

  2. <html lang="zh-CN">
    3. 

  3. <head>
    4. 

  4. <meta charset="UTF-8">
    5. 

  5. <meta name="viewport" content="width=device-width,initial-scale=1">
    6. 

  6. <title>帮助手册 - 车牌识别系统</title>
    7. 

  7. <style>
    8. 

  8. *{box-sizing:border-box;margin:0;padding:0}
    9. 

  9. body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f0f2f5;color:#333}
    10. 

  10. .navbar{background:#1a1a2e;color:#fff;padding:12px 20px;display:flex;align-items:center;gap:20px;box-shadow:0 2px 8px rgba(0,0,0,0.15)}
    11. 

  11. .navbar a{color:#ccc;text-decoration:none;padding:6px 12px;border-radius:4px;font-size:14px}
    12. 

  12. .navbar a:hover,.navbar a.active{background:rgba(255,255,255,0.15);color:#fff}
    13. 

  13. .navbar .brand{font-size:16px;font-weight:bold;color:#4fc3f7;margin-right:10px}
    14. 

  14. .container{max-width:960px;margin:20px auto;padding:0 16px}
    15. 

  15. .card{background:#fff;border-radius:8px;margin-bottom:16px;box-shadow:0 1px 4px rgba(0,0,0,0.08);overflow:hidden}
    16. 

  16. .card-title{background:#263238;color:#fff;padding:10px 16px;font-size:14px;font-weight:600;display:flex;align-items:center;justify-content:space-between;cursor:pointer;user-select:none}
    17. 

  17. .card-title:hover{background:#37474f}
    18. 

  18. .card-title .arrow{transition:transform 0.2s;font-size:12px}
    19. 

  19. .card-title.collapsed .arrow{transform:rotate(-90deg)}
    20. 

  20. .card-body{padding:16px 20px;line-height:1.8;font-size:14px}
    21. 

  21. .card-body.hidden{display:none}
    22. 

  22. h3{color:#1a1a2e;margin:16px 0 8px;font-size:15px;border-left:3px solid #667eea;padding-left:10px}
    23. 

  23. h4{color:#333;margin:12px 0 6px;font-size:14px}
    24. 

  24. table{width:100%;border-collapse:collapse;margin:8px 0 16px;font-size:13px}
    25. 

  25. th{background:#f5f5f5;padding:8px 10px;text-align:left;font-weight:600;border-bottom:2px solid #e0e0e0;white-space:nowrap}
    26. 

  26. td{padding:8px 10px;border-bottom:1px solid #f0f0f0;vertical-align:top}
    27. 

  27. td:first-child{font-family:monospace;color:#d32f2f;white-space:nowrap;font-size:12px}
    28. 

  28. code{background:#f5f5f5;padding:2px 6px;border-radius:3px;font-size:12px;color:#d32f2f;font-family:monospace}
    29. 

  29. pre{background:#1e1e2e;color:#cdd6f4;padding:14px 18px;border-radius:6px;font-size:12px;overflow-x:auto;margin:8px 0 16px;line-height:1.6}
    30. 

  30. pre code{background:none;color:#cdd6f4;padding:0;font-size:12px}
    31. 

  31. .tip{background:#e8f5e9;border-left:4px solid #4caf50;padding:10px 14px;margin:8px 0;border-radius:0 4px 4px 0;font-size:13px}
    32. 

  32. .warn{background:#fff3e0;border-left:4px solid #ff9800;padding:10px 14px;margin:8px 0;border-radius:0 4px 4px 0;font-size:13px}
    33. 

  33. .note{background:#e3f2fd;border-left:4px solid #2196f3;padding:10px 14px;margin:8px 0;border-radius:0 4px 4px 0;font-size:13px}
    34. 

  34. ul{padding-left:20px;margin:6px 0}
    35. 

  35. li{margin:4px 0;font-size:13px;line-height:1.7}
    36. 

  36. .toc{background:#fff;border-radius:8px;padding:16px 24px;margin-bottom:16px;box-shadow:0 1px 4px rgba(0,0,0,0.08)}
    37. 

  37. .toc h2{font-size:16px;color:#1a1a2e;margin-bottom:10px;border-bottom:2px solid #667eea;padding-bottom:6px}
    38. 

  38. .toc ol{padding-left:20px;columns:2;column-gap:30px}
    39. 

  39. .toc li{margin:4px 0;font-size:13px;break-inside:avoid}
    40. 

  40. .toc a{color:#667eea;text-decoration:none}
    41. 

  41. .toc a:hover{text-decoration:underline}
    42. 

  42. @media(max-width:768px){
    43. 

  43. .navbar{flex-wrap:wrap;gap:8px;padding:10px 14px}
    44. 

  44. .navbar .brand{font-size:14px;width:100%}
    45. 

  45. .navbar a{font-size:12px;padding:4px 8px}
    46. 

  46. .container{padding:0 10px;margin:10px auto}
    47. 

  47. .toc ol{columns:1}
    48. 

  48. table{font-size:12px;display:block;overflow-x:auto}
    49. 

  49. th,td{padding:6px 8px}
    50. 

  50. td:first-child{font-size:11px}
    51. 

  51. }
    52. 

  52. @media(max-width:480px){
    53. 

  53. .navbar .brand{font-size:13px}
    54. 

  54. .navbar a{font-size:11px;padding:3px 6px}
    55. 

  55. .card-body{padding:12px 14px}
    56. 

  56. }
    57. 

  57. </style>
    58. 

  58. </head>
    59. 

  59. <body>
    60. 

  60. <nav class="navbar">
    61. 

  61.   <span class="brand">🚛 车牌识别系统</span>
    62. 

  62.   <a href="/">监控首页</a>
    63. 

  63.   <a href="/video">视频预览</a>
    64. 

  64.   <a href="/locks">锁定管理</a>
    65. 

  65.   <a href="/help" class="active">帮助手册</a>
    66. 

  66. </nav>
    67. 

  67. 

  68. <div class="container">
    69. 

  69. 

  70. <div class="toc">
    71. 

  71. <h2>📋 目录</h2>
    72. 

  72. <ol>
    73. 

  73.   <li><a href="#sec1">系统概述</a></li>
    74. 

  74.   <li><a href="#sec2">快速部署指南</a></li>
    75. 

  75.   <li><a href="#sec3">config.ini 完整配置说明</a></li>
    76. 

  76.   <li><a href="#sec4">RTSP 摄像头配置</a></li>
    77. 

  77.   <li><a href="#sec5">车牌识别上传流程</a></li>
    78. 

  78.   <li><a href="#sec6">MQTT 数据上报配置</a></li>
    79. 

  79.   <li><a href="#sec7">称重系统对接</a></li>
    80. 

  80.   <li><a href="#sec8">ROI 区域识别配置</a></li>
    81. 

  81.   <li><a href="#sec9">交替锁定机制</a></li>
    82. 

  82.   <li><a href="#sec10">登录认证与权限</a></li>
    83. 

  83.   <li><a href="#sec11">frpc.toml 内网穿透配置详解</a></li>
    84. 

  84.   <li><a href="#sec12">Nginx 反向代理配置详解</a></li>
    85. 

  85.   <li><a href="#sec13">SSL/HTTPS 证书配置</a></li>
    86. 

  86.   <li><a href="#sec14">系统监控与日志</a></li>
    87. 

  87.   <li><a href="#sec15">Web 管理功能</a></li>
    88. 

  88.   <li><a href="#sec16">数据库与备份</a></li>
    89. 

  89.   <li><a href="#sec17">常见问题 FAQ</a></li>
    90. 

  90. </ol>
    91. 

  91. </div>
    92. 

  92. 

  93. <!-- 1. 系统概述 -->
    94. 

  94. <div class="card" id="sec1">
    95. 

  95. <div class="card-title" onclick="toggleCard(this)">1. 系统概述 <span class="arrow">▼</span></div>
    96. 

  96. <div class="card-body">
    97. 

  97. <h3>系统简介</h3>
    98. 

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

  99. <ul>
    100. 

  100.   <li>多路 RTSP 摄像头实时抓拍识别（进场/出场/侧面进/侧面出）</li>
    101. 

  101.   <li>车牌识别结果自动上传至云端 API</li>
    102. 

  102.   <li>称重系统对接（TCP 协议），自动关联车牌与称重数据</li>
    103. 

  103.   <li>MQTT 协议实时推送识别结果</li>
    104. 

  104.   <li>飞书群消息通知（异常报警）</li>
    105. 

  105.   <li>Web 管理界面（监控首页、视频预览、系统配置、锁定管理等）</li>
    106. 

  106.   <li>frpc 内网穿透管理 + Nginx stream + ssl_preread 协议分流（HTTP 自动跳 HTTPS）</li>
    107. 

  107.   <li>登录认证与角色权限控制</li>
    108. 

  108.   <li>SD 卡写入寿命保护（内存缓冲 + 每日定时写盘）</li>
    109. 

  109. </ul>
    110. 

  110. 

  111. <h3>运行环境</h3>
    112. 

  112. <table>
    113. 

  113.   <tr><th>项目</th><th>要求</th></tr>
    114. 

  114.   <tr><td>硬件</td><td>树莓派 5 8GB（推荐）</td></tr>
    115. 

  115.   <tr><td>系统</td><td>Debian 13 (trixie) / Ubuntu 24.04 aarch64</td></tr>
    116. 

  116.   <tr><td>依赖</td><td>HyperLPR3 SDK、FFmpeg、libcurl、OpenSSL、cJSON、Mosquitto、Nginx</td></tr>
    117. 

  117.   <tr><td>内网穿透</td><td>frpc（通过 systemctl 管理）</td></tr>
    118. 

  118.   <tr><td>协议分流</td><td>Nginx stream + ssl_preread（TCP 层 HTTP/HTTPS 自动检测分流）</td></tr>
    119. 

  119. </table>
    120. 

  120. 

  121. <h3>网络架构总览（v2 — nginx stream + ssl_preread 方案）</h3>
    122. 

  122. <pre>外网客户端                        frps 服务器                    本机（树莓派5）
    123. 

  123. ─────────                        ─────────                    ─────────────
    124. 

  124.                                                                ┌─ TLS → nginx stream → C++ HTTPS:8080 (透传)
    125. 

  125. https://mqtt.zhonjin.com:40963/  ─TCP─→  discover.zhonjin.com:9443  ─TCP─→  frpc ─→ nginx:40963 (stream+ssl_preread)
    126. 

  126. http://mqtt.zhonjin.com:40963/   ─TCP─→            ↑                ─TCP─→  frpc ─→└─ HTTP → nginx:8081 (301→HTTPS)
    127. 

  127. https://mqtt.zhonjin.com:40964/  ─TCP─→            ↑                ─TCP─→  frpc ─→ nginx:8082 (HTTPS代理) → ttyd:7681</pre>
    128. 

  128. <div class="tip"><strong>v2 方案优势：</strong>公网只需一个端口 40963，nginx stream 在 TCP 层自动检测协议类型并分流。HTTP 自动跳 HTTPS，HTTPS 透传到 C++ 应用处理。用户只需记住一个地址。</div>
    129. 

  129. 

  130. <h3>目录结构</h3>
    131. 

  131. <table>
    132. 

  132.   <tr><th>路径</th><th>说明</th></tr>
    133. 

  133.   <tr><td>PlateRecApp</td><td>主程序二进制</td></tr>
    134. 

  134.   <tr><td>config.ini</td><td>主配置文件</td></tr>
    135. 

  135.   <tr><td>config.txt</td><td>MD5 校验配置</td></tr>
    136. 

  136.   <tr><td>hyperlpr3/</td><td>HyperLPR3 SDK 模型文件</td></tr>
    137. 

  137.   <tr><td>assets/web/</td><td>Web 页面文件（HTML/CSS/JS）</td></tr>
    138. 

  138.   <tr><td>data/</td><td>数据库目录（auth.db、upload_records.db、system_metrics.db）</td></tr>
    139. 

  139.   <tr><td>photos/</td><td>抓拍图片存储目录</td></tr>
    140. 

  140.   <tr><td>scripts/</td><td>运维脚本（sudoers 配置、密码重置等）</td></tr>
    141. 

  141. </table>
    142. 

  142. </div>
    143. 

  143. </div>
    144. 

  144. 

  145. <!-- 2. 快速部署指南 -->
    146. 

  146. <div class="card" id="sec2">
    147. 

  147. <div class="card-title" onclick="toggleCard(this)">2. 快速部署指南 <span class="arrow">▼</span></div>
    148. 

  148. <div class="card-body">
    149. 

  149. <h3>编译部署</h3>
    150. 

  150. <ol>
    151. 

  151.   <li>解压代码包：<code>tar xzf fix24_vXX.tar.gz</code></li>
    152. 

  152.   <li>编译：<code>cd fix24/build && cmake .. && make -j4</code></li>
    153. 

  153.   <li>部署文件到安装目录（如 <code>/opt/openAI/project/003.PlateRecAPP/</code>）</li>
    154. 

  154.   <li>复制 HTML 文件：<code>cp -r assets/web/ /安装目录/assets/web/</code></li>
    155. 

  155.   <li>配置 sudoers（frpc 管理需要）：<code>sudo bash scripts/setup_frpc_sudoers.sh</code></li>
    156. 

  156.   <li>安装 nginx stream 模块：<code>sudo apt install libnginx-mod-stream</code></li>
    157. 

  157.   <li>部署 nginx stream 配置文件（详见第 12 章）</li>
    158. 

  158.   <li>部署 SSL 证书（C++ 应用自管理，详见第 13 章）</li>
    159. 

  159.   <li>修改 <code>config.ini</code> 配置（参考下文各节）</li>
    160. 

  160.   <li>启动服务：<code>sudo systemctl restart nginx && sudo systemctl restart PlateRecApp</code></li>
    161. 

  161. </ol>
    162. 

  162. 

  163. <h3>systemd 服务配置</h3>
    164. 

  164. <p>PlateRecApp 服务文件路径：<code>/etc/systemd/system/PlateRecApp.service</code></p>
    165. 

  165. <pre>Unit]
    166. 

  166. Description=PlateRecApp License Plate Recognition System
    167. 

  167. After=network.target frpc.service
    168. 

  168. 

  169. [Service]
    170. 

  170. User=stevenroc
    171. 

  171. Group=stevenroc
    172. 

  172. WorkingDirectory=/opt/openAI/project/003.PlateRecAPP
    173. 

  173. ExecStartPre=/bin/sleep 10
    174. 

  174. ExecStart=/opt/openAI/project/003.PlateRecAPP/PlateRecApp
    175. 

  175. TimeoutStartSec=30
    176. 

  176. TimeoutStopSec=10
    177. 

  177. Restart=on-failure
    178. 

  178. RestartSec=5
    179. 

  179. StandardOutput=append:/opt/openAI/project/003.PlateRecAPP/PlateRecApp.log
    180. 

  180. LimitNOFILE=1048576
    181. 

  181. 

  182. [Install]
    183. 

  183. WantedBy=multi-user.target</pre>
    184. 

  184. <div class="tip">PlateRecApp 以非 root 用户运行（stevenroc），frpc 管理通过 sudoers 授权。日志输出由 v36 内存缓冲系统接管，systemd 的 StandardOutput 仅作备份。</div>
    185. 

  185. 

  186. <h3>密码重置</h3>
    187. 

  187. <p>如忘记管理员密码，运行：<code>python3 reset_passwords.py</code></p>
    188. 

  188. 

  189. <h3>Nginx 服务配置（v2 — stream 方案）</h3>
    190. 

  190. <p>安装 stream 模块并部署配置：</p>
    191. 

  191. <pre># 安装 stream 模块（必须）
    192. 

  192. sudo apt install -y libnginx-mod-stream
    193. 

  193. 

  194. # 验证模块
    195. 

  195. nginx -V 2>&amp;1 | grep stream
    196. 

  196. 

  197. # 替换 nginx.conf（详见第 12 章）
    198. 

  198. sudo cp nginx-stream.conf /etc/nginx/nginx.conf
    199. 

  199. 

  200. # 验证配置
    201. 

  201. sudo nginx -t
    202. 

  202. 

  203. # 启动/重载
    204. 

  204. sudo systemctl enable nginx
    205. 

  205. sudo systemctl restart nginx</pre>
    206. 

  206. </div>
    207. 

  207. </div>
    208. 

  208. 

  209. <!-- 3. config.ini 完整配置 -->
    210. 

  210. <div class="card" id="sec3">
    211. 

  211. <div class="card-title" onclick="toggleCard(this)">3. config.ini 完整配置说明 <span class="arrow">▼</span></div>
    212. 

  212. <div class="card-body">
    213. 

  213. <p>配置文件路径：<code>&lt;安装目录&gt;/config.ini</code>，ini 格式，section 和 key 均不区分大小写。</p>
    214. 

  214. 

  215. <h3>[config] 核心识别配置</h3>
    216. 

  216. <table>
    217. 

  217.   <tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
    218. 

  218.   <tr><td>project_name</td><td>string</td><td>-</td><td>项目名称</td></tr>
    219. 

  219.   <tr><td>point_number</td><td>string</td><td>-</td><td>站点编号</td></tr>
    220. 

  220.   <tr><td>throughway</td><td>string</td><td>-</td><td>通道名称</td></tr>
    221. 

  221.   <tr><td>rtsp_url_front_in</td><td>string</td><td>-</td><td>前侧进场摄像头 RTSP 地址</td></tr>
    222. 

  222.   <tr><td>rtsp_url_front_out</td><td>string</td><td>-</td><td>前侧出场摄像头 RTSP 地址</td></tr>
    223. 

  223.   <tr><td>rtsp_url_side_in</td><td>string</td><td>-</td><td>侧面进场摄像头 RTSP 地址</td></tr>
    224. 

  224.   <tr><td>rtsp_url_side_out</td><td>string</td><td>-</td><td>侧面出场摄像头 RTSP 地址</td></tr>
    225. 

  225.   <tr><td>app_api</td><td>string</td><td>-</td><td>云端上传 API 地址</td></tr>
    226. 

  226.   <tr><td>app_key</td><td>string</td><td>-</td><td>API 认证 Key</td></tr>
    227. 

  227.   <tr><td>app_secret</td><td>string</td><td>-</td><td>API 认证 Secret</td></tr>
    228. 

  228.   <tr><td>DEBUG_LOG</td><td>int</td><td>0</td><td>调试日志开关（0=关闭，1=开启）</td></tr>
    229. 

  229.   <tr><td>TestFlag</td><td>int</td><td>0</td><td>测试模式开关</td></tr>
    230. 

  230.   <tr><td>wType</td><td>int</td><td>0</td><td>称重类型（0=禁用，1=启用）</td></tr>
    231. 

  231.   <tr><td>TIME_WINDOW</td><td>int</td><td>5</td><td>识别时间窗口（分钟），同一车牌在窗口内不重复上传</td></tr>
    232. 

  232.   <tr><td>MAX_PHOTO_GROUPS</td><td>int</td><td>100</td><td>最大照片组数缓存</td></tr>
    233. 

  233.   <tr><td>in_out_interval</td><td>int</td><td>5</td><td>⚠️ 单位是<strong>分钟</strong>！交替锁定间隔（同一车牌进出最短时间），内部转为秒存储</td></tr>
    234. 

  234.   <tr><td>PLATE_CONFIDENCE_THRESHOLD</td><td>float</td><td>0.7</td><td>车牌识别置信度阈值（0~1），低于此值不上传</td></tr>
    235. 

  235.   <tr><td>PLATE_LOG_THRESHOLD</td><td>float</td><td>0.5</td><td>日志记录置信度阈值</td></tr>
    236. 

  236.   <tr><td>AlternatingMerge</td><td>int</td><td>0</td><td>交替合并开关（0=关闭，1=开启）</td></tr>
    237. 

  237.   <tr><td>hw_decode_mode</td><td>string</td><td>auto</td><td>硬件解码模式：auto/soft/drm</td></tr>
    238. 

  238.   <tr><td>hw_decode_device</td><td>string</td><td>/dev/dri/renderD128</td><td>硬件解码设备路径</td></tr>
    239. 

  239.   <tr><td>rtsp_transport</td><td>string</td><td>tcp</td><td>RTSP 传输协议：tcp/udp</td></tr>
    240. 

  240.   <tr><td>PhotoMaxCapacityMB</td><td>int</td><td>1024</td><td>照片目录最大容量（MB），超限自动清理旧照片</td></tr>
    241. 

  241.   <tr><td>LogRetentionDays</td><td>int</td><td>30</td><td>日志保留天数</td></tr>
    242. 

  242. </table>
    243. 

  243. 

  244. <h3>[server] Web 服务配置</h3>
    245. 

  245. <table>
    246. 

  246.   <tr><th>参数</th><th>说明</th></tr>
    247. 

  247.   <tr><td>ip</td><td>Web 服务监听地址（含端口），如 <code>0.0.0.0:8080</code>。v2 方案下 PlateRecApp 提供 HTTPS 服务（SSL 自管理），nginx stream 透传 TLS 流量到此处</td></tr>
    248. 

  248. </table>
    249. 

  249. 

  250. <h3>[mqtt] MQTT 上报配置</h3>
    251. 

  251. <table>
    252. 

  252.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    253. 

  253.   <tr><td>MQTT_HOST</td><td>-</td><td>MQTT Broker 地址（填写后自动启用 MQTT）</td></tr>
    254. 

  254.   <tr><td>MQTT_PORT</td><td>1883</td><td>MQTT Broker 端口</td></tr>
    255. 

  255.   <tr><td>MQTT_USER</td><td>-</td><td>MQTT 用户名</td></tr>
    256. 

  256.   <tr><td>MQTT_PASS</td><td>-</td><td>MQTT 密码</td></tr>
    257. 

  257.   <tr><td>MQTT_TOPIC</td><td>-</td><td>推送主题</td></tr>
    258. 

  258.   <tr><td>MQTT_CLIENT_ID</td><td>-</td><td>客户端 ID</td></tr>
    259. 

  259.   <tr><td>PLATE_COLOR</td><td>-</td><td>车牌颜色标识（随 MQTT 消息上报）</td></tr>
    260. 

  260.   <tr><td>VEHICLE_TYPE</td><td>-</td><td>车辆类型标识（随 MQTT 消息上报）</td></tr>
    261. 

  261. </table>
    262. 

  262. 

  263. <h3>[auth] 登录认证配置</h3>
    264. 

  264. <table>
    265. 

  265.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    266. 

  266.   <tr><td>enabled</td><td>1</td><td>认证开关（0=关闭，1=开启）</td></tr>
    267. 

  267.   <tr><td>db_path</td><td>data/auth.db</td><td>认证数据库路径</td></tr>
    268. 

  268.   <tr><td>session_idle_timeout</td><td>1800</td><td>Session 空闲超时（秒）</td></tr>
    269. 

  269.   <tr><td>session_max_timeout</td><td>28800</td><td>Session 最大超时（秒）</td></tr>
    270. 

  270.   <tr><td>session_remember_timeout</td><td>604800</td><td>记住登录超时（秒）</td></tr>
    271. 

  271.   <tr><td>max_failed_attempts</td><td>5</td><td>最大登录失败次数</td></tr>
    272. 

  272.   <tr><td>lockout_duration</td><td>900</td><td>锁定时长（秒）</td></tr>
    273. 

  273. </table>
    274. 

  274. 

  275. <h3>[ssl] HTTPS 配置（v2 — C++ 应用自管理）</h3>
    276. 

  276. <table>
    277. 

  277.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    278. 

  278.   <tr><td>enabled</td><td>1</td><td>HTTPS 开关。v2 方案下必须设为 1（C++ 应用直接处理 TLS）</td></tr>
    279. 

  279.   <tr><td>cert_path</td><td>ssl/plate_fullchain.pem</td><td>SSL 证书路径（相对于安装目录）</td></tr>
    280. 

  280.   <tr><td>key_path</td><td>ssl/plate_privkey.pem</td><td>SSL 私钥路径（相对于安装目录）</td></tr>
    281. 

  281. </table>
    282. 

  282. <div class="note">v2 方案变更：nginx stream 只做 TCP 分流，不解密 TLS。SSL 证书由 C++ 应用自己管理，<code>enabled</code> 必须为 1。</div>
    283. 

  283. 

  284. <h3>[system] 系统监控配置（v38 内存缓冲）</h3>
    285. 

  285. <table>
    286. 

  286.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    287. 

  287.   <tr><td>monitor_interval</td><td>2</td><td>监控采集间隔（秒），delta 法计算 CPU 使用率</td></tr>
    288. 

  288.   <tr><td>temp_alert_threshold</td><td>70</td><td>温度告警阈值（°C）</td></tr>
    289. 

  289.   <tr><td>cpu_alert_threshold</td><td>90</td><td>CPU 告警阈值（%）</td></tr>
    290. 

  290.   <tr><td>db_path</td><td>data/system_metrics.db</td><td>监控数据库路径</td></tr>
    291. 

  291.   <tr><td>history_retention_days</td><td>7</td><td>原始数据保留天数</td></tr>
    292. 

  292.   <tr><td>aggregation_retention_days</td><td>365</td><td>聚合数据保留天数</td></tr>
    293. 

  293.   <tr><td>flush_time</td><td>23:20</td><td>每日定时刷盘时间（HH:MM）</td></tr>
    294. 

  294. </table>
    295. 

  295. 

  296. <h3>[frpc] 内网穿透配置</h3>
    297. 

  297. <table>
    298. 

  298.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    299. 

  299.   <tr><td>config_path</td><td>-</td><td>frpc.toml 配置文件路径</td></tr>
    300. 

  300.   <tr><td>protected_tunnels</td><td>-</td><td>受保护隧道名称（逗号分隔）</td></tr>
    301. 

  301.   <tr><td>auto_rollback</td><td>1</td><td>重启失败自动回滚（0/1）</td></tr>
    302. 

  302.   <tr><td>admin_addr</td><td>127.0.0.1</td><td>frpc Admin API 地址</td></tr>
    303. 

  303.   <tr><td>admin_port</td><td>7400</td><td>frpc Admin API 端口</td></tr>
    304. 

  304.   <tr><td>admin_user</td><td>-</td><td>frpc Admin 用户名</td></tr>
    305. 

  305.   <tr><td>admin_password</td><td>-</td><td>frpc Admin 密码</td></tr>
    306. 

  306. </table>
    307. 

  307. 

  308. <h3>[log] 日志配置（v36 内存缓冲）</h3>
    309. 

  309. <table>
    310. 

  310.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    311. 

  311.   <tr><td>enabled</td><td>1</td><td>内存缓冲模式（1=内存缓冲，0=直写文件）</td></tr>
    312. 

  312.   <tr><td>log_file</td><td>PlateRecApp.log</td><td>日志文件路径</td></tr>
    313. 

  313.   <tr><td>buffer_size_mb</td><td>20</td><td>内存缓冲区上限（MB）</td></tr>
    314. 

  314.   <tr><td>flush_time</td><td>23:20</td><td>每日定时刷盘时间（HH:MM）</td></tr>
    315. 

  315.   <tr><td>retention_days</td><td>30</td><td>日志文件保留天数</td></tr>
    316. 

  316.   <tr><td>redirect_stdout</td><td>1</td><td>捕获 stdout/stderr（0/1）</td></tr>
    317. 

  317.   <tr><td>auto_flush_on_exit</td><td>1</td><td>退出时立即刷盘（0/1）</td></tr>
    318. 

  318. </table>
    319. 

  319. 

  320. <h3>[feishu] 飞书通知配置</h3>
    321. 

  321. <table>
    322. 

  322.   <tr><th>参数</th><th>说明</th></tr>
    323. 

  323.   <tr><td>APP_ID</td><td>飞书应用 App ID</td></tr>
    324. 

  324.   <tr><td>APP_SECRET</td><td>飞书应用 App Secret</td></tr>
    325. 

  325.   <tr><td>CHAT_ID</td><td>飞书群聊 ID</td></tr>
    326. 

  326.   <tr><td>TIMEOUT_SECOND</td><td>请求超时时间（秒）</td></tr>
    327. 

  327.   <tr><td>WarningSigns</td><td>抑制紧急报警（1=抑制，0=正常）</td></tr>
    328. 

  328. </table>
    329. 

  329. 

  330. <h3>[weight] 称重系统配置</h3>
    331. 

  331. <table>
    332. 

  332.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    333. 

  333.   <tr><td>flagWeight</td><td>0</td><td>称重系统开关（0/1）</td></tr>
    334. 

  334.   <tr><td>weight_server_ip</td><td>-</td><td>称重服务器 IP</td></tr>
    335. 

  335.   <tr><td>weight_server_port</td><td>-</td><td>称重服务器端口</td></tr>
    336. 

  336.   <tr><td>weight_threshold_in</td><td>0</td><td>进场称重阈值（吨）</td></tr>
    337. 

  337.   <tr><td>weight_threshold_out</td><td>0</td><td>出场称重阈值（吨）</td></tr>
    338. 

  338.   <tr><td>default_entry_weight</td><td>0</td><td>默认进场重量</td></tr>
    339. 

  339.   <tr><td>default_exit_weight</td><td>0</td><td>默认出场重量</td></tr>
    340. 

  340.   <tr><td>weight_detection_time</td><td>5000</td><td>称重检测时间（毫秒）</td></tr>
    341. 

  341.   <tr><td>tcp_connect_timeout</td><td>3000</td><td>TCP 连接超时（毫秒）</td></tr>
    342. 

  342.   <tr><td>MAX_WEIGHT</td><td>100</td><td>最大称重值（吨）</td></tr>
    343. 

  343.   <tr><td>STABLE_SAMPLE_COUNT</td><td>5</td><td>稳定采样次数</td></tr>
    344. 

  344.   <tr><td>STABLE_THRESHOLD_KG</td><td>50</td><td>稳定判定阈值（公斤）</td></tr>
    345. 

  345.   <tr><td>CANDIDATE_DATA_COUNT</td><td>3</td><td>候选数据次数</td></tr>
    346. 

  346.   <tr><td>MAX_UPLOAD_RETRIES</td><td>3</td><td>上传最大重试次数</td></tr>
    347. 

  347.   <tr><td>RETRY_DELAY_MS</td><td>1000</td><td>重试延迟（毫秒）</td></tr>
    348. 

  348. </table>
    349. 

  349. 

  350. <h3>[terminal] 终端/SSH 配置</h3>
    351. 

  351. <table>
    352. 

  352.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    353. 

  353.   <tr><td>ttyd_port</td><td>7681</td><td>ttyd Web 终端端口</td></tr>
    354. 

  354.   <tr><td>ttyd_credential</td><td>-</td><td>ttyd 登录凭据（user:password）</td></tr>
    355. 

  355.   <tr><td>ttyd_max_clients</td><td>5</td><td>ttyd 最大客户端数</td></tr>
    356. 

  356.   <tr><td>ssh_keys_path</td><td>-</td><td>SSH 公钥存储路径</td></tr>
    357. 

  357. </table>
    358. 

  358. </div>
    359. 

  359. </div>
    360. 

  360. 

  361. <!-- 4. RTSP 摄像头配置 -->
    362. 

  362. <div class="card" id="sec4">
    363. 

  363. <div class="card-title" onclick="toggleCard(this)">4. RTSP 摄像头配置 <span class="arrow">▼</span></div>
    364. 

  364. <div class="card-body">
    365. 

  365. <h3>摄像头地址格式</h3>
    366. 

  366. <p>标准 RTSP 地址格式：</p>
    367. 

  367. <pre>rtsp://用户名:密码@摄像头IP:554/stream</pre>
    368. 

  368. 

  369. <h3>四路摄像头说明</h3>
    370. 

  370. <table>
    371. 

  371.   <tr><th>参数</th><th>方向</th><th>说明</th></tr>
    372. 

  372.   <tr><td>rtsp_url_front_in</td><td>前→进</td><td>前方摄像头，捕捉进场车辆</td></tr>
    373. 

  373.   <tr><td>rtsp_url_front_out</td><td>前→出</td><td>前方摄像头，捕捉出场车辆</td></tr>
    374. 

  374.   <tr><td>rtsp_url_side_in</td><td>侧→进</td><td>侧面摄像头，捕捉进场车辆</td></tr>
    375. 

  375.   <tr><td>rtsp_url_side_out</td><td>侧→出</td><td>侧面摄像头，捕捉出场车辆</td></tr>
    376. 

  376. </table>
    377. 

  377. 

  378. <h3>硬件解码（树莓派5推荐配置）</h3>
    379. 

  379. <table>
    380. 

  380.   <tr><th>模式</th><th>值</th><th>说明</th></tr>
    381. 

  381.   <tr><td>自动</td><td>auto</td><td>优先硬件解码，不可用则回退软件</td></tr>
    382. 

  382.   <tr><td>软件解码</td><td>soft</td><td>CPU 解码，兼容性最好</td></tr>
    383. 

  383.   <tr><td>DRM 硬件</td><td>drm</td><td>DRM 硬件加速（树莓派5推荐）</td></tr>
    384. 

  384. </table>
    385. 

  385. <div class="tip">树莓派 5 推荐：<code>hw_decode_mode=drm</code>，<code>hw_decode_device=/dev/dri/renderD128</code>，<code>rtsp_transport=tcp</code></div>
    386. 

  386. </div>
    387. 

  387. </div>
    388. 

  388. 

  389. <!-- 5. 车牌识别上传流程 -->
    390. 

  390. <div class="card" id="sec5">
    391. 

  391. <div class="card-title" onclick="toggleCard(this)">5. 车牌识别上传完整流程 <span class="arrow">▼</span></div>
    392. 

  392. <div class="card-body">
    393. 

  393. <h3>识别流程</h3>
    394. 

  394. <ol>
    395. 

  395.   <li><strong>摄像头抓拍</strong>：RTSP 视频流实时解码，检测到车辆运动时触发抓拍</li>
    396. 

  396.   <li><strong>车牌识别</strong>：HyperLPR3 引擎识别车牌号，返回车牌文本 + 置信度</li>
    397. 

  397.   <li><strong>置信度过滤</strong>：低于 <code>PLATE_CONFIDENCE_THRESHOLD</code> 则丢弃</li>
    398. 

  398.   <li><strong>时间窗口去重</strong>：同一车牌在 <code>TIME_WINDOW</code> 分钟内不重复上传</li>
    399. 

  399.   <li><strong>交替锁定检查</strong>：同一车牌进出间隔低于 <code>in_out_interval</code> 分钟则锁定</li>
    400. 

  400.   <li><strong>ROI 过滤</strong>：如启用 ROI，只识别指定区域内的车牌</li>
    401. 

  401.   <li><strong>数据上传</strong>：HTTP POST 将识别结果 + 照片上传至 <code>app_api</code></li>
    402. 

  402.   <li><strong>MQTT 推送</strong>：如启用 MQTT，同步推送识别结果</li>
    403. 

  403.   <li><strong>飞书通知</strong>：异常报警发送飞书群消息</li>
    404. 

  404. </ol>
    405. 

  405. 

  406. <h3>照片存储与自动清理</h3>
    407. 

  407. <ul>
    408. 

  408.   <li>照片保存在 <code>PlateJPG/</code> 目录下，文件名格式：<code>车牌号_时间戳_方向.jpg</code>（如 <code>沪FQ7108_1787365677_side_out.jpg</code>）</li>
    409. 

  409.   <li>系统每日凌晨 <strong>2:00</strong> 自动执行照片清理任务（间隔 24 小时）</li>
    410. 

  410.   <li>清理策略：当 <code>PlateJPG/</code> 目录下所有 .jpg 文件总大小超过 <code>PhotoMaxCapacityMB</code>（默认 1024MB）时，按文件修改时间从旧到新逐个删除，直到总大小降至阈值以下</li>
    411. 

  411.   <li>删除照片后递归清理空子目录</li>
    412. 

  412.   <li>清理日志输出示例：
    413. 

  413. <pre>[照片清理] PlateJPG/ 当前 1156 MB / 1024 MB 阈值，共 8234 个文件
    414. 

  414. [照片清理] 删除 1523 张照片(按时间从旧到新)，释放 156 MB，当前 1000 MB
    415. 

  415. [照片清理] 同步清空DB路径字段: 2847 个字段已更新</pre>
    416. 

  416.   </li>
    417. 

  417. </ul>
    418. 

  418. 

  419. <h4>照片清理与数据库同步（v41 修复）</h4>
    420. 

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

  421. <ul>
    422. 

  422.   <li>业务记录（车牌号、联单编号、抓拍时间、上传状态等）<strong>完整保留</strong>，仅清空路径字段</li>
    423. 

  423.   <li>Web 前端路径为 NULL 时显示灰色斜体「已清理」占位，不再显示 broken image</li>
    424. 

  424.   <li>即使 DB 清理与页面加载存在竞态，<code>&lt;img onerror&gt;</code> 也会自动替换为「已清理」</li>
    425. 

  425.   <li>程序启动时自动执行一次孤儿路径扫描（<code>db_purge_missing_photo_paths</code>），修复历史遗留数据</li>
    426. 

  426. </ul>
    427. 

  427. <div class="tip">💡 调整容量阈值：修改 <code>config.ini</code> 中 <code>PhotoMaxCapacityMB</code> 的值并重启服务。例如设为 2048 表示允许 2GB 照片存储。</div>
    428. 

  428. </div>
    429. 

  429. </div>
    430. 

  430. 

  431. <!-- 6. MQTT -->
    432. 

  432. <div class="card" id="sec6">
    433. 

  433. <div class="card-title" onclick="toggleCard(this)">6. MQTT 数据上报配置 <span class="arrow">▼</span></div>
    434. 

  434. <div class="card-body">
    435. 

  435. <h3>启用条件</h3>
    436. 

  436. <p>在 <code>[mqtt]</code> 段中填写 <code>MQTT_HOST</code> 即自动启用 MQTT 推送。</p>
    437. 

  437. 

  438. <h3>配置示例</h3>
    439. 

  439. <pre>[mqtt]
    440. 

  440. MQTT_HOST=mqtt.example.com
    441. 

  441. MQTT_PORT=1883
    442. 

  442. MQTT_USER=username
    443. 

  443. MQTT_PASS=password
    444. 

  444. MQTT_TOPIC=plate/recognition
    445. 

  445. MQTT_CLIENT_ID=plate_rec_station_01</pre>
    446. 

  446. <div class="warn">MQTT 连接失败时系统会自动重连，不影响识别和上传功能。</div>
    447. 

  447. </div>
    448. 

  448. </div>
    449. 

  449. 

  450. <!-- 7. 称重系统 -->
    451. 

  451. <div class="card" id="sec7">
    452. 

  452. <div class="card-title" onclick="toggleCard(this)">7. 称重系统对接 <span class="arrow">▼</span></div>
    453. 

  453. <div class="card-body">
    454. 

  454. <h3>工作原理</h3>
    455. 

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

  456. 

  457. <h3>重量判定逻辑</h3>
    458. 

  458. <ul>
    459. 

  459.   <li>连续 <code>STABLE_SAMPLE_COUNT</code> 次读数变化 &lt; <code>STABLE_THRESHOLD_KG</code> 公斤，视为稳定</li>
    460. 

  460.   <li>稳定后取 <code>CANDIDATE_DATA_COUNT</code> 次读数的中值作为最终重量</li>
    461. 

  461.   <li>重量超过 <code>MAX_WEIGHT</code> 吨视为异常，丢弃</li>
    462. 

  462. </ul>
    463. 

  463. 

  464. <h3>阈值说明</h3>
    465. 

  465. <ul>
    466. 

  466.   <li><code>weight_threshold_in</code>：进场最低重量（吨），低于此值可能表示空车</li>
    467. 

  467.   <li><code>weight_threshold_out</code>：出场最低重量（吨）</li>
    468. 

  468.   <li><code>default_entry_weight</code>：无法获取称重数据时的默认进场重量</li>
    469. 

  469.   <li><code>default_exit_weight</code>：无法获取称重数据时的默认出场重量</li>
    470. 

  470.   <li><code>weight_detection_time</code>：称重检测时间（毫秒，默认 5000）</li>
    471. 

  471.   <li><code>tcp_connect_timeout</code>：TCP 连接超时（毫秒，默认 3000）</li>
    472. 

  472.   <li><code>MAX_UPLOAD_RETRIES</code>：上传最大重试次数（默认 3）</li>
    473. 

  473.   <li><code>RETRY_DELAY_MS</code>：重试延迟（毫秒，默认 1000）</li>
    474. 

  474. </ul>
    475. 

  475. </div>
    476. 

  476. </div>
    477. 

  477. 

  478. <!-- 8. ROI -->
    479. 

  479. <div class="card" id="sec8">
    480. 

  480. <div class="card-title" onclick="toggleCard(this)">8. ROI 区域识别配置 <span class="arrow">▼</span></div>
    481. 

  481. <div class="card-body">
    482. 

  482. <h3>配置方式</h3>
    483. 

  483. <ul>
    484. 

  484.   <li><strong>Web 可视化</strong>：首页连接状态面板中拖拽设置 ROI 区域</li>
    485. 

  485.   <li><strong>手动配置</strong>：在 config.ini 的 <code>[config]</code> 段填写坐标值</li>
    486. 

  486. </ul>
    487. 

  487. <h3>参数说明</h3>
    488. 

  488. <table>
    489. 

  489.   <tr><th>参数</th><th>说明</th></tr>
    490. 

  490.   <tr><td>roi_in_x/y/w/h</td><td>进场 ROI 区域坐标和尺寸（像素）</td></tr>
    491. 

  491.   <tr><td>roi_in_enabled</td><td>1=启用进场 ROI</td></tr>
    492. 

  492.   <tr><td>roi_out_x/y/w/h</td><td>出场 ROI 区域坐标和尺寸</td></tr>
    493. 

  493.   <tr><td>roi_out_enabled</td><td>1=启用出场 ROI</td></tr>
    494. 

  494.   <tr><td>roi_debug_enabled</td><td>1=在抓拍图上绘制 ROI 框（调试用）</td></tr>
    495. 

  495. </table>
    496. 

  496. </div>
    497. 

  497. </div>
    498. 

  498. 

  499. <!-- 9. 交替锁定 -->
    500. 

  500. <div class="card" id="sec9">
    501. 

  501. <div class="card-title" onclick="toggleCard(this)">9. 交替锁定机制 <span class="arrow">▼</span></div>
    502. 

  502. <div class="card-body">
    503. 

  503. <h3>机制说明</h3>
    504. 

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

  505. 

  506. <h3>工作流程</h3>
    507. 

  507. <ol>
    508. 

  508.   <li>车牌 A 被识别为"进"方向</li>
    509. 

  509.   <li>5 分钟内（默认）车牌 A 再次被识别为"出"方向</li>
    510. 

  510.   <li>系统判定为异常，创建交替锁定记录</li>
    511. 

  511.   <li>锁定期间该车牌不会被上传</li>
    512. 

  512.   <li>超过 2 小时锁定自动清零，或手动在"锁定管理"页面清除</li>
    513. 

  513. </ol>
    514. 

  514. 

  515. <table>
    516. 

  516.   <tr><th>参数</th><th>默认值</th><th>说明</th></tr>
    517. 

  517.   <tr><td>in_out_interval</td><td>5</td><td>交替锁定间隔（⚠️ 单位分钟），小于此间隔的进/出切换会被锁定</td></tr>
    518. 

  518.   <tr><td>AlternatingMerge</td><td>0</td><td>交替合并开关</td></tr>
    519. 

  519. </table>
    520. 

  520. <div class="warn"><code>in_out_interval</code> 单位是<strong>分钟</strong>，不是秒！填 5 表示 5 分钟 = 300 秒。</div>
    521. 

  521. </div>
    522. 

  522. </div>
    523. 

  523. 

  524. <!-- 10. 认证与权限 -->
    525. 

  525. <div class="card" id="sec10">
    526. 

  526. <div class="card-title" onclick="toggleCard(this)">10. 登录认证与权限 <span class="arrow">▼</span></div>
    527. 

  527. <div class="card-body">
    528. 

  528. <h3>角色定义</h3>
    529. 

  529. <table>
    530. 

  530.   <tr><th>角色</th><th>Role值</th><th>可访问页面</th></tr>
    531. 

  531.   <tr><td>普通用户</td><td>0</td><td>首页、视频、称重、锁定管理</td></tr>
    532. 

  532.   <tr><td>管理员</td><td>1</td><td>普通用户 + 系统配置</td></tr>
    533. 

  533.   <tr><td>超级管理员</td><td>2</td><td>所有页面（含系统监控、frpc管理、SSH密钥、日志、帮助）</td></tr>
    534. 

  534. </table>
    535. 

  535. 

  536. <h3>默认账号</h3>
    537. 

  537. <table>
    538. 

  538.   <tr><th>用户名</th><th>密码</th><th>角色</th></tr>
    539. 

  539.   <tr><td>admin</td><td>zhongjin188A</td><td>超级管理员</td></tr>
    540. 

  540.   <tr><td>zhonjin</td><td>zhonjin</td><td>普通用户</td></tr>
    541. 

  541. </table>
    542. 

  542. 

  543. <h3>安全特性</h3>
    544. 

  544. <ul>
    545. 

  545.   <li>密码 bcrypt 加密存储（cost=12）</li>
    546. 

  546.   <li>连续登录失败锁定账号</li>
    547. 

  547.   <li>CSRF Token 防护</li>
    548. 

  548.   <li>Session 超时自动失效</li>
    549. 

  549.   <li>登录速率限制</li>
    550. 

  550. </ul>
    551. 

  551. </div>
    552. 

  552. </div>
    553. 

  553. 

  554. <!-- 11. frpc.toml 详解 -->
    555. 

  555. <div class="card" id="sec11">
    556. 

  556. <div class="card-title" onclick="toggleCard(this)">11. frpc.toml 内网穿透配置详解 <span class="arrow">▼</span></div>
    557. 

  557. <div class="card-body">
    558. 

  558. 

  559. <h3>配置文件位置</h3>
    560. 

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

  561. 

  562. <h3>v2 方案 — nginx stream 分流（推荐）</h3>
    563. 

  563. <p>使用 nginx stream + ssl_preread 方案，<strong>只需一个公网端口 40963</strong> 即可同时处理 HTTP 和 HTTPS：</p>
    564. 

  564. <pre># frpc.toml — v2 方案（nginx stream 分流）
    565. 

  565. 

  566. serverAddr = "discover.zhonjin.com"
    567. 

  567. serverPort = 9443
    568. 

  568. auth.method = "token"
    569. 

  569. auth.token  = "你的frps认证Token"
    570. 

  570. transport.tls.enable = true
    571. 

  571. clientID = "ssd_40960"
    572. 

  572. 

  573. # frpc Admin HTTP API
    574. 

  574. webServer.addr = "127.0.0.1"
    575. 

  575. webServer.port = 7400
    576. 

  576. webServer.user = "admin"
    577. 

  577. webServer.password = "你的管理密码"
    578. 

  578. 

  579. # 隧道1：主服务（外网40963→本机nginx:40963，stream自动分流HTTP/HTTPS）
    580. 

  580. [[proxies]]
    581. 

  581. name       = "plate_web"
    582. 

  582. type       = "tcp"
    583. 

  583. localIP    = "127.0.0.1"
    584. 

  584. localPort  = 40963    # ← 转发到 nginx stream，不是 C++ 的 8080
    585. 

  585. remotePort = 40963
    586. 

  586. 

  587. # 隧道2：ttyd终端（外网40964→本机nginx:8082→ttyd:7681）
    588. 

  588. [[proxies]]
    589. 

  589. name       = "ttyd_web"
    590. 

  590. type       = "tcp"
    591. 

  591. localIP    = "127.0.0.1"
    592. 

  592. localPort  = 8082     # ← nginx HTTPS 反向代理（SSL 终止 + WebSocket）
    593. 

  593. remotePort = 40964</pre>
    594. 

  594. 

  595. <h3>隧道说明（v2）</h3>
    596. 

  596. <table>
    597. 

  597.   <tr><th>隧道名</th><th>外网端口</th><th>本机端口</th><th>用途</th></tr>
    598. 

  598.   <tr><td>plate_web</td><td>40963</td><td>nginx stream:40963</td><td>HTTP/HTTPS 合一，stream 自动分流</td></tr>
    599. 

  599.   <tr><td>ttyd_web</td><td>40964</td><td>nginx HTTPS:8082</td><td>Web 终端（nginx SSL→ttyd:7681）</td></tr>
    600. 

  600. </table>
    601. 

  601. 

  602. <h3>v2 数据流向</h3>
    603. 

  603. <pre>HTTP  流量: 公网:40963 → frpc → nginx:40963 (stream) → $ssl_preread=""  → 127.0.0.1:8081 (nginx HTTP) → 301 重定向到 HTTPS
    604. 

  604. HTTPS 流量: 公网:40963 → frpc → nginx:40963 (stream) → $ssl_preread≠"" → 127.0.0.1:8080 (C++ HTTPS) → 直接处理
    605. 

  605. Web SSH:  公网:40964 → frpc → nginx:8082 (HTTPS反向代理, SSL终止) → 127.0.0.1:7681 (ttyd HTTP)</pre>
    606. 

  606. 

  607. <div class="tip"><strong>v1→v2 迁移注意：</strong>不再需要 40965 端口。HTTPS 主服务统一使用 <code>https://mqtt.zhonjin.com:40963/</code>。</div>
    608. 

  608. 

  609. <h3>参数详解</h3>
    610. 

  610. <table>
    611. 

  611.   <tr><th>参数</th><th>说明</th></tr>
    612. 

  612.   <tr><td>serverAddr</td><td>frps 服务器域名或 IP</td></tr>
    613. 

  613.   <tr><td>serverPort</td><td>frps 服务端口（默认 7000，本项目用 9443）</td></tr>
    614. 

  614.   <tr><td>auth.method</td><td>认证方式，固定为 <code>token</code></td></tr>
    615. 

  615.   <tr><td>auth.token</td><td>与 frps 约定的认证 Token</td></tr>
    616. 

  616.   <tr><td>webServer.addr/port</td><td>frpc Admin API 监听地址，PlateRecApp 通过此接口获取隧道状态</td></tr>
    617. 

  617.   <tr><td>webServer.user/password</td><td>Admin API 认证凭据（需与 config.ini [frpc] 段一致）</td></tr>
    618. 

  618.   <tr><td>[[proxies]] name</td><td>隧道唯一名称，PlateRecApp Web 界面按名称识别</td></tr>
    619. 

  619.   <tr><td>[[proxies]] type</td><td>隧道类型，本项目全部使用 <code>tcp</code>（透传 TCP 流）</td></tr>
    620. 

  620.   <tr><td>[[proxies]] localPort</td><td>本机目标端口，frpc 将外网流量转发到此端口</td></tr>
    621. 

  621.   <tr><td>[[proxies]] remotePort</td><td>frps 服务器暴露的外网端口，客户端通过此端口访问</td></tr>
    622. 

  622. </table>
    623. 

  623. 

  624. <h3>隧道保护</h3>
    625. 

  625. <p>在 <code>config.ini [frpc]</code> 段配置受保护隧道，防止 Web 界面误删关键隧道：</p>
    626. 

  626. <pre>protected_tunnels = plate_web,ttyd_web</pre>
    627. 

  627. <div class="warn">受保护的隧道无法通过 Web 管理界面删除。如需删除，必须先修改 config.ini 中的 <code>protected_tunnels</code> 字段。</div>
    628. 

  628. 

  629. <h3>frpc 管理命令</h3>
    630. 

  630. <pre># 查看 frpc 状态
    631. 

  631. systemctl status frpc
    632. 

  632. 

  633. # 重启 frpc
    634. 

  634. sudo systemctl restart frpc
    635. 

  635. 

  636. # 查看 frpc 日志
    637. 

  637. tail -f /var/log/frpc.log
    638. 

  638. 

  639. # 通过 Admin API 查看隧道状态
    640. 

  640. curl -u admin:密码 http://127.0.0.1:7400/api/status/tcp</pre>
    641. 

  641. </div>
    642. 

  642. </div>
    643. 

  643. 

  644. <!-- 12. Nginx 反向代理详解 -->
    645. 

  645. <div class="card" id="sec12">
    646. 

  646. <div class="card-title" onclick="toggleCard(this)">12. Nginx stream + ssl_preread 配置详解（v2） <span class="arrow">▼</span></div>
    647. 

  647. <div class="card-body">
    648. 

  648. 

  649. <h3>架构说明</h3>
    650. 

  650. <p>v2 方案使用 nginx 的 <code>stream</code> 模块 + <code>ssl_preread</code> 功能，在 <strong>TCP 层面</strong>检测流量类型并自动分流：</p>
    651. 

  651. <ul>
    652. 

  652.   <li><strong>端口 40963</strong>：nginx stream 监听，检测协议类型（TLS / HTTP）</li>
    653. 

  653.   <li><strong>TLS 流量</strong> → 透传到 C++ HTTPS 服务（127.0.0.1:8080）</li>
    654. 

  654.   <li><strong>HTTP 流量</strong> → nginx HTTP 模块（127.0.0.1:8081）→ 301 重定向到 HTTPS</li>
    655. 

  655. </ul>
    656. 

  656. <div class="tip"><strong>关键区别：</strong>stream 模块是 TCP 层代理，不解密 TLS 流量。SSL 证书由 C++ 应用自己管理，nginx 只做协议检测和分流。</div>
    657. 

  657. 

  658. <h3>nginx.conf 完整配置</h3>
    659. 

  659. <p>文件路径：<code>/etc/nginx/nginx.conf</code>（替换整个文件）</p>
    660. 

  660. <pre># 加载 stream 动态模块
    661. 

  661. load_module modules/ngx_stream_module.so;
    662. 

  662. 

  663. events {
    664. 

  664.     worker_connections 1024;
    665. 

  665. }
    666. 

  666. 

  667. # ============================================================
    668. 

  668. # stream 块 — TCP 层协议分流（在 http 块外面）
    669. 

  669. # ============================================================
    670. 

  670. stream {
    671. 

  671.     # 根据 ssl_preread 检测结果选择后端
    672. 

  672.     # $ssl_preread_protocol 的可能值：
    673. 

  673.     #   ""          → HTTP 流量（非 TLS）
    674. 

  674.     #   "TLSv1.2"   → TLS 1.2
    675. 

  675.     #   "TLSv1.3"   → TLS 1.3
    676. 

  676.     map $ssl_preread_protocol $backend {
    677. 

  677.         ""        http_backend;    # HTTP → nginx HTTP 8081
    678. 

  678.         default   tls_backend;     # TLS → C++ HTTPS 8080
    679. 

  679.     }
    680. 

  680. 

  681.     # TLS 后端 — C++ HTTPS 服务
    682. 

  682.     upstream tls_backend {
    683. 

  683.         server 127.0.0.1:8080;
    684. 

  684.     }
    685. 

  685. 

  686.     # HTTP 后端 — nginx HTTP 301 重定向
    687. 

  687.     upstream http_backend {
    688. 

  688.         server 127.0.0.1:8081;
    689. 

  689.     }
    690. 

  690. 

  691.     # 主服务器 — 监听公网端口
    692. 

  692.     server {
    693. 

  693.         listen 40963;
    694. 

  694.         proxy_pass $backend;
    695. 

  695.         ssl_preread on;          # 启用 SSL 预读检测协议
    696. 

  696.     }
    697. 

  697. }
    698. 

  698. 

  699. # ============================================================
    700. 

  700. # http 块 — HTTP → HTTPS 301 重定向
    701. 

  701. # ============================================================
    702. 

  702. http {
    703. 

  703.     sendfile on;
    704. 

  704.     tcp_nopush on;
    705. 

  705.     tcp_nodelay on;
    706. 

  706.     keepalive_timeout 65;
    707. 

  707. 

  708.     include /etc/nginx/mime.types;
    709. 

  709.     default_type application/octet-stream;
    710. 

  710. 

  711.     access_log /var/log/nginx/access.log;
    712. 

  712.     error_log  /var/log/nginx/error.log;
    713. 

  713. 

  714.     # HTTP → HTTPS 301 重定向
    715. 

  715.     server {
    716. 

  716.         listen 8081;
    717. 

  717.         server_name _;
    718. 

  718.         return 301 https://$host:40963$request_uri;
    719. 

  719.     }
    720. 

  720. 

  721.     # ============================================================
    722. 

  722.     # ttyd Web 终端 HTTPS 反向代理（端口 8082）
    723. 

  723.     # ============================================================
    724. 

  724.     # frpc 隧道：外网 40964 → nginx:8082 → ttyd:7681
    725. 

  725.     # nginx 做 SSL 终止，再通过 HTTP 代理到 ttyd（含 WebSocket 支持）
    726. 

  726.     server {
    727. 

  727.         listen 8082 ssl;
    728. 

  728.         server_name _;
    729. 

  729. 

  730.         ssl_certificate     /etc/nginx/ssl/plate_fullchain.pem;
    731. 

  731.         ssl_certificate_key /etc/nginx/ssl/plate_privkey.pem;
    732. 

  732.         ssl_protocols TLSv1.2 TLSv1.3;
    733. 

  733.         ssl_ciphers HIGH:!aNULL:!MD5:!RC4;
    734. 

  734.         ssl_prefer_server_ciphers on;
    735. 

  735.         ssl_session_cache shared:SSL_Ttyd:5m;
    736. 

  736.         ssl_session_timeout 1h;
    737. 

  737. 

  738.         location / {
    739. 

  739.             proxy_pass http://127.0.0.1:7681;
    740. 

  740.             proxy_set_header Host $host;
    741. 

  741.             proxy_set_header X-Real-IP $remote_addr;
    742. 

  742.             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    743. 

  743.             proxy_set_header X-Forwarded-Proto $scheme;
    744. 

  744. 

  745.             # WebSocket 支持（ttyd 核心通信方式）
    746. 

  746.             proxy_http_version 1.1;
    747. 

  747.             proxy_set_header Upgrade $http_upgrade;
    748. 

  748.             proxy_set_header Connection "upgrade";
    749. 

  749. 

  750.             # ttyd 长连接超时
    751. 

  751.             proxy_read_timeout 86400s;
    752. 

  752.             proxy_send_timeout 86400s;
    753. 

  753.         }
    754. 

  754.     }
    755. 

  755. }</pre>
    756. 

  756. 

  757. <h3>核心原理</h3>
    758. 

  758. <table>
    759. 

  759.   <tr><th>组件</th><th>作用</th><th>说明</th></tr>
    760. 

  760.   <tr><td>stream 块</td><td>TCP 层代理</td><td>与 http 块平级，不处理 HTTP 协议，只做 TCP 转发</td></tr>
    761. 

  761.   <tr><td>ssl_preread on</td><td>SSL 预读</td><td>在 TLS 握手阶段读取 ClientHello，获取协议版本，不解密</td></tr>
    762. 

  762.   <tr><td>map $ssl_preread_protocol</td><td>协议分流</td><td>空字符串 = HTTP，非空 = TLS</td></tr>
    763. 

  763.   <tr><td>upstream tls_backend</td><td>TLS 后端</td><td>透传到 C++ 应用（8080），C++ 自己处理 TLS 握手</td></tr>
    764. 

  764.   <tr><td>upstream http_backend</td><td>HTTP 后端</td><td>转发到 nginx HTTP 8081，返回 301 重定向</td></tr>
    765. 

  765.   <tr><td>server 8082 ssl</td><td>ttyd HTTPS 代理</td><td>SSL 终止后代理到 ttyd:7681，支持 WebSocket</td></tr>
    766. 

  766. </table>
    767. 

  767. 

  768. <h3>部署步骤</h3>
    769. 

  769. <ol>
    770. 

  770.   <li>安装 stream 模块：<code>sudo apt install -y libnginx-mod-stream</code></li>
    771. 

  771.   <li>验证模块：<code>ls -l /usr/lib/nginx/modules/ngx_stream_module.so</code></li>
    772. 

  772.   <li>备份原配置：<code>sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak</code></li>
    773. 

  773.   <li>替换配置：<code>sudo cp nginx-stream.conf /etc/nginx/nginx.conf</code></li>
    774. 

  774.   <li>删除默认站点（如有）：<code>sudo rm -f /etc/nginx/sites-enabled/default</code></li>
    775. 

  775.   <li>验证配置：<code>sudo nginx -t</code></li>
    776. 

  776.   <li>启动 nginx：<code>sudo systemctl enable nginx && sudo systemctl restart nginx</code></li>
    777. 

  777. </ol>
    778. 

  778. 

  779. <h3>前置条件</h3>
    780. 

  780. <table>
    781. 

  781.   <tr><th>项目</th><th>要求</th></tr>
    782. 

  782.   <tr><td>nginx 版本</td><td>≥ 1.11.5（支持 stream 模块）</td></tr>
    783. 

  783.   <tr><td>stream 模块</td><td>libnginx-mod-stream（Debian）或 nginx-mod-stream（CentOS）</td></tr>
    784. 

  784.   <tr><td>C++ 应用</td><td>必须启用 HTTPS，监听 127.0.0.1:8080</td></tr>
    785. 

  785.   <tr><td>SSL 证书</td><td>C++ 应用自行管理（config.ini 的 [ssl] 段）</td></tr>
    786. 

  786. </table>
    787. 

  787. 

  788. <h3>验证方法</h3>
    789. 

  789. <pre># 检查端口监听
    790. 

  790. ss -tlnp | grep -E '40963|8080|8081'
    791. 

  791. # 预期输出：
    792. 

  792. # LISTEN  0.0.0.0:40963  nginx (stream)
    793. 

  793. # LISTEN  127.0.0.1:8081  nginx (http 301)
    794. 

  794. # LISTEN  0.0.0.0:8080  PlateRecApp (HTTPS)
    795. 

  795. 

  796. # 测试 HTTP 重定向（应返回 301）
    797. 

  797. curl -I http://localhost:40963/
    798. 

  798. # 预期：HTTP/1.1 301 Moved Permanently
    799. 

  799. #       Location: https://localhost:40963/
    800. 

  800. 

  801. # 测试 HTTPS（应返回 200）
    802. 

  802. curl -kI https://localhost:40963/
    803. 

  803. # 预期：HTTP/1.1 200 OK
    804. 

  804. 

  805. # 浏览器测试（清除缓存或用无痕模式）
    806. 

  806. # 访问 http://mqtt.zhonjin.com:40963/ → 自动跳转到 https://mqtt.zhonjin.com:40963/</pre>
    807. 

  807. 

  808. <h3>端口规划总结</h3>
    809. 

  809. <table>
    810. 

  810.   <tr><th>端口</th><th>服务</th><th>说明</th></tr>
    811. 

  811.   <tr><td><strong>40963</strong></td><td>nginx stream</td><td>公网入口，TLS/HTTP 分流</td></tr>
    812. 

  812.   <tr><td>8081</td><td>nginx http</td><td>HTTP 301 重定向（仅内部）</td></tr>
    813. 

  813.   <tr><td>8080</td><td>C++ HTTPS</td><td>PlateRecApp Web 服务（SSL 自管理）</td></tr>
    814. 

  814.   <tr><td><strong>40964</strong></td><td>nginx HTTPS→ttyd</td><td>Web 终端（nginx:8082 SSL终止→ttyd:7681）</td></tr>
    815. 

  815.   <tr><td>8082</td><td>nginx HTTPS 代理</td><td>ttyd Web 终端 HTTPS 反向代理（仅内部）</td></tr>
    816. 

  816.   <tr><td>7400</td><td>frpc Admin</td><td>隧道状态查询（仅 127.0.0.1）</td></tr>
    817. 

  817. </table>
    818. 

  818. </div>
    819. 

  819. </div>
    820. 

  820. 

  821. <!-- 13. SSL/HTTPS 证书配置 -->
    822. 

  822. <div class="card" id="sec13">
    823. 

  823. <div class="card-title" onclick="toggleCard(this)">13. SSL/HTTPS 证书配置（v2 — C++ 应用自管理） <span class="arrow">▼</span></div>
    824. 

  824. <div class="card-body">
    825. 

  825. 

  826. <div class="note"><strong>v2 方案变更：</strong>nginx stream 只做 TCP 层协议分流，不解密 TLS 流量。SSL 证书由 C++ 应用（PlateRecApp）自己管理，通过 config.ini 的 <code>[ssl]</code> 段配置。nginx 不再需要 SSL 证书。</div>
    827. 

  827. 

  828. <h3>config.ini [ssl] 段配置</h3>
    829. 

  829. <pre>[ssl]
    830. 

  830. enabled=1
    831. 

  831. cert_path=ssl/plate_fullchain.pem
    832. 

  832. key_path=ssl/plate_privkey.pem</pre>
    833. 

  833. <div class="tip">v2 方案下 SSL 证书文件放在安装目录的 <code>ssl/</code> 子目录下（或任意自定义路径），不再需要 <code>/etc/nginx/ssl/</code>。</div>
    834. 

  834. 

  835. <h3>方式一：Let's Encrypt 证书 — 阿里云 DNS 验证（推荐）</h3>
    836. 

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

  837. 

  838. <h4>方案对比</h4>
    839. 

  839. <table>
    840. 

  840.   <tr><th>验证方式</th><th>端口要求</th><th>通配符</th><th>自动续期</th><th>本项目适用</th></tr>
    841. 

  841.   <tr><td>HTTP-01 (standalone)</td><td>公网 80</td><td>❌</td><td>✅</td><td>❌ 80 端口不可用</td></tr>
    842. 

  842.   <tr><td>TLS-ALPN-01</td><td>公网 443</td><td>❌</td><td>✅</td><td>❌ 443 端口不可用</td></tr>
    843. 

  843.   <tr><td><strong>DNS-01 (dns-aliyun)</strong></td><td><strong>无</strong></td><td><strong>✅</strong></td><td><strong>✅</strong></td><td><strong>✅ 推荐</strong></td></tr>
    844. 

  844.   <tr><td>手动 DNS</td><td>无</td><td>✅</td><td>❌ 手动</td><td>⚠️ 每 90 天手动操作</td></tr>
    845. 

  845. </table>
    846. 

  846. 

  847. <h4>一键部署</h4>
    848. 

  848. <pre># 1. 安装 certbot + 阿里云 DNS 插件
    849. 

  849. sudo apt update
    850. 

  850. sudo apt install -y certbot python3-pip
    851. 

  851. sudo pip3 install certbot-dns-aliyun
    852. 

  852. 

  853. # 2. 配置阿里云 AccessKey（RAM 子账号，需 AliyunDNSFullAccess 权限）
    854. 

  854. sudo mkdir -p /etc/letsencrypt
    855. 

  855. sudo vim /etc/letsencrypt/aliyun.ini
    856. 

  856. # 内容：
    857. 

  857. #   dns_aliyun_access_key = 你的AccessKeyID
    858. 

  858. #   dns_aliyun_access_key_secret = 你的AccessKeySecret
    859. 

  859. sudo chmod 600 /etc/letsencrypt/aliyun.ini
    860. 

  860. 

  861. # 3. 一键申请通配符证书（自动通过 DNS API 验证）
    862. 

  862. sudo certbot certonly \
    863. 

  863.     --authenticator dns-aliyun \
    864. 

  864.     --dns-aliyun-credentials /etc/letsencrypt/aliyun.ini \
    865. 

  865.     --dns-aliyun-propagation-seconds 30 \
    866. 

  866.     --server https://acme-v02.api.letsencrypt.org/directory \
    867. 

  867.     --agree-tos --no-eff-email \
    868. 

  868.     --email admin@zhonjin.com \
    869. 

  869.     -d mqtt.zhonjin.com \
    870. 

  870.     -d "*.zhonjin.com"
    871. 

  871. 

  872. # 4. 部署证书到 PlateRecApp
    873. 

  873. mkdir -p ssl/
    874. 

  874. sudo cp /etc/letsencrypt/live/mqtt.zhonjin.com/fullchain.pem ssl/plate_fullchain.pem
    875. 

  875. sudo cp /etc/letsencrypt/live/mqtt.zhonjin.com/privkey.pem   ssl/plate_privkey.pem
    876. 

  876. sudo chown stevenroc:stevenroc ssl/*.pem
    877. 

  877. chmod 644 ssl/plate_fullchain.pem
    878. 

  878. chmod 600 ssl/plate_privkey.pem
    879. 

  879. 

  880. # 5. 配置自动续期（每天 3:00 检查，续期后自动部署）
    881. 

  881. (crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet --deploy-hook /opt/openAI/project/003.PlateRecAPP/scripts/renew_ssl.sh") | crontab -
    882. 

  882. 

  883. # 6. 重启 PlateRecApp
    884. 

  884. sudo systemctl restart PlateRecApp</pre>
    885. 

  885. 

  886. <h4>续期部署脚本 renew_ssl.sh</h4>
    887. 

  887. <pre>#!/bin/bash
    888. 

  888. # /opt/openAI/project/003.PlateRecAPP/scripts/renew_ssl.sh
    889. 

  889. DOMAIN="mqtt.zhonjin.com"
    890. 

  890. SSL_DIR="/opt/openAI/project/003.PlateRecAPP/ssl"
    891. 

  891. 

  892. cp /etc/letsencrypt/live/${DOMAIN}/fullchain.pem ${SSL_DIR}/plate_fullchain.pem
    893. 

  893. cp /etc/letsencrypt/live/${DOMAIN}/privkey.pem   ${SSL_DIR}/plate_privkey.pem
    894. 

  894. chown stevenroc:stevenroc ${SSL_DIR}/*.pem
    895. 

  895. chmod 644 ${SSL_DIR}/plate_fullchain.pem
    896. 

  896. chmod 600 ${SSL_DIR}/plate_privkey.pem
    897. 

  897. systemctl restart PlateRecApp
    898. 

  898. echo "$(date) SSL 证书续期部署成功" >> /opt/openAI/project/003.PlateRecAPP/ssl_renew.log</pre>
    899. 

  899. 

  900. <h4>阿里云 RAM 权限配置</h4>
    901. 

  901. <ol>
    902. 

  902.   <li>登录 <a href="https://ram.console.aliyun.com/" target="_blank">RAM 控制台</a> → 用户 → 创建用户</li>
    903. 

  903.   <li>勾选 <strong>OpenAPI 调用访问</strong>，保存 AccessKey ID 和 Secret</li>
    904. 

  904.   <li>添加权限：<code>AliyunDNSFullAccess</code>（云解析 DNS 管理）</li>
    905. 

  905. </ol>
    906. 

  906. <div class="tip">DNS 验证原理：certbot 通过阿里云 API 自动添加 <code>_acme-challenge.mqtt.zhonjin.com</code> TXT 记录，Let's Encrypt CA 查询 DNS 验证域名所有权，全程无需开放任何端口。</div>
    907. 

  907. <div class="warn"><strong>前提：</strong>域名 mqtt.zhonjin.com 的 DNS 解析必须使用阿里云（<code>dns9.hichina.com</code>）。如果 DNS 在其他服务商，需先迁移到阿里云，或改用对应插件（如 <code>certbot-dns-cloudflare</code>、<code>certbot-dns-dnspod</code>）。</div>
    908. 

  908. 

  909. <h3>方式二：自签名证书</h3>
    910. 

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

  911. <pre># 创建证书目录
    912. 

  912. mkdir -p ssl/
    913. 

  913. 

  914. # 生成自签名证书（10年有效期）
    915. 

  915. openssl req -x509 -newkey rsa:2048 -nodes \
    916. 

  916.   -keyout ssl/plate_privkey.pem \
    917. 

  917.   -out    ssl/plate_fullchain.pem \
    918. 

  918.   -days   3650 \
    919. 

  919.   -subj   "/CN=mqtt.zhonjin.com/O=PlateRecApp/C=CN"
    920. 

  920. 

  921. # 设置权限
    922. 

  922. chmod 600 ssl/plate_privkey.pem
    923. 

  923. chmod 644 ssl/plate_fullchain.pem
    924. 

  924. 

  925. # 重启 PlateRecApp 加载证书
    926. 

  926. sudo systemctl restart PlateRecApp</pre>
    927. 

  927. 

  928. <h3>证书文件说明</h3>
    929. 

  929. <table>
    930. 

  930.   <tr><th>文件</th><th>用途</th><th>config.ini 参数</th></tr>
    931. 

  931.   <tr><td>plate_fullchain.pem</td><td>完整证书链（含中间 CA）</td><td>cert_path</td></tr>
    932. 

  932.   <tr><td>plate_privkey.pem</td><td>私钥文件（严禁泄露）</td><td>key_path</td></tr>
    933. 

  933. </table>
    934. 

  934. 

  935. <h3>v1→v2 迁移说明</h3>
    936. 

  936. <div class="warn"><strong>v1 方案：</strong>SSL 证书由 nginx 管理（<code>/etc/nginx/ssl/</code>），nginx 做 HTTPS 终止后转发 HTTP 到 C++。<br>
    937. 

  937. <strong>v2 方案：</strong>SSL 证书由 C++ 应用管理，nginx stream 只做 TCP 分流，不解密 TLS。不再需要 <code>/etc/nginx/ssl/</code> 目录。</div>
    938. 

  938. </div>
    939. 

  939. </div>
    940. 

  940. 

  941. <!-- 14. 系统监控与日志 -->
    942. 

  942. <div class="card" id="sec14">
    943. 

  943. <div class="card-title" onclick="toggleCard(this)">14. 系统监控与日志 <span class="arrow">▼</span></div>
    944. 

  944. <div class="card-body">
    945. 

  945. <h3>系统监控（实时）</h3>
    946. 

  946. <ul>
    947. 

  947.   <li>CPU 使用率（delta 法计算，含每核使用率、负载均值）</li>
    948. 

  948.   <li>内存使用率（总量/已用/可用）</li>
    949. 

  949.   <li>磁盘使用率（根分区容量/已用/可用）</li>
    950. 

  950.   <li>CPU 温度监控，超阈值告警（阈值由 <code>temp_alert_threshold</code> 配置）</li>
    951. 

  951.   <li>CPU 使用率告警（阈值由 <code>cpu_alert_threshold</code> 配置）</li>
    952. 

  952.   <li>PlateRecApp 进程资源占用（RSS 内存、CPU 占用）</li>
    953. 

  953.   <li>frpc 运行状态、MQTT 连接状态、称重系统连接状态</li>
    954. 

  954. </ul>
    955. 

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

  956. 

  957. <h3>历史监控数据（v37+）</h3>
    958. 

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

  959. <ul>
    960. 

  960.   <li><strong>采集间隔</strong>：<code>monitor_interval</code>（默认 2 秒），delta 法计算 CPU 使用率，不阻塞采集线程</li>
    961. 

  961.   <li><strong>定时刷盘</strong>：每日 <code>flush_time</code>（默认 23:20）将内存监控数据批量写入 <code>system_metrics.db</code>，减少 SD 卡写入次数（v38 起）</li>
    962. 

  962.   <li><strong>三级存储</strong>：原始数据（2秒间隔）→ 小时聚合 → 日聚合，自动降采样</li>
    963. 

  963.   <li><strong>自动清理</strong>：原始数据保留 <code>history_retention_days</code> 天（默认 7 天），聚合数据保留 <code>aggregation_retention_days</code> 天（默认 365 天）</li>
    964. 

  964.   <li><strong>历史查询 API</strong>：<code>/api/monitor/history?range=1h|6h|24h|7d|30d</code>，自动选择合适的数据粒度</li>
    965. 

  965.   <li><strong>统计接口</strong>：<code>/api/monitor/stats</code> 返回数据库记录数和运行状态</li>
    966. 

  966. </ul>
    967. 

  967. 

  968. <h3>SD 卡写入保护策略（v38）</h3>
    969. 

  969. <ul>
    970. 

  970.   <li><strong>系统监控</strong>：内存缓冲，每日 23:20 一次写入，SD 卡写入从 2880 次/天降至 1 次</li>
    971. 

  971.   <li><strong>运行日志</strong>：内存环形缓冲区，Web 日志页面零磁盘 I/O，每日 23:20 写入 <code>PlateRecApp_YYYYMMDD.log</code></li>
    972. 

  972.   <li><strong>旧版日志清理</strong>：内存模式启用时自动跳过旧版 copytruncate，避免无意义读写</li>
    973. 

  973.   <li><strong>退出安全刷盘</strong>：SIGTERM/SIGINT 时立即执行最后一次刷盘</li>
    974. 

  974. </ul>
    975. 

  975. 

  976. <h3>日志管理（v36 内存缓冲）</h3>
    977. 

  977. <ul>
    978. 

  978.   <li><strong>内存缓冲模式</strong>（<code>enabled=1</code>，默认）：所有日志写入内存环形缓冲区，Web 日志页面直接从内存读取，零磁盘 I/O</li>
    979. 

  979.   <li><strong>直写文件模式</strong>（<code>enabled=0</code>）：传统模式，日志直接写入文件</li>
    980. 

  980.   <li><strong>定时刷盘</strong>：每日 <code>flush_time</code>（默认 23:20）自动将内存日志批量写入 <code>PlateRecApp_YYYYMMDD.log</code></li>
    981. 

  981.   <li><strong>退出刷盘</strong>：<code>auto_flush_on_exit=1</code> 时，收到 SIGTERM/SIGINT 信号立即刷盘，防止日志丢失</li>
    982. 

  982.   <li><strong>stdout 捕获</strong>：<code>redirect_stdout=1</code> 时，stdout/stderr 通过 pipe 重定向到内存缓冲区统一收集</li>
    983. 

  983.   <li>Web 界面实时查看日志（支持 Tail 模式），显示内存使用率和缓冲状态</li>
    984. 

  984.   <li>超期日志文件自动清理（由 <code>retention_days</code> 控制），支持手动触发刷盘</li>
    985. 

  985. </ul>
    986. 

  986. <div class="note">两个子系统的 <code>flush_time</code> 均配置为 23:20，分别在 <code>[log]</code> 和 <code>[system]</code> 段中设置，可独立调整。</div>
    987. 

  987. </div>
    988. 

  988. </div>
    989. 

  989. 

  990. <!-- 15. Web管理 -->
    991. 

  991. <div class="card" id="sec15">
    992. 

  992. <div class="card-title" onclick="toggleCard(this)">15. Web 管理功能 <span class="arrow">▼</span></div>
    993. 

  993. <div class="card-body">
    994. 

  994. <table>
    995. 

  995.   <tr><th>页面</th><th>路径</th><th>权限</th><th>说明</th></tr>
    996. 

  996.   <tr><td>监控首页</td><td>/</td><td>所有用户</td><td>实时监控、识别记录、连接状态、ROI设置</td></tr>
    997. 

  997.   <tr><td>视频预览</td><td>/video</td><td>所有用户</td><td>实时视频流</td></tr>
    998. 

  998.   <tr><td>称重记录</td><td>/weight</td><td>所有用户</td><td>称重数据</td></tr>
    999. 

  999.   <tr><td>锁定管理</td><td>/locks</td><td>所有用户</td><td>交替锁定记录</td></tr>
    1000. 

  1000.   <tr><td>帮助手册</td><td>/help</td><td>超级管理员</td><td>本文档</td></tr>
    1001. 

  1001.   <tr><td>系统配置</td><td>/config</td><td>管理员+</td><td>config.ini 在线编辑</td></tr>
    1002. 

  1002.   <tr><td>系统监控</td><td>/system</td><td>超级管理员</td><td>CPU/内存/温度/磁盘</td></tr>
    1003. 

  1003.   <tr><td>frpc 管理</td><td>/frpc</td><td>超级管理员</td><td>内网穿透状态和配置</td></tr>
    1004. 

  1004.   <tr><td>SSH 密钥</td><td>/ssh-keys</td><td>超级管理员</td><td>SSH 公钥管理</td></tr>
    1005. 

  1005.   <tr><td>日志管理</td><td>/logs</td><td>超级管理员</td><td>系统日志查看</td></tr>
    1006. 

  1006.   <tr><td>登录</td><td>/login</td><td>公开</td><td>用户登录页面</td></tr>
    1007. 

  1007. </table>
    1008. 

  1008. 

  1009. <h3>Tab 分离：实时数据 + 历史查询（v41 新增）</h3>
    1010. 

  1010. <p>首页和称重页均改为 Tab 分离结构，自动刷新与手动查询完全独立：</p>
    1011. 

  1011. <table>
    1012. 

  1012.   <tr><th>Tab</th><th>数据来源</th><th>刷新方式</th></tr>
    1013. 

  1013.   <tr><td>📡 实时数据 / 实时称重</td><td>固定最新 20 条，无条件加载</td><td>每 30 秒自动刷新</td></tr>
    1014. 

  1014.   <tr><td>🔍 历史查询</td><td>按筛选条件查询，支持完整分页</td><td>手动触发，不自动刷新</td></tr>
    1015. 

  1015. </table>
    1016. 

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

  1017. 

  1018. <h3>分类查询筛选条件（v41）</h3>
    1019. 

  1019. <p>历史查询 Tab 支持多维度组合筛选（所有条件 AND 组合）：</p>
    1020. 

  1020. <table>
    1021. 

  1021.   <tr><th>筛选条件</th><th>首页</th><th>称重页</th><th>说明</th></tr>
    1022. 

  1022.   <tr><td>车牌号</td><td>✅</td><td>✅</td><td>模糊匹配，如"沪A"</td></tr>
    1023. 

  1023.   <tr><td>联单编号</td><td>✅</td><td>✅</td><td>模糊匹配</td></tr>
    1024. 

  1024.   <tr><td>方向</td><td>✅</td><td>✅</td><td>全部 / 进站 / 出站</td></tr>
    1025. 

  1025.   <tr><td>上传状态</td><td>✅</td><td>✅</td><td>首页：成功/失败；称重页多一个"待上传"(status=0)</td></tr>
    1026. 

  1026.   <tr><td>飞书状态</td><td>✅</td><td>—</td><td>全部 / 已发送 / 失败 / 未发送</td></tr>
    1027. 

  1027.   <tr><td>日期范围</td><td>✅</td><td>✅</td><td>按抓拍时间过滤（YYYY-MM-DD）</td></tr>
    1028. 

  1028. </table>
    1029. 

  1029. 

  1030. <h3>分页控件（v41）</h3>
    1031. 

  1031. <ul>
    1032. 

  1032.   <li><strong>每页条数</strong>：可选 20 / 50 / 100 条</li>
    1033. 

  1033.   <li><strong>页码导航</strong>：首页 / 上一页 / 页码（当前页前后各 2 页，含首末页和省略号）/ 下一页 / 末页</li>
    1034. 

  1034.   <li><strong>跳转</strong>：输入页码 + GO 按钮快速跳转</li>
    1035. 

  1035.   <li><strong>信息栏</strong>：显示"第 X/Y 页 · 共 Z 条"</li>
    1036. 

  1036. </ul>
    1037. 

  1037. </div>
    1038. 

  1038. </div>
    1039. 

  1039. 

  1040. <!-- 16. 数据库 -->
    1041. 

  1041. <div class="card" id="sec16">
    1042. 

  1042. <div class="card-title" onclick="toggleCard(this)">16. 数据库与备份 <span class="arrow">▼</span></div>
    1043. 

  1043. <div class="card-body">
    1044. 

  1044. <h3>数据库文件</h3>
    1045. 

  1045. <table>
    1046. 

  1046.   <tr><th>文件</th><th>路径</th><th>说明</th></tr>
    1047. 

  1047.   <tr><td>认证数据库</td><td>data/auth.db</td><td>用户账号、密码、Session</td></tr>
    1048. 

  1048.   <tr><td>识别记录</td><td>data/upload_records.db</td><td>车牌识别上传记录</td></tr>
    1049. 

  1049.   <tr><td>系统监控</td><td>data/system_metrics.db</td><td>性能监控时序数据（原始+小时聚合+日聚合）</td></tr>
    1050. 

  1050. </table>
    1051. 

  1051. <div class="tip">v29 版本起，所有数据库统一存放在 <code>data/</code> 目录下。系统首次启动时自动将旧路径数据库迁移到新位置（旧文件保留为备份）。</div>
    1052. 

  1052. 

  1053. <h3>upload_records 表结构</h3>
    1054. 

  1054. <table>
    1055. 

  1055.   <tr><th>字段</th><th>说明</th></tr>
    1056. 

  1056.   <tr><td>id</td><td>自增主键</td></tr>
    1057. 

  1057.   <tr><td>create_time</td><td>记录创建时间</td></tr>
    1058. 

  1058.   <tr><td>capture_time</td><td>抓拍时间（用于时间对齐）</td></tr>
    1059. 

  1059.   <tr><td>plate_number</td><td>车牌号</td></tr>
    1060. 

  1060.   <tr><td>tb_num</td><td>联单编号</td></tr>
    1061. 

  1061.   <tr><td>station_type</td><td>方向：1=进站，2=出站</td></tr>
    1062. 

  1062.   <tr><td>lo_photo_path / hi_photo_path</td><td>照片文件名（相对 PlateJPG/），清理后为 NULL</td></tr>
    1063. 

  1063.   <tr><td>lo_upload_status / hi_upload_status</td><td>上传状态：0=待传，1=成功，2=失败</td></tr>
    1064. 

  1064.   <tr><td>feishu_status</td><td>飞书通知：1=已发送，2=失败，3=未发送</td></tr>
    1065. 

  1065.   <tr><td>retry_count</td><td>重试次数（上限 5 次）</td></tr>
    1066. 

  1066. </table>
    1067. 

  1067. 

  1068. <h3>备份建议</h3>
    1069. 

  1069. <ul>
    1070. 

  1070.   <li>定期备份 <code>data/</code> 目录和 <code>config.ini</code></li>
    1071. 

  1071.   <li>nginx SSL 证书和配置文件备份：<code>/etc/nginx/ssl/</code>、<code>/etc/nginx/conf.d/</code></li>
    1072. 

  1072.   <li>frpc 配置修改时系统自动备份</li>
    1073. 

  1073.   <li>照片数据在 <code>PhotoMaxCapacityMB</code> 限制内自动管理，重要照片建议另行备份</li>
    1074. 

  1074. </ul>
    1075. 

  1075. </div>
    1076. 

  1076. </div>
    1077. 

  1077. 

  1078. <!-- 17. FAQ -->
    1079. 

  1079. <div class="card" id="sec17">
    1080. 

  1080. <div class="card-title" onclick="toggleCard(this)">17. 常见问题 FAQ <span class="arrow">▼</span></div>
    1081. 

  1081. <div class="card-body">
    1082. 

  1082. 

  1083. <h3>Q: HTTP 访问没有跳转到 HTTPS？</h3>
    1084. 

  1084. <p>A: 检查以下几点：</p>
    1085. 

  1085. <ul>
    1086. 

  1086.   <li>确认 nginx stream 模块已安装：<code>nginx -V 2>&amp;1 | grep stream</code></li>
    1087. 

  1087.   <li>确认 nginx 配置正确：<code>sudo nginx -t</code></li>
    1088. 

  1088.   <li>确认 8081 端口正在监听：<code>ss -tlnp | grep 8081</code></li>
    1089. 

  1089.   <li>确认 frpc 隧道 <code>plate_web</code> 正常运行（localPort 为 40963）</li>
    1090. 

  1090.   <li>浏览器可能缓存了旧的重定向，尝试清除缓存或无痕模式</li>
    1091. 

  1091.   <li>测试本机重定向：<code>curl -I http://localhost:40963/</code>，应返回 301</li>
    1092. 

  1092. </ul>
    1093. 

  1093. 

  1094. <h3>Q: HTTPS 访问返回错误？</h3>
    1095. 

  1095. <p>A: v2 方案下 TLS 由 C++ 应用处理，检查：</p>
    1096. 

  1096. <ul>
    1097. 

  1097.   <li>PlateRecApp 是否正在运行：<code>systemctl status PlateRecApp</code></li>
    1098. 

  1098.   <li>PlateRecApp 是否启用了 HTTPS：<code>config.ini [ssl] enabled=1</code></li>
    1099. 

  1099.   <li>SSL 证书文件是否存在：<code>ls -l ssl/plate_fullchain.pem ssl/plate_privkey.pem</code></li>
    1100. 

  1100.   <li>nginx stream 是否正常监听：<code>ss -tlnp | grep 40963</code></li>
    1101. 

  1101.   <li>nginx 错误日志：<code>sudo tail -f /var/log/nginx/error.log</code></li>
    1102. 

  1102. </ul>
    1103. 

  1103. 

  1104. <h3>Q: <code>unknown directive "stream"</code>？</h3>
    1105. 

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

  1106. 

  1107. <h3>Q: frpc 重启后隧道不生效？</h3>
    1108. 

  1108. <p>A: 检查 frpc.toml 配置语法：</p>
    1109. 

  1109. <pre>frpc verify -c /path/to/frpc.toml</pre>
    1110. 

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

  1111. 

  1112. <h3>Q: 自签名证书浏览器警告怎么消除？</h3>
    1113. 

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

  1114. <ul>
    1115. 

  1115.   <li>方式1：使用 Let's Encrypt 免费证书（需域名解析到公网 IP）</li>
    1116. 

  1116.   <li>方式2：在客户端将自签名 CA 证书添加到受信任的根证书列表</li>
    1117. 

  1117.   <li>方式3：忽略警告，继续使用（加密通信正常，仅证书不受信任）</li>
    1118. 

  1118. </ul>
    1119. 

  1119. 

  1120. <h3>Q: 摄像头连接失败怎么办？</h3>
    1121. 

  1121. <p>A: 确认 RTSP 地址格式正确，在 VLC 中测试播放。尝试 <code>rtsp_transport=tcp</code>。</p>
    1122. 

  1122. 

  1123. <h3>Q: in_out_interval 填 5 是 5 秒还是 5 分钟？</h3>
    1124. 

  1124. <p>A: <strong>5 分钟</strong>。单位是分钟，系统内部自动 ×60 转为秒。</p>
    1125. 

  1125. 

  1126. <h3>Q: 照片被自动清理后，Web 页面看到"已清理"怎么办？</h3>
    1127. 

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

  1128. 

  1129. <h3>Q: 日志中出现 <code>[路径校验] 转换绝对路径失败</code> 错误？</h3>
    1130. 

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

  1131. 

  1132. <h3>Q: 如何调整照片存储上限？</h3>
    1133. 

  1133. <p>A: 修改 <code>config.ini</code> 的 <code>[config]</code> 段中 <code>PhotoMaxCapacityMB</code> 值并重启服务。例如：</p>
    1134. 

  1134. <pre>[config]
    1135. 

  1135. PhotoMaxCapacityMB=2048   # 调整为 2GB</pre>
    1136. 

  1136. 

  1137. <h3>Q: 称重页的"待上传"状态是什么意思？</h3>
    1138. 

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

  1139. 

  1140. <h3>Q: 如何重置管理员密码？</h3>
    1141. 

  1141. <pre>cd /opt/openAI/project/003.PlateRecAPP
    1142. 

  1142. python3 reset_passwords.py</pre>
    1143. 

  1143. </div>
    1144. 

  1144. </div>
    1145. 

  1145. 

  1146. </div>
    1147. 

  1147. 

  1148. <script>
    1149. 

  1149. function toggleCard(el) {
    1150. 

  1150.   el.classList.toggle('collapsed');
    1151. 

  1151.   var body = el.nextElementSibling;
    1152. 

  1152.   body.classList.toggle('hidden');
    1153. 

  1153. }
    1154. 

  1154. </script>
    1155. 

  1155. </body>
    1156. 

  1156. </html>
    1157.