基于深度学习的人脸识别签到系统：Flask与face_recognition实战拆解

简介：基于深度学习的人脸识别签到系统是一套完整的毕业设计项目源码，主要面向计算机相关专业学生及需要快速搭建签到功能的后端开发者。项目以Python实现，覆盖人脸检测、特征提取、身份比对及签到记录管理等核心流程，并配有Web管理界面，可有效替代传统人工点名或刷卡签到，适合用于课程设计、毕业设计或小型场景的考勤演示。资源包共含27个文件，大小约102.26MB；其中8个Python脚本负责后端业务与人脸识别逻辑，7个HTML模板实现登录、注册、首页及404等页面，另有数据库文件、配置文档、字体文件及样式表等，结构清晰，便于按模块理解与二次开发。压缩包内提供完整的依赖清单与初始化说明，读者可自行搭建虚拟环境后运行，获得包含管理员账号、数据库迁移及基础前端界面在内的可执行项目，节省从零搭建的时间。目前已有4467人学习下载，适合需要参考实际工程结构并快速上手人脸识别签到场景的开发者。

1. 基于深度学习的人脸识别签到系统：从照片注册到自动签到的完整链路

有人问我，毕设里做“基于深度学习的人脸识别签到系统”，最难的不是训练模型，而是把识别模型和 Web 签到流程真正串起来。这套 Y27.zip 里的 faceRegister-master 源码，走的正是这条路：深度学习部分用 face_recognition 库封装好的 ResNet 特征提取，业务部分用 Flask 写管理后台和签到页面，数据落在 SQLite 里，照片注册、人脸比对、签到记录一条线打通。适合两类人：一类是拿它当毕设底座的在校生，另一类是想快速验证“人脸识别门禁机”式签到逻辑的从业者。下文按部署、代码、排错的顺序拆，最后给进阶调参建议。

2. 系统全貌与选型：Flask + face_recognition + SQLite，为什么这套组合适合复现

2.1 目录结构与模块职责

先说解压后看到什么。Y27.zip 解出来是 faceRegister-master，顶层文件不少，但按用途分其实就七组。我习惯拿到一个项目先画目录地图，不然很容易在一个 .py 文件里转晕：

这里有个细节值得单独提醒：model 权重目录在压缩包里叫 faceRecognitonModels，少了个字母 i，不是 Recognition。我第一次打开时以为是文件名写错了，结果发现整个项目内部引用都按这个拼写来的。这种“将错就错”的命名在毕业设计源码里很常见，你解压后千万别手滑改成标准拼写，不然 functions.py 加载模型时会直接找不到路径。

从职责划分能看出，这不是一个把识别逻辑写死在页面里的 demo，而是分了入口、服务、模型、迁移四层。api.py 单独拎出来意味着签到端可以不是浏览器，而是校园卡机、手机端甚至人脸识别门禁机外设去调接口，这在答辩演示时是个很加分的切入点。

2.2 face_recognition 的深度学习原理与模型文件

识别链路的核心是 face_recognition 库，它的底层是 dlib，dlib 里跑的是一个 ResNet 变体——29 层卷积网络，输入 150×150 的标准化人脸图，输出一个 128 维的特征向量。训练是在 LFW 数据集上做的，官方给的准确率是 99.38%，对签到这种“一对多找人”的场景足够用。

faceRecognitonModels 目录里放的，就是这套深度学习链路需要的三个权重文件，常见情况是这样的组合：dlib_face_recognition_resnet_model_v1.dat 负责把检测到的人脸框转成 128 维向量；shape_predictor_68_face_landmarks.dat 负责定位眼睛、鼻子、嘴角等 68 个关键点，用于人脸对齐；mmod_human_face_detector.dat 是带 CNN 的人脸检测器，用来框出人脸位置。如果你解压后看到目录里只有其中一两个，不用慌，face_recognition 库本身还自带一份默认权重，缺的会自动回退到默认加载，只是识别精度会略有差异。

