树莓派人脸识别门禁系统实战：OpenCV+PyQt5从零搭建

简介：本资源是一套完整部署于树莓派平台的人脸识别门禁系统实现方案，面向嵌入式AI初学者、物联网项目开发者及高校课程设计学生，解决轻量级边缘端身份认证场景下的软硬件协同开发问题。压缩包共452个文件，含19个核心Python源码（涵盖图像采集、Haar级联检测、LBPH训练与识别逻辑）、400张pgm格式人脸样本图像、7个png界面资源、3个OpenCV级联分类器xml文件、1个Qt Designer生成的ui界面文件及配套css样式表，整体体积12.51MB，结构清晰，便于按模块理解与调试。已有58人学习下载，资源附带README.md说明文档、users.csv用户管理表、shell启动脚本及VNC远程部署指引，覆盖从环境配置、数据集构建、模型训练到GUI交互控制的全流程，特别适合动手实践人脸识别嵌入式落地的关键环节。

1. 项目概述：为什么在树莓派上做一套人脸识别门禁

我最初接触这个项目，是因为一个朋友的创业团队要给公司做个简单的考勤门禁。买成品门禁终端吧，一个好几千，功能还封闭，想自定义都无从下手；用纯软方案吧，又得弄一台X86主机挂墙上，功耗高、体积大，看着就不像话。后来一合计，干脆用树莓派做——体积小、功耗只有几瓦，跑Python和OpenCV完全够用，再用Qt写个管理界面，通过VNC远程调试，一套自研门禁系统就出来了。整套硬件成本控制在几百元以内，项目本身也特别适合拿来练手，既能学到计算机视觉的基础流程，又能接触到嵌入式Linux、GUI开发、GPIO外设控制这些实战技能。

这套系统解决的核心问题其实很清晰：人脸检测负责“找到脸”，人脸识别负责“认出是谁”，Qt界面负责“跟人交互”，树莓派负责“把这些串起来”，VNC负责“远程维护”。门禁场景相比手机人脸解锁，最大的特点是光照不稳定、距离不固定、识别对象基数小但需要权限管理，所以算法不需要上深度神经网络那么重，传统OpenCV方案在树莓派上反而更顺畅。

适合谁来参考？我认为这几种人最合适：一是刚入门OpenCV，想做一个完整项目的人；二是想给宿舍、小工作室、小型仓库做个门禁/考勤方案的人；三是做毕设或课程设计、需要一套能跑起来还能讲解原理的技术方案的人。如果你属于其中任何一类，这篇博文应该能帮你少走不少弯路。

2. 整体设计与技术选型：从场景需求反推每个技术点

2.1 技术方案的分层思考

很多朋友看到“人脸识别门禁”第一反应是：“不要用深度学习嘛？YOLO、FaceNet不香吗？”我当时也纠结过，但冷静下来分析后发现，门禁场景有几个特殊性：

• 识别对象数量小，通常一个门禁系统就几十个人，最多几百人；
• 每个人可以配合录入多张照片，受控环境比无约束识别简单得多；
• 树莓派4B的CPU算力有限，跑深度学习模型虽然能跑，但帧率和功耗都吃亏；
• 成本敏感，如果非要加Intel神经计算棒或者Edge TPU，硬件复杂度就上去了。

所以我的最终选型是：OpenCV的Haar Cascade做人脸检测，OpenCV的LBPH算法做人脸识别。这两个方案都是OpenCV内置的，无需额外训练深度模型，推理速度在树莓派上可以跑到实时，代码逻辑也容易解释清楚。对门禁这种“受控识别”场景，识别率足够好。

整体架构分四层：

这套架构的最大优点是各层耦合度低。算法层可以单独在PC上调试，界面层也可以先在本机用假数据模拟运行，最后再全部搬到板子上联调。门禁系统出问题时，你能很快定位到底是摄像头、算法、界面还是GPIO控制的问题。

2.2 为什么用Qt而不是Web页面

有人会问：做个简单的门禁，直接开机自动跑脚本不行吗？或者用Flask写个Web管理页面，手机浏览器访问不也很方便？

