OpenCV人脸识别门禁系统源码解析与实战指南

简介：面向Python与OpenCV学习者的完整人脸识别门禁系统源码包，适合希望掌握人脸检测、特征提取、实时视频流处理及门禁联动逻辑的开发者。资源共34个文件，包含10个Python脚本、4个XML级联分类器、多张示例图片与测试视频、中文字体及说明文档，压缩包约116MB，目录结构清晰。脚本从视频基础操作、摄像头人脸识别，到人脸68个特征点提取、面部编码匹配，完整覆盖人脸识别流程中的关键环节；配合haarcascade_frontalface_default.xml与face_recognition库，可快速搭建从图像采集、特征比对到白名单判断的实时门禁系统。资源内还提供示例素材和中文字体，便于直接运行并观察不同参数对识别效果的影响，同时附带的说明文档有助于理解阈值设置与特征比对原理。整体已有1358人学习下载，适合作为课程设计、毕业设计或计算机视觉入门实践项目参考。

1. 项目概述

1.1 这个源码包到底是什么

先说结论：这是一套基于 Python 和 OpenCV 实现的本地人脸识别门禁系统，整体思路不复杂——摄像头采集人脸，OpenCV 做人脸检测，LBPH 算法做人脸识别，识别通过后控制继电器开锁，同时记录进出日志。源码包的解压结构一般是main.py、face_train.py、face_detect.py、attendance.py、haarcascade_frontalface_default.xml这类文件组合，属于典型的计算机视觉入门级项目。

这类项目在毕业设计、课程作业里出现频率很高，因为它的技术栈覆盖了摄像头调用、图像处理、算法训练、硬件控制、数据库写入这几个完整环节，正好符合“做一个能跑的东西”的要求。但说实话，源码包里的代码质量参差不齐，很多是从开源项目改来的，真正能直接跑通的不到一半，大部分都要调依赖版本、改摄像头 index、处理路径中文问题。

1.2 适合什么人用

如果你是刚学完 Python 基础、想接触 OpenCV 的初学者，这个项目是个不错的起点——它把“训练模型”和“调用模型”分成了两个脚本，逻辑清晰，能帮你理解人脸识别的基本链路。如果是准备毕设答辩的学生，这套代码配合硬件（树莓派或者 USB 摄像头 + 继电器模块）就能演示完整的门禁流程，演示效果比纯软件模拟要加分不少。已经工作的开发者也可以拿它当原型验证，比如给公司做个访客登记系统，或者改造成人脸打卡考勤，底层逻辑是一样的。

不过有一点要提前说清楚：OpenCV 自带的人脸检测是基于 Haar 特征的经典方法，检测速度还行但精度一般，在实际光线复杂、人脸角度偏转的环境下效果会打折扣。它适合作为学习项目或 demo，生产环境建议换用 Dlib 或深度学习方案。

2. 整体设计与思路拆解

2.1 系统架构和数据流

这个门禁系统的核心链路是“采集-训练-识别-控制-记录”，五个环节串起来就是一个完整的人脸识别业务闭环。

采集阶段，代码调用摄像头（cv2.VideoCapture）逐帧读取画面，用CascadeClassifier先定位画面里的人脸区域，然后把裁剪出的人脸灰度图保存到data/目录下，一个人需要采集 30-50 张不同角度的照片。训练阶段，系统把所有采集到的人脸照片读入内存，为每张照片打上标签（通常是用户 ID），用cv2.face.LBPHFaceRecognizer_create()创建识别器，train()方法训练后把模型保存成trainer.yml文件。识别阶段是核心，系统持续读取摄像头画面，每检测到一张人脸就调用predict()方法，返回一个置信度分数，分数低于阈值就判定为“认识这个人”。判定通过后，通过串口或 GPIO 向继电器模块发送信号，触发门锁动作，同时把识别结果（人员 ID、时间、是否通过）写入本地 SQLite 数据库。

这个设计的关键点在于把训练和识别分离。训练阶段不需要实时性，识别阶段才要求响应速度，分离后你可以随时用新数据重训模型而不用重启门禁主程序。

2.2 为什么选择 OpenCV 而不是别的人脸识别方案

选 OpenCV 做这个项目最直接的原因是它“全家桶式”地集成了整套工具链。从底层矩阵运算、图像缩放、灰度转换，到人脸检测的 Haar Cascade 模型，再到 LBPH 人脸识别算法，全部通过cv2一个包就能调用。对新手来说，不用额外研究 NumPy 数组怎么操作图像，OpenCV 已经帮你把这些底层细节都封装好了。