选型理由值得展开说。为什么不自己训练一个 CNN？因为毕设和工程复现要的是“能用”，不是“从零造轮子”。自己训一个识别网络，你得先凑几万张标注人脸，配 CUDA 环境，训几十个 epoch，最后准确率还不一定比预训练模型好。而 face_recognition 这个方案把“深度学习环境配置”的成本压到了最低：模型文件打进包里，代码调用就三行。

如果你去对比 ArcFace 之类的方案，就会发现那套要配 MXNet 或 InsightFace 环境，依赖链长得多，单是编译就能劝退一半人。这套源码选了 face_recognition，等于把深度学习部分做成了黑匣子，你只需要关心输入图片、输出向量、比对阈值这三个口子，剩下的交给预训练权重。对毕业设计来说，这个取舍非常务实——你把精力省下来去写签到业务和页面，答辩时讲识别原理反而更从容。

2.3 数据流与表结构：从注册照片到签到记录

整个系统的数据流我梳理成六步：管理员在 add_user.html 提交学号、姓名和照片 → functions.py 提取照片里的人脸编码 → 编码序列化后存入 SQLite 的 user 表 → 签到端摄像头取帧 → 提取当前人脸编码 → 与库中全部编码算距离，小于阈值判为同一人 → 写入 attendance 表并跳转签到结果页。

模型的表结构在 models/init.py 里，典型实现是两张表，代码结构大致如下：

# models/__init__.py 里的表结构，常见做法是用户表和签到表分开 from datetime import datetime from flask_sqlalchemy import SQLAlchemy db = SQLAlchemy() class User(db.Model): __tablename__ = 'user' id = db.Column(db.Integer, primary_key=True) student_id = db.Column(db.String(20), unique=True, nullable=False) # 学号，唯一约束 name = db.Column(db.String(50), nullable=False) face_encoding = db.Column(db.Text) # 128 维向量，JSON 序列化后存文本 role = db.Column(db.String(10), default='user') # admin / user class Attendance(db.Model): __tablename__ = 'attendance' id = db.Column(db.Integer, primary_key=True) student_id = db.Column(db.String(20), nullable=False) check_time = db.Column(db.DateTime, default=datetime.now)

说明一下这里的取舍。face_encoding 用 Text 而不是用 BLOB 二进制，是为了让数据库文件可以直接被导出、用文本工具查看甚至手动修改，这对调试很有帮助——我排错时经常直接把 data.sqlite 拖进 SQLiteStudio，看某条记录的编码是否为空，一眼就能定位问题。role 字段区分管理员和普通用户，init 命令生成的管理员账户 role 值是 admin，普通签到用户是 user，页面上的编辑、删除按钮就是靠这个字段控制显隐的。

签到表只存了学号和签到时间，没有存人脸照片，因为照片在注册时已经用来生成编码，运行期比对只发生在“编码 vs 编码”之间，不需要再回查照片。如果你后续想给签到记录加现场抓拍图，那就需要在表里加一个 image_path 字段，并把摄像头帧保存到磁盘，这是后话。

3. 环境搭建与部署：venv 隔离、依赖安装、数据库迁移一条龙

3.1 virtualenv 创建与依赖安装

部署的第一步是建虚拟环境。为什么必须用 virtualenv 而不是直接 pip install 到全局？因为这套依赖里有 dlib 和 face_recognition，它们对 numpy 和编译工具链的版本非常敏感，全局环境里只要有一个包版本冲突，后面 import 阶段就会翻车。虚拟环境相当于给这个项目单独划了一间隔离舱，装坏了删掉重建就是，成本极低。

Windows 下的完整命令链如下：

pip install virtualenv virtualenv venv venv\Scripts\activate

说明一下每条命令的作用。第一条装 virtualenv 工具本身；第二条在当前目录创建名为 venv 的虚拟环境目录，里面会自带一份独立的 Python 解释器和 pip；第三条激活环境，激活成功后命令行提示符前面会出现 (venv) 前缀，这一步很多人会漏。如果你在 Linux 或 macOS 上操作，激活命令要换成 source venv/bin/activate，Windows 的 Scripts 目录在 Linux 下是不存在的——这个差异我踩过，在 Windows 上写的笔记拿到 Mac 上直接复制会报“目录不存在”。