我当然考虑过Web方案。Flask确实开发快，浏览器访问灵活，但有个致命问题：门禁管理界面需要显示实时摄像头画面，Web推流需要额外的编码/解码环节，延迟不可控。而Qt配合Python可以直接把OpenCV的帧数据转成QImage绘制到界面上，完全跳过Web服务器这一层，单机直连，延迟和稳定性都更可控。

树莓派上用Qt还有个额外的好处：跨平台开发方便。你可以先在Windows/Linux桌面上用PyQt5把界面写好、跑通逻辑，再拷贝到树莓派上运行。PyQt5在树莓派上可以通过apt直接安装编译好的armhf版本，不需要从源码编译，省掉一大把时间。

2.3 树莓派型号与摄像头选择

如果预算允许，我更推荐树莓派4B的4G甚至8G内存版本。2G版本跑桌面+VNC+OpenCV会有点紧张，因为OpenCV的内存开销取决于图像分辨率和连续识别帧的缓存，实际测试发现2G板子在跑连续识别时，可用内存经常掉到100M以下，可能会导致系统卡顿。8G版本就宽松很多，还能顺便跑个Nginx存抓拍日志。

摄像头方面，树莓派官方CSI摄像头（OV5647）优先。USB摄像头也可以用，但在树莓派上偶尔会出现供电不足导致掉线，而且OpenCV打开USB摄像头的设备号可能需要从 /dev/video0 改成 /dev/video1 之类的，排查起来麻烦。CSI摄像头没有这个问题，但需要用raspi-config开启Camera接口，而且要注意OpenCV对CSI摄像头不直接兼容，需要用picamera2库桥接。

这里有一个关键点很多人会踩坑：树莓派系统升级到Bullseye之后，官方的picamera库被替换成picamera2，OpenCV的cv2.VideoCapture默认打不开CSI摄像头。解决办法是先通过picamera2拿到RGB帧，再转成OpenCV的BGR格式。后面我会单独用一小节来讲。

2.4 数据流与执行流程设计

门禁系统的工作流程如下：

1. 系统启动，加载Qt界面，初始化摄像头，加载已训练的人脸模型；
2. 使用人体红外传感器（HC-SR501）检测门口是否有人活动，触发人脸识别流程；
3. 摄像头抓取一帧画面，先做缩放和灰度化；
4. Haar Cascade检测画面中的人脸区域，裁剪出人脸ROI；
5. 对ROI做直方图均衡化，归一化尺寸后送入LBPH模型识别；
6. 识别结果（人ID、置信度）与预设阈值比较，判断是否放行；
7. 通过则GPIO输出高电平，触发舵机转动/继电器吸合，完成开门；
8. Qt界面实时刷新画面和识别结果，记录日志。

3. 环境搭建与工具链准备

3.1 树莓派系统初始化

树莓派系统镜像选择Raspberry Pi OS（Bookworm版本之前的Bullseye更稳定）。如果完全做门禁设备，我建议安装Lite版本不带桌面，然后按需安装轻量桌面和VNC。但考虑到要用Qt界面显示摄像头画面，为了方便调试，我选择的是Raspberry Pi OS with Desktop版本，省去折腾窗口管理器的功夫。

系统烧录推荐用树莓派官方的Raspberry Pi Imager，在烧录前可以提前配置SSH、WiFi、主机名等参数。这一步虽然简单，但作用很大：对门禁设备这种无人值守的场景，提前开好SSH意味着你后续远程维护不需要额外接键盘显示器。

烧录完成后，首次开机先做几件事：

sudo raspi-config

在 raspi-config 界面里依次设置：

• 开启Camera接口（Interface Options -> Camera）；
• 开启VNC（Interface Options -> VNC）；
• 根据实际网络环境设置好WiFi或有线网络。

然后更新系统：

sudo apt update sudo apt upgrade -y

树莓派默认软件源在国外，更新速度不稳定。建议换成国内镜像源，具体方法是修改/etc/apt/sources.list，把deb.debian.org替换为mirrors.aliyun.com或mirrors.tuna.tsinghua.edu.cn。一定要先备份原文件再改：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo nano /etc/apt/sources.list