对比其他方案，TensorFlow 或 PyTorch 这种深度学习框架能训练的模型精度更高，但光装环境就要折腾半天，还要准备大量标注数据，对入门项目来说学习成本太高。Dlib 的精度和速度都不错，但安装时经常遇到编译失败的问题，Windows 下尤其折磨人。OpenCV 的 LBPH 算法虽然精度不算顶尖，但它不需要 GPU，纯 CPU 就能跑实时识别，对硬件要求低，主流电脑和树莓派都能流畅运行，适合作为教学和原型验证工具。

从“门禁系统”这个实际应用场景看，普通办公门禁对识别速度的要求是“秒级以内”，对精度的要求其实是“别把陌生人放进来”。LBPH 配合合适的置信度阈值，在光线稳定的室内环境下完全够用。

2.3 功能模块划分

这套代码从功能上可以划分为四个模块：人脸采集模块负责控制摄像头、检测人脸区域、保存训练样本；模型训练模块负责读取样本、提取特征、生成模型文件；实时识别模块负责摄像头实时检测、置信度比对、判定结果输出；记录管理模块负责识别日志写入数据库，这个用 Python 内置的sqlite3就能实现，不需要额外装 MySQL 之类的大型数据库。

这样的模块划分对后续扩展很友好。比如你想加一个“刷脸成功时播放语音提示”，只需要在识别模块的判定分支里插入pygame或win32com.client的调用，不用动其他模块。想把门禁记录同步到钉钉或企业微信，只需要改记录管理模块的数据推送逻辑，核心识别代码完全不用变。

3. 环境搭建与依赖安装

3.1 安装 Python 和 OpenCV 的完整步骤

先说 Python 版本，建议用 3.8 到 3.10 之间，太新的版本（比如 3.12、3.13）容易出现某些依赖库还没适配的情况。下载安装包时记得勾选“Add Python to PATH”这个选项，不然后面在命令行输python会提示找不到命令。

装上 Python 之后，建议创建一个独立的虚拟环境来跑这个项目，不要直接装到全局环境，不然以后做别的项目时依赖冲突会很头疼。创建命令如下：

python -m venv face_env

激活虚拟环境，Windows 系统用face_env\Scripts\activate，Linux 用source face_env/bin/activate。激活成功后命令行前面会出现(face_env)前缀。然后安装 OpenCV 和依赖库：

pip install opencv-python opencv-contrib-python numpy

这里有个关键点：普通的人脸识别接口cv2.face.LBPHFaceRecognizer_create()不是核心包opencv-python里的，而是在opencv-contrib-python这个扩展包中。很多人代码运行时报AttributeError: module 'cv2.face' has no attribute 'LBPHFaceRecognizer_create'，就是因为只装了基础版没装 contrib 版。两个包都要装，没有冲突。

其它依赖按需安装：

pip install pillow openpyxl

如果要做串口控制硬件，还需要pyserial：

pip install pyserial

3.2 验证摄像头和 OpenCV 是否正常

装完环境后，先不要急着跑门禁代码，先单独测试一下摄像头能不能正常打开。用小脚本验证：

import cv2 cap = cv2.VideoCapture(0) if not cap.isOpened(): print("摄像头打开失败") else: ret, frame = cap.read() if ret: cv2.imwrite("test.jpg", frame) print("摄像头正常，已保存测试图片") cap.release()

如果VideoCapture(0)打不开摄像头，先试cv2.VideoCapture(1)。笔记本自带摄像头通常对应 0，外接 USB 摄像头可能对应 1 或者更高 index。台式机插了多个摄像头的情况更复杂，可以用下面这段代码列出所有可用设备：

import cv2 for i in range(5): cap = cv2.VideoCapture(i) if cap.isOpened(): print(f"设备 {i} 可用") cap.release()

3.3 常见安装踩坑记录

第一个坑是 pip 下载速度慢。OpenCV 的包很大（约 40MB），默认官方源在国内下载经常超时。解决办法是指定国内镜像源：

pip install opencv-contrib-python -i https://pypi.tuna.tsinghua.edu.cn/simple

第二个坑是ModuleNotFoundError: No module named 'cv2'。这个报错一般是两种情况：一是装成功了但当前终端环境不对，比如没激活虚拟环境就运行代码；二是安装时断网导致包不完整，重新执行一遍安装命令即可。

