简介：一套基于 OpenCV 的人脸识别门禁系统项目资料包，面向计算机视觉初学者、嵌入式开发者及毕业设计使用者。内容完整覆盖人脸检测、特征提取、身份识别、权限认证、日志记录与用户管理等关键环节，并给出从硬件准备、数据集采集、算法训练到界面设计的实现思路和代码工程，适合对照学习一整套门禁系统的开发流程。

压缩包共包含 205 个文件，整体约 31.4MB。主要文件以 C++ 源代码、头文件、人脸图像样本、可执行程序，以及 Qt、Visual Studio、Keil 等工程配置文件为主，同时附带说明文档和串口通信模块，便于支撑上位机识别与下位机控制联动调试。目前已有 644 人学习下载。资料内部含人脸识别核心算法实现、门禁控制终端界面代码、串口通信模块和项目构建文件，既可直接运行验证，也可二次修改扩展，能够帮助读者快速搭建实验环境、梳理模块间协作关系，并完成从图像采集到门禁动作的完整功能测试。

1. 人脸识别门禁：这套源码包里真正值钱的是识别到开锁的完整链路

很多人听到"Python 基于 OpenCV 人脸识别门禁系统"的第一反应是：又是一个 Haar + LBPH 的练手作业。但打开这份工程文件会发现，事情没那么简单——源码包里除了 OpenCV 识别相关代码，还有 mainwindow.cpp、FaceRecognition.cpp、qextserialbase.cpp、win_qextserialport.cpp 这一串 Qt 串口通信文件，甚至带 STM32/51 单片机端的 main.c 和 STARTUP.A51。也就是说，这不是一个只跑在电脑屏幕上的识别 Demo，而是一条从摄像头抓帧、人脸检测、特征识别、到串口发指令开锁的完整链路。适合正在搭课设/毕设门禁系统、或者想把手头识别模型接到真实硬件上的开发者。你所关心的"识别准不准、门能不能动、日志记没记"，恰恰是这套包落地的关键。

2. 算法链路拆解：从 Haar 检测框到 LBPH 置信度

2.1 人脸检测：Haar Cascades 为什么在门禁场景依然够用

OpenCV 里人脸检测的经典方案有三个级联检测器家族：Haar、HOG 和 LBP。HOG 检测精度高但计算量大，一帧 640×480 的灰度图跑 HOG 在普通电脑上都要几十毫秒，放到嵌入式板子上直接掉帧。而 Haar Cascades 是 Viola-Jones 框架的产物，用积分图加速，检测一张人脸在 PC 上能做到几毫秒到十几毫秒，配合 OpenCV 自带的 haarcascade_frontalface_default.xml，在门禁这种"人正对摄像头、距离 0.3~1.5 米、光照基本可控"的场景下足够可靠。

用 Haar 做检测时，真正影响最终识别率的不是检测器本身，而是 detectMultiScale 的参数。我一般会这么设：

import cv2 cascade = cv2.CascadeClassifier( cv2.data.haarcascades + "haarcascade_frontalface_default.xml" ) faces = cascade.detectMultiScale( gray, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80), maxSize=(400, 400), )

scaleFactor 是每轮缩放的比例，1.1 表示每次缩小 10%。这个值越小，检测越精细但耗时越长；大于 1.3 容易漏掉小脸。minNeighbors 控制一个候选框周围至少要多少个相邻框确认，设 3 会误检多一点，设 5 以上更稳。minSize 设(80, 80)是让检测器忽略掉远处的小目标，避免把背景里的玩具脸当成正脸。门禁场景里，摄像头一般固定在 1.4 米高度，人站在门前 50 公分到 1 米，这个范围刚好能被框住。

2.2 特征提取与识别：LBPH 的阈值与置信度逻辑

拿到人脸框之后，接下来就是特征提取。OpenCV 的 face 模块提供了三种传统识别器：Eigenfaces、Fisherfaces 和 LBPH。Eigenfaces 本质是 PCA 降维，Fisherfaces 是 LDA 线性判别，两者都对全局光照敏感——门禁门口的灯一换，识别率就崩。LBPH 不一样，它把图像划分成小块，每一块提取局部二值模式直方图，再把所有块拼接成特征向量。因为描述的是局部纹理关系，光照变化带来的影响被显著削弱，这也是门禁项目里 LBPH 成为默认选择的核心原因。

识别器.predict() 返回两个值：label 和 confidence。LBPH 的置信度本质是待测图的 LBP 直方图与训练样本直方图之间的相似距离，数值越小代表距离越近、越像。OpenCV 默认把 0~100 作为推荐区间，但这只是参考。实际使用时，我会先拿训练集自身跑一遍 predict，统计出真实分布，再定阈值。比如训练 20 张样本，自识别置信度集中在 35~55，那阈值定到 70 就足够宽松；如果训练样本只有 5 张，置信度往往飙到 90+，这时阈值就得往 100 以上放宽。