还要注意，如果使用较新版本的Raspberry Pi OS，可能还需要修改/etc/apt/sources.list.d/raspi.list，同样换源后执行update。

3.2 安装VNC并用远程桌面调试

VNC在这里是远程调试工具，不是必须的联机组件。但门禁设备通常放在门口或弱电箱角落，没有显示器。调试Qt界面、看摄像头画面、改代码都靠VNC远程桌面。

Raspberry Pi OS Desktop版本自带RealVNC Server。开启步骤：

sudo raspi-config # Interface Options -> VNC -> Enable

也可以在终端直接执行：

sudo systemctl enable vncserver-x11-serviced.service sudo systemctl start vncserver-x11-serviced.service

VNC服务在桌面环境下默认监听5900端口。Windows或Mac电脑安装VNC Viewer，输入树莓派的IP地址就能连接。如果VNC连接后黑屏，最常见的原因是分辨率设置问题，在raspi-config的Display Options里把分辨率固定为1280x720或1920x1080，再重启VNC服务。

VNC还有一个比较隐蔽的坑：默认虚拟桌面与真实桌面共享，如果你通过SSH登录而没启动完整桌面环境，VNC连接后可能只看到灰色背景或终端窗口。解决办法是登录VNC后手动执行startx，或者确认autologin已经开启。我比较推荐的做法是只保留VNC远程桌面一种桌面访问方式，平时不要物理接显示器，避免分辨率识别冲突。

3.3 Python、OpenCV与PyQt5安装

树莓派系统自带Python3，但版本可能偏旧。我建议直接用系统自带的Python3（通常是3.9/3.11），不要急着升级，因为很多Python包在树莓派上的预编译版本是绑定系统Python版本的。

OpenCV的安装有两条路：

1. sudo apt install python3-opencv—— 优点是安装快、依赖全，缺点是版本通常比pip源旧，比如apt里可能只有4.5.x版本而pip上已经到4.8+；
2. pip3 install opencv-contrib-python—— 优点是版本新、包含contrib模块（人脸识别LBPH就是contrib模块里的），缺点是有可能与系统库冲突。

在实际项目中，我建议直接使用pip安装opencv-contrib-python。因为LBPH识别器cv2.face.LBPHFaceRecognizer在opencv-python主包里是没有的，必须靠contrib扩展库。如果只装opencv-python，导入cv2.face时会直接报AttributeError。

如果pip安装过程卡在编译阶段或者下载太慢，可以指定国内PyPI镜像源：

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

PyQt5安装相对直接：

sudo apt install python3-pyqt5

用apt装PyQt5的好处是保证与系统Qt库版本一致，避免出现xcb相关报错。如果后续要用Qt Designer设计界面，可以再安装：

sudo apt install qt5-designer

有些朋友习惯在Windows上用PyCharm写代码、再同步到树莓派执行，我建议开发流程这样设计：代码在电脑上写好，通过Git或scp同步到树莓派，VNC里跑起来看效果。因为OpenCV和摄像头画面有很强的硬件相关性，纯在电脑上开发会遇到“电脑上正常板子上报错”的情况。

3.4 摄像头框架与OpenCV桥接问题

在最新版的Raspberry Pi OS Bullseye/Bookworm上，cv2.VideoCapture直接打开CSI摄像头大概率失败。原因很简单：新的摄像头驱动基于libcamera框架，不再向OpenCV暴露传统的V4L2设备节点。

如果你用的是老版本系统（Buster及之前），可以直接：

cap = cv2.VideoCapture(0)

但在新版本系统上，我建议通过picamera2桥接：

from picamera2 import Picamera2 picam2 = Picamera2() config = picam2.create_still_configuration(main={"size": (640, 480), "format": "RGB888"}) picam2.configure(config) picam2.start()

然后从picam2.capture_array()拿到的帧是RGB格式，需要转换成OpenCV的BGR：

frame_bgr = cv2.cvtColor(rgb_frame, cv2.COLOR_RGB2BGR)