第三个坑是 Python 3.12 以上版本跑opencv-contrib-python时可能报ImportError: DLL load failed，这是新版 Python 与 OpenCV 的兼容性问题，建议直接换回 Python 3.10。

4. 核心代码实现解析

4.1 人脸检测：Haar Cascade 的工作原理

OpenCV 的人脸检测器用的是一种叫 Haar Cascade 的算法，思路是训练一个级联分类器，用若干矩形特征去匹配人脸的灰度分布规律。比如眼睛区域会比周围皮肤暗，鼻梁区域会比两侧亮，这些特征组合起来就形成了一套“判断是不是人脸”的规则。

使用方法很简洁，加载训练好的 XML 模型文件，然后调用detectMultiScale()：

import cv2 face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') def detect_faces(gray_img): faces = face_cascade.detectMultiScale( gray_img, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80) ) return faces

这个接口是开箱即用的，先转灰度图再传入检测器。从原理上看，scaleFactor=1.1表示每次搜索窗口缩放的比例，数值越小检测越精细但速度越慢；minNeighbors=5表示每个候选框周围至少要有多少个相邻框都确认它是人脸，数值越大误检测越少但可能漏检；minSize用来忽略小区域，过滤掉远处的人脸，避免噪声影响。

4.2 数据采集：保存人脸样本的完整流程

数据采集阶段的代码如下：

import cv2 import os def collect_samples(user_id, sample_num=50): cam = cv2.VideoCapture(0) face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') # 创建存放目录 save_dir = f'data/user_{user_id}' os.makedirs(save_dir, exist_ok=True) count = 0 while count < sample_num: ret, frame = cam.read() if not ret: continue gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = face_cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)) for (x, y, w, h) in faces: # 裁剪人脸区域并统一缩放为 200x200 face_region = gray[y:y+h, x:x+w] face_resized = cv2.resize(face_region, (200, 200)) # 保存图片，命名规则：用户ID_序号.jpg cv2.imwrite(f'{save_dir}/{count}.jpg', face_resized) count += 1 # 画矩阵框用于实时反馈 cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2) cv2.putText(frame, f'{count}/{sample_num}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2) cv2.imshow('Collecting', frame) if cv2.waitKey(1) == ord('q'): break cam.release() cv2.destroyAllWindows()

采集的时候要注意：不要只对着摄像头不动，要缓慢地左右转动头部、稍微仰头低头、变换表情，光线好时多拍几张，光线暗时再补拍几张。因为训练出来的模型要能适应不同角度和光线，样本越多样化，识别准确率越高。每张人脸照片在保存前都统一缩放为 200x200，这样做是为了消除不同人脸在画面中大小不一致对训练效果的影响。

4.3 模型训练：LBPH 人脸识别算法解读

LBPH（Local Binary Pattern Histogram，局部二值模式直方图）的核心思路是把人脸图像分解成多个小区域，对每个区域提取纹理特征，再把所有特征统计成直方图，每张人脸就对应一个“特征指纹”。识别的时候，把待检测人脸的特征指纹与所有已知人脸的指纹做对比，距离最小的那个就是匹配结果。

训练代码如下：

import cv2 import os import numpy as np def train_model(): face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') recognizer = cv2.face.LBPHFaceRecognizer_create() faces = [] labels = [] label_dict = {} # 记录每个用户ID对应的姓名，文件命名要带数字 for user_folder in os.listdir('data'): user_path = os.path.join('data', user_folder) if not os.path.isdir(user_path): continue # 从文件夹名称提取用户编号 label = int(user_folder.split('_')[1]) label_dict[label] = user_folder for img_name in os.listdir(user_path): img_path = os.path.join(user_path, img_name) gray = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) faces.append(gray) labels.append(label) recognizer.train(faces, np.array(labels)) recognizer.save('trainer.yml') print(f"训练完成，共 {len(faces)} 张照片")

用os.listdir遍历data/目录，每个子文件夹对应一个用户，文件夹名字格式是user_1、user_2这种，数字就是该用户的标签。训练完后生成trainer.yml文件，这个文件里存储了所有人的 LBPH 特征模型。用户 ID 最好从 1 开始，不要从 0 开始,因为 LBPH 内部有些标签和索引有关系，从 0 可能在切换模型时出问题。