2.3 一张训练样本的完整流向：采集、灰度化、直方图、标签

要把图像喂给 LBPH，流程是固定的：摄像头采集彩色帧 → 转灰度 → Haar 检测框出人脸 → 把人脸区域 resize 成统一尺寸 → 调用 train()。注意，LBPH 的 train() 接受的是两个 list：图像 list 和标签 list，标签必须是整数，而且要跟人脸一一对应。如果样本目录里混着一张空图或灰度图读失败，train 直接抛错。

import cv2 import os import numpy as np def load_training_set(data_dir): faces, labels = [], [] name_to_label = {} for name in os.listdir(data_dir): person_dir = os.path.join(data_dir, name) if not os.path.isdir(person_dir): continue label = len(name_to_label) # 每个目录一个递增标签 name_to_label[name] = label for file in os.listdir(person_dir): img = cv2.imread(os.path.join(person_dir, file), cv2.IMREAD_GRAYSCALE) if img is None: continue img = cv2.resize(img, (200, 200)) faces.append(img) labels.append(label) recognizer = cv2.face.LBPHFaceRecognizer_create() recognizer.train(faces, np.array(labels)) recognizer.save("face_model.yml") print("saved labels:", name_to_label)

这段代码里两个细节值得注意：一是统一 resize 到 200×200，LBPH 不要求输入尺寸固定，但如果训练和识别时人脸尺寸差异太大，直方图分布会明显漂移；二是标签用目录名自动生成而不是手写，新增用户时不用改代码，多建一个文件夹、跑一次训练就行。

3. 工程代码包拆解：Qt 界面、识别线程与串口开锁怎么拼到一起

3.1 文件清单与模块职责

这个资源包里的文件看着多，按职责分只有四块：界面层、识别层、串口通信层、单片机固件。拿到包先对照这张表定位，不要上来就找某个函数。

FaceRecognition.cpp 和 mainwindow.cpp 是你最需要读的两个文件：前者告诉你算法是怎么被封装成接口的，后者告诉你摄像头帧是怎么被送进识别器、识别结果又是怎么触发串口写操作的。

3.2 识别线程怎么组织：抓帧 → 识别 → 结果回传

Qt 工程里如果直接把识别循环写进主窗口的 timer 回调，界面会卡得没法看。常见做法是把识别拆到独立 QThread，主线程只负责显示抓到的帧和最终结果。这个思路在 Python 里同样适用，我用 PyQt 复刻时通常这样组织：

import cv2 import threading from collections import deque class RecognitionThread(threading.Thread): def __init__(self, model_path, cascade_path): super().__init__() self.recognizer = cv2.face.LBPHFaceRecognizer_create() self.recognizer.read(model_path) self.cascade = cv2.CascadeClassifier(cascade_path) self.frame_queue = deque(maxlen=2) self.result_queue = deque(maxlen=2) self.running = True def push_frame(self, frame): if len(self.frame_queue) < self.frame_queue.maxlen: self.frame_queue.append(frame) def run(self): while self.running: if not self.frame_queue: continue frame = self.frame_queue.popleft() gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = self.cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)) for (x, y, w, h) in faces: roi = cv2.resize(gray[y:y+h, x:x+w], (200, 200)) label, confidence = self.recognizer.predict(roi) self.result_queue.append((label, confidence, (x, y, w, h)))

用 deque 而不是 list 是为了控制积压：摄像头是 30fps，识别循环如果跑不到 30fps，帧会越积越多，识别结果越来越滞后。maxlen=2 意味着一旦队列满了，旧的帧直接丢弃，新帧始终是最新的。这就是门禁系统"实时性"的关键——识别慢一点可以接受，但识别结果不能是 5 秒前的画面。

3.3 串口开门链路：QextSerialPort 与 pyserial 的等价实现

资源包里的 win_qextserialport.cpp 是 Windows 平台的串口实现，qextserialbase.cpp 是跨平台抽象层。从代码结构能看出，它的工作模式是：识别成功 → 组装开锁指令帧 → 通过串口发送到单片机 → 单片机解析指令后拉高继电器 GPIO。指令帧格式在每个项目里都不一样，但常见做法是"帧头 + 命令字 + 校验码"，比如AA 55 01 01前两个字节是头，第三个字节表示开锁，第四个是校验。

在 Python 里等价实现非常短：

import serial import time ser = serial.Serial( port="COM3", baudrate=9600, bytesize=8, parity="N", stopbits=1, timeout=0.5, ) def unlock_door(): payload = bytes([0xAA, 0x55, 0x01, 0x01]) ser.write(payload) time.sleep(1) ser.write(bytes([0xAA, 0x55, 0x00, 0x00])) # 关锁