激活之后，安装依赖：

pip install -r requirements.txt

requirements.txt 里锁的是这套源码声明过的依赖，至少包含 Flask、Flask-Script、Flask-Migrate、face_recognition、numpy 这几个核心项。我没法替你核实每个包的具体版本号，但强烈建议装的时候留意 pip 输出的版本信息，尤其是 dlib 和 face_recognition 这一对——face_recognition 依赖特定版本的 dlib，如果 pip 自动给你装了不兼容的版本，后面跑 functions.py 时会报属性错误。装完可以执行 python -c "import face_recognition; print(face_recognition.version)" 验证一下，能出版本号说明 dlib 和 face_recognition 的链路是通的。

3.2 数据库升级与管理员初始化

依赖装完先别急着启动，还有两步初始化要做，顺序不能反：

python app.py db upgrade python app.py init

第一条 db upgrade 是跑 Alembic 迁移。为什么不用 db.create_all()？因为 create_all 只会“创建不存在的表”，如果你的 data.sqlite 已经存在但缺字段，它不会帮你补；而迁移脚本是版本化的，upgrade 会把 models 里的表结构对外面这几个版本文件逐个比对，缺哪张表、缺哪个字段都补上。这相当于给数据库上了后悔药，改坏了可以 downgrade 回退。

第二条 init 是生成管理员账户。这个命令在 app.py 里是用 Flask-Script 的 Manager 注册的，执行完它会在 user 表里插入一条学号为 000000、密码为 666666 的记录。注意这个密码是明文还是哈希，取决于 models 里的 User 类有没有写密码哈希逻辑——如果是毕设源码，很多直接明文存的，你自己上线前务必改成 werkzeug.security 的 generate_password_hash。

提示：管理员账户只有这一条，学号 000000，密码 666666，登录页面用它进后台。如果 init 忘了跑，直接 runserver 启动再去登录，页面会一直提示密码错误。

3.3 启动服务与验证页面

初始化完成后，启动命令最简单：

python app.py runserver

这个 runserver 是 Flask-Script 提供的，默认监听 127.0.0.1:5000，debug 模式默认开。浏览器访问 http://127.0.0.1:5000，先看到的是登录页。用 000000 / 666666 登录进去，左侧应该有添加用户、编辑用户、签到记录这几个入口。

如果你要局域网测试——比如用手机摄像头对着电脑屏幕做识别演示——建议改成这样启动：

python app.py runserver -h 0.0.0.0 -p 8080

-h 0.0.0.0 表示监听所有网卡，这样同一局域网里的手机、平板都能访问；-p 8080 是换端口，避开 5000 可能被占用的冲突。手机访问时用电脑的局域网 IP，Windows 上敲 ipconfig 查 IPv4 地址，Linux/Mac 上敲 ifconfig 或 ip addr。注意改了 host 后，Windows 防火墙会弹窗询问是否允许 Python 通过，一定要点允许，不然手机端永远连不上——这个坑后面排错章节还会提。

启动后建议按这个顺序做冒烟验证：登录 → 添加一个真实用户并传正面照片 → 回到首页用摄像头或上传图片测识别 → 看签到记录里有没有生成新条目。四步全通，说明环境是健康的，再往下拆代码才有意义。

4. 核心代码拆解：functions.py 的识别链路与 fontToImg 的文本渲染

4.1 人脸编码提取与比对：128 维向量是怎么算出来的

functions.py 是整个项目的识别心脏。它对外暴露的核心函数，常见实现是这样的：

# functions.py 里的编码提取函数，image_path 指向一张本地照片 import face_recognition def get_face_encoding(image_path): image = face_recognition.load_image_file(image_path) locations = face_recognition.face_locations(image, model="hog") if len(locations) != 1: return None # 没检测到人脸，或者检测到多张人脸，都返回空 encoding = face_recognition.face_encodings(image, locations)[0] return list(encoding)

