让我来为你完成这篇高质量的项目复盘与实战博文。1. 项目从需求到架构为什么考勤系统最终采用Django 人脸识别先聊一个真实的场景。某个有三百多号人的中型公司行政部每个月月底对考勤记录都要花整整两天。不是数据量大而是问题多有人忘打卡、有人让同事代打、有人拿着门禁卡刷完就溜甚至还有拿照片对着摄像头晃的。HR补签申请单堆成小山财务核算薪资时又因为迟到早退的争议来回扯皮。接手这个考勤系统的改造项目后我的首要目标不是“上人脸识别”这个技术噱头而是先把考勤链路上的人为漏洞堵住——考勤系统做不到绝对的物理管控但至少要保证“记录对应到真实的人”让数据能追溯到人、能复核、能统计。对比几种主流方案RFID卡成本低但无法防止代刷指纹机存在接触卫生和干手指识别率问题真正适合的是“摄像头人脸识别 后台记录比对”。选型时确定两个硬指标一是员工打卡体验不能比刷卡慢太多二是识别必须支持活体检测杜绝照片和视频攻击。同时因为公司内部没有专门运维团队系统要部署简单、维护成本低最好一个普通技术人员就能扛住——于是服务端直接锁定Python生态里成熟度极高的Django理由很直接Django自带Admin后台、ORM和迁移机制考勤这种典型的管理系统用它开发效率是最高的。人脸识别部分选择离线推理方案不依赖外部收费接口数据不出内网。整体架构按三个模块拆分员工与人脸特征管理模块、打卡识别模块、考勤统计与异常处理模块。Django负责Web服务、数据库和业务逻辑人脸识别模块以独立服务的方式供Django调用通过HTTP接口或进程内调用实现解耦。这样做的核心原因是人脸识别算法迭代快如果和业务代码强耦合以后升级模型就要动整个业务系统拆开后替换识别引擎只需保证接口不变考勤业务完全不受影响。这套架构还有一个隐性收益监控摄像头资源复用。公司走廊和门口已有海康摄像头通过RTSP流接入识别服务后不需要额外采购专用考勤机硬件成本几乎为零。系统上线后员工从摄像头前正常走过即可完成打卡高峰期排队现象大幅缓解月底核对时间从两天压缩到半天。下面把整个系统从设计到落地的关键环节完整拆开来讲。2. 数据模型与核心流程设计考勤记录如何做到可追溯考勤系统最容易犯的设计错误是只建一张“打卡记录表”然后让SQL去算迟到早退。实际落地时你会发现补卡申请、外勤、请假、加班、调休这些业务状态掺杂进来后单表统计会彻底失控。所以第一件事是把数据模型拆细。核心表设计如下员工表包含工号、姓名、部门、岗位、入职日期、状态以及与Django用户表的一对一关联用于权限控制。人脸特征表存储员工的128维/512维特征向量和对应照片Hash用于识别比对。单独建表是为了方便后续做底库热更新以及多算法版本切换。考勤记录表每次识别打卡生成一条记录字段包括员工、时间、识别分数、抓拍照片路径、打卡方向上班/下班、设备编号。补卡申请/审批表用于异常处理关联考勤记录或人工补录。请假/加班/外勤表作为考勤计算时的抵消数据源。员工注册流程是系统可用性的基石。员工进入注册页面后需在摄像头前正脸、左侧、右侧、抬头、低头各采集一次每张图像都经过质量校验亮度、模糊度、人脸框大小、角度质量合格才提取特征入库。这一步要求严格是因为底库特征质量决定了后续识别上限——如果注册照片模糊或角度太大打卡时无论怎么调阈值识别率都上不去。打卡识别流程分四步抓拍、检测、比对、写入。摄像头实时帧送入检测器当检测到人脸且人脸框宽度超过画面上限的20%时判断为“有意打卡”自动提取特征与底库比对拿到员工ID后写入考勤记录。写入时记录识别分数和原始抓拍图图像保留30天才清理方便月底争议复核。识别过程整个耗时控制在500ms以内员工无感通过。考勤统计不是实时算的而是每天凌晨通过Django的定时任务跑批。跑批逻辑严格按“先取每日首次打卡作为上班时间再取最后一次作为下班时间”的规则计算再与排班表做差值判断迟到早退。遇到请假、外勤、补卡流程的使用统计结果会自动引用审批通过的数据。这里有一个重要经验考勤记录一旦生成绝不物理删除只做状态变更。因为所有涉及薪资的审计都需要保留事实记录。3. 人脸识别模块的工程化落地模型选型、阈值调优与活体检测人脸识别这个环节大多数教程停留在“调用库返回距离”的层面但真正做工程时坑非常多。我调研了三条路线OpenCV自带的人脸检测器、dlib face_recognition库、以及专门的人脸识别商用离线SDK。OpenCV的Haar级联检测器适合做人脸框定位但特征提取能力较弱不可直接用于识别。face_recognition库在CPU上单张特征提取约1秒左右识别精度在可控光照下够用但需要自己处理性能问题。商用离线SDK精度高、自带活体检测但授权费用和平台绑定需要评估。最终采用“OpenCV负责检测对齐 face_recognition负责特征提取比对 自研简单活体规则”的组合各取所长且完全离线。活体检测是这次改造的重点否则系统上线三天就会被一张A4照片打穿。初期采用“动作指令活体”系统随机要求眨眼、张嘴、转头配合成功才放行准确率高但体验差高峰期员工容易烦躁。后来调整为“静默活体”利用摄像头连续帧的画面差异、人脸关键点位移规律、以及纹理特征判断是否为真人。实际权衡后采用“多帧抓拍 关键点轨迹校验”的折中方案打卡时连续抓5帧如果人脸框位置和关键点在几帧间有自然的微小抖动照片、手机会被识别为静止或用屏幕弯曲导致的非自然形变则判断为活体。纯离线实现不需要云端接口。阈值调优是最需要耐心的一步。face_recognition的face_distance输出0到1的距离距离越小越相似一般默认阈值0.6。默认阈值在标准光照测试集上表现不错但实际办公场景差别很大。我们在三个现场做了超过2000次打卡样本的测试结论如下场景推荐相似度阈值说明走道自然光充足0.50误识极低识别率可达99%走廊灯光偏黄/较暗0.55抑制过暗导致特征偏移逆光/强背光门口0.45必须配合补光否则识别率严重下降戴眼镜人员较多0.52眼镜反光会拉大特征距离这个表是实测数据不是拍脑袋。阈值太高比如0.60会出现A员工刷成B员工的误识阈值太低比如0.40则戴个口罩、换个发型就被拒之门外。调优时不要只看准确率还要算“误识率”和“拒识率”两个指标尤其是误识率考勤系统中一次误识就会带来薪资纠纷宁可多拒绝几次也不能认错人。性能优化方面CPU推理时face_recognition提取一次特征约1秒出头直接传给打卡流程会导致队列积压。优化的做法是三管齐下第一只对检测质量合格的人脸提取特征排除低分辨率帧减少无效计算第二用OpenCV的LBPH做一级粗筛先排除明显不匹配的人特征距离 0.75的直接跳过只有接近阈值的人才进入精细比对可过滤掉约60%的无关计算第三将特征比对做成定时批量任务每秒最多处理10个队列请求让摄像头侧只负责抓图。原理解释一下粗筛用的LBPH要求图片旋转不变性差但速度极快恰好适合“排除明显不相似的人”这一场景。4. Django服务端接口设计与高并发打卡场景避坑指南Django部分的核心不只是写几个视图函数而是要把它当成一个能承受早晚高峰并发的小型中台来设计。员工早上9点到岗的5分钟窗口内可能有上百人同时经过打卡摄像头这意味着接口层和数据库层都要针对写并发做防护。下面给出打卡接口的核心逻辑示例from django.db import transaction from django.views.decorators.http import require_POST from django.http import JsonResponse import json, time require_POST def punch(request): data json.loads(request.body) face_feature data.get(feature, []) captured_image data.get(image_path, ) device_id data.get(device_id, unknown) # 1. 底库比对由识别服务完成这里只接收结果 employee_id request.session.get(matched_employee_id) if not employee_id: return JsonResponse({code: 401, msg: 未识别}) punch_time time.time() # 2. 同一员工5秒内只允许一条有效记录防止摄像头多帧重复写入 lock_key fpunch_lock:{employee_id}:{int(punch_time // 10)} if cache.setnx(lock_key, 1, timeout10): with transaction.atomic(): AttendanceRecord.objects.create( employee_idemployee_id, punch_timedatetime.fromtimestamp(punch_time), scorerequest.session.get(match_score, 0.0), image_pathcaptured_image, device_iddevice_id ) return JsonResponse({code: 0, msg: ok}) else: return JsonResponse({code: 408, msg: 重复打卡或时间间隔过短})这段代码解决了一个非常典型的现实问题摄像头在人脸通过后会连续输出多帧识别服务可能对同一员工在几百毫秒内生成重复记录。如果不去重月底统计会多出大量“幽灵打卡”。设计上引入带锁语义的cache.setnx依赖Redis来保证“同一员工10秒内只落地一条记录”比在数据库做唯一约束更灵活因为约束条件里包含动态的时间窗口。数据库层必须开启事务。原因很简单考勤记录的写入虽然只是一条INSERT但后续会触发当日统计缓存的更新、异常提醒生成、以及可能的WebSocket通知。任何一个环节半途失败都会造成数据不一致。事务能保证要么全部成功要么全部回滚这在月底对账时能省去大量排查时间。还有一类问题容易被忽略考勤报表接口的性能。如果用ORM直接对几十万条考勤记录做聚合分组页面加载会慢到让人怀疑人生。我的做法是设计一张AttendanceDailySummary表每天凌晨由定时任务生成每个员工的日汇总。所有报表接口只查汇总表不查明细表。明细表仅用于复核和审计。这个设计带来的体验提升是质变——月底导出报表从分钟级降到秒级。权限与安全设计同样不能马虎。考勤数据属于员工隐私必须做到精细化权限控制。用Django内置的Group和Permission做RBAC普通员工只能查看自己的考勤和提交补卡申请部门主管可以查看本部门数据但不能修改原始记录HR和系统管理员才有审批和导出权限。登录必须强制开启MFA哪怕是最简单的TOTP并且所有导出操作写入审计日志记录操作人、时间、导出的时间范围和条数。这点在应对内部审计时极其重要。5. 前端交互与部署实录从Django Admin到门禁联动管理端页面我一开始图省事直接用了Django Admin但真实使用半个月后发现两个问题HR习惯的操作方式按部门筛选、日期区间批量标记、导出Excel在Admin上实现起来很费劲而且Admin默认展示所有字段考勤记录表里那些技术字段特征向量、设备编号对HR来说就是噪音。所以最终用Django Jinja2模板写了一套轻量管理页面只保留三个视图实时打卡流水、日汇总表、异常处理中心。员工端则做成了适配手机浏览器的H5页面员工可以查看个人打卡记录、提交补卡申请完全不需要安装App。前端页面的一个关键细节是“打卡实时流水页面”要支持轮询刷新。打卡终端本来就部署在门口行政人员希望能直观看到“谁刚刚打卡了”所以每2秒拉一次最新20条记录同时展示抓拍小图。这个小功能看似简单但行政满意度很高——他们终于不用等月底才看到异常了。部署架构采用经典方案Nginx Gunicorn PostgreSQL Redis。为什么不用SQLite哪怕考勤数据量不大SQLite在高并发写入时会触发“database is locked”错误早晚高峰多人同时打卡时必现。PostgreSQL的稳定性在写并发场景下更让人放心。Gunicorn配置4个worker每个worker配合多线程处理实测单机扛住300人同时打卡的并发毫无压力。人脸识别服务单独部署在同一台机器上的另一个进程通过Unix Socket与Django通信避免HTTP端口暴露也进一步降低了延迟。摄像头接入这块建议优先使用支持RTSP的标准网络摄像头。代码层面只需维护一个设备列表每个设备是一个URL# 拉流抓帧示例识别服务侧 ffmpeg -rtsp_transport tcp -i rtsp://192.168.1.100:554/stream1 \ -frames:v 1 -q:v 2 /srv/captures/$(date %s).jpg实测表明采用TCP传输比UDP稳定得多在Wi-Fi环境下尤其明显UDP断流概率在弱网下接近20%。管理后台增加设备状态监控面板摄像头断线自动通知这是系统稳定运行的重要保障。如果后续要做门禁联动只需在打卡成功时调用门禁控制器的HTTP接口即可。因为人脸识别模块与业务模块的接口是解耦的扩展联动不需要改动Django主体代码在识别服务回调里加几行代码就行。我之前就在两个出入口做了实验从识别成功到门禁开锁延迟约300ms完全可用。6. 实战问题排查与调优记录一次上线让你少踩两年坑整理了上线过程中最典型的七个问题按出现频率排序问题一很多人都用手机屏幕照片打印的“带表情照片”打卡。原因是系统初期活体检测只做了“关键点位移”而小幅晃动的照片也能通过。修复方案是增加“周期性检测”要求在2秒内人脸关键点位移幅度小于一个阈值同时检测屏幕摩尔纹特征数字屏幕才有。虽然不能100%防住但能挡住99%的投机行为。问题二戴眼镜人士识别率剧烈波动。有些员工镜片反光严重特征距离在0.45到0.7之间横跳。线下在工位上补采了镜前和抬头两个姿势的特征把多特征模板取平均距离识别率稳定在98%以上。因此建议人脸底库允许一个员工存储多个特征向量。问题三光线变化导致误识率升高。办公室朝西的门口下午逆光严重识别率一度掉到85%。加装一盏补光灯后问题立刻缓解识别率回升到99%。硬件层面尽量保证摄像头照射区域无强逆光这比任何算法调优都更有效。问题四高峰期识别排队导致的“扎堆打卡失败”。多人连续通过时推理队列积压员工反复经过几百毫秒没有反馈。优化措施是Django接收识别结果后立即返回抓拍和比对异步进行同时把特征比对服务做成并行处理单个摄像头独占一个推理进程互不干扰。问题五员工换发型/戴帽子的情况。特征比对对发型变化容忍度尚可但帽子会造成大面积遮挡。实测中处理办法是注册时明确要求拍照不戴帽、头发不遮眉打卡时如果帽子遮挡面积过大检测器会判定为“无人脸”并引导重新打卡而不是强行识别。问题六月底导出Excel乱码。这个问题不大但极影响体验。解决方案是在Django的StreamingHttpResponse返回CSV时写入BOM头\ufeff大多数Excel版本会正常识别UTF-8编码。问题七考勤异常申诉流程卡住。员工提交补卡申请后审批人没收到通知。原因是通知机制只做了邮件发送而审批人邮件不常看。后来在管理后台首页增加“待办事项”面板审批人登录就能看到流程处理时间大幅缩短。问题现象排查方向解决建议同一人重复打卡看Redis锁是否生效检查SETNXtimeout是否过短识别成功但无人像照片检查摄像头抓帧时序确认抓拍时间与识别时间对齐月底统计迟到数异常查补卡审批是否已同步确认审批状态变更后要更新汇总表识别服务CPU高检查是否有人触发大量无效比对增加人脸尺寸下限过滤远距离路人某时段突然全部识别失败检查是否有人为断电在设备状态页面添加告警日志个人实操心得除非是出现了明显统计错误不要轻易修改已经跑通的阈值。每次调整都要记录版本、日期、场景和前后数据对比。考勤系统的核心不是模型的准确率有多高而是规则稳定、数据可靠、流程闭环。只要这三个目标达成即使单次识别偶尔失败员工也可以通过补卡流程解决整个系统的满意度依然很高。如果后续想继续扩展可以做三件事一是接入更先进的深度活体检测模型进一步压缩照片打卡的漏洞二是把识别服务做成独立的微服务支持多办公楼多设备统一管理三是对照片和个人特征做脱敏加密存储满足数据隐私合规要求。这些都是从“能用”走向“好用”的必经之路每一步都值得单独写一篇复盘文章来记录。 
长河君 · 2026/10/19 19:27:58 · 阅读 1.2k Django + 人脸识别考勤系统实战：从数据模型到部署避坑指南
让我来为你完成这篇高质量的项目复盘与实战博文。1. 项目从需求到架构为什么考勤系统最终采用Django 人脸识别先聊一个真实的场景。某个有三百多号人的中型公司行政部每个月月底对考勤记录都要花整整两天。不是数据量大而是问题多有人忘打卡、有人让同事代打、有人拿着门禁卡刷完就溜甚至还有拿照片对着摄像头晃的。HR补签申请单堆成小山财务核算薪资时又因为迟到早退的争议来回扯皮。接手这个考勤系统的改造项目后我的首要目标不是“上人脸识别”这个技术噱头而是先把考勤链路上的人为漏洞堵住——考勤系统做不到绝对的物理管控但至少要保证“记录对应到真实的人”让数据能追溯到人、能复核、能统计。对比几种主流方案RFID卡成本低但无法防止代刷指纹机存在接触卫生和干手指识别率问题真正适合的是“摄像头人脸识别 后台记录比对”。选型时确定两个硬指标一是员工打卡体验不能比刷卡慢太多二是识别必须支持活体检测杜绝照片和视频攻击。同时因为公司内部没有专门运维团队系统要部署简单、维护成本低最好一个普通技术人员就能扛住——于是服务端直接锁定Python生态里成熟度极高的Django理由很直接Django自带Admin后台、ORM和迁移机制考勤这种典型的管理系统用它开发效率是最高的。人脸识别部分选择离线推理方案不依赖外部收费接口数据不出内网。整体架构按三个模块拆分员工与人脸特征管理模块、打卡识别模块、考勤统计与异常处理模块。Django负责Web服务、数据库和业务逻辑人脸识别模块以独立服务的方式供Django调用通过HTTP接口或进程内调用实现解耦。这样做的核心原因是人脸识别算法迭代快如果和业务代码强耦合以后升级模型就要动整个业务系统拆开后替换识别引擎只需保证接口不变考勤业务完全不受影响。这套架构还有一个隐性收益监控摄像头资源复用。公司走廊和门口已有海康摄像头通过RTSP流接入识别服务后不需要额外采购专用考勤机硬件成本几乎为零。系统上线后员工从摄像头前正常走过即可完成打卡高峰期排队现象大幅缓解月底核对时间从两天压缩到半天。下面把整个系统从设计到落地的关键环节完整拆开来讲。2. 数据模型与核心流程设计考勤记录如何做到可追溯考勤系统最容易犯的设计错误是只建一张“打卡记录表”然后让SQL去算迟到早退。实际落地时你会发现补卡申请、外勤、请假、加班、调休这些业务状态掺杂进来后单表统计会彻底失控。所以第一件事是把数据模型拆细。核心表设计如下员工表包含工号、姓名、部门、岗位、入职日期、状态以及与Django用户表的一对一关联用于权限控制。人脸特征表存储员工的128维/512维特征向量和对应照片Hash用于识别比对。单独建表是为了方便后续做底库热更新以及多算法版本切换。考勤记录表每次识别打卡生成一条记录字段包括员工、时间、识别分数、抓拍照片路径、打卡方向上班/下班、设备编号。补卡申请/审批表用于异常处理关联考勤记录或人工补录。请假/加班/外勤表作为考勤计算时的抵消数据源。员工注册流程是系统可用性的基石。员工进入注册页面后需在摄像头前正脸、左侧、右侧、抬头、低头各采集一次每张图像都经过质量校验亮度、模糊度、人脸框大小、角度质量合格才提取特征入库。这一步要求严格是因为底库特征质量决定了后续识别上限——如果注册照片模糊或角度太大打卡时无论怎么调阈值识别率都上不去。打卡识别流程分四步抓拍、检测、比对、写入。摄像头实时帧送入检测器当检测到人脸且人脸框宽度超过画面上限的20%时判断为“有意打卡”自动提取特征与底库比对拿到员工ID后写入考勤记录。写入时记录识别分数和原始抓拍图图像保留30天才清理方便月底争议复核。识别过程整个耗时控制在500ms以内员工无感通过。考勤统计不是实时算的而是每天凌晨通过Django的定时任务跑批。跑批逻辑严格按“先取每日首次打卡作为上班时间再取最后一次作为下班时间”的规则计算再与排班表做差值判断迟到早退。遇到请假、外勤、补卡流程的使用统计结果会自动引用审批通过的数据。这里有一个重要经验考勤记录一旦生成绝不物理删除只做状态变更。因为所有涉及薪资的审计都需要保留事实记录。3. 人脸识别模块的工程化落地模型选型、阈值调优与活体检测人脸识别这个环节大多数教程停留在“调用库返回距离”的层面但真正做工程时坑非常多。我调研了三条路线OpenCV自带的人脸检测器、dlib face_recognition库、以及专门的人脸识别商用离线SDK。OpenCV的Haar级联检测器适合做人脸框定位但特征提取能力较弱不可直接用于识别。face_recognition库在CPU上单张特征提取约1秒左右识别精度在可控光照下够用但需要自己处理性能问题。商用离线SDK精度高、自带活体检测但授权费用和平台绑定需要评估。最终采用“OpenCV负责检测对齐 face_recognition负责特征提取比对 自研简单活体规则”的组合各取所长且完全离线。活体检测是这次改造的重点否则系统上线三天就会被一张A4照片打穿。初期采用“动作指令活体”系统随机要求眨眼、张嘴、转头配合成功才放行准确率高但体验差高峰期员工容易烦躁。后来调整为“静默活体”利用摄像头连续帧的画面差异、人脸关键点位移规律、以及纹理特征判断是否为真人。实际权衡后采用“多帧抓拍 关键点轨迹校验”的折中方案打卡时连续抓5帧如果人脸框位置和关键点在几帧间有自然的微小抖动照片、手机会被识别为静止或用屏幕弯曲导致的非自然形变则判断为活体。纯离线实现不需要云端接口。阈值调优是最需要耐心的一步。face_recognition的face_distance输出0到1的距离距离越小越相似一般默认阈值0.6。默认阈值在标准光照测试集上表现不错但实际办公场景差别很大。我们在三个现场做了超过2000次打卡样本的测试结论如下场景推荐相似度阈值说明走道自然光充足0.50误识极低识别率可达99%走廊灯光偏黄/较暗0.55抑制过暗导致特征偏移逆光/强背光门口0.45必须配合补光否则识别率严重下降戴眼镜人员较多0.52眼镜反光会拉大特征距离这个表是实测数据不是拍脑袋。阈值太高比如0.60会出现A员工刷成B员工的误识阈值太低比如0.40则戴个口罩、换个发型就被拒之门外。调优时不要只看准确率还要算“误识率”和“拒识率”两个指标尤其是误识率考勤系统中一次误识就会带来薪资纠纷宁可多拒绝几次也不能认错人。性能优化方面CPU推理时face_recognition提取一次特征约1秒出头直接传给打卡流程会导致队列积压。优化的做法是三管齐下第一只对检测质量合格的人脸提取特征排除低分辨率帧减少无效计算第二用OpenCV的LBPH做一级粗筛先排除明显不匹配的人特征距离 0.75的直接跳过只有接近阈值的人才进入精细比对可过滤掉约60%的无关计算第三将特征比对做成定时批量任务每秒最多处理10个队列请求让摄像头侧只负责抓图。原理解释一下粗筛用的LBPH要求图片旋转不变性差但速度极快恰好适合“排除明显不相似的人”这一场景。4. Django服务端接口设计与高并发打卡场景避坑指南Django部分的核心不只是写几个视图函数而是要把它当成一个能承受早晚高峰并发的小型中台来设计。员工早上9点到岗的5分钟窗口内可能有上百人同时经过打卡摄像头这意味着接口层和数据库层都要针对写并发做防护。下面给出打卡接口的核心逻辑示例from django.db import transaction from django.views.decorators.http import require_POST from django.http import JsonResponse import json, time require_POST def punch(request): data json.loads(request.body) face_feature data.get(feature, []) captured_image data.get(image_path, ) device_id data.get(device_id, unknown) # 1. 底库比对由识别服务完成这里只接收结果 employee_id request.session.get(matched_employee_id) if not employee_id: return JsonResponse({code: 401, msg: 未识别}) punch_time time.time() # 2. 同一员工5秒内只允许一条有效记录防止摄像头多帧重复写入 lock_key fpunch_lock:{employee_id}:{int(punch_time // 10)} if cache.setnx(lock_key, 1, timeout10): with transaction.atomic(): AttendanceRecord.objects.create( employee_idemployee_id, punch_timedatetime.fromtimestamp(punch_time), scorerequest.session.get(match_score, 0.0), image_pathcaptured_image, device_iddevice_id ) return JsonResponse({code: 0, msg: ok}) else: return JsonResponse({code: 408, msg: 重复打卡或时间间隔过短})这段代码解决了一个非常典型的现实问题摄像头在人脸通过后会连续输出多帧识别服务可能对同一员工在几百毫秒内生成重复记录。如果不去重月底统计会多出大量“幽灵打卡”。设计上引入带锁语义的cache.setnx依赖Redis来保证“同一员工10秒内只落地一条记录”比在数据库做唯一约束更灵活因为约束条件里包含动态的时间窗口。数据库层必须开启事务。原因很简单考勤记录的写入虽然只是一条INSERT但后续会触发当日统计缓存的更新、异常提醒生成、以及可能的WebSocket通知。任何一个环节半途失败都会造成数据不一致。事务能保证要么全部成功要么全部回滚这在月底对账时能省去大量排查时间。还有一类问题容易被忽略考勤报表接口的性能。如果用ORM直接对几十万条考勤记录做聚合分组页面加载会慢到让人怀疑人生。我的做法是设计一张AttendanceDailySummary表每天凌晨由定时任务生成每个员工的日汇总。所有报表接口只查汇总表不查明细表。明细表仅用于复核和审计。这个设计带来的体验提升是质变——月底导出报表从分钟级降到秒级。权限与安全设计同样不能马虎。考勤数据属于员工隐私必须做到精细化权限控制。用Django内置的Group和Permission做RBAC普通员工只能查看自己的考勤和提交补卡申请部门主管可以查看本部门数据但不能修改原始记录HR和系统管理员才有审批和导出权限。登录必须强制开启MFA哪怕是最简单的TOTP并且所有导出操作写入审计日志记录操作人、时间、导出的时间范围和条数。这点在应对内部审计时极其重要。5. 前端交互与部署实录从Django Admin到门禁联动管理端页面我一开始图省事直接用了Django Admin但真实使用半个月后发现两个问题HR习惯的操作方式按部门筛选、日期区间批量标记、导出Excel在Admin上实现起来很费劲而且Admin默认展示所有字段考勤记录表里那些技术字段特征向量、设备编号对HR来说就是噪音。所以最终用Django Jinja2模板写了一套轻量管理页面只保留三个视图实时打卡流水、日汇总表、异常处理中心。员工端则做成了适配手机浏览器的H5页面员工可以查看个人打卡记录、提交补卡申请完全不需要安装App。前端页面的一个关键细节是“打卡实时流水页面”要支持轮询刷新。打卡终端本来就部署在门口行政人员希望能直观看到“谁刚刚打卡了”所以每2秒拉一次最新20条记录同时展示抓拍小图。这个小功能看似简单但行政满意度很高——他们终于不用等月底才看到异常了。部署架构采用经典方案Nginx Gunicorn PostgreSQL Redis。为什么不用SQLite哪怕考勤数据量不大SQLite在高并发写入时会触发“database is locked”错误早晚高峰多人同时打卡时必现。PostgreSQL的稳定性在写并发场景下更让人放心。Gunicorn配置4个worker每个worker配合多线程处理实测单机扛住300人同时打卡的并发毫无压力。人脸识别服务单独部署在同一台机器上的另一个进程通过Unix Socket与Django通信避免HTTP端口暴露也进一步降低了延迟。摄像头接入这块建议优先使用支持RTSP的标准网络摄像头。代码层面只需维护一个设备列表每个设备是一个URL# 拉流抓帧示例识别服务侧 ffmpeg -rtsp_transport tcp -i rtsp://192.168.1.100:554/stream1 \ -frames:v 1 -q:v 2 /srv/captures/$(date %s).jpg实测表明采用TCP传输比UDP稳定得多在Wi-Fi环境下尤其明显UDP断流概率在弱网下接近20%。管理后台增加设备状态监控面板摄像头断线自动通知这是系统稳定运行的重要保障。如果后续要做门禁联动只需在打卡成功时调用门禁控制器的HTTP接口即可。因为人脸识别模块与业务模块的接口是解耦的扩展联动不需要改动Django主体代码在识别服务回调里加几行代码就行。我之前就在两个出入口做了实验从识别成功到门禁开锁延迟约300ms完全可用。6. 实战问题排查与调优记录一次上线让你少踩两年坑整理了上线过程中最典型的七个问题按出现频率排序问题一很多人都用手机屏幕照片打印的“带表情照片”打卡。原因是系统初期活体检测只做了“关键点位移”而小幅晃动的照片也能通过。修复方案是增加“周期性检测”要求在2秒内人脸关键点位移幅度小于一个阈值同时检测屏幕摩尔纹特征数字屏幕才有。虽然不能100%防住但能挡住99%的投机行为。问题二戴眼镜人士识别率剧烈波动。有些员工镜片反光严重特征距离在0.45到0.7之间横跳。线下在工位上补采了镜前和抬头两个姿势的特征把多特征模板取平均距离识别率稳定在98%以上。因此建议人脸底库允许一个员工存储多个特征向量。问题三光线变化导致误识率升高。办公室朝西的门口下午逆光严重识别率一度掉到85%。加装一盏补光灯后问题立刻缓解识别率回升到99%。硬件层面尽量保证摄像头照射区域无强逆光这比任何算法调优都更有效。问题四高峰期识别排队导致的“扎堆打卡失败”。多人连续通过时推理队列积压员工反复经过几百毫秒没有反馈。优化措施是Django接收识别结果后立即返回抓拍和比对异步进行同时把特征比对服务做成并行处理单个摄像头独占一个推理进程互不干扰。问题五员工换发型/戴帽子的情况。特征比对对发型变化容忍度尚可但帽子会造成大面积遮挡。实测中处理办法是注册时明确要求拍照不戴帽、头发不遮眉打卡时如果帽子遮挡面积过大检测器会判定为“无人脸”并引导重新打卡而不是强行识别。问题六月底导出Excel乱码。这个问题不大但极影响体验。解决方案是在Django的StreamingHttpResponse返回CSV时写入BOM头\ufeff大多数Excel版本会正常识别UTF-8编码。问题七考勤异常申诉流程卡住。员工提交补卡申请后审批人没收到通知。原因是通知机制只做了邮件发送而审批人邮件不常看。后来在管理后台首页增加“待办事项”面板审批人登录就能看到流程处理时间大幅缩短。问题现象排查方向解决建议同一人重复打卡看Redis锁是否生效检查SETNXtimeout是否过短识别成功但无人像照片检查摄像头抓帧时序确认抓拍时间与识别时间对齐月底统计迟到数异常查补卡审批是否已同步确认审批状态变更后要更新汇总表识别服务CPU高检查是否有人触发大量无效比对增加人脸尺寸下限过滤远距离路人某时段突然全部识别失败检查是否有人为断电在设备状态页面添加告警日志个人实操心得除非是出现了明显统计错误不要轻易修改已经跑通的阈值。每次调整都要记录版本、日期、场景和前后数据对比。考勤系统的核心不是模型的准确率有多高而是规则稳定、数据可靠、流程闭环。只要这三个目标达成即使单次识别偶尔失败员工也可以通过补卡流程解决整个系统的满意度依然很高。如果后续想继续扩展可以做三件事一是接入更先进的深度活体检测模型进一步压缩照片打卡的漏洞二是把识别服务做成独立的微服务支持多办公楼多设备统一管理三是对照片和个人特征做脱敏加密存储满足数据隐私合规要求。这些都是从“能用”走向“好用”的必经之路每一步都值得单独写一篇复盘文章来记录。