我封装了一个Camera类，统一摄像头访问逻辑，这样后续不管接CSI还是USB摄像头，主程序不用改。这个封装工作在门禁系统里非常值得做，因为摄像头是整套系统里故障率最高的组件，独立成模块方便排查。

4. 核心算法实现：人脸检测识别的每一行代码细节

4.1 Haar Cascade做人脸检测

OpenCV的人脸检测传统方案是Haar Cascade，用一个训练好的级联分类器在灰度图上滑窗检测。虽然比不上深度学习检测器的精度，但胜在轻量、快、树莓派上跑得动。

加载检测器文件：

import cv2 cascade_path = "haarcascade_frontalface_default.xml" face_cascade = cv2.CascadeClassifier(cascade_path)

这个xml文件在opencv-python包安装目录的data文件夹下，找不到时可以通过以下命令定位：

import cv2 import os print(cv2.data.haarcascades)

检测代码：

def detect_faces(frame): gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) gray = cv2.equalizeHist(gray) # 直方图均衡化，增强对比度 faces = face_cascade.detectMultiScale( gray, scaleFactor=1.1, minNeighbors=5, minSize=(80, 80) ) return faces

equalizeHist的作用非常关键。门禁场景的摄像头通常装在门口，逆光或者暗光很常见，不做直方图均衡化，人脸区域对比度低，检测器和识别器效果都会打折扣。有些网络教程不会提这一步，但实测下来，在暗光环境下做不做均衡化，识别成功率差距很明显。如果你希望增强效果更温和，可以做成自适应直方图均衡化cv2.createCLAHE，但代价是增加一点计算量。

detectMultiScale的几个参数解释一下：

• scaleFactor=1.1：每次搜索窗口缩放倍率，1.1表示每次缩小10%。越小检测越慢但越精确，太大容易漏检；
• minNeighbors=5：每个候选区域需要至少被多少个邻近检测窗口确认，值太小误检多，值太大漏检多；
• minSize=(80,80)：最小人脸尺寸，门禁场景人脸离摄像头不会太近，调大到80x80可以明显降低CPU负载。

4.2 LBPH人脸识别原理与训练流程

LBPH（Local Binary Pattern Histogram）把一张人脸图划分成若干个小格子（例如8x8），每个像素跟邻域像素比较生成二进制编码，再统计每个格子的灰度直方图，最后把所有格子的直方图拼接起来作为人脸特征。识别时计算特征向量之间的距离，输出置信度评分。

训练流程分三步：采集人脸样本、训练模型、保存模型。我先创建一个人脸样本采集脚本：

def collect_samples(person_id, save_dir="dataset"): cap = get_camera() count = 0 total = 60 while count < total: frame = cap.read() faces = detect_faces(frame) for (x, y, w, h) in faces: face_roi = frame[y:y+h, x:x+w] face_roi = cv2.cvtColor(face_roi, cv2.COLOR_BGR2GRAY) face_roi = cv2.resize(face_roi, (100, 100)) cv2.imwrite(f"{save_dir}/person_{person_id}_{count}.jpg", face_roi) count += 1 cv2.imshow("collect", face_roi) if cv2.waitKey(200) & 0xFF == ord('q'): return

采集样本时要注意采集脸部角度的多样性。实际使用中，摄像头录入的通常都是正面照片，但人员进门时脸会偏低、偏高、偏左、偏右。所以我会让每个人在镜头前缓慢转动头部，分别采集正面、左转30度、右转30度、抬头、低头五个角度，采集60-80张。

训练脚本：

import cv2 import os import numpy as np def load_training_data(data_dir): images = [] labels = [] for file_name in os.listdir(data_dir): if not file_name.endswith(".jpg"): continue img_path = os.path.join(data_dir, file_name) img = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) images.append(img) label = int(file_name.split("_")[1]) labels.append(label) return images, np.array(labels) images, labels = load_training_data("dataset") recognizer = cv2.face.LBPHFaceRecognizer_create() recognizer.train(images, labels) recognizer.save("face_model.yml")