波特率默认 9600 是单片机项目最保守的选择，51 核在 11.0592MHz 晶振下正好整除，误差最小。写完之后必须 sleep 一下再写关锁指令，否则门锁继电器刚吸合就被释放，人还没推门锁又落回去了。这里最容易翻车——后面避坑章节我会专门讲。

4. 把项目跑起来：环境、参数与一份 Python 复现骨架

4.1 环境准备：OpenCV 的 face 模块藏在 contrib 里

这个项目的算法端是 C++，但文档说明里给的复现路径可以用 Python。先装依赖，环境搞错后面全白搭。很多人卡在第一步：装了 opencv-python，结果import cv2.face报错，因为 LBPHFaceRecognizer 不在基础包里，它属于 opencv-contrib。

pip install opencv-contrib-python pip install numpy pip install pyserial pip install pyqt5

注意，opencv-contrib-python 和 opencv-python 不能同时装，两个包都提供 cv2，同时存在会互相覆盖，可能导致 import 崩溃。装完验证一下：

import cv2 print(cv2.__version__) print(hasattr(cv2, "face")) # 必须输出 True

4.2 训练与识别参数：LBPH 的四个核心参数怎么调

LBPH 有几个参数直接决定识别率，文档说明里不一定写全，但实际调的时候全用得上：

创建识别器时把参数传进去：

recognizer = cv2.face.LBPHFaceRecognizer_create( radius=1, neighbors=8, grid_x=9, grid_y=9 )

grid_x 和 grid_y 设太大会导致特征维度上升、训练变慢，而且样本少时容易过拟合。我的经验是 8×8 到 9×9 之间对门禁场景最稳。radius=2 在光照剧烈的户外有用，室内 1 就够。

4.3 一份最小可跑的 Python 复现骨架

把上述逻辑串起来，一个不依赖 Qt 的识别循环长这样：

import cv2 import os import numpy as np DATA_DIR = "./faces" MODEL_PATH = "door_model.yml" CASCADE_PATH = cv2.data.haarcascades + "haarcascade_frontalface_default.xml" # —— 训练阶段 —— faces, labels, name_map = [], [], {} for name in os.listdir(DATA_DIR): d = os.path.join(DATA_DIR, name) if not os.path.isdir(d): continue name_map[len(name_map)] = name for f in os.listdir(d): img = cv2.imread(os.path.join(d, f), cv2.IMREAD_GRAYSCALE) if img is not None: faces.append(cv2.resize(img, (200, 200))) labels.append(len(name_map) - 1) model = cv2.face.LBPHFaceRecognizer_create() if faces: model.train(faces, np.array(labels)) model.save(MODEL_PATH) print("trained, label map:", name_map) else: model.read(MODEL_PATH) # —— 识别阶段 —— cascade = cv2.CascadeClassifier(CASCADE_PATH) cap = cv2.VideoCapture(0) while True: ok, frame = cap.read() if not ok: break gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) faces = cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80)) for (x, y, w, h) in faces: roi = cv2.resize(gray[y:y+h, x:x+w], (200, 200)) label, conf = model.predict(roi) name = name_map.get(label, "unknown") color = (0, 255, 0) if conf < 70 else (0, 0, 255) cv2.rectangle(frame, (x, y), (x+w, y+h), color, 2) cv2.putText(frame, f"{name}: {conf:.0f}", (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, color, 2) cv2.imshow("door access", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()

训练和识别在同一份代码里通过有没有样本目录区分，是为了快速验证链路：先建./faces/张三/放几张照片跑训练，再跑识别看能不能认出自己。我强调一点，这个骨架里阈值 70 是临时的，真正上线前要按 6.1 节的方法重新标定。

5. 避坑记录：识别不准、掉帧与门锁不动作的五个根因

5.1 现象：识别器把所有人都判为"陌生人"

置信度输出常年 100 以上，注册过的人脸也认不出来。

原因：最常见的是样本太少且光照太单一。LBPH 本质是局部直方图比对，训练时拍的是白天自然光，识别时是晚上顶灯，直方图分布偏移超过阈值，自然匹配不上。还有一个隐藏原因：训练和识别的缩放尺寸不一致，训练用 200×200，识别时忘了 resize 或者 resize 成 64×64，直方图分布完全变了。

解决：每个用户至少采集 15~20 张，覆盖正面、左右偏转 15 度、抬头低头小角度；训练和识别必须走同一个预处理函数，统一灰度化、resize、直方图均衡化。直方图均衡化对光照偏移有显著的补偿效果，推荐加上：

roi = cv2.equalizeHist(cv2.resize(gray[y:y+h, x:x+w], (200, 200)))

5.2 现象：摄像头预览流畅，但一开识别就掉帧卡顿

画面像幻灯片，按键响应迟钝，CPU 占用满。