说明几点。face_locations 默认走 HOG 检测器，这是 CPU 上的快速检测，一张普通照片几十毫秒出结果；如果你把 model 参数改成 "cnn"，它会调 dlib 的 CNN 检测器，精度更高但慢得多，而且需要编译时带 CUDA 支持，否则还是跑 CPU。签到场景我一般用默认的 hog 就够了，CNN 留给光线复杂的大合影场景。

返回值特意转成 list，而不是保留 numpy 的 ndarray，原因是为了 JSON 序列化。numpy 数组不能直接 json.dumps，转成 list 后 128 个浮点数可以存进 SQLite 的 Text 字段，读出来再 json.loads 还原——这是整个项目数据流转最关键的格式约定。

比对函数的典型实现：

# functions.py 里的比对函数，known_encodings 是库里全部用户的编码列表 import numpy as np def match_face(known_encodings, target_encoding, tolerance=0.6): # face_distance 返回与所有人的欧氏距离，越小越像 distances = face_recognition.face_distance(known_encodings, target_encoding) index = int(np.argmin(distances)) if distances[index] < tolerance: return index # 命中库中第 index 个用户 return -1

逻辑上讲，人脸比对本质是算 128 维空间里的欧氏距离。同一个人不同角度、不同光线的两张照片，距离一般在 0.3 到 0.5 之间；不同的人基本都在 0.6 以上。tolerance 默认 0.6，就是这个项目的判定阈值——小于等于 0.6 算同一人，大于 0.6 拒绝。想更严就把 0.6 改成 0.45，想更松改成 0.7，具体怎么调我在最后一章展开。

4.2 管理员添加用户与照片入库

添加用户这个页面是 add_user.html，对应 app.py 里的一个路由。表单提交学号、姓名、照片三个字段，后端处理流程按 Flask 惯例组织：

# app.py 里的添加用户路由，结构按 Flask 常规写法还原 import json, os from flask import request, redirect, url_for, flash @app.route('/add_user', methods=['GET', 'POST']) def add_user(): if request.method == 'POST': student_id = request.form['student_id'].strip() name = request.form['name'].strip() photo = request.files['photo'] save_path = os.path.join('uploads', student_id + '.jpg') photo.save(save_path) encoding = get_face_encoding(save_path) if encoding is None: os.remove(save_path) # 提取失败要清理临时文件 flash('未检测到人脸，请上传清晰的正面照片') return redirect(url_for('add_user')) user = User(student_id=student_id, name=name, face_encoding=json.dumps(encoding)) db.session.add(user) db.session.commit() flash('添加成功') return redirect(url_for('index')) return render_template('add_user.html')

这里有个容易忽略的坑：照片先保存再提取，提取失败后 os.remove 这行是必须的。不然每次传一张模糊照片就留下一个垃圾文件，uploads 目录会越堆越满，而且这些没入库的照片会泄漏到静态目录里成为安全隐患。我见过不少翻车现场，就是忘了这行清理，答辩时被老师翻到 uploads 里一堆无效图片。

另一个细节是学号做了 strip 去空格。很多表单提交的学号带了隐形空格，如果不去掉，存入数据库时 ' 20230001' 和 '20230001' 会被当成两个不同用户，签到端比对时永远匹配不上。

4.3 fontToImg.py 与自定义字体：签到界面的中文渲染

fontToImg.py 这个脚本加的有点突兀，但它是“让界面看起来完整”的关键。OpenCV 的 putText 函数不支持中文，你直接往上写字，输出的图片里全是问号。项目里这个脚本的常见用途，是把中文姓名渲染到签到成功或失败的提示图上，做法是用 PIL 加载 font/simsun.ttc 字体文件，先在 Pillow 里把中文画到一张图上，再转成 OpenCV 的 BGR 格式或直接作为 JPEG 保存。