训练出来的yml文件就是模型，后续部署只需要分发这个文件，不需要带着原始照片。每个用户一个人ID，建立一个id_name.json文件存ID和姓名的映射关系。

4.3 识别与置信度阈值调优

识别时调用：

label, confidence = recognizer.predict(face_roi)

其中confidence是置信度距离，值越小表示与被识别样本的相似度越高。LBPH的confidence值范围不是0-100，实际输出可能从几十到一两百不等，我测试下来：

• 同一个人，光照正常，正脸，confidence < 60，非常可靠；
• 同一个人，光线复杂，confidence 60-90，基本可靠；
• 不同人，普遍在120以上。
• 同一个人的侧脸样本不足时，confidence可能跳到100-130，造成误拒。

所以阈值我建议设置为80。大于80直接拒绝，60到80之间可以再抓一帧做二次确认，连续两帧都小于80才放行。这个二次确认机制能显著降低误识别率，代价是多花100毫秒，门禁场景完全能接受。

还可以在前端界面增加一个动态调参入口，根据实际环境微调阈值，比在代码里硬编码方便得多。我最终界面上的阈值默认值就是80，管理员登录后可以改为70或90。

4.4 Qt界面设计与多线程处理

Qt界面采用PyQt5编写，布局分三个区域：

• 左侧大区域显示摄像头实时画面，叠加识别结果文字；
• 右上区域显示最近5条通行记录；
• 右下区域是操作按钮：录入新用户、切换识别模式、系统设置。

界面代码结构：

class MainWindow(QtWidgets.QMainWindow): def __init__(self): super().__init__() self.setWindowTitle("树莓派人脸门禁系统") self.resize(1280, 720) # 初始化摄像头、识别器、GPIO... self.init_ui() self.init_camera_thread()

一个关键问题：摄像头读取和人脸识别不能放在Qt主线程里，否则界面会卡死。正确做法是用QThread或QTimer轮询。我推荐用QThread专门跑识别循环，通过信号槽把识别结果传给主线程刷新界面：

class RecognizeThread(QThread): frame_signal = pyqtSignal(object) result_signal = pyqtSignal(int, int, int) def run(self): while self.running: frame = get_camera_frame() faces = detect_faces(frame) for (x, y, w, h) in faces: # 识别 + 置信度计算 ... self.result_signal.emit(x, y, w, h, label, confidence) self.frame_signal.emit(frame)

这里要注意FPS控制：树莓派上完整跑一帧检测 + 识别大约需要150-300ms，如果界面一直刷新会把CPU吃满。实测中我在识别循环里加了sleep(0.05)，把帧率限制在10FPS左右，对门禁判定完全够用，CPU占用率从90%降到40%。

4.5 GPIO控制门锁

树莓派上控制门锁有两种常见方式：舵机模拟开关门，或者继电器控制电插锁/电磁锁。如果只是做原型演示，舵机就够了；做真实门禁，用继电器驱动电插锁更可靠。

舵机方案：

import RPi.GPIO as GPIO import time GPIO.setmode(GPIO.BCM) GPIO.setup(18, GPIO.OUT) servo = GPIO.PWM(18, 50) # 50Hz PWM def open_door(): servo.start(0) servo.ChangeDutyCycle(7.5) # 90度 time.sleep(1) servo.stop()

继电器方案就简单许多，GPIO输出高电平触发继电器吸合：

GPIO.setmode(GPIO.BCM) GPIO.setup(17, GPIO.OUT) def open_door(): GPIO.output(17, GPIO.HIGH) time.sleep(3) # 开锁3秒后自动落锁 GPIO.output(17, GPIO.LOW)

这种开关量控制在代码上很简单，但硬件上一定要留意：树莓派GPIO只能提供3.3V电压、最多16mA电流，控制继电器需要接一个三极管或光耦隔离，不能直接拿GPIO接继电器线圈。我用的是5V继电器模块（带光耦隔离），VCC接外接5V电源，IN接树莓派GPIO17。通电前用万用表量一下针脚定义，有些继电器模块是低电平触发，不确认就直接把GPIO置低，容易烧板子。

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

