153 lines
6.5 KiB
Markdown
153 lines
6.5 KiB
Markdown
# 服务端文档
|
|
|
|
## 1. 推荐服务端版本
|
|
当前项目推荐使用：`server/server_encrypted.cpp`
|
|
|
|
原因：
|
|
- 支持 STM32 上传加密签到数据。
|
|
- 支持 Qt 管理端所需管理 API。
|
|
- 支持 K210 人脸照片与映射同步相关 API。
|
|
|
|
## 2. 端口与数据文件
|
|
- HTTP 端口：`8082`
|
|
- SQLite 数据库：`attendance.db`
|
|
- 启动备份目录：`backups/`
|
|
- 日志：运行时生成 `attendance.log`
|
|
- 旧数据迁移来源：`attendance_database.csv`、`timeslots_config.json`、`mapping_config.json`、`face_id_mapping.json`、`pending_delete.json`、`sync_request.json`、`sync_version.txt`
|
|
- 人脸目录：`faces/`
|
|
- 全局同步版本：存储在 `attendance.db` 的 `kv_store` 表中。
|
|
- 删除任务：存储在 `pending_delete` 表中，包含 `task_id`、`face_id`、`student_id`、`created_at`、`status`、`ack_at`。
|
|
- 设备同步状态：存储在 `device_sync_state` 表中，用于追踪各端最近同步版本和 ACK 版本。
|
|
|
|
## 3. 签到数据链路
|
|
1. STM32 调用 `POST /api/v1/attendance/checkins` 上传 Base64 密文。
|
|
2. 服务端按 AES-128-CBC 解密并解析 JSON。
|
|
3. 将记录写入 `attendance.db` 的 `records` 表（含 `class_id` 字段）。
|
|
|
|
## 4. 核心 API（按模块）
|
|
### 4.1 考勤与统计
|
|
- `POST /api/v1/attendance/checkins`
|
|
- `GET /api/v1/attendance/records?limit=&offset=`
|
|
- `GET /api/v1/attendance/statistics`
|
|
- `POST /api/v1/attendance/records/clear`
|
|
- `DELETE /api/v1/attendance/records?timestamp=&student_id=`
|
|
- `GET /api/v1/system/health`
|
|
- `GET /api/v1/system/storage`
|
|
- `GET /api/v1/system/time`
|
|
|
|
说明：
|
|
- `/api/v1/attendance/records` 与 `/api/v1/attendance/statistics` 默认返回明文 JSON；请求头包含 `X-Encrypted-Response: true` 时返回加密数据。
|
|
|
|
### 4.2 时间段与查重
|
|
- `POST /api/v1/config/time-slots`
|
|
- `GET /api/v1/config/time-slots`
|
|
- `GET /api/v1/attendance/duplicates?student_id=&slot_start=&slot_end=`
|
|
- `GET /api/v1/attendance/today?slot_start=&slot_end=`
|
|
|
|
### 4.3 映射与照片
|
|
- `POST /api/v1/config/mappings`
|
|
- `GET /api/v1/config/mappings`
|
|
- `GET /api/v1/faces/photos`
|
|
- `GET /api/v1/faces/photos/<id>`
|
|
- `POST /api/v1/faces/photos/<face_id>`
|
|
- `POST /api/v1/faces/mappings`
|
|
- `GET /api/v1/faces/mappings`
|
|
- `GET /api/v1/faces/student-ids`
|
|
|
|
### 4.4 统一同步接口（推荐）
|
|
- `GET /api/v1/sync/state?client=<client>&last_version=<version>`
|
|
- `POST /api/v1/sync/ack`
|
|
- `GET /api/v1/sync/version`
|
|
|
|
说明：
|
|
- 服务端是唯一权威状态源。
|
|
- 每次签到、清空/删除记录、修改时间段、修改映射、上传照片、删除人脸，服务端都会递增 `kv_store.sync_version`。
|
|
- 设备端保存自己的 `last_version`，请求时带给服务端。
|
|
- 服务端会记录每个 `client` 的 `last_seen_version`、`last_ack_version` 和 `last_seen_at`，可通过 `/api/v1/system/storage` 查看。
|
|
- 如果版本无变化，服务端返回 `changed:false`，设备端无需重复解析配置。
|
|
- 如果版本有变化，服务端返回 `changed:true` 和当前客户端需要的状态。
|
|
- `/api/v1/sync/version` 只返回当前版本和服务端时间，适合调试时快速确认同步版本。
|
|
|
|
客户端示例：
|
|
- `client=k210`：返回 `face_mappings` 和 `pending_delete`。
|
|
- `client=stm32`：返回 `time_slots` 和 `server_time`。
|
|
- `client=qt`：返回时间段、人脸映射、照片列表、学生ID列表、记录、统计和映射配置。
|
|
- `client=all`：返回全部可同步状态。
|
|
|
|
K210 删除确认示例：
|
|
|
|
```json
|
|
{
|
|
"client": "k210",
|
|
"version": 12,
|
|
"deleted": ["2", "3"],
|
|
"task_ids": ["2-1770000000", "3-1770000001"]
|
|
}
|
|
```
|
|
|
|
### 4.5 人脸删除与同步控制
|
|
- `DELETE /api/v1/faces/<student_id>?delete_records=true`
|
|
- `GET /api/v1/faces/pending-delete`
|
|
- `POST /api/v1/faces/delete-ack`
|
|
- `GET /api/v1/sync/request`
|
|
- `POST /api/v1/sync/request/ack`
|
|
- `POST /api/v1/sync/trigger`
|
|
|
|
说明：这些是 v1 下的兼容控制接口；推荐设备端优先使用统一同步接口，只有手动调试或兼容旧流程时才单独调用。
|
|
|
|
### 4.6 旧接口兼容
|
|
服务端内部仍保留旧 `/api/...` 路由兼容层，便于历史程序临时访问；新代码和新文档统一使用 `/api/v1/...`。
|
|
|
|
## 5. 编译与运行
|
|
Windows（示例）：
|
|
```bash
|
|
cd server
|
|
g++ -o server_encrypted.exe server_encrypted.cpp -lws2_32 -lcrypto -lssl -lsqlite3 -std=c++11
|
|
server_encrypted.exe
|
|
```
|
|
|
|
Linux（示例）：
|
|
```bash
|
|
cd server
|
|
g++ -o server_encrypted server_encrypted.cpp -lcrypto -lssl -lsqlite3 -lpthread -std=c++11
|
|
./server_encrypted
|
|
```
|
|
|
|
说明：服务端启动时会自动创建 `attendance.db`。如果检测到旧 CSV/JSON 文件，会在首次启动时导入；之后以后端 API 和 SQLite 为准。
|
|
|
|
## 6. 备份与恢复
|
|
服务端启动时如果发现已有 `attendance.db`，会先复制到 `backups/attendance_YYYY-MM-DD_HH-MM-SS.db`。备份失败时服务端会停止启动，避免在没有恢复点的情况下继续写入。
|
|
|
|
恢复步骤：
|
|
1. 停止 `server_encrypted`。
|
|
2. 将当前 `attendance.db` 改名保留，例如 `attendance.broken.db`。
|
|
3. 从 `backups/` 选择最近可用备份，复制为 `attendance.db`。
|
|
4. 重新启动服务端，访问 `/api/v1/system/storage`，确认 `ok:true`、`quick_check:"ok"`。
|
|
|
|
## 7. 公网部署安全
|
|
本机或内网演示可以直接监听 `0.0.0.0:8082`。公网部署建议：
|
|
- 设置 `ATTENDANCE_BIND_HOST=127.0.0.1`，只让服务端监听本机。
|
|
- 使用 Nginx 或 Caddy 终止 HTTPS，并由反向代理转发到 `127.0.0.1:8082`。
|
|
- 配置 HTTPS 后立即轮换 `ATTENDANCE_API_TOKEN`、设备端 Token 和相关密钥。
|
|
- 反向代理层继续限制来源 IP、请求体大小和访问日志脱敏。
|
|
|
|
## 8. 自动化回归
|
|
服务端启动后可运行：
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "change-me-token"
|
|
```
|
|
|
|
脚本覆盖 health、storage、time、sync、records、statistics、time-slots、mappings、faces 等低风险接口；真实 AES 签到正文和真实照片上传仍保留手动验证。
|
|
|
|
## 9. 版本说明
|
|
仓库仅保留当前推荐版本：`server_encrypted.cpp`。旧版实验服务端与测试脚本已清理，避免误部署非鉴权接口。
|
|
|
|
## 10. 关键一致性要求
|
|
- AES Key/IV 必须与 STM32、Qt 完全一致。
|
|
- 若 Qt 无法解析记录，先检查是否误连到非加密版本服务端。
|
|
|
|
## 11. 后续优化
|
|
服务端当前已经完成 SQLite 主存储、v1 接口、自动备份和统一同步模型。后续需要继续跟踪的风险和优化项已统一记录在 `docs/05_项目审查问题清单.md`。
|
|
|