简介这份资源是面向Java后端开发者与计算机专业学生的SpringBoot人脸识别考勤系统后端项目源码适合作为课程设计、毕业设计或企业考勤模块的技术参考。项目以SpringBoot为核心框架结合OpenCV完成人脸检测与识别并通过SpringSecurity实现安全控制、Spring事务管理保障数据一致性同时采用RESTful API与前端交互配合Actuator监控应用状态整体结构贴近真实工程实践。压缩包共209个文件约1.16MB包含31个Java源文件、33个HTML页面、64个JavaScript脚本以及CSS样式、XML配置、properties与yml配置文件等另有少量图片与构建脚本覆盖后端逻辑、前端页面与项目配置多个层面。目前已有37人学习下载读者可从中获取完整的后端接口设计思路、依赖管理方式与目录组织参考便于快速理解SpringBoot考勤系统的实现路径并迁移到自己的项目中。1. 从一张打卡照片到考勤记录SpringBoot 人脸识别考勤后端到底在做什么员工站在门禁机前刷脸屏幕弹出「张三 签到成功」这条记录几乎同时写进数据库HR 后台刷新就能看到——这套流程里人脸识别考勤系统后端承担的是「把一张脸变成一条可信考勤记录」的全部脏活。它要接住前端传来的图像或特征值调用识别引擎比对出人员身份再结合排班规则判断这次打卡算迟到、早退还是正常最后落库并对外提供查询接口。基于 SpringBoot 做这件事核心吸引力在于它把 Web 层、事务、定时任务、缓存这些后端刚需都收敛成开箱即用的 starter让你能把精力放在识别链路和考勤规则上而不是重复搭架子。适合谁看正在做前后端分离项目实战的 Java 后端、要交毕设的学生、以及想把公司老旧刷卡机升级成人脸识别的运维开发。下面按「识别怎么接、考勤怎么算、坑在哪」一路拆到能跑。2. 识别引擎选型与 SpringBoot 接入从 SDK 到 HTTP 服务人脸识别考勤系统的成败一半在识别引擎选得对不对。后端本身不做人脸比对它只负责调度。市面上常见三类接入方式本地 SDK如 ArcFace 离线 SDK、自建识别服务Python 侧跑模型Java 通过 HTTP 调、云厂商 API。选型时先问三个问题并发多少人、是否允许人脸图像出内网、预算多少。中小团队和毕设场景我一般推荐「Java 后端 独立识别服务」的拆分识别服务用 Python 封装SpringBoot 只做业务编排这样识别模型升级不影响考勤逻辑也方便本地调试。2.1 三种接入方式的对比与选型理由方式延迟离线可用维护成本适用场景本地 SDKArcFace 等低是高需处理动态库固定门禁机、内网自建识别服务中是中多端复用、可扩展云 API高否低快速验证、小规模本地 SDK 的坑在于 JNI 调用和动态库版本Windows 和 Linux 的 .so/.dll 不通用部署时经常翻车。自建服务把复杂度隔离在 Python 侧Java 只认 HTTP 契约是性价比最高的做法。云 API 适合先跑通流程但人脸数据出内网这件事在很多公司过不了合规慎用。2.2 用 RestTemplate 调识别服务的最小可用代码识别服务对外暴露一个/face/match接口入参是 base64 图像返回人员 ID 和相似度。SpringBoot 侧用 RestTemplate 调用注意设置超时识别是慢操作默认无超时会把 Tomcat 线程拖死。Configuration public class RestTemplateConfig { Bean public RestTemplate faceRestTemplate() { // 连接超时 2s读取超时 5s识别服务偶尔抖动不能拖垮主线程 SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(2000); factory.setReadTimeout(5000); return new RestTemplate(factory); } }Service public class FaceRecognizeService { Resource(name faceRestTemplate) private RestTemplate restTemplate; private static final String MATCH_URL http://127.0.0.1:8000/face/match; public MatchResult match(String base64Image) { FaceMatchRequest req new FaceMatchRequest(); req.setImage(base64Image); // 识别服务约定返回 {code, personId, score} ResponseEntityFaceMatchResponse resp restTemplate.postForEntity(MATCH_URL, req, FaceMatchResponse.class); if (resp.getBody() null || resp.getBody().getCode() ! 0) { throw new BizException(识别服务返回异常); } return new MatchResult(resp.getBody().getPersonId(), resp.getBody().getScore()); } }逻辑说明把 RestTemplate 单独配置 Bean 而不是全局注入是为了让识别调用和普通业务调用用不同的超时策略。参数说明connectTimeout控制建连readTimeout控制识别耗时识别服务冷启动第一次可能超过 5 秒建议识别服务侧做预热。相似度阈值不要写死在 Java 里放到配置中心或数据库方便按现场光线调整。2.3 识别结果的可信度校验拿到 personId 和 score 不能直接用。score 低于阈值常见 0.750.85按引擎不同要拒绝并记录「识别失败」事件而不是当成陌生人。还要做活体检测结果的透传如果识别服务返回livenessfalse即使相似度再高也不能算打卡成功否则一张照片就能代打卡。这一步是很多毕设项目忽略的地方答辩时容易被追问。3. 考勤业务建模打卡记录、排班规则与迟到判定识别出人只是第一步考勤系统后端真正复杂的是「这次打卡算不算数」。核心表就三张员工表、排班表、打卡记录表。打卡记录表存原始事件谁、什么时间、哪个设备、识别分数迟到早退这些结论不要直接写死在记录里而是查询时按排班规则实时计算或者由定时任务每天结算一次生成日考勤汇总。前者灵活后者查询快我一般两者都做实时算给前端看定时任务落汇总表给报表用。3.1 打卡记录表设计与关键字段CREATE TABLE attendance_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, person_id BIGINT NOT NULL COMMENT 员工ID, device_id VARCHAR(64) NOT NULL COMMENT 门禁设备编号, punch_time DATETIME NOT NULL COMMENT 打卡时间, match_score DECIMAL(5,4) NOT NULL COMMENT 识别相似度, liveness TINYINT(1) NOT NULL DEFAULT 1 COMMENT 活体检测结果, punch_type TINYINT NOT NULL COMMENT 1签到 2签退, create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, INDEX idx_person_time (person_id, punch_time) ) COMMENT 原始打卡记录;字段说明punch_time用数据库时间还是设备时间要统一建议以服务端接收时间为准设备时间不可信。match_score保留四位小数便于后续分析阈值。索引idx_person_time是必须的考勤查询几乎都是按人按时间段捞。3.2 迟到早退判定的服务层实现public AttendanceResult judge(Long personId, LocalDateTime punchTime) { // 1. 查当天排班没有排班说明休息日打卡只记录不判定 Schedule schedule scheduleMapper.findByPersonAndDate(personId, punchTime.toLocalDate()); if (schedule null) { return AttendanceResult.restDay(); } // 2. 签到晚于上班时间 宽限期算迟到 LocalDateTime workStart LocalDateTime.of(punchTime.toLocalDate(), schedule.getStartTime()); LocalDateTime lateLine workStart.plusMinutes(schedule.getGraceMinutes()); if (punchTime.isAfter(lateLine)) { long lateMinutes Duration.between(workStart, punchTime).toMinutes(); return AttendanceResult.late(lateMinutes); } return AttendanceResult.normal(); }逻辑说明宽限期graceMinutes是必须的没有它每天早高峰电梯排队都会产生大量「迟到 1 分钟」的无效申诉。参数说明graceMinutes建议 515 分钟按公司制度配。判定逻辑要幂等同一个人同一分钟重复打卡只保留一条靠person_id punch_time唯一索引或 Redis 去重。3.3 重复打卡与跨天班次处理门禁机经常连拍同一个人 3 秒内传 5 张图后端必须去重。简单做法是用 Redis 的SETNXkey 为punch:{personId}:{分钟}过期 60 秒。跨天班次比如夜班 22:00 到次日 6:00是考勤系统的经典难点判定时不能按自然日切要按排班的shift_date归属。我一般把排班表的日期字段定义为「班次开始日」所有打卡按这个日期归集避免凌晨打卡算到第二天。4. 接口设计与前后端联调签到、查询与跨域后端接口要围绕「设备端」和「管理端」两类调用方设计。设备端只调签到接口要求极简、高并发、低延迟管理端调查询和报表接口要求灵活筛选。前后端分离项目实战里跨域和鉴权是最容易卡住联调的两个点。4.1 签到接口的幂等与限流PostMapping(/api/attendance/punch) public Result punch(RequestBody Valid PunchRequest req) { // 1. 限流同一设备每秒最多 5 次防止设备异常刷接口 if (!rateLimiter.tryAcquire(device: req.getDeviceId(), 5)) { return Result.fail(请求过于频繁); } // 2. 识别 MatchResult match faceRecognizeService.match(req.getImage()); if (match.getScore() threshold) { return Result.fail(识别失败请重试); } // 3. 幂等去重 String dedupKey punch: match.getPersonId() : req.getMinuteBucket(); if (!redisTemplate.opsForValue().setIfAbsent(dedupKey, 1, 60, TimeUnit.SECONDS)) { return Result.success(已打卡); } // 4. 落库并判定 attendanceService.saveAndJudge(match.getPersonId(), req.getDeviceId(), match.getScore()); return Result.success(打卡成功); }逻辑说明限流放在识别之前避免无效请求打到识别服务。幂等 key 用分钟粒度同一分钟重复提交直接返回成功前端体验也好。参数说明threshold从配置读minuteBucket由前端或后端按当前时间生成保证同一分钟内一致。4.2 跨域配置与设备鉴权设备端和管理端来源不同跨域配置要精确到路径不要图省事用allowedOrigins(*)配allowCredentials(true)浏览器会直接拒绝。设备鉴权建议用签名而非 JWT设备端存密钥比存 token 更现实。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/attendance/**) .allowedOrigins(https://admin.example.com) .allowedMethods(GET, POST) .allowCredentials(true) .maxAge(3600); } }参数说明maxAge设 3600 秒减少预检请求。设备端接口单独走签名拦截器校验deviceId timestamp signtimestamp 偏差超过 5 分钟拒绝防重放。4.3 查询接口的分页与时间范围管理端查询打卡记录必须强制传时间范围否则全表扫描。用 MyBatis-Plus 分页时注意 count 语句也会扫全表时间范围索引要建好。返回给前端的字段做裁剪不要把 base64 图像带回去图像单独存对象存储库里只存路径。5. 避坑与排查识别、并发、时间三类高频翻车这一章是我踩过的血泪经验按「现象 → 原因 → 解决」写照着排查能省不少时间。现象一识别服务偶发超时签到接口大面积 500。原因RestTemplate 没配超时识别服务 GC 或模型加载时线程堆积Tomcat 线程被占满。解决按 2.2 配置独立超时 Bean识别服务侧加健康检查和预热超时后降级为「请重试」而不是抛异常。现象二同一个人一分钟内出现多条打卡记录。原因Redis 去重 key 用了秒级或没设过期或者多台设备并发时 key 生成规则不一致。解决统一用分钟粒度 keysetIfAbsent加过期时间数据库再加唯一索引兜底。现象三凌晨打卡算到了第二天夜班考勤全乱。原因判定逻辑用LocalDate.now()取自然日没按排班归属日。解决排班表存shift_date打卡记录冗余shift_date字段所有统计按它分组。现象四跨域配置后管理端仍报 CORS 错误。原因allowedOrigins(*)和allowCredentials(true)冲突或者拦截器在 CORS 之前返回了 401。解决写明确来源把 CORS 配置放在拦截器之前生效OPTIONS 预检请求直接放行。现象五识别阈值调高后员工抱怨刷不上。原因阈值一刀切没考虑现场光线和设备差异。解决阈值按设备配置早晚光线差的门禁机单独调低同时记录失败样本用于后续优化。6. 进阶技巧用异步与缓存把签到响应压到 200ms 内签到接口的响应时间直接决定员工体验超过 500ms 就会感觉卡。识别本身占大头但后端能做的优化不少。我的习惯是把「识别 → 落库 → 判定」拆成同步和异步两段识别和落库同步做保证打卡不丢迟到判定和汇总统计异步做用 Spring 的Async或消息队列。这样接口只等识别判定结果前端稍后刷新即可。Async(attendanceExecutor) public void asyncJudge(Long recordId, Long personId, LocalDateTime punchTime) { // 异步判定失败重试三次仍失败进死信表人工处理 AttendanceResult result judge(personId, punchTime); recordMapper.updateResult(recordId, result); }线程池要单独配核心线程数按识别 QPS 估队列有界拒绝策略用CallerRunsPolicy避免丢任务。缓存方面排班表变动少启动时全量加载到本地 Caffeine按personId date命中避免每次判定查库。识别服务返回的人员信息也可以缓存减少一次查询。验证优化效果不要靠感觉用 JMeter 或 wrk 压签到接口看 P99 而不是平均值。我一般会盯三个数识别服务 P99、签到接口 P99、数据库写入耗时。如果识别 P99 正常但接口 P99 高多半是线程池或锁的问题。最后留一句我的习惯任何涉及时间的逻辑先在测试环境把系统时间调到跨天、跨月、跨年各跑一遍考勤系统的时间 bug 从来不会在正常上班时间出现。希望帮到你。本文还有配套的精品资源点击获取