5.1 VNC连不上、黑屏或掉线

这三个问题出现的频率最高。

连不上的排查顺序：先在树莓派本机终端执行hostname -I获取IP地址，在电脑上执行ping 树莓派IP确认网络通。然后确认VNC服务是否开启：执行sudo systemctl status vncserver-x11-serviced。如果服务正常但连接被拒，检查raspi-config里VNC是否开启，以及是否需要重启。

黑屏的常见原因有三类：

1. 桌面未启动。Lite版系统没装桌面，VNC连接后看不到图形界面，需要startx启动桌面；
2. 已登录桌面但没有活动会话。在raspi-config的System选项里开启Auto Login（自动登录桌面），VNC默认连接当前用户会话；
3. 分辨率太高，VNC Viewer显示异常。在raspi-config的Display Options里把分辨率调整为1280x720后重启树莓派。

掉线问题绝大多数和电源有关。树莓派4B对5V/3A电源要求严格，电源功率不足时网卡会随机断连，USB外设也会异常。建议直接用官方电源，不要贪便宜买杂牌5V/2A充电头。如果门禁设备放在弱电箱里，可以加一个5V/3A的DC-DC电源模块，避免WiFi环境下电压不稳。

5.2 OpenCV无法打开摄像头

在新系统上，cv2.VideoCapture(0)失败非常正常。除了前面说的改用picamera2桥接，还有一个常见原因是当前用户不在video组：

sudo usermod -a -G video pi

另外要注意设备节点权限，执行ls -l /dev/video*，如果显示crw-rw----而当前用户不属于video组，就需要加组后重新登录。

对于USB摄像头，cv2.VideoCapture(0)偶尔会打不开但设备确实存在，这时可以尝试：

ls /dev/video*

如果发现存在多个video节点，尝试cv2.VideoCapture(1)或更高的设备号。有些USB摄像头会被系统复合成一个video设备和若干metadata设备，正确的节点通常是video0。

5.3 人脸识别accuracy不高

识别不准是最影响使用体验的问题。根据我的实际操作经验，识别率排在第一位的影响因素不是算法，而是录入样本的质量。

录入时注意三点：

1. 确保人脸区域在画面中心且占比足够大，占整个画面的1/4以上；
2. 光线环境跟实际运行环境接近。如果门禁在走廊安装，晚上有灯光，建议也在同样的灯光条件下录入样本；
3. 样本数量要够。我在项目中测试过，每人20张样本识别率约80%，每人60张样本识别率能到95%以上。

如果识别率还是不够，可以尝试在预处理阶段做两件事：先equalizeHist再识别，以及把人脸ROI规范化为100x100。不要用64x64，分辨率太低会损失纹理细节，LBPH对这种损失很敏感。

还有一种情况：多人共用一套系统时，两个人的标签ID搞混了。检查dataset文件夹的命名，person_ID_序号.jpg中的ID是唯一的，训练前用脚本遍历一遍，打印出每个ID对应的样本数，避免样本不均衡导致模型偏向样本多的那个人。

5.4 树莓派运行过程异常卡顿

树莓派4B跑完整系统加OpenCV加Qt界面的负载确实不低。降低CPU负载最有效的方法是降低图像分辨率。摄像头采集分辨率从1920x1080降低到640x480，人脸检测耗时能下降3-5倍。640x480的分辨率对人脸识别来说足够，因为人脸检测后还要做90-100像素的ROI裁剪，瓶颈不在原图分辨率。

还有一招是把Qt界面的刷新频率和识别频率分离。界面显示帧率可以低到5FPS，识别逻辑保持在10FPS，两者通过信号槽异步交互。我在代码里把界面刷新改用QTimer控制，每200ms刷一次，识别线程独立跑，CPU占用率再降一截。

5.5 GPIO控制不生效但代码没报错

GPIO控制不生效的排查难点在于“代码没报错但不动作”。先用一个最简程序测试：

import RPi.GPIO as GPIO GPIO.setmode(GPIO.BCM) GPIO.setup(17, GPIO.OUT) GPIO.output(17, GPIO.HIGH)

