简介这是一套面向计算机及相关专业毕业设计的Python企业考勤系统源码基于Django框架融合目标检测与人脸识别技术。系统覆盖员工自动注册、人脸打卡、考勤实时监控与异常事件处理并提供数据分析工具生成考勤报告支撑企业管理者决策。源码共713个文件约267.69MB以307个Python文件为核心含Django后端逻辑与算法实现同时搭配81个SCSS、36个JS、28个CSS及13个HTML前端文件便于界面理解与调整另有SQL数据库脚本、说明文档、LW及PPT等配套材料部署环境要求Python 3.7、MySQL 5.7适合使用PyCharm开发调试。项目结构清晰代码注释完整可直接运行并支持二次开发是课程设计或毕业答辩的高质量参考方案。目前已有92人学习下载。1. 考勤系统的核心矛盾为什么目标检测人脸识别能从根本上解决代打卡代打卡有多泛滥做过行政或考勤管理的人心里都有数。我见过最夸张的公司一个部门 30 人代打卡比例能到四成月底导考勤表的时候 HR 对着照片墙核对到怀疑人生。传统 IC 卡考勤机和指纹机都有天然漏洞卡可以转交指纹膜几十块钱一套。换成目标检测人脸识别的逻辑就不一样了摄像头实时画面里必须出现一张能定位到的人脸提取特征后与库里的员工人脸编码比对确认是本人且确实到岗才写一条考勤记录等于把“人到”拆成了“脸到 活人 时间点”三件事一起验证。这篇文章要拆的这套 Django MySQL 考勤系统就是沿这条线索完整落地的案例OpenCV 做画面中的人脸目标检测face_recognition 提特征做比对后端用 Django 组织业务和规则引擎数据落到 MySQL。它解决了什么一是防代打卡二是把签到、签退、迟到、早退、加班计算这类规则集中管理三是给 HR 一张能直接导出的报表。源码包里包括完整项目源码、MySQL 建表脚本、说明文档、LW 文档和答辩 PPT适合正在做毕业设计、想快速复现一套完整 Web视觉项目的同学也适合中小企业在选型时拿来做技术验证。2. 技术架构与选型DjangoMySQLOpenCV 为何是这类题目的最优解选技术栈不能只看哪个火要看业务形态合不合。考勤系统的核心是“Web 管理端 摄像头识别端 数据库存储”三段式Django 的 MTV 架构、ORM 和自带 Admin 后台恰好覆盖了管理端和存储层OpenCV 和 face_recognition 覆盖视觉层MySQL 承担最终持久化。这个组合在毕业设计和中小企业项目中出现频率极高不是因为什么开源社区的热度而是因为它真的能在一个月内把全流程跑通。2.1 Django 的 MTV 架构与考勤业务天然匹配Django 的 Model-Template-View 三层对考勤系统来说非常舒服。Model 层直接对应员工表、部门表、考勤记录表ORM 让你不用手写复杂的 JOINTemplate 层负责管理后台的页面渲染Django Admin 甚至不用写一行前端代码就能生成可用的增删改查界面View 层处理签到请求、规则计算、报表导出这些业务逻辑。我打开这个项目源码时第一件事就是看 models.py因为表结构设计决定了整个业务能不能撑起来。典型的模型设计长这样from django.db import models class Department(models.Model): name models.CharField(max_length50, uniqueTrue) created_at models.DateTimeField(auto_now_addTrue) class Meta: db_table department class Employee(models.Model): emp_no models.CharField(max_length20, uniqueTrue) name models.CharField(max_length50) department models.ForeignKey(Department, on_deletemodels.SET_NULL, nullTrue) face_encoding models.TextField() # 128维人脸向量序列化后存文本 photo_path models.CharField(max_length255, blankTrue) status models.BooleanField(defaultTrue) # 离职或禁用置False class Meta: db_table employees class AttendanceRecord(models.Model): employee models.ForeignKey(Employee, on_deletemodels.CASCADE) date models.DateField() sign_in_time models.TimeField(nullTrue, blankTrue) sign_out_time models.TimeField(nullTrue, blankTrue) status models.CharField(max_length20, defaultnormal) class Meta: db_table attendance_records unique_together (employee, date)这段代码有三个关键设计值得注意。第一employee 和 date 设置 unique_together从数据库层面保证同一个人同一天只能有一条记录防止签到接口被并发请求刷出多条脏数据。第二face_encoding 存的是 128 维向量的序列化字符串因为 MySQL 没有向量类型这种方案最通用读出来用 json.loads 转成 numpy 数组就能比对。第三Employee 表里加 status 字段员工离职不用物理删除所有历史考勤记录的外键都不会断。从选型角度说Django 的 migrations 机制也是加分项。你改完模型跑一句python manage.py makemigrations再migrate表结构自动同步比手写 SQL 脚本维护起来省心得多。而且 Django 的 CSRF 中间件、ORM 参数化查询天然防注入答辩的时候老师问安全性的问题你有现成的答案可讲。2.2 MySQL 表设计与索引策略考勤记录别裸奔考勤系统最怕的是表越来越大之后查询越来越慢。一个月 200 人的公司考勤记录也就 4000 多条感觉不到问题但如果是 2000 人的规模一年就是几十万条没有索引的查询能把页面拖到十几秒。这个项目的建表脚本里attendance_records 表的索引设计是合理的核心是联合索引。先看建表 SQLCREATE TABLE attendance_records ( id INT AUTO_INCREMENT PRIMARY KEY, employee_id INT NOT NULL, date DATE NOT NULL, sign_in_time TIME DEFAULT NULL, sign_out_time TIME DEFAULT NULL, status VARCHAR(20) DEFAULT normal, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_employee_date (employee_id, date), KEY idx_date (date), KEY idx_employee_status (employee_id, status), CONSTRAINT fk_attendance_employee FOREIGN KEY (employee_id) REFERENCES employees(id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里 idx_date 单独建索引很重要因为 HR 最常用的查询是“某个月的考勤汇总”WHERE 条件里大概率只有 date 范围。uk_employee_date 联合唯一索引既保证了数据唯一性又覆盖了“查某个人某天记录”这种高频查询。utf8mb4 字符集是常识了但很多新手建库时默认是 utf8遇到生僻字或 emoji 直接报错后面坑还特别多。我在实际项目中还会加一个 idx_date_employee 联合索引来覆盖更复杂的报表查询比如“某段时间内所有迟到的人”。这个看项目规模和实际查询频次再定毕业设计阶段有上面三个索引已经完全够用索引不是越多越好写入性能会受影响。2.3 人脸识别库与目标检测框架的选型对比别一上来就追 YOLO人脸识别这块选型网上教程五花八门有人上来就推 YOLOv8 做检测然后让新手折腾 CUDA、标注数据集结果卡在环境配置上两周没出活。这个项目用的组合是经典的 dlib face_recognition OpenCV检测部分基于 HOG 特征不是深度学习模型但胜在开箱即用。我列一个对比表方便你判断为什么这个项目选它方案检测方式识别向量维度环境复杂度适用场景face_recognitionHOG CNN 可选128 维低pip 即可考勤这种小规模人脸库dlib 直接调用HOG / MMOD128 维中需编译有定制需求的场景OpenCV HaarHaar Cascade无只检测低仅做人脸定位YOLOv8 FaceNet深度学习检测器512 维或更高高需 GPU大规模人脸库考勤系统的核心需求是人脸库最多几百人识别速度要快准确率要稳。face_recognition 的 128 维向量在几百人规模下的区分度完全足够而且 CPU 就能跑不需要 GPU 推理这大大降低了部署门槛。HOG 检测器在正脸、光线正常的情况下表现很好唯一的弱项是侧脸和大角度俯仰这个后面避坑章节细说。目标检测在这个项目里的定位是“先找到脸在哪再做识别”。HOG 检测器本质上就是一种目标检测算法它把图像分成小块计算梯度方向直方图训练一个分类器判断每个窗口是不是人脸。好处是可解释性强答辩时你能讲清楚它的原理不像深度学习模型那样做个黑匣子。当然如果你手里有标注好的数据集后续替换成 YOLO 也是可行的第 6 章我会讲替换和验证的思路。3. 从摄像头画面到考勤结果人脸识别目标检测的完整管线现在进入最核心的部分。整套系统的视觉管线可以拆成四步图像采集 → 人脸检测定位 → 特征提取 → 比对判定。每一步都有对应的代码模块也有各自的参数坑。3.1 目标检测层用 HOG 定位人脸区域并做质量过滤管线第一步是把摄像头传来的帧或图片里所有人脸框出来。face_recognition 库封装了 dlib 的 HOG 检测器调用非常简单但参数和前后处理决定了效果上限。import cv2 import numpy as np import face_recognition def detect_and_validate_face(img_bytes: bytes, min_face_size: int 100): 从图片字节流中检测人脸返回最大的那张脸的编码和位置。 min_face_size 控制最小人脸边长过小说明人离摄像头太远不计入考勤。 # 字节流转成 OpenCV 图像 img_array np.frombuffer(img_bytes, dtypenp.uint8) img_bgr cv2.imdecode(img_array, cv2.IMREAD_COLOR) if img_bgr is None: return None, None, False # face_recognition 内部用的是 RGB 顺序OpenCV 是 BGR必须转 rgb_img cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB) # 返回人脸位置列表每个元素是 (top, right, bottom, left) face_locations face_recognition.face_locations(rgb_img, modelhog) if not face_locations: return None, None, False # 取面积最大的人脸作为主识别目标避免后台多人入镜干扰 main_face max(face_locations, keylambda loc: (loc[2] - loc[0]) * (loc[1] - loc[3])) top, right, bottom, left main_face face_width right - left face_height bottom - top # 过滤距离太远、人脸太小的帧 if face_width min_face_size or face_height min_face_size: return None, main_face, False # 返回该人脸区域的编码 encodings face_recognition.face_encodings(rgb_img, known_face_locations[main_face]) if not encodings: return None, main_face, False return encodings[0], main_face, True这段代码里有两个容易被忽略的设计。一是modelhog参数face_recognition 支持 hog 和 cnn 两种模型cnn 精度更高但需要 GPUCPU 环境下 hog 的单帧速度能到几十毫秒对考勤场景够用。二是 min_face_size 过滤这是从真实需求倒推出来的如果员工站在三米外刷脸脸只有几十像素识别率很低且容易误判等于形同虚设。考勤终端一般把摄像头装在 1.5 米高的位置员工站立距离 0.5 到 1 米人脸宽度在 100 到 200 像素之间这个门限值需要根据实际安装环境调整。3.2 特征提取128 维向量背后的距离逻辑人脸检测定位之后下一步是从人脸区域提取特征向量。face_recognition 底层是 dlib 的 ResNet 模型输入一张人脸图像输出一个 128 维的浮点向量。这个向量的特点是同一个人的不同照片向量之间的距离很小不同人的向量距离明显更大。于是识别问题就变成了纯粹的数学问题——算欧几里得距离。import json import numpy as np from .models import Employee def match_employee(face_vector, threshold0.45): 遍历员工库返回距离最近的员工和对应的欧氏距离。 threshold 是判定通过的最大距离越小越严格。 if face_vector is None: return None, None best_employee None best_distance float(inf) # 从数据库读取所有在职员工的人脸编码 for emp in Employee.objects.filter(statusTrue): try: emp_vector np.array(json.loads(emp.face_encoding)) except (json.JSONDecodeError, ValueError): # 编码数据损坏时跳过不影响整体流程 continue # 计算欧几里得距离 distance np.linalg.norm(emp_vector - face_vector) if distance best_distance: best_distance distance best_employee emp if best_employee is None or best_distance threshold: return None, best_distance return best_employee, best_distance参数说明里最关键的阈值 threshold。face_recognition 官方文档给出的参考值范围是 0.4 到 0.6小于 0.4 代表极其相似大于 0.6 基本是不同的人。但实际部署时不能照抄这个数字因为它会受到摄像头型号、光线条件、员工面部状态的影响。我之前做过一个项目同一套阈值在会议室摄像头下误报率极低换到走廊的逆光摄像头后同一个人前后两天都匹配不上。所以落地时我会先采集每个员工 3 到 5 张不同角度的照片算出各员工两两之间的距离分布再画出一条分布曲线。如果员工自己两张照片的距离都在 0.2 到 0.3而不同员工的最小距离在 0.7 以上那 0.45 就是安全阈值留足了余量。3.3 活体与防作弊单靠特征比对远远不够这个项目里比较加分的设计是它没止步于特征比对还利用检测结果做了简单的防作弊判断。有些人可能觉得人脸识别就完事了其实对抗翻拍照片是考勤系统的隐藏需求。网上买一个高清的纸质照片立牌或者直接把手机屏幕怼到摄像头前都能骗过静态的人脸识别因为只要图像里有一张清晰的脸提取出的特征就能匹配上。解决思路有两个层面。轻量级方案是让用户完成一个动作比如眨眼、点头但 face_recognition 本身不提供活体检测能力这套系统采用的办法是检测画面里的人脸尺寸和位置变化判断是否存在持续运动。def is_live_frame(prev_face_box, curr_face_box, frame_threshold5): 简单的活体判断连续两帧人脸位置和尺寸变化小于阈值则认为是静态画面。 手机或照片翻拍时人脸框几乎不移动真实人脸会有轻微抖动和位移。 if prev_face_box is None or curr_face_box is None: return False prev_t, prev_r, prev_b, prev_l prev_face_box curr_t, curr_r, curr_b, curr_l curr_face_box prev_cx (prev_l prev_r) / 2 prev_cy (prev_t prev_b) / 2 curr_cx (curr_l curr_r) / 2 curr_cy (curr_t curr_b) / 2 center_dist abs(curr_cx - prev_cx) abs(curr_cy - prev_cy) prev_w prev_r - prev_l curr_w curr_r - curr_l width_change abs(curr_w - prev_w) return center_dist frame_threshold or width_change frame_threshold这个方案的逻辑很朴素但有效真实的人脸在摄像头前会存在微小的位置晃动和呼吸带来的尺寸变化而静态照片或屏幕里固定不动的照片人脸框参数几乎不变。当然它的局限也很明显如果员工刻意保持不动或者对方用手机播放一段提前录好的点头视频这套判断就会被绕过。更严格的活体检测需要走红外结构光或者深度摄像头那属于硬件层面的事情了。对于毕业设计和使用普通 USB 摄像头的场景运动检测已经能挡住大部分偷懒操作而且答辩时能讲清楚设计意图。4. 考勤业务闭环签到接口、规则引擎与报表导出的 Django 实现视觉管线只解决“这个人是谁”的问题考勤系统的另外半边是“记录下来并算清楚”。签到签退接口怎么设计、规则怎么配置、报表怎么出这三件事决定了系统能不能从 demo 变成真正能用的工具。4.1 签到与签退接口一张 Base64 图片换一条考勤记录前端的摄像头采集到图片后通过 HTTP POST 请求把图片数据发给 Django 后端。考虑到浏览器端拿到的多数是 Base64 字符串接口设计成 JSON 格式比 multipart/form-data 更通用。后端拿到图片后走一遍第 3 章的识别管线命中员工就写考勤记录。import base64 import json from datetime import datetime from django.http import JsonResponse from django.views.decorators.csrf import csrf_exempt from .face_utils import detect_and_validate_face, match_employee from .models import AttendanceRecord csrf_exempt def sign_in_out(request): 签到/签退共用接口。 请求体: {image: data:image/jpeg;base64,xxxx, action: in} action 为 in 或 out分别记录签到和签退时间。 if request.method ! POST: return JsonResponse({code: 400, msg: 仅支持POST请求}) try: payload json.loads(request.body) img_b64 payload.get(image, ) action payload.get(action, in) except json.JSONDecodeError: return JsonResponse({code: 400, msg: 请求体不是合法JSON}) # 去掉 data:image/...;base64, 前缀只保留纯Base64部分 if , in img_b64: img_b64 img_b64.split(,, 1)[1] try: img_bytes base64.b64decode(img_b64) except Exception: return JsonResponse({code: 400, msg: image字段不是合法Base64}) # 检测 提取特征 过滤远距离小脸 face_vector, face_box, ok detect_and_validate_face(img_bytes) if not ok: return JsonResponse({code: 501, msg: 未检测到有效人脸请靠近摄像头}) # 与员工库比对 employee, distance match_employee(face_vector, threshold0.45) if employee is None: return JsonResponse({code: 502, msg: 未匹配到员工请确认已录入人脸}) today datetime.now().date() now_time datetime.now().time() # get_or_create 保证同一天同一个人只有一条记录 record, created AttendanceRecord.objects.get_or_create( employeeemployee, datetoday, defaults{sign_in_time: now_time if action in else None, sign_out_time: now_time if action out else None} ) if action in: if not created and record.sign_in_time: return JsonResponse({code: 503, msg: 今日已签到, name: employee.name}) record.sign_in_time now_time else: if not record.sign_in_time: return JsonResponse({code: 504, msg: 尚未签到不能签退}) record.sign_out_time now_time record.save() return JsonResponse({code: 200, msg: 操作成功, name: employee.name, distance: round(distance, 4)})这个接口的设计有几个可以抄作业的点。第一统一返回code msg结构成功是 200业务失败是 5xx前端只需要判断 code 就能处理所有分支。第二get_or_create 的 defaults 参数配合 created 标志位处理了“首次签到”和“重复签到”两种状态代码分支清爽。第三签退时强制检查是否已有签到记录这个逻辑防止了员工早上直接点签退导致的全天空记录。如果你要在生产环境用还需要补一个防并发锁因为 get_or_create 在高并发下有可能出现重复记录。Django 层可以用 select_for_update 事务锁或者靠 MySQL 的唯一索引兜底后者更稳。4.2 考勤规则参数化迟到、早退、缺卡、加班不再写死在代码里很多新手做考勤系统会把规则写死在视图函数里比如if now_time 9:00: return 迟到。这种做法的痛点是每家公司规则都不一样有的上班时间是 8:30 有的 9:00有的迟到 10 分钟内不扣钱有的加班必须超过 1 小时才算。把这堆变量写死在代码里换一家公司就要改代码重新部署一点都不实际。这个项目把规则做成了一个独立的配置模型考勤计算逻辑从配置里读取参数这是比单纯实现功能更成熟的设计。看规则模型和计算函数from django.db import models class AttendanceRule(models.Model): 考勤规则配置同一时间只启用一条生效规则 name models.CharField(max_length50) work_start_time models.TimeField() # 例如 09:00 work_end_time models.TimeField() # 例如 18:00 late_grace_minutes models.IntegerField(default10) # 迟到宽限分钟数 early_grace_minutes models.IntegerField(default10) # 早退宽限分钟数 work_hours_per_day models.FloatField(default8) # 每日标准工时 is_active models.BooleanField(defaultTrue) class Meta: db_table attendance_rulefrom datetime import datetime, time, timedelta def calc_status(rule, sign_in, sign_out): 根据规则和签到签退时间计算考勤状态。 返回状态字符串: 正常 / 迟到 / 早退 / 缺卡 / 迟到早退 status_parts [] if sign_in is None or sign_out is None: return 缺卡 # 拼接当天的迟到时间基准线: work_start_time 宽限分钟 late_base datetime.combine(datetime.today(), rule.work_start_time) \ timedelta(minutesrule.late_grace_minutes) sign_in_dt datetime.combine(datetime.today(), sign_in) if sign_in_dt late_base: late_minutes int((sign_in_dt - late_base).total_seconds() // 60) status_parts.append(f迟到{late_minutes}分钟) early_base datetime.combine(datetime.today(), rule.work_end_time) \ - timedelta(minutesrule.early_grace_minutes) sign_out_dt datetime.combine(datetime.today(), sign_out) if sign_out_dt early_base: early_minutes int((early_base - sign_out_dt).total_seconds() // 60) status_parts.append(f早退{early_minutes}分钟) return .join(status_parts) if status_parts else 正常参数说明值得留意。宽限分钟数这个参数最容易踩坑很多考勤系统默认宽限为 0结果员工 9 点 00 分 30 秒打卡就算迟到申诉单堆积如山。实际业务里一般给 5 到 15 分钟宽限具体跟企业文化挂钩所以一定要做成可配置项而不是常量。加班计算同理标准工时设为 8 小时后超过部分按加班处理但要区分工作日加班和周末加班那是更细的业务规则毕业设计做到这个深度已经够用了。另外注意 datetime.combine 的使用因为 TimeField 只有时分秒必须和日期拼起来才能做加减这是个容易忽略的细节。更稳妥的做法是在 TimeField 之外额外存一个日期字段或者直接用 DateTimeField 存储完整时间戳避免跨天计算时出现逻辑错乱。4.3 报表导出从 Django Admin 到 Excel 下载考勤系统最终用户是 HRHR 最烦的不是看页面而是导表格。Django Admin 自带列表过滤和导出 CSV 的功能但 CSV 用 Excel 打开中文容易乱码而且 HR 要的往往是带格式的月度汇总表。这个项目里提供了基于 openpyxl 的 Excel 导出功能按月份汇总每个员工的出勤天数、迟到次数、早退次数和加班时长。from openpyxl import Workbook from openpyxl.styles import Font, PatternFill from django.http import HttpResponse from datetime import datetime from .models import AttendanceRecord, Employee def export_monthly_report(request, year, month): 导出指定月份的考勤汇总Excel。 行: 员工维度; 列: 出勤天数, 迟到次数, 早退次数, 缺卡次数, 加班时长 wb Workbook() ws wb.active ws.title f{year}-{month}考勤汇总 headers [工号, 姓名, 部门, 出勤天数, 迟到次数, 早退次数, 缺卡次数] ws.append(headers) # 表头加粗 底色方便HR直接打印 for cell in ws[1]: cell.font Font(boldTrue) cell.fill PatternFill(start_colorD9E1F2, end_colorD9E1F2, fill_typesolid) start_date datetime(year, month, 1).date() end_date datetime(year, month 1, 1).date() if month 12 else datetime(year 1, 1, 1).date() employees Employee.objects.filter(statusTrue).select_related(department) for emp in employees: records AttendanceRecord.objects.filter( employeeemp, date__gtestart_date, date__ltend_date ) late_count sum(1 for r in records if 迟到 in r.status) early_count sum(1 for r in records if 早退 in r.status) miss_count sum(1 for r in records if r.status 缺卡) present_days sum(1 for r in records if r.status ! 缺卡) ws.append([ emp.emp_no, emp.name, emp.department.name if emp.department else -, present_days, late_count, early_count, miss_count ]) response HttpResponse( content_typeapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) response[Content-Disposition] fattachment; filenameattendance_{year}_{month}.xlsx wb.save(response) return response这段代码里date__gte和date__lt的组合是查询连续日期范围的标准写法注意结束日期用的是下个月 1 号加左闭右开区间这样不会漏掉月末最后一天的数据。select_related(department)会预加载部门信息避免在循环里逐条查数据库造成 N1 查询几百人的报表导出差距不明显几千人的时候这个优化能省好几秒。openpyxl 写入后直接wb.save(response)输出为一个 HTTP 响应不会在服务器磁盘上留下临时文件这是个值得养成的习惯。如果你需要更复杂的格式比如合并单元格、数据透视表openpyxl 也支持但毕业设计做到表头样式加粗填充已经能拿出手。5. 部署避坑与常见问题排查环境、数据、生产环境三大战场这个项目复现过程中我把走过的坑按类别整理在后面。每一类我都按“现象 → 原因 → 解决”的格式写这样你遇到问题能直接对号入座。说实话源码拿到手第一天就能跑通的人不多大部分时间都花在环境矛盾和莫名其妙的底层库报错上。5.1 Python 环境与依赖冲突dlib 编译是第一个拦路虎现象执行pip install face_recognition时报错最后几行出现Failed to build dlib或CMake must be installed安装过程直接终止。原因face_recognition 依赖 dlib而 dlib 在 Windows 上默认没有预编译的 wheel 包。pip 会尝试从源码编译需要系统里有 CMake 和 C 编译工具链很多人的机器上根本没装这两个东西。解决Python 3.7 到 3.10 版本优先找 dlib 的预编译 whl 文件。先装好 Visual Studio 的 C 桌面开发组件或者直接下载对应 Python 版本的 dlib wheel 文件离线安装然后再装 face_recognition 就不会再触发编译。我一般用 Python 3.8 或 3.9 跑这个项目dlib 的兼容性最好Python 3.11 以上容易遇到二进制不兼容的问题。还有一类高发的环境冲突是 numpy 版本。face_recognition 依赖较老的 numpy API如果你先装了最新版 numpy 再装 face_recognition它可能不会被自动降级运行时报module numpy has no attribute float。解决方式是把 numpy 降到 1.24 以下版本。5.2 MySQL 连接卡点认证插件、时区、字符集三连坑现象Django 的python manage.py migrate执行时报django.db.utils.OperationalError: (2059, Authentication plugin caching_sha2_password cannot be loaded)。原因MySQL 8.0 默认认证插件是 caching_sha2_password而项目中 Django 连接用的是 PyMySQL 库早期版本不支持这个插件。解决两种方案任选其一。第一种把 MySQL 用户的认证插件改回 mysql_native_passwordALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;第二种是升级 PyMySQL 到 1.0 以上版本新版已支持 caching_sha2_password。我一般直接用第二种因为不用动 MySQL 的全局配置。数据库连接后还有时区坑。Django 的USE_TZ True时写入数据库的时间会自动转成 UTC。如果你在 settings.py 里忘了配置TIME_ZONE Asia/Shanghai考勤记录的签到时间会显示成比北京实际时间早 8 小时。排查方法很简单SELECT NOW()和 Python 的datetime.now()对比一下。另一个高频坑是字符集。建库时如果用了默认 latin1插入中文员工姓名会报Incorrect string value。建库时手动执行CREATE DATABASE attendance CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;可以根治。5.3 摄像头与图片流问题帧率低、画面糊、请求超时现象前端摄像头预览流畅但点签到后要等 3 到 5 秒才出结果有时直接请求超时。原因前端把摄像头原始分辨率的 Base64 图片整个发给后端一张 1920x1080 的 JPEG 图片可能 500KB 到 1MBBase64 编码后体积再膨胀三分之一。后端解析大图、做检测、提取特征耗时长是必然的。解决前端在调用摄像头时直接限制分辨率用navigator.mediaDevices.getUserMedia的 constraints 把视频流拉到 640x480这个分辨率做人脸检测完全够。如果还嫌慢可以在前端用 canvas 把图片压缩到宽度 480px 再转 Base64体积能控制到 30KB 以内。上传后后端的识别时间是毫秒级的。另外摄像头光线不足时检测率会明显下降。这个项目里我建议在考勤终端旁边补一盏常亮灯或者用cv2.convertScaleAbs做一次直方图均衡化代码里加两行预处理就能有效提升检测率。5.4 识别准确率的玄学问题阈值、双胞胎和侧脸现象员工 A 识别成了员工 B或者同一员工上午能识别下午就识别不了。原因第一种误识别的根因是阈值设置过松或者两个员工的 128 维向量距离小于等于阈值直接匹配错了。第二种识别失败的原因多半是光线变化导致脸部特征分布偏移监控摄像头的自动白平衡会在不同时间段改变图像色彩。解决分三步排查。第一步收集每个员工至少 3 张不同场景的照片统计组内距离和组间距离确定安全的阈值区间。这个数据可视化之后你会直观看到有些人的组内距离都能到 0.5根本原因是录入照片质量太差。第二步把人脸识别失败时的图片保存下来定期回看能发现是角度问题还是光线问题。第三步采集端要求员工尽量正向面对摄像头系统里可以加一个姿态提示检测到人脸偏转角度过大就提示“请正对摄像头”这个基于人脸关键点检测能做到但不是 face_recognition 的开箱功能。还有一个容易被忽略的点入库的人脸编码不要太久不更新。人的体重变化、发型变化、胡须变化都会让编码漂移我之前做的系统每个月会扫描一次识别失败记录失败的图片如果确认是本人就重新生成编码更新到数据库。这就是一个自愈机制不复杂但非常提升长期使用的体验。6. 进阶优化阈值自校准、识别速度拉满、把 HOG 换成 YOLOv8如果你复现完基础功能还想继续加深度我建议从三个方向动手都集中在识别链路本身投入产出比最高。第一个方向是阈值自校准脚本。手动调阈值靠玄学写一个脚本统计员工库内两两距离分布自动推荐一个 99% 安全边际的阈值这才是工程做法。脚本逻辑不复杂读取所有员工的 face_encoding分别计算同人不同照片距离均值组内距离和不同人之间距离最小值组间距离输出一张距离分布图取组间最小距离和组内最大距离的中位点作为推荐阈值。这一步做完你下次换摄像头或加新人时不用再凭感觉调参数。第二个方向是识别速度优化。当前代码循环遍历所有员工算距离几百人时还好上千人时每次签到要几十毫秒到上百毫秒。把所有人的编码向量堆叠成一个二维数组用 numpy 矩阵一次性计算距离速度能提升一个量级。除了向量化还可以把人脸编码从 MySQL 全量加载到内存做缓存员工表不常变定时 10 分钟同步一次即可。第三个方向是模型替换验证。face_recognition 的 HOG 检测器在侧脸和复杂背景下确实不如 YOLO 系列。替换思路是用 YOLOv8 做人脸检测输出边界框然后把边界框部分裁出来喂给 face_recognition 做特征提取后续比对逻辑完全不变。验证方法是用 50 张正脸、50 张侧脸、50 张低光照图片分别跑 HOG 和 YOLO 管线统计检测成功率和识别准确率画一张混淆矩阵对比。这个过程工作量不大但能让你彻底理解检测和识别是两个解耦的环节替换任何一环都不影响另一环。这套 Django MySQL 人脸识别的考勤系统我在复现过程中最大的收获不是代码本身而是认识到工程落地的瓶颈往往不在算法而在数据采集质量和边界参数。从那以后我每做一个考勤项目都强制先走一遍人脸距离分布统计用数据说话而不是靠感觉调阈值这个习惯帮我省了不知道多少沟通成本。希望这份拆解能让你也少踩几个坑不管是拿来写毕业论文还是做企业试点都能把时间花在真正有技术含量的地方。本文还有配套的精品资源点击获取