让我来为你完成这篇高质量的项目复盘与实战博文。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 = f"punch_lock:{employee_id}:{int(punch_time // 10)}" if cache.setnx(lock_key, '1', timeout=10): with transaction.atomic(): AttendanceRecord.objects.create( employee_id=employee_id, punch_time=datetime.fromtimestamp(punch_time), score=request.session.get('match_score', 0.0), image_path=captured_image, device_id=device_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高检查是否有人触发大量无效比对增加人脸尺寸下限，过滤远距离路人某时段突然全部识别失败检查是否有人为断电在设备状态页面添加告警日志个人实操心得：除非是出现了明显统计错误，不要轻易修改已经跑通的阈值。每次调整都要记录版本、日期、场景和前后数据对比。考勤系统的核心不是模型的准确率有多高，而是规则稳定、数据可靠、流程闭环。只要这三个目标达成，即使单次识别偶尔失败，员工也可以通过补卡流程解决，整个系统的满意度依然很高。如果后续想继续扩展，可以做三件事：一是接入更先进的深度活体检测模型，进一步压缩照片打卡的漏洞；二是把识别服务做成独立的微服务，支持多办公楼多设备统一管理；三是对照片和个人特征做脱敏加密存储，满足数据隐私合规要求。这些都是从“能用”走向“好用”的必经之路，每一步都值得单独写一篇复盘文章来记录。
让我来为你完成这篇高质量的项目复盘与实战博文。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 = f"punch_lock:{employee_id}:{int(punch_time // 10)}" if cache.setnx(lock_key, '1', timeout=10): with transaction.atomic(): AttendanceRecord.objects.create( employee_id=employee_id, punch_time=datetime.fromtimestamp(punch_time), score=request.session.get('match_score', 0.0), image_path=captured_image, device_id=device_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高检查是否有人触发大量无效比对增加人脸尺寸下限，过滤远距离路人某时段突然全部识别失败检查是否有人为断电在设备状态页面添加告警日志个人实操心得：除非是出现了明显统计错误，不要轻易修改已经跑通的阈值。每次调整都要记录版本、日期、场景和前后数据对比。考勤系统的核心不是模型的准确率有多高，而是规则稳定、数据可靠、流程闭环。只要这三个目标达成，即使单次识别偶尔失败，员工也可以通过补卡流程解决，整个系统的满意度依然很高。如果后续想继续扩展，可以做三件事：一是接入更先进的深度活体检测模型，进一步压缩照片打卡的漏洞；二是把识别服务做成独立的微服务，支持多办公楼多设备统一管理；三是对照片和个人特征做脱敏加密存储，满足数据隐私合规要求。这些都是从“能用”走向“好用”的必经之路，每一步都值得单独写一篇复盘文章来记录。