用万用表测GPIO17引脚对GND的电压，如果代码运行时有3.3V而外设不动作，问题出在电平匹配或驱动能力上；如果电压一直是0V，检查GPIO模式，确认代码里用的引脚编号和实际接线一致。GPIO.setmode有BCM和BOARD两种模式，BCM对应芯片引脚编号，BOARD对应40针排座的物理引脚编号，混用是新手最常见的错误。

如果继电器模块接了而迟迟不吸合，检查是否为低电平触发：有些继电器模块标注“HIGH-level trigger”，有些标注“LOW-level trigger”。我在一个项目里就遇到过写着高电平触发结果实际低电平才亮的模块，用万用表量一下或者看模块丝印说明，比反复改代码靠谱。

6. 项目部署与无人值守运行方式

门禁系统开发完成后，不能指望每次开机都手动登录桌面再点图标运行。我配置了开机自启动：

在/etc/systemd/system/下创建face-door.service：

[Unit] Description=FACE Door Access Control After=network.target [Service] User=pi WorkingDirectory=/home/pi/face_door Environment=DISPLAY=:0 Environment=XAUTHORITY=/home/pi/.Xauthority ExecStart=/usr/bin/python3 /home/pi/face_door/main.py Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target

然后执行：

sudo systemctl daemon-reload sudo systemctl enable face-door.service sudo systemctl start face-door.service

注意Environment=DISPLAY=:0这块，如果Qt界面需要显示在VNC桌面里，systemd服务必须继承X11的DISPLAY和XAUTHORITY环境变量，否则启动时Qt会报could not connect to display。

日志管理同样重要，我在主程序里用Python的logging模块同时输出到文件和终端：

import logging logging.basicConfig( filename="door_access.log", level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s" )

每次识别成功或拒绝都写一条日志，包括时间、姓名、置信度。日志不仅方便排查问题，也方便后续做考勤统计。

7. 常见问题速查表

另外说一下，很多报错你看着复杂，其实只是某个依赖没装。最常见的就是ModuleNotFoundError: No module named 'cv2'或者No module named 'face'，前者说明OpenCV没装好，后者说明装的是opencv-python而不是opencv-contrib-python。卸载重装一次，然后通过python3 -c "import cv2; print(cv2.__version__)"验证版本，再把cv2.face打出来看有没有LBPH识别器，这两步就能解决一大半环境问题。

还有个小技巧，当你远程改代码后界面没有变化时，有可能是因为systemd服务里跑的还是旧进程，不能只改代码文件，还要sudo systemctl restart face-door.service才能生效。我在这个上面吃过好几次亏，改完代码发现界面还是老状态，以为代码错了，结果发现是服务没重启。

8. 踩过几次坑之后的最终心得

这个项目做完后，我最大的感受是：门禁系统真正的核心不是人脸识别算法，而是稳定性设计。算法再准，电源一抖、服务一崩、摄像头一掉线都白搭。如果你是自己做来玩，能跑通就不错了；如果是真的要放在门口当生产设备用，一定要把异常处理写好——摄像头读取失败自动重启、识别线程崩溃后自动拉起、GPU占用过高时自动降分辨率，这些都值得花时间。

对于也想从零做一遍的朋友，我的建议流程是：先在PC上跑通OpenCV人脸检测和识别，再把同样的代码挪到树莓派上，先别管Qt界面和GPIO，确认摄像头和识别链路稳定后，再加界面、加门锁控制。每一步都验证通过再往前走，排查问题的范围会小很多。千万别一上来就想着全套东西一次跑通，否则你会同时面对摄像头、算法、界面、GPIO四类问题，完全没有头绪。

最后分享一个小技巧：识别结果除了写日志，我还把每次识别成功那一帧的人脸截图存到一个snapshots目录，文件名带时间戳。这样以后有人截图对不上号，翻记录时能直接看到现场画面。成本几乎为零，但排查问题时价值极大。一个低成本的门禁系统做到这步，已经比市面上一堆成品方案更实用了。

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