yzfh/bishe-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

传输加密

Browse Source
This commit is contained in:
纪田野
2026-05-04 21:03:06 +08:00
parent 1ff2e6af01
commit e720b1a392
5 changed files with 190 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
00_项目总文档.md
+27 -21
View File
@@ -7,9 +7,9 @@
| 部分 | 所在目录 | 主要职责 | 可以把它理解成 |
| --- | --- | --- | --- |
| STM32 固件端 | `stm32/` | 接收 K210 识别结果、判断是否允许签到、加密上传记录、控制 OLED/蜂鸣器/指示灯/补光灯 | 考勤机主控板 |
| K210 识别端 | `k210/` | 摄像头采集、人脸检测、人脸特征比对、添加/删除本地人脸、上传人脸照片、同步人脸映射 | 摄像头和 AI 识别模块 |
| C++ 服务端 | `server/` | 提供 HTTP API、保存考勤记录、保存配置、管理照片和同步状态 | 中心服务器 |
| Qt 管理端 | `QT/` | Windows/Android 图形管理界面，用于查看记录、统计、配置时间段、管理映射和照片 | 管理后台 |
| K210 识别端 | `k210/` | 摄像头采集、人脸检测、人脸特征比对、添加/删除本地人脸、上传人脸照片、同步人脸档案 | 摄像头和 AI 识别模块 |
| C++ 服务端 | `server/` | 提供 HTTP API、保存考勤记录、时间段、学生班级档案、人脸档案、照片和同步状态 | 中心服务器 |
| Qt 管理端 | `QT/` | Windows/Android 图形管理界面，用于查看记录、统计、配置时间段、管理班级、人脸照片和照片对应学生信息 | 管理后台 |
整个系统的目标是：
@@ -26,14 +26,20 @@
K210 本地添加人脸时，会生成一个原始人脸编号，例如 `ID:1`、`ID:2`。这个编号只表示 K210 本地第几个录入的人脸。
真实考勤需要的是学号，例如 `20240001`。所以项目里有一个“人脸 ID 到学号”的映射：
真实考勤需要的是学号，例如 `20240001`。所以项目里通过人脸档案维护“人脸 ID 到学号”的绑定：
```json
{
"mappings": {
"1": "20240001",
"2": "20240002"
}
"face_profiles": [
{
"face_id": "1",
"student_id": "20240001"
},
{
"face_id": "2",
"student_id": "20240002"
}
]
}
```
@@ -63,15 +69,15 @@ attendance.db
| 文件或目录 | 作用 |
| --- | --- |
| `attendance.db` | 主数据库，保存记录、配置、映射、同步状态 |
| `attendance.db` | 主数据库，保存记录、配置、学生班级档案、人脸档案、同步状态 |
| `faces/` | 人脸照片目录，保存 K210 上传的 `.jpg` |
| `backups/` | 数据库备份目录 |
服务端数据以 SQLite 为准，考勤记录、配置、映射和同步状态都保存在 `attendance.db` 中。
服务端数据以 SQLite 为准，考勤记录、时间段配置、学生班级档案、人脸档案和同步状态都保存在 `attendance.db` 中。
### 2.4 同步版本号是什么
服务端维护一个全局同步版本号 `sync_version`。当考勤记录、时间段、映射、人脸照片、删除任务等数据发生变化时，服务端会把版本号加一。
服务端维护一个全局同步版本号 `sync_version`。当考勤记录、时间段、学生档案、班级信息、人脸档案、人脸照片、删除任务等数据发生变化时，服务端会把版本号加一。
设备同步时会带上自己上次同步到的版本：
@@ -92,7 +98,7 @@ flowchart LR
STM32 -->|"USART1 AT 指令"| ESP1["ESP8266"]
ESP1 -->|"HTTP + AES 签到"| Server["C++ 服务端 8082"]
K210 -->|"UART2 AT 指令"| ESP2["K210 侧 ESP8266"]
ESP2 -->|"HTTP 上传照片/同步映射"| Server
ESP2 -->|"HTTP 上传照片/同步人脸档案"| Server
Qt["Qt 管理端 Windows/Android"] -->|"HTTP API"| Server
Server --> SQLite["attendance.db"]
Server --> Faces["faces/*.jpg"]
@@ -154,14 +160,14 @@ POST /api/v1/faces/photos/<face_id>
```
7. Qt 管理端进入“人脸管理”，刷新后可以看到照片。
8. 管理员为该 face_id 填写真实学号并保存映射。
9. 服务端保存映射并触发同步。
8. 管理员在该 face_id 的编辑弹窗中填写真实学号、姓名和班级，并保存人脸档案。
9. 服务端保存人脸档案并触发同步。
10. K210 拉取同步状态后更新本地 `face_mapping.txt`，识别发送时把 `face_id` 转成真实学号，`recordftr.txt` 中的原始 `ID:<face_id>` 保持不变。
### 4.3 删除人脸流程
1. Qt 管理端删除某个学生或人脸。
2. 服务端删除照片、映射，按需要删除考勤记录。
2. 服务端删除照片、解除人脸绑定，按需要删除考勤记录。
3. 服务端写入待删除任务 `pending_delete`，并提升同步版本。
4. K210 定期检查同步请求或拉取统一同步状态。
5. K210 在本地删除对应特征和照片。
@@ -251,7 +257,7 @@ K210 侧：
### 8.1 API Token
除少数公开接口外，服务端要求请求头中带 Token：
除 `OPTIONS` 预检请求外，服务端要求业务接口请求头中带 Token：
```text
X-Api-Token: atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV
@@ -277,18 +283,18 @@ Qt 端也会读取同名环境变量；STM32 和 K210 目前是写在代码里
| Key | `2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c` |
| IV | `00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f` |
STM32 上传签到使用加密请求。Qt 当前普通记录和统计请求使用 JSON 明文响应，代码仍保留了解密能力。
业务 JSON 接口统一使用 AES-128-CBC + PKCS#7 + Base64 传输。POST JSON 请求体需要携带 `X-Encrypted: AES128-CBC`，GET/DELETE/POST 的 JSON 响应由服务端加密后返回 `X-Encrypted: AES128-CBC`。K210 人脸照片 JPEG 因体积和分块传输限制保留原始二进制上传/下载，照片列表、同步状态、删除确认等 JSON 仍走加密链路。
## 9. 推荐启动顺序
1. 启动服务端，确认 `http://服务器IP:8082/api/v1/system/health` 返回健康状态。
1. 启动服务端，用 Qt 或带 Token 与 AES 解密能力的客户端确认 `/api/v1/system/health` 返回健康状态。
2. 启动 Qt 管理端，在配置中心填写服务端地址和 API Token，点击“保存”后再点“测试连接”。
3. 在 Qt 管理端新增签到时间段并保存。
4. 烧录并启动 STM32，确认 OLED 显示系统就绪。
5. 启动 K210，确认摄像头画面、模型加载和 WiFi 连接正常。
6. 在 K210 添加人脸，等待照片上传到服务端。
7. 在 Qt 管理端为照片对应的人脸 ID 填写真实学号并保存映射。
8. K210 同步映射后，再让同一人进行识别签到。
7. 在 Qt 管理端为照片对应的人脸 ID 点击“编辑”，填写真实学号、姓名和班级并保存人脸档案。
8. K210 同步人脸档案后，再让同一人进行识别签到。
9. 在 Qt 管理端查看考勤记录和统计结果。
## 10. 一键理解各端关系
@@ -297,7 +303,7 @@ STM32 上传签到使用加密请求。Qt 当前普通记录和统计请求使
| --- | --- | --- |
| 改服务端地址 | Qt 配置中心、STM32/K210 代码常量 | 各端 HTTP 请求指向新服务器 |
| 设置允许签到的时间 | Qt 配置中心 | Qt 保存到服务端，STM32 定期下载 |
| 给人脸绑定学号 | Qt 人脸管理 | 服务端保存映射，K210 同步后更新本地 `face_mapping.txt`，识别发送时转换成学号 |
| 给人脸维护学生信息 | Qt 人脸管理 | 服务端保存学生档案和人脸档案，K210 同步后更新本地 `face_mapping.txt`，识别发送时转换成学号 |
| 添加人脸 | K210 按键短按 | K210 保存特征和照片，照片上传服务端 |
| 删除人脸 | Qt 人脸管理或 K210 删除模式 | Qt 删除会生成服务端同步任务；K210 本地删除只影响本地 |
| 查看记录 | Qt 考勤记录页 | Qt 从服务端读取最近记录 |