简介：这是一套面向计算机相关专业毕业设计与人脸识别应用开发学习的完整项目，基于Python、Flask与OpenCV深度学习框架实现人脸识别签到系统，涵盖源码、数据集与详细文档，下载后即可运行并支持二次扩展。压缩包共28个文件，8个Python文件覆盖应用主程序、API接口、业务逻辑与模型调用，7个HTML文件提供登录、注册、签到、管理等前端页面，另含SQLite数据库、4个数据文件、环境依赖清单与README说明文档，整体约101.47MB，目录层次分明，便于按模块翻阅。目前已有341人学习下载，适合用于毕业设计答辩、课程设计、项目立项演示或企业内训参考。项目中还内置Flask数据库迁移脚本、人脸识别模型文件与字体处理工具，并附有测试脚本和运行说明；借助完整源码与配套文档，读者既能理解Flask与传统OpenCV及深度模型结合的完整链路，也能在真实签到场景中快速落地部署，是完成学业项目与入门人脸识别应用的高质量素材。
1. 人脸识别签到系统到底解决什么问题：一个被低估的“小而全”项目
教室点名、会议室签到、实验室打卡，这三类场景的共同痛点是“确认这个人是谁”和“记录他来了”这两件事需要人手工完成。基于Python+Flask+OpenCV深度学习的人脸识别签到系统，就是把摄像头拍到的画面变成一条签到记录：前端页面负责采集图像，后端Flask负责业务逻辑和数据库操作，OpenCV和深度学习模型负责人脸检测与特征提取。这套方案的技术栈非常典型，但不代表它简单——真正难的不是调用几个人脸识别库，而是把检测、提特征、比对、写库这一整条链路串起来，并确保在不同光照、角度下不翻车。它特别适合作为毕业设计、实验室考勤或小型会议室签到系统的起点，也是一个能把“深度学习”从理论落到工程实践的完整样本。
2. 为什么是 Python+Flask+OpenCV+深度学习：选型逻辑与系统骨架
2.1 人脸识别三条实现路线：从传统方法到深度学习，为什么最终选组合方案
做一个人脸识别签到系统，第一件事不是写代码，而是选人脸识别的实现路线。我见过很多项目在第一步就选错，导致后面识别率怎么调都上不去。常见的有三条路线。
第一条是OpenCV自带的传统方法，比如Haar Cascade或LBP级联分类器。用detectMultiScale就能框出人脸，代码量极少，但误检率很高，稍微侧个脸或者光线暗一点就检测不到。更麻烦的是它只能告诉你“这里有张脸”，不能告诉你“这是谁”。要完成签到，还得另找人脸比对方案。这条路线适合做图像处理课程的作业，不适合做签到系统。
第二条是dlib加face_recognition库。dlib提供HOG人脸检测和68个关键点，face_recognition基于ResNet提取128维特征向量，封装得很友好，几行代码就能完成人脸编码和比对。但dlib在Windows上编译很折磨人，需要Visual Studio和CMake，装错版本直接报error: OpenCV(4.4.0)这种让人头皮发麻的错。而且face_recognition的模型是个黑匣子，答辩时老师问“特征是怎么提取的”，答不上来会很难看。
第三条是深度学习方案：检测端用MTCNN、RetinaFace或OpenCV DNN自带的YuNet，特征提取端用ArcFace或FaceNet的ONNX模型。这也是我在这个项目里推荐的做法。优势有两个：一是依赖少，OpenCV 4.5.4以上自带的FaceDetectorYN可以直接做检测，不需要额外装检测框架；二是ArcFace这类模型在公开人脸数据集上的表现远好于face_recognition的ResNet模型，对光照、角度、遮挡的鲁棒性更强。用cv2.dnn.readNetFromONNX加载模型，代码写起来也不复杂。深度学习流程比传统方法复杂，但换来的是可控的精度和可解释的模块划分，这正是答辩时最需要的。
2.2 Flask在系统里的定位：只做业务编排，不做图像计算
选Flask还是FastAPI，是很多人在动手前纠结的问题。我的观点很直接：这个项目用Flask更合适。Flask的好处是同步模型简单，模板渲染和表单处理开箱即用，网上资料多，遇到问题随便搜都有答案。FastAPI的异步和自动Swagger文档确实漂亮，但人脸识别这个场景根本没有高并发压力——一个教室几十个人轮流签到，每秒一个请求已经很夸张了。Flask的学习成本和部署成本都更低，对毕业设计来说尤其友好。
架构上要有一个明确的分工：Flask只负责接收请求、调度识别模块、读写数据库、返回结果，绝对不要在路由函数里写图像处理逻辑。正确做法是把人脸检测和特征提取封装成独立的类或函数，在Flask启动时加载一次模型，后续所有请求复用。模型加载是个耗时操作，ArcFace的ONNX模型加载一次大概需要几百毫秒，如果每个签到请求都重新加载一次，系统会卡到让人怀疑人生，内存也会被撑爆。我一般会在app.py里像下面这样把模型挂在模块级：
from flask import Flask from face_module import FaceDetector, FaceEncoder app = Flask(__name__) # 全局单例：进程启动时加载一次，所有请求共用 detector = FaceDetector("face_detection_yunet_2023mar.onnx") encoder = FaceEncoder("arcface.onnx")这里FaceDetector和FaceEncoder是自定义的封装类，稍后会讲内部实现。关键是app、detector、encoder三个对象都只在模块加载时初始化一次。Flask开发服务器默认是单进程多线程，模型只保留一份，线程之间共享，不存在拷贝问题。如果之后用gunicorn部署并开了多个worker，那每个worker进程都会加载一份模型，内存会成倍增长，开两个worker就够了，别贪多。
2.3 项目目录结构与运行流程：先看清全貌再动手
一个能跑通的人脸识别签到系统，目录结构大致是这样的：
| 路径 | 作用 |
|---|---|
| app.py | Flask入口，注册所有路由 |
| face_module.py | 人脸检测、特征提取、比对的封装 |
| models/ | 存放ONNX模型文件 |
| requirements.txt | 依赖清单 |
| templates/index.html | 签到前端页面 |
| static/upload/ | 注册时上传的人脸照片 |
| dataset/ | 原始人脸数据集（用于模型微调或验证） |
| attendance.db | SQLite数据库，自动生成 |
运行流程是：启动app.py，浏览器打开签到页面，页面调用摄像头拍照，照片通过POST请求发给后端。后端先做人脸检测，确认画面里有人脸，然后提取特征向量，与数据库里预先录入的特征做比对，超过阈值就判定为匹配，写入签到记录并返回姓名。注册流程类似，只是比对变成了写入——把学号、姓名和新提取的特征向量一起存进数据库。
这个流程里最核心的模块是face_module.py，后面两章会把检测、提特征、比对三件事拆开讲透。
3. 从摄像头画面到128维特征向量：人脸识别核心流水线
3.1 用OpenCV DNN做人脸检测：YuNet模型的加载与边界框处理
人脸检测是整个链路的第一环，检测不到人脸，后面全白搭。OpenCV从4.5.4版本开始内置了YuNet人脸检测模型，文件名叫face_detection_yunet_2023mar.onnx，在OpenCV官方GitHub的zoo目录里能找到下载链接。它的优势是模型小、速度快、支持CPU推理，单张人脸检测只要几十毫秒，非常适合签到这种低延迟场景。
import cv2 class FaceDetector: def __init__(self, model_path, conf_threshold=0.9): # 输入尺寸先给一个默认值，检测时再根据实际图像调整 self.detector = cv2.FaceDetectorYN.create( model_path, "", (320, 320), conf_threshold ) self.conf_threshold = conf_threshold def detect(self, frame): img_h, img_w = frame.shape[:2] # 关键：输入尺寸必须和当前图像尺寸一致 self.detector.setInputSize((img_w, img_h)) _, faces = self.detector.detect(frame) if faces is None: return [] # faces形状是(N, 15)，前4个值是x, y, w, h return faces def crop_faces(self, frame): faces = self.detect(frame) results = [] for face in faces: x, y, w, h = face[:4].astype(int) # 扩大裁剪框，把额头和下巴都包含进来 # 特征提取模型对完整人脸更敏感，只裁窄框会丢信息 margin_x = int(0.15 * w) margin_y = int(0.25 * h) x1 = max(0, x - margin_x) y1 = max(0, y - margin_y) x2 = min(frame.shape[1], x + w + margin_x) y2 = min(frame.shape[0], y + h + margin_y) results.append(frame[y1:y2, x1:x2]) return results这段代码里有几个关键细节。setInputSize必须每次调用都设置，并且要和当前帧的宽高一致，否则会检测失败或结果错位。置信度阈值conf_threshold设0.9可以过滤大量误检，但如果人脸比较远或者画质差，可以降到0.7，后面再靠特征比对兜底。裁剪时加margin是血泪经验——直接按检测框裁剪会把发际线和下巴裁掉，导致特征提取模型输入的人脸不完整，识别精度明显下降。margin的比例不用太大，横向0.15、纵向0.25是我常用的值。
3.2 用ArcFace提取特征向量：输入规格、归一化与L2处理
检测到人脸并裁剪出来后，下一步是提取特征向量。ArcFace是当前人脸识别领域常用的损失函数和模型结构，它的ONNX版本输入通常是112×112的RGB图像，输出是512维的浮点向量。这个向量经过L2归一化后，可以直接用余弦相似度来度量两个人脸的相似程度。
import cv2 import numpy as np class FaceEncoder: def __init__(self, model_path, input_size=(112, 112)): self.net = cv2.dnn.readNetFromONNX(model_path) self.input_size = input_size def encode(self, face_img): # 统一尺寸 img = cv2.resize(face_img, self.input_size) # 转RGB，很多ONNX模型是用RGB通道训练的 img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # 归一化到[-1, 1]，这是ArcFace类模型的标准预处理 img = img.astype(np.float32) / 127.5 - 1.0 # 构建blob并推理 blob = cv2.dnn.blobFromImage( img, scalefactor=1.0, size=self.input_size, mean=(0, 0, 0), swapRB=False ) self.net.setInput(blob) embedding = self.net.forward().flatten() # L2归一化：让向量长度为1，后面直接算内积就是余弦相似度 norm = np.linalg.norm(embedding) if norm > 1e-10: embedding = embedding / norm return embedding预处理这几个参数是踩坑重灾区。swapRB这个参数尤其要注意：如果模型训练时用的是RGB图，而OpenCV默认读进来的图是BGR，就必须在blobFromImage里设swapRB=True，或者像我这样提前cvtColor转成RGB。两种做法等效，但我习惯在构建blob之前显式转换，因为swapRB只在blobFromImage内部生效，容易让人忽略预处理链路的实际颜色空间。归一化公式x / 127.5 - 1.0是ArcFace官方预处理的标准写法，输入被映射到[-1, 1]区间。不要自作主张改用/ 255.0，那会让模型输入分布偏移，特征质量明显下降。L2归一化这一步也不能省，不归一化直接算余弦，数值上会受向量模长干扰，阈值就失去意义了。
3.3 特征比对与阈值选择：余弦相似度为什么够用
提取到512维向量后，比对逻辑很简单。因为两个向量都做了L2归一化，所以它们的点积就等于余弦相似度，取值范围是[-1, 1]，越大越相似。
def cosine_similarity(vec_a, vec_b): # 两个向量都必须经过L2归一化 return float(np.dot(vec_a, vec_b))阈值的选择直接决定系统的可用性。阈值设得太高，真人签到会被拒绝，用户体验极差；设得太低，随便一个路人甲都能冒充。我见过太多项目在阈值上翻车：用一个固定值0.5跑遍所有场景，结果室内光线暗一点就识别失败。合理的做法是预留一个配置项，在部署现场用真实摄像头采集正负样本对，画出一条ROC曲线，选等错误率最低的点。没有验证条件时，可以用0.35到0.45这个区间起步，然后根据实际表现微调。同一个人在不同光线、角度下的余弦相似度通常在0.5以上，而不同人之间的相似度一般低于0.3，所以0.4附近是一个相对稳妥的起点。
4. 把签到业务接进Flask：数据库、注册与打卡路由
4.1 数据表设计：学生、特征、签到记录三张表
人脸识别签到系统本质上还是一个业务系统，数据设计要支撑“谁注册了”“谁签到了”这两个核心问题。我用SQLite做存储，因为它是文件型数据库，不需要单独安装服务，部署时直接带着.db文件走。三张表的关系很清晰：student存学生基本信息，face_feature存人脸特征向量，attendance存签到记录。
CREATE TABLE IF NOT EXISTS student ( id INTEGER PRIMARY KEY AUTOINCREMENT, student_no TEXT NOT NULL UNIQUE, name TEXT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE IF NOT EXISTS face_feature ( id INTEGER PRIMARY KEY AUTOINCREMENT, student_id INTEGER NOT NULL, feature BLOB NOT NULL, sample_count INTEGER DEFAULT 1, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (student_id) REFERENCES student(id) ); CREATE TABLE IF NOT EXISTS attendance ( id INTEGER PRIMARY KEY AUTOINCREMENT, student_id INTEGER NOT NULL, checkin_date TEXT NOT NULL, checkin_time DATETIME DEFAULT CURRENT_TIMESTAMP, status TEXT DEFAULT 'normal', FOREIGN KEY (student_id) REFERENCES student(id) );face_feature.feature字段用BLOB类型存储人脸特征向量。向量是512个float32数值，直接存成二进制比存文本高效得多，读取后用np.frombuffer还原成ndarray即可。sample_count字段记录这个人录了几张人脸样本，为后面提升识别准确率留了余地——一个人存3到5张不同角度的脸，比对时取最大相似度，这是提高鲁棒性最简单的办法，不用改算法。
这里有一个设计取舍：我把checkin_date单独拆出来存日期字符串，而不是依赖checkin_time做日期提取。原因是判断“今天是否已签到”需要频繁查询，如果每次都写date(checkin_time)，SQLite会对每行执行日期函数，学生多了以后查询会变慢。直接在插入时算好当天日期字符串，查询就变成等值匹配，速度更快，也更好建索引。
4.2 注册流程：照片上传、特征入库与重名处理
注册流程的核心是把“一张脸”变成“一条特征记录”并和学号关联。前端上传照片后，后端先做人脸检测，检测不到就返回错误，检测到了就提取特征写库。
@app.route("/api/register", methods=["POST"]) def register(): data = request.get_json() student_no = data.get("student_no") name = data.get("name") image_base64 = data.get("image") if not all([student_no, name, image_base64]): return jsonify({"code": 1, "msg": "学号、姓名和照片不能为空"}) frame = decode_base64_image(image_base64) if frame is None: return jsonify({"code": 1, "msg": "图片解码失败"}) face_imgs = detector.crop_faces(frame) if len(face_imgs) == 0: return jsonify({"code": 1, "msg": "没有检测到人脸，请正对摄像头并保持光线充足"}) if len(face_imgs) > 1: return jsonify({"code": 1, "msg": "检测到多张人脸，请让其他人离开画面"}) embedding = encoder.encode(face_imgs[0]) conn = get_db_conn() # 检查学号是否已存在，防止重复注册 existing = conn.execute( "SELECT id FROM student WHERE student_no = ?", (student_no,) ).fetchone() if existing: # 更新特征，而不是插入新学生 conn.execute( "UPDATE face_feature SET feature = ?, updated_at = CURRENT_TIMESTAMP WHERE student_id = ?", (embedding.astype(np.float32).tobytes(), existing[0]) ) else: cursor = conn.execute( "INSERT INTO student (student_no, name) VALUES (?, ?)", (student_no, name) ) student_id = cursor.lastrowid conn.execute( "INSERT INTO face_feature (student_id, feature, sample_count) VALUES (?, ?, ?)", (student_id, embedding.astype(np.float32).tobytes(), 1) ) conn.commit() conn.close() return jsonify({"code": 0, "msg": f"学生 {name} 注册成功"})这个路由里我做了两个防御性设计。一是“多张人脸直接拒绝”，因为注册阶段必须保证录入的是目标学生本人，如果照片里还有别人，特征向量会被干扰。二是“学号已存在时更新特征”，学生换发型、戴眼镜都会导致特征漂移，重新注册比删了再建更合理。decode_base64_image是前端上传的base64字符串解析函数，具体实现是去掉data:image/jpeg;base64,前缀后用cv2.imdecode解码。这里务必注意解码结果的通道顺序，如果前端canvas生成的图片是RGB，而后端直接用cv2.imdecode解，得到的是BGR，颜色空间不一致会导致特征质量下降。我的做法是在前端先转成JPEG的base64，后端解出来就是OpenCV默认的BGR格式，与检测和提特征的预处理链路一致。
4.3 签到流程：比对、去重、写库一次完成
签到路由是系统的核心路径，性能要求比注册高，因为它在使用中会被频繁调用。流程是：前端拍照上传 → 后端检测人脸 → 提取特征 → 和库里所有特征比对 → 找到最相似的人且相似度超过阈值 → 插入签到记录。
@app.route("/api/checkin", methods=["POST"]) def checkin(): data = request.get_json() image_base64 = data.get("image") if not image_base64: return jsonify({"code": 1, "msg": "缺少图像数据"}) frame = decode_base64_image(image_base64) face_imgs = detector.crop_faces(frame) if len(face_imgs) == 0: return jsonify({"code": 1, "msg": "未检测到人脸，请正对摄像头"}) # 多人同框时只取最大人脸，避免签错人 max_face = max(face_imgs, key=lambda img: img.shape[0] * img.shape[1]) embedding = encoder.encode(max_face) conn = get_db_conn() rows = conn.execute( "SELECT s.id, s.name, f.feature FROM student s " "JOIN face_feature f ON s.id = f.student_id" ).fetchall() best_student_id = None best_name = None best_score = -1 for sid, name, feat_blob in rows: feat = np.frombuffer(feat_blob, dtype=np.float32) score = cosine_similarity(embedding, feat) if score > best_score: best_score = score best_student_id = sid best_name = name conn.close() if best_score < 0.40: return jsonify({"code": 1001, "msg": "无法识别，请靠近摄像头或重新注册"}) return handle_attendance_insert(best_student_id, best_name, best_score)handle_attendance_insert是去重和写库的辅助函数，逻辑是检查这个人今天是否已经签过到。如果签过，返回“已签到”而不重复插入；如果没签过，插入新记录。这里有个实际体验问题：很多学生走到摄像头前会停留几秒，前端如果连续拍照，会产生好几条签到请求。如果不做去重，一个人会签七八次到，后面统计考勤就乱套了。所以去重逻辑必须在服务端做，不能依赖前端控制。
def handle_attendance_insert(student_id, name, score): today = datetime.now().strftime("%Y-%m-%d") conn = get_db_conn() existing = conn.execute( "SELECT id FROM attendance WHERE student_id = ? AND checkin_date = ?", (student_id, today) ).fetchone() if existing: conn.close() return jsonify({"code": 2, "msg": f"{name} 今天已签到", "name": name}) conn.execute( "INSERT INTO attendance (student_id, checkin_date, status) VALUES (?, ?, ?)", (student_id, today, "normal") ) conn.commit() conn.close() return jsonify({"code": 0, "msg": f"签到成功：{name}", "name": name})全表扫描比对在几十个人的班级场景下完全没有压力，SQLite读取几十行特征二进制再计算余弦，整个流程耗时在100毫秒以内。但如果系统要撑几百人甚至上千人，这种线性扫描就会变成性能瓶颈。到那个量级，要么引入支持向量索引的数据库，要么做两级筛选——先用粗粒度特征缩小候选集，再做精细比对。毕业设计通常不需要考虑这个，但如果答辩老师问扩展性，你就说“当前架构单机支撑百人规模没问题，更大规模需要引入向量数据库或分片”，这是真实的工程判断。
4.4 前端怎么配合：getUserMedia采集与canvas转图
前端这块不需要写得多复杂，但有一个关键点：别让用户先拍照再上传文件，而是直接调摄像头实时取帧。用浏览器的getUserMedia接口拿到视频流后，绘制到<video>标签上，再用canvas.drawImage截取当前帧，最后canvas.toDataURL('image/jpeg')转成base64发送给后端。
const video = document.getElementById('video'); const canvas = document.getElementById('canvas'); const ctx = canvas.getContext('2d'); async function startCamera() { const stream = await navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480 } }); video.srcObject = stream; await video.play(); } function captureAndCheckin() { canvas.width = video.videoWidth; canvas.height = video.videoHeight; ctx.drawImage(video, 0, 0, canvas.width, canvas.height); const base64Image = canvas.toDataURL('image/jpeg', 0.8); fetch('/api/checkin', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ image: base64Image }) }).then(res => res.json()).then(data => { alert(data.msg); }); }getUserMedia有一个安全限制：只有在localhost或HTTPS环境下才能调用摄像头。如果部署到局域网IP，浏览器会直接拒绝，这是新手最容易懵的地方。本地调试用127.0.0.1访问就行，如果是教室内网部署，建议用nginx加HTTPS证书，或者退一步让用户手动拍照上传文件。JPEG压缩质量0.8足够人脸识别用了，base64体积大约几十KB，局域网传输毫无压力。不需要用PNG，PNG对照片的压缩率差，传输慢，还会明显增大请求体。
5. 避坑：人脸识别签到最常见的6个翻车点
5.1 cv2.error和ModuleNotFoundError：环境安装的连环坑
现象：执行import cv2直接报ModuleNotFoundError: No module named 'cv2'；或者在安装OpenCV后import时爆cv2.error: OpenCV(4.4.0) C:\users\... pip-req-build...这类底层错误。
原因：环境搞混了。最常见的是电脑上装了多个Python，pip install opencv-python装到了A环境，但IDE或终端用的是B环境。另一种是版本不匹配，比如Python 3.12刚发布时，OpenCV的预编译wheel还没跟上，装出来跑不起来。
解决：创建一个干净的虚拟环境，不要用系统Python裸奔。我的习惯是：
python -m venv venv venv\Scripts\activate # Windows # 或者 source venv/bin/activate # Linux/Mac pip install --upgrade pip pip install opencv-python numpy flask装完先验证环境一致性：
python -c "import cv2; print(cv2.__version__)"如果打印出版本号就正常了。注意一定要用python -m pip install而不要只敲pip install，因为前者能确保pip和python属于同一个环境。PyCharm里还要检查解释器路径是否指向venv目录。另外，Windows上如果装了多个OpenCV版本（conda一份、pip一份），import时会加载到错误的那份，建议把site-packages里残留的cv2文件夹清干净再重装。
5.2 识别率一塌糊涂：光照、角度、遮挡三座大山
现象：白天识别没问题，傍晚光线暗一点就频繁签到失败；学生侧着脸看屏幕，识别就翻车；戴口罩几乎全挂。
原因：人脸识别模型对光照、姿态、遮挡非常敏感。检测框能框住脸，但特征提取模型输入的是112×112的小图，光线暗导致对比度低、侧脸导致关键区域被压缩、遮挡直接丢失面部信息，这些都会让特征向量偏离正常分布。
解决：分三层处理。第一层是采集端，签到页面做实时提示，判断画面亮度均值，低于阈值就提示“光线不足，请开灯”。第二层是算法端，给检测框加margin、增加注册样本数，每人存3到5张不同角度的特征向量，比对时取最大相似度。第三层是现场端，摄像头安装位置要正对签到区域，高度与人脸齐平，避免俯拍和仰拍。口罩这个问题，如果必须支持，需要换用带口罩识别的专用模型，普通ArcFace解决不了，不要硬扛。
5.3 摄像头权限与设备占用：本地能跑、部署就废
现象：浏览器页面打开后摄像头画面黑屏，控制台报NotAllowedError；或者后端用cv2.VideoCapture(0)读取摄像头时返回False。
原因：浏览器只有localhost和HTTPS协议下才允许调用getUserMedia，用IP地址访问会被拒绝。同时打开多个页面抢用摄像头，或者手机扫码时微信内置浏览器禁用了摄像头权限，也会导致黑屏。
解决：所有调试统一走http://127.0.0.1:5000，不要用IP。需要局域网访问时，要么配HTTPS，要么改成上传照片的方式而不是直接调摄像头。后端读取USB摄像头报False，先检查摄像头驱动是否正常、是否被其他应用占用，Windows下可以用cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)强制指定采集后端。这个参数在Windows上能解决很多莫名奇妙的摄像头打不开问题。
5.4 Flask模型加载慢、内存爆涨：全局单例没做好的后果
现象：第一个请求进来卡了十几秒，后续请求也时不时卡顿；任务管理器看到Python进程内存不断上涨。
原因：把模型加载写在了路由函数内部，每个请求都执行一次cv2.dnn.readNetFromONNX，模型文件反复从磁盘读、反复初始化，CPU和内存都被拖垮。开发模式默认不开多线程，但一个卡顿请求阻塞整个应用。
解决：严格使用模块级单例模式。所有初始化放在模块加载阶段，路由内部只调用已经加载好的模型。还要注意Flask开发服务器的debug=True模式会开两个进程处理代码热重载，那两个进程各加载一份模型，内存翻倍是正常的，不要慌。部署时用debug=False，并在启动脚本里显式声明单进程：
app.run(host="0.0.0.0", port=5000, debug=False)生产环境如果坚持用gunicorn，--workers 1就够了，这个项目没有多进程需求，多开的worker纯粹浪费内存。
5.5 阈值拍脑袋乱设：固定0.5害死人
现象：注册后第二天来签到，同一张脸识别失败；或者随便拿张手机照片放摄像头前，居然也能签到成功。
原因：阈值设得太高或太低，而且没有考虑不同模型、不同摄像头、不同光照下的分数分布差异。ArcFace的余弦分数分布和face_recognition的欧氏距离分布完全不同，网上抄来的阈值不一定适配你的模型。
解决：把阈值放到配置文件里，部署后做一次真实的“阈值校准”。具体做法是采集20个已注册学生的正面照作为正样本，再采集20个非注册人脸作为负样本，分别计算与库特征的相似度，取正样本最低分和负样本最高分的中间值作为阈值。没有条件采集时，先用0.4起步，然后观察一周签到日志：如果出现“无法识别”的投诉，就下调0.05；如果出现“不是我本人但签到成功”，就上调0.05。这个方法不优雅但非常实用。
5.6 前端反复调接口导致重复签到：服务端去重不能省
现象：学生A站在摄像头前，3秒内签到了5次，考勤统计时出现5条记录。
原因：前端可能因为点击多次或自动重试发送了多个请求，服务端没有判断“今天是否已签到”。
解决：签到路由必须做去重，按student_id + checkin_date查重。我给出的handle_attendance_insert已经实现了这个逻辑。但要注意，判断去重的查询和插入记录之间有一个时间窗口，高并发下两个请求可能同时通过查重，然后各插一条。单进程开发服务器下这个概率很低，但严谨起见可以在attendance表上建联合唯一索引：
CREATE UNIQUE INDEX idx_student_date ON attendance(student_id, checkin_date);这样即使并发插入，数据库层面也会拒绝重复记录，应用侧捕获冲突异常返回“今日已签到”。索引是兜底防线，务必加上。
6. 让系统真正落地：阈值调优、活体检测与验证评估方法
系统跑通只是第一步，真正让它可靠可用，还需要做三件收尾工作。
第一件是阈值调优。别在代码里写死score = 0.4，把阈值放到一个config.py文件里，然后做一次真实验证。建议从你录入的注册库里挑30个人，每人拍一张当天的新照片作为正样本，再找30个非注册人作为负样本。扫描从0.20到0.60的阈值，计算每个阈值下的召回率（正样本中签到成功的比例）和误识率（负样本中签到成功的比例），取两者交叉点附近的值。没有现成工具就写个十行脚本，这个数据比任何经验值都靠谱。
第二件是活体检测。目前的系统本质上只能判断“画面中的人脸属于谁的建模”，如果学生拿一张打印照片或手机图片放摄像头前，也能通过。这在实际考勤中是个明显的漏洞。最简单的活体检测方案是用OpenCV读人脸关键点，要求用户完成一次眨眼或张嘴动作，检测到动作变化才认为人脸是活的。具体可以用面部68点标定提取左右眼的纵横比EAR，连续几帧EAR低于阈值表示眨眼，把这个检测挂在签到接口前即可。注意检测要限时，比如5秒内完成眨眼动作，否则用户体验太差。
第三件是量化验证。写一个验证脚本，遍历dataset/目录下每个人的照片，计算识别准确率和平均耗时。这个数据既能帮你了解系统边界，也能在毕业设计论文里写进系统测试章节。我一般会统计三组数字：注册用户在室内光照下的识别率、逆光和暗光下的识别率、不同人脸的误识率。把这些数字整理成表格，答辩时比口头描述“效果很好”有说服力得多。
最后说一个我自己的教训。第一次做类似项目时，我花了大量时间折腾模型选型和训练，结果把工程端的事情——摄像头权限、阈值校准、重复签到——全忽略了，最后演示当天连签到记录都写不进数据库。从那以后我调整了顺序：先把工程链路完整跑通，再回头调精度和模型。这个系统真正的复杂度不在吹嘘的深度模型，而在从摄像头到数据库的每一个小细节。检查环境、跑通流程、校准阈值，这三步做完系统就基本能用了。希望帮到你。
本文还有配套的精品资源，点击获取