# fontToImg.py 的核心逻辑：PIL 画中文，再输出给 OpenCV 或直接存图 from PIL import Image, ImageDraw, ImageFont def draw_cn_text(text, font_path='font/simsun.ttc', font_size=48): font = ImageFont.truetype(font_path, font_size) # 先测量文字尺寸，生成恰好能容纳的底图 bbox = font.getbbox(text) img = Image.new('RGB', (bbox[2] + 20, bbox[3] + 20), color=(255, 255, 255)) draw = ImageDraw.Draw(img) draw.text((10, 10), text, font=font, fill=(0, 0, 0)) return img def cn_text_to_bgr(text): img = draw_cn_text(text) return img # 需要叠加时转成 numpy 数组再走 OpenCV

这个脚本的存在提醒一件事：解压后千万不要为了省空间把 font/simsun.ttc 删掉。simsun.ttc 是十几 MB 的中文字体文件，看着像占地方的“大块头”，但实际上 templates 和签到结果页凡是需要中文叠加的地方都依赖它。一旦缺失，轻则姓名显示成方框，重则页面 500——这种隐藏依赖不看代码根本发现不了。

另外，如果你嫌 simsun 宋体不好看，可以把这个 ttc 换成微软雅黑 msyh.ttc 或思源黑体的 otf 文件，只要把 fontToImg.py 里的 load 路径指过去就行，代码逻辑不用动。字体属于纯视觉资源，换掉不影响任何业务逻辑。

5. 常见问题与排查：dlib 编译失败、识别不准、数据库迁移翻车的 5 个现场

5.1 现象一：pip 安装 face_recognition 时在 dlib 上编译报错

现象：执行 pip install -r requirements.txt，装到 dlib 时刷出一长串红色报错，最后一行是 error: command 'gcc' failed 或者 cl.exe failed，装不下去。

原因：dlib 在 Windows 上默认走源码编译，需要 C++ 编译器和 CMake。你的机器上如果只有 Python，没有 Visual Studio 的 C++ 构建工具链，编译必然失败。在 Linux 上对应的是缺 g++ 和 cmake。

解决：Windows 上先装 Visual Studio Build Tools，安装时勾选“使用 C++ 的桌面开发”和 CMake 工具；装完重启再跑 pip install dlib。更省事的办法是直接去 pypi 或阿里的镜像源找对应 Python 版本的 dlib 预编译 wheel，pip install 指定 wheel 文件路径，跳过编译。我一般建议优先用预编译 wheel，能把整个安装时间从十几分钟压缩到两分钟，也会少踩一堆编译器的玄学错误。

5.2 现象二：添加用户时提示“未检测到人脸”

现象：add_user 页面传一张照片，后端 flash 提示检测失败，用户加不进去。

原因：三种最常见——照片分辨率太低，人脸区域小于 150×150；照片不是正脸，侧脸超过 45 度导致关键点定位失败；或者照片是压缩过度的网图，人脸部分已经糊成色块。

解决：先确认照片里人脸至少占画面四分之一，把人脸裁出来单独存一张图再试。用手机前置摄像头拍正脸，避免逆光。项目里 get_face_encoding 返回 None 时只会给一句“未检测到人脸”，没有具体原因，所以排查时建议临时在 functions.py 里把 locations 的打点数量打印出来，看是 0 还是 1——0 说明检测器没找到人脸，大于 1 说明照片里有不止一张脸，而注册接口要求只能一张。

5.3 现象三：两个人长得像，签到互相认错

现象：A 同学用自己照片注册，B 同学对着摄像头，系统却签到了 A。

原因：tolerance 用的默认 0.6，对长得像的脸来说这个阈值太松。face_recognition 的距离分布里，双胞胎或者眉眼接近的人可能只有 0.55 的差距，0.6 的阈值直接就误判了。

解决：把比对函数的 tolerance 从 0.6 降到 0.45 到 0.5 之间。降阈值会带来另一个代价——同一人因为光线变化、戴眼镜摘眼镜导致距离变大，可能会被拒签，这时需要给每个用户多注册几张照片（正面、左侧、右侧各一张），比对时取“与本人所有照片的最小距离”作为最终距离。这个“一人多图”的思路，正是人脸识别门禁机实际部署时的标配做法。

5.4 现象四：python app.py db upgrade 卡死或报错

现象：init 执行时报 user 表已存在，或 upgrade 报 operational error no such table: alembic_version。