4.4 实时识别与门禁控制

识别主程序的逻辑是这样：

import cv2 import numpy as np import datetime import sqlite3 import threading def recognize_face(): recognizer = cv2.face.LBPHFaceRecognizer_create() recognizer.read('trainer.yml') face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml') confidence_threshold = 80 # 低于 80 分才认为是已登记人员 cam = cv2.VideoCapture(0) while True: ret, frame = cam.read() if not ret: continue gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = face_cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)) for (x, y, w, h) in faces: face_region = gray[y:y+h, x:x+w] face_resized = cv2.resize(face_region, (200, 200)) # predict 返回 (标签, 置信度) label, confidence = recognizer.predict(face_resized) if confidence < confidence_threshold: cv2.putText(frame, f'User: {label} ({confidence:.1f})', (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2) unlock_door() # 触发开锁 log_entry(label, confidence) # 记录日志 else: cv2.putText(frame, f'Unknown ({confidence:.1f})', (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 0, 255), 2) cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 0, 255), 2) cv2.imshow('Face Door Access', frame) if cv2.waitKey(1) == ord('q'): break cam.release() cv2.destroyAllWindows()

这段代码里最关键、也最容易踩坑的是置信度阈值confidence_threshold的设置。LBPH 预测返回的 confidence 值表示匹配距离，理论上越小说明越匹配，80 分以内通常是很接近的匹配。但实际效果受训练样本质量、光照变化影响很大，有人 50 分就是本人，有人 90 分都还是本人。建议先在程序里把预测分数打印出来观察一段时间，看看本人和非本人的分数分布，再确定最合适的阈值。如果你发现经常把陌生人识别成自己人，就调低阈值，比如从 80 改成 60；如果自己人老是被拒，就调高一些。

4.5 数据记录模块：新增人员怎么处理

门禁系统的日志记录用 SQLite 就足够了，它不需要额外的数据库服务，Python 自带，写完直接生成一个.db文件，用任意 SQLite 图形化工具都能打开查看。建表和写入的代码：

import sqlite3 import datetime def init_db(): conn = sqlite3.connect('access_log.db') c = conn.cursor() c.execute(''' CREATE TABLE IF NOT EXISTS access_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, confidence REAL, access_time TEXT NOT NULL, result TEXT NOT NULL ) ''') conn.commit() conn.close() def log_entry(user_id, confidence): now = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S') conn = sqlite3.connect('access_log.db') c = conn.cursor() c.execute( "INSERT INTO access_log (user_id, confidence, access_time, result) VALUES (?, ?, ?, ?)", (user_id, confidence, now, 'ALLOWED') ) conn.commit() conn.close()

新增人员的完整流程：运行collect_samples(new_user_id)采集照片，再运行train_model()重新训练，最后重启识别程序即可。不需要改任何配置。设计时建议把用户 ID 与真实姓名的对应关系单独存一个表，日后查记录时想显示“张三”而不是“ID 1”会方便很多。

5. 硬件接线与完整运行实录

5.1 树莓派方案和继电器接线

如果你想把软件和硬件打通，做成真正的门禁系统，最省钱的方案是用树莓派（或香橙派等 Linux 开发板）加 USB 摄像头加一个 5V 继电器模块，继电器再控制电插锁的电源通断。

接线很简单：树莓派的 GPIO 引脚（比如 GPIO18）接继电器模块的 IN 针脚，树莓派的 GND 接继电器的 GND，继电器的公共端（COM）和常开端（NO）串联到电插锁的供电回路里。代码层面只需要在unlock_door()函数里用 GPIO 控制高低电平：

import RPi.GPIO as GPIO import time RELAY_PIN = 18 GPIO.setmode(GPIO.BCM) GPIO.setup(RELAY_PIN, GPIO.OUT) GPIO.output(RELAY_PIN, GPIO.HIGH) # 默认关闭继电器 def unlock_door(duration=3): GPIO.output(RELAY_PIN, GPIO.LOW) # 低电平触发继电器闭合 time.sleep(duration) GPIO.output(RELAY_PIN, GPIO.HIGH) # 断开继电器

Linux 上跑之前记得给 Python 添加 GPIO 权限，用sudo python main.py运行，或者把用户加入gpio组，不然会报缺少权限的错误。如果是 Windows 电脑不想接 GPIO，也可以改用串口控制 Arduino，树莓派方案则直接用 GPIO 最省事。