原因：检测和识别都阻塞在主线程里，detectMultiScale 每帧全图扫描 640×480 灰度图，加 resize 加 predict，一帧总耗时可能超过 80ms，30fps 的视频源根本吃不下。

解决：把识别丢到独立线程，主线程只抓帧和显示；降低处理分辨率，把灰度图缩放一半再检测。还有一个高频操作是把识别帧率压到 10~15fps，人站在门前停留时间远超过 100ms，识别结果完全够用：

process_this_frame = frame_count % 2 == 0

5.3 现象：识别成功但门锁纹丝不动

界面上已经弹出"通过"，但继电器不吸合。

原因：绝大多数是串口链路问题。先确认串口设备号对不对（Windows 下 COM3 可能被蓝牙占用），再确认波特率跟单片机端一致——两端一个 9600 一个 115200，收的永远是乱码。其次是帧格式没对齐，单片机按AA 55 01 01解析，上位机发的却是 ASCII 字符串"open"，协议直接报废。

解决：接线后用串口助手手动发帧测试，不要拿上位机调。先用串口调试工具把预期帧头发出去，看继电器动不动；动了再排查上位机侧代码，不动就查波特率和硬件接线。我习惯在发送口加一行日志，把每次发出的十六进制字节打出来，对照协议文档逐字节核对：

print("TX:", ser.hex(payload))

5.4 现象：注册新用户后，旧用户全部无法识别

新用户能过，老用户全变陌生人，或者反过来。

原因：LBPH 的 train() 不是增量学习，每次调用都是重建整个模型。如果你代码里每次都把所有样本重新 train 再 save，理论上没问题；但如果你只读取旧模型然后 train 新用户的两张图，旧特征会被直接覆盖掉。

解决：训练逻辑永远保留全量样本目录，新增用户只是往目录里加文件夹，然后全量重训。如果样本量很大，重训时间是个问题，那就做持久化存储：把每个用户的直方图特征单独存文件，识别时逐个比对，但这套方案自由度更高，复杂度也更大，不适合入门项目。

5.5 现象：编译 Qt/C++ 工程时一堆 LINK 错误，找不到 opencv_world 符号

原因：开发环境没配置好。这个资源包里的 OpenCV 工程用的是动态链接，需要把 opencv 的 bin 目录加进 PATH，在 .pro 文件里正确写 INCLUDEPATH 和 LIBS，缺任何一个都会在链接阶段报 LNK 2019 这类错。

解决：新建一个最小化验证工程，只做imread + imshow，先跑通 OpenCV 链接；再串 Qt 界面；最后加识别模块。模块分层验证，不要一口气编译整个工程。资源包里带了 ../3rdparty 等原有路径配置信息，我拿到包后会把里面的路径全部改写成本机绝对路径或相对路径，避免编译时踩路径雷。

6. 进阶验证：置信度阈值、样本增强与日志回放

6.1 用训练集置信度分布反推阈值

把临时阈值 70 换成科学标定：拿训练集自身做交叉预测，统计所有样本的置信度均值与标准差。以均值加三倍标准差作为基线阈值，再留 10% 的余量。

scores = [] for img, lab in zip(faces, labels): pred_label, conf = model.predict(img) scores.append(conf) mean_c = np.mean(scores) std_c = np.std(scores) threshold = mean_c + 3 * std_c + 10 print(f"threshold recommended: {threshold:.1f}")

这套逻辑的意义在于：不同用户、不同样本量下的置信度分布差异很大，固定写死 70 或 80 纯属玄学。而用训练集自身分布推导，至少是数据驱动。

6.2 小样本增强：10 张图撑起一个可用模型

门禁注册不像手机录脸那样能引导用户转一圈，往往就三五张照片。对这种小样本，我会做水平翻转、小角度旋转和亮度扰动。特别注意不要做镜像之外的大变换，门禁识别的是真人，过度增强反而让模型学到奇怪的特征。

6.3 日志回放：把摄像头源换成视频文件再验一次

上线前把摄像头源换成录好的视频，跑一遍完整流程，记录每帧的识别结果到 CSV：

with open("access_log.csv", "a") as log: log.write(f"{time.time()},{label},{confidence:.1f},{granted}\n")

日志回放的价值在于把"当时识别对没对"变成了可复现的数据。从那以后我拿到任何识别类工程，都会先跑一轮视频回放，确认日志输出、串口指令、计数逻辑全部一致，再让用户上真机。这个习惯帮我校掉过不少上线前根本发现不了的问题——比如视频里能识别、真机上因为曝光问题一进门就闪烁。

整套资源里最值得下载仔细读的，就是文档说明里那段从硬件准备到用户管理的十个步骤，以及源码包中 FaceRecognition 与串口层如何衔接的实现。希望帮到你。

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