原因：data.sqlite 已经存在，而且是之前用旧版代码跑出来的库，表结构不完整；或者 data.sqlite 是空文件，Alembic 的版本表没建起来。毕设源码里 data.sqlite 经常跟着压缩包一起发出来，里面可能残留开发者本地跑过的脏数据，直接拿去 upgrade 就会和新迁移脚本冲突。

解决：备份现有 data.sqlite 后把它删掉，重新执行 python app.py db upgrade && python app.py init。如果不想丢数据，就先手工给旧库补 alembic_version 表，再用 upgrade head 强制对齐——但毕业设计场景不值得这么折腾，删库重建五分钟搞定。从那以后我拿到这种带 .sqlite 的源码包，第一反应永远是把它的 data.sqlite 改名备份再初始化，而不是直接用原文件。

5.5 现象五：runserver 启动提示端口 5000 被占用

现象：python app.py runserver 启动即报 Address already in use，或者页面一直转圈。

原因：5000 是调试服务常用端口，本机可能已有其他进程占用，比如之前跑过的 Flask 残留进程、别的开发服务器。

解决：一条命令查占用，Windows 上 netstat -ano | findstr :5000，Linux/Mac 上 lsof -i :5000，拿到 PID 后 taskkill /PID 进程号 /F（Windows）或 kill -9 进程号（Linux/Mac）。不想杀进程就按第三章说的启动时指定端口 python app.py runserver -p 8080。另外提醒一句，如果用了 -h 0.0.0.0 局域网访问，Windows 防火墙弹窗一定要点允许，不然手机端一直 connection refused，还以为是代码问题。

6. 进阶玩法：调 tolerance、批量导入照片与出门禁机风格的验收

6.1 阈值调优的正确姿势

如果你要把这套系统从“能跑”调到“能用”，第一个要动的是 tolerance。别直接猜，用数据说话：写一个脚本，把库中每个用户的注册照和一张现场自拍照做 face_distance 统计，算同人距离的均值和跨人距离的均值，取二者的中点为阈值。实操时我一般先设 0.5，然后用 10 个人的测试集跑一遍，统计误识率和拒识率，再微调——0.5 偏严就涨到 0.55，偏松就降到 0.45。

6.2 批量导入：把一整个班的照片一次性灌进去

手动在页面添加用户太慢，可以用一个独立脚本循环调用 functions.py 的接口：

# batch_import.py：批量导入目录下的证件照，文件名即学号 import os, json from functions import get_face_encoding from models import db, User def import_folder(folder_path): for filename in os.listdir(folder_path): if not filename.lower().endswith('.jpg'): continue student_id = filename.split('.')[0] encoding = get_face_encoding(os.path.join(folder_path, filename)) if encoding is None: print('跳过', student_id) continue db.session.add(User(student_id=student_id, name=student_id, face_encoding=json.dumps(encoding))) db.session.commit()

脚本会跳过检测不到人脸的照片，并把跳过的学号打印出来，方便你回头单独补录。这个功能对答辩前临时录入十几个同学非常实用。

6.3 出门禁机风格的验收

最后验收时，把摄像头对准电脑屏幕，用手机前置摄像头拍摄屏幕里的签到页，模拟真实的人脸识别门禁机场景。重点测三件事：光线变化时是否稳定（开灯、关灯各测一次）、戴眼镜与摘眼镜是否都通过、两个人同时出现在画面里会不会误判。这三项过了，整套系统在技术层面的完成度就立住了。

关于这套系统的定位，我的态度是：它不是工业级产品，但作为毕业设计和签到逻辑验证，结构完整、链路清晰，识别精度在可控场景下也够用。真正的生产部署还需要换 MySQL、加 Redis 缓存、做分布式会话，但那已经是下一步的事了。

从那以后我每次拿到这种带模型权重的 Flask 项目，第一件事都是看 requirements.txt 和模型目录是否齐整，第二件事是检查 data.sqlite 是不是脏数据，然后才敢动 pip install——这套顺序帮我避开过好几次深夜排错的局面。希望帮到你。

本文还有配套的精品资源，点击获取