5.2 从零到一：完整运行流程

拿到源码包后按这个顺序操作基本不会出问题：

1. 创建项目目录并把源码包解压进去，注意路径中不要含有中文和空格，OpenCV 对中文路径的支持不太好，很多imread返回 None 的问题都是中文路径导致的。
2. 安装 Python 3.10 和虚拟环境，激活后按requirements.txt安装依赖，opencv-contrib-python千万别漏。
3. 修改collect_samples中摄像头 index 和用户 ID，运行采集 30-50 张人脸，眼睛正视摄像头、缓慢转动头部。
4. 修改train_model中data目录路径，运行训练，确认生成了trainer.yml。
5. 修改recognize_face中的模型路径和阈值，运行主程序测试。
6. 如果接硬件，把继电器、电插锁、电源连接好，测试unlock_door是否正常工作。
7. 确认日志写入access_log.db。

5.3 实测效果记录

我用一台 i5-8250U 的旧笔记本 + 普通 USB 720p 摄像头做了测试。训练集一个人 40 张照片，LBPH 识别速度在 CPU 上能达到每秒 15 帧左右，肉眼感觉不到延迟。置信度方面：本人正常正面识别大约是 55-70，戴着口罩直接无法检测到人脸；同事的脸测试出来是 100 以上，参考性很强。实验说明阈值设在 80 在这个室内场景下是稳定的。

人脸检测稳定性和光线关系非常大。背光的昏暗房间里，检测距离从正常光照的 2 米缩到 1 米内，而且侧脸基本失效。要提升实际可用性，可以在摄像头旁边加补光灯，或者换用分辨率高、感光好的摄像头。

6. 常见问题与排查技巧实录

6.1 高频报错与解决方案速查表

6.2 识别准确率差怎么办

模型训练好后发现“自己的脸都识别不了”，或者“谁的脸都能开门”，这是最常见的两个问题。第一个情况一般是采集照片数量不够或者角度太单一，建议重新采集至少 40 张照片，采集时不断变换头部角度和表情。第二个情况通常是置信度阈值设置得太宽松，比如设了 90 或 100，此时很多不相似的脸都能通过。你可以把阈值调到 60 试一下，同时观察非本人脸的 confidence 数值分布，能有效区分。

另外，训练图片分辨率太低也会导致特征提取失败，保存的人脸区域如果小于 100x100，建议直接丢弃，不加入训练集。

6.3 门禁联动失效的排查顺序

如果软件识别已经通过但门没开，按以下顺序排查：先用万用表量继电器电源是不是正常；然后检查 GPIO 引脚号是否正确，GPIO.BOARD 和 GPIO.BCM 的引脚编号方式完全不一样，混用会导致控制错引脚；再看unlock_door是不是被调用了，可以在函数里加一行print观察输出；最后确认继电器是高电平触发还是低电平触发，这个模块不同型号触发逻辑可能相反，代码里要匹配实际硬件。大部分“门没反应”的问题最后都是出在这四个环节里，逐个排除即可。

7. 项目扩展方向

这个源码包保底能跑通门禁识别流程，但它更值得学习的地方在于整体架构思路。深度学习方案比如用face_recognition库替换 LBPH 算法，代码改动量其实不大，识别精度却能提升一个档次。想继续深入的话，可以试试给系统加一个 Web 管理后台——Flask 做接口，前端做一个简单页面，就能在手机或电脑上查看实时识别记录和远程开锁；也可以对接企业微信或钉钉的机器人，识别成功时推送消息给管理员；把 SQLite 换成 MySQL 或 PostgreSQL 之后，多人同时刷脸的并发场景也能扛住。硬件部分也能扩展，加入红外传感器后还能实现“有人靠近时自动唤醒摄像头”，降低功耗。

这些扩展方向里我自己的体会是：与其频繁地重写整个项目，不如先调好核心门禁链路，然后逐步加功能，每一步的小改动都能帮助你理解整套系统是如何协作的，出问题时也能更快定位到具体模块。

最后分享一个经验：很多人在做完人脸识别项目后直接把代码和资料丢到网盘就完事了，但等答辩或换电脑时才发现环境变量少配了、模型文件丢了、采集的照片被清了。建议把整个项目文件、安装依赖、运行说明整合为一个 README 文件，写好每个 Python 脚本的用途，最好附上整个系统的流程图——这对日后再回来维护这套代码时帮助最大。

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