Skip to content
Durian2005Public

About

本地离线人脸识别登录系统:Python + OpenCV (YuNet/SFace) + Flask + SQLite,口令 + 人脸 1:1 验证 + 随机动作挑战反欺骗

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

人脸识别登录系统(本地版)

一个跑在自己电脑上的轻量人脸识别登录实验项目。识别、存储全部在本机完成,人脸图像不上传。


⚠️ 用途声明与安全边界(请先读这段)

这是教学 / 实验项目,请勿用于真实的门禁、考勤或身份认证场景。

  • 只有轻量反欺骗,不是完整的活体检测。 人脸登录前需要完成一次随机动作挑战 (转头 / 抬头 / 低头)。这能挡住静态照片与事先录好的视频 —— 挑战由服务端随机生成、 一次性、带有效期,预录素材对不上指令。但挡不住攻击者拿着照片或手机屏实时配合动作 旋转,也挡不住实时换脸 / 深度伪造。它把门槛从「举张照片」提高到「必须实时配合随机动作」,仅此而已。
  • 相似度阈值默认 0.50。已用 LFW 公开数据集做过量化标定(结果见 阈值标定报告):这套「YuNet + SFace + 余弦」在 LFW 上的 等错误率约 0.73%,按「误接受率 ≤ 0.1%」标出的推荐阈值是 0.375 —— 与 OpenCV 官方文档 给出的 SFace 参考值 0.363 相差不到 4%。也就是说默认的 0.50 偏严: 在标定集上它会拒掉约 9.4% 的本人尝试。默认值暂保留 0.50(偏严更保守), 想放宽请照报告里的数字自行调整 —— 页面上的「阈值校准」卡片可以直接改。
  • 登录接口会返回相似度数值 —— 这是刻意为之,便于校准阈值,生产环境不应如此。
  • 服务使用 Flask 开发服务器,只监听 127.0.0.1,不要暴露到公网。
  • 服务会校验请求的 Host 与 Origin:本机上的其它网页拿不到摄像头画面 (/api/stream 另有每进程随机令牌),也关不掉服务。完整的攻击面、 缓解措施与残余风险见 THREAT_MODEL.md —— 那份文档同样写清了「明确防不住什么」。

如果你需要能抵御呈现攻击(presentation attack)的方案,本项目不是: 它只有一层轻量动作挑战,缺少真正的活体检测、深度伪造检测等必要环节。这里实现的是 口令认证基线 + 人脸作为辅助因子 + 轻量反欺骗的完整工程骨架,而不是一个安全的人脸认证产品。


获取源码

git clone https://github.com/Durian2005/FaceLogin.git
cd FaceLogin

怎么运行(一键启动)

最省事:双击 一键启动-无窗口.vbs

双击后不会弹出任何窗口,等 2–3 秒浏览器自动打开 http://127.0.0.1:5000/。 不用了直接关掉网页就行——约 5 秒后服务自动停止、摄像头自动释放,不需要额外操作。

想看到运行日志:双击 一键启动-有窗口.bat

会弹出一个命令行窗口,日志实时可见。那个窗口就是服务本身,关掉窗口服务就停了。

全部脚本:

文件 说明
一键启动-无窗口.vbs 推荐。静默无窗口启动,自动开浏览器
一键启动-有窗口.bat 有窗口、日志实时可见;关窗即停,排错时用
停止服务.bat 强制停止服务(一般用不到——关掉网页会自动停)
诊断.bat 检查环境并生成 diagnose_result.txt
  • 关掉网页 ≈ 关掉软件:约 5 秒后服务自行退出(宽限期内重新打开页面会取消退出,所以刷新不会误杀)。
  • 服务已经在运行时再双击启动器不会启动第二个副本,只会帮你把浏览器打开。
  • 启动失败会弹窗说明原因(不再默默闪退),详情同时写进 launch_log.txt。
  • Windows 默认隐藏文件扩展名,所以显示出来的文件名不带 .vbs / .bat——按名称区分即可。

完整的分步操作(注册、录入人脸、登录、出错怎么办)见 使用教程.md。

页面与操作路径

界面是六张独立的页面,由服务端路由驱动(/、/register、/login、/enroll、 /console、/settings)。能不能进某张页面由服务端判定 —— 走不进去就重定向到该去的 地方,所以不会出现"点得动但用不了"的入口。

页面 地址 什么时候能进 在这页能做什么
欢迎 / 未登录 看实时画面;按「本机是否已有账号」二选一:登录 / 创建账号
创建账号 /register 未登录 用户名 + 密码 + 确认密码;成功后自动登录并直接进入录入页
登录 /login 未登录 「人脸登录」(需完成随机动作挑战)或「密码登录」;成功后自动进入主控台(没录过人脸的先去录入页)
录入人脸 /enroll 已登录 逐组采集 3 组、显示真实进度 1/3 → 3/3;也可以跳过直奔主控台
主控台 /console 已登录 且已有人脸模板 账号状态、重新录入、进入设置、退出登录;右侧是本人最近的记录
设置 /settings 已登录 阈值校准(调低需密码确认)、删除人脸数据(需密码确认)

顶部常驻三步进度条(注册账号 → 录入人脸 → 登录验证),由服务端渲染,标明"你在第几步"。 每张页面只有一处"你现在该做什么"的引导条,其余说明收进折叠的提示文字里。

几处刻意的设计:

  • 人脸登录前有准备阶段:点「人脸登录」后先出现"请正对摄像头、保持不动约 1 秒", 点「我准备好了」才开始。基线帧是在开始之后才采的,所以不会再有"一看到指令就转头、 把基线采成侧脸"导致的误判超时。
  • 采集进度是真的:录入时逐组调用接口,进度条与按钮上的"正在采集第 2/3 组…"都来自 实际完成的组数,不是客户端计时器假装出来的。
  • 后端错误码都有中文文案,不会再出现 login_required 这类裸英文码直出。
  • 「关页即停」的判定:真正关闭页面才通知服务端退出;页内跳转靠一个 5 秒时效的标记 区分,不触发退出。极端情况(点了链接又立刻取消、随后马上关页)会漏掉一次通知, 此时由"120 秒无页面活动"兜底退出。
  • 右下角浮层统一显示操作结果(成功 / 失败原因),几秒后自动消失,失败类提示停留更久。

前端是 layout + 每页一个文件(app/templates/,用 Flask 自带的 Jinja2 继承), CSS 与 JS 全部内联,不引用任何 CDN、不经过任何构建步骤 —— 离线环境下也能完整工作。

登录策略(默认值,可用环境变量覆盖)

项 默认 环境变量
人脸相似度阈值 0.50(标定推荐 0.375,见报告) FACELOGIN_THRESHOLD(也可在页面上改,改后落库)
允许失败次数 3 FACELOGIN_MAX_FAILS
锁定时长 180 秒 FACELOGIN_LOCK_SECONDS
密码哈希 Argon2id 装不上 argon2-cffi 时自动退回标准库 scrypt
人脸登录的活体检测 开启(随机动作挑战) FACELOGIN_LIVENESS(设 0 关闭;关闭即等于放弃反照片欺骗能力)
会话 8 小时,HttpOnly + SameSite=Lax —
数据文件 data\faces.db FACELOGIN_DATA(改目录)
模型目录 <项目根>\models FACELOGIN_MODELS(见下方「人脸模型」)
关掉网页后自动退出 开启 FACELOGIN_AUTO_EXIT(设 0 关闭该功能)
└ 退出宽限期 5 秒 FACELOGIN_EXIT_GRACE
└ 无活动兜底超时 120 秒 FACELOGIN_EXIT_IDLE
  • 密码错误或人脸不匹配都会累计失败次数,连续 3 次锁定 3 分钟;锁定期内密码和人脸两种方式都无法登录。
  • 用户名不存在时也做一次等价的哈希运算,避免通过响应快慢猜出账号是否存在。
  • 人脸登录是「账号先行 + 1:1 比对」,不需要遍历所有用户。

人脸登录的活体检测(随机动作挑战)

人脸登录现在是两步:先向服务端要一个随机动作,做完并通过判定后,才拿那一帧去比对。

① POST /api/liveness/start   → 服务端随机下发:转向左 / 转向右 / 抬头 / 低头
② 用户在摄像头前做动作         → 服务端约 14 Hz 采样,逐帧估算头部姿态
③ POST /api/liveness/verify  → 判定动作成立且已转回正对镜头 → 用那一帧提特征 → 1:1 比对

判定依据是由 5 个关键点推算的头部姿态代理值(零额外模型、零额外依赖):

指标 定义 正视 动作方向
yaw (鼻尖 x − 双眼中点 x)/ 瞳距 ≈ 0 转向自己左侧 → 增大
pitch (鼻尖 y − 双眼中点 y)/(嘴角中点 y − 双眼中点 y) ≈ 0.5 抬头 → 减小;低头 → 增大

正视取值因人、因坐姿而异(实测同一个人不同时刻 yaw 在 +0.01 ~ +0.07 之间浮动), 所以判定一律用相对基线的变化量:先采 4 帧求基线中位数,再看偏移是否超过阈值。

参数 值 说明
动作成立阈值 yaw 0.13 / pitch 0.10 滑窗 5 帧内至少命中 3 帧
空闲时的自然噪声 yaw ±0.04 / pitch ±0.01 实测值 —— 阈值约为噪声底的 3 倍 / 10 倍
单次挑战最长时间 8 秒 超时或没做动作都判不通过
挑战有效期 90 秒,一次性 取出即作废,并绑定当前浏览器会话

采样分三段:基线 → 等动作 → 等回正。第三段不只是为了体验 —— 它保证「通过动作验证的 那一帧」和「送去比对的那一帧」来自同一段连续画面,而不是中途被换掉。

为什么是动作挑战、不是眨眼检测:YuNet 只输出人脸框 + 5 个关键点(双眼、鼻尖、左右嘴角), 不含眼睑,判断不了眼睛开合。要做眨眼检测必须再引入一个关键点模型。

做不对动作会不会被锁号? 不会。动作没做出来不累计失败次数 —— 否则动作不熟练的用户 会被锁号。只有真正跑到特征比对且不通过时才计数;反复重试挑战对攻击者也没有帮助。

这个防护的边界(与 README 顶部声明一致):

攻击方式 能否挡住
举着一张静态照片 ✅ 挡得住 —— 挑战随机且一次性,照片不会动
播放事先录好的视频 ✅ 挡得住 —— 预录素材对不上随机指令
实时拿着照片 / 手机屏配合旋转 ❌ 挡不住
实时换脸 / 深度伪造 ❌ 挡不住

另外还有一层启发式:采样过程中若人脸位置发生突变(例如画面被切到另一路视频), 会以 face_changed 直接判失败。这只是粗筛,不是可靠的防切换机制。

关掉网页就自动退出(释放摄像头)

页面每 2 秒轮询一次 /api/state,本身就是心跳;关闭或刷新页面时前端再通过 sendBeacon 发一次 /api/bye。收到后先给 5 秒宽限期,期间只要有新的页面请求进来就取消退出 (所以「刷新页面」不会被误判成「关闭」),宽限期过了才真正退出进程并释放摄像头。

情况 行为
关掉网页 / 关掉浏览器 约 5 秒后自动退出
刷新页面 不退出(宽限期内重新加载会取消)
浏览器崩溃、来不及通知 120 秒无任何请求后自动退出(兜底)
只启动、从未打开过页面 永不自动退出(避免"启动完就自己没了")
想让它一直跑 启动前设 FACELOGIN_AUTO_EXIT=0

数据存在哪里

SQLite 单文件:data\faces.db(首次运行自动创建)

表 存什么
users 用户名、密码哈希、失败计数、锁定截止时间、最后登录时间
face_templates 人脸特征向量(128 维 float32,512 字节 BLOB),每用户最多保留 8 组
login_events 审计事件:注册、密码/人脸登录、动作挑战、锁定、录入、删除、阈值变更
settings 会话签名密钥、当前阈值

不保存原始人脸照片,也不保存摄像头视频。 但特征向量本身仍是敏感生物特征信息,不要把这个文件随意复制给别人。

目录结构

FaceLogin/
├─ 一键启动-无窗口.vbs       一键启动(推荐,无窗口)
├─ 一键启动-有窗口.bat       有窗口启动(能看到日志)
├─ 停止服务.bat              停止服务
├─ 诊断.bat                  环境诊断
├─ 打包.bat                  打包成免安装的 Windows 文件夹
├─ 使用教程.md               分步使用说明(先看这个)
├─ README.md                 本文件
├─ THREAT_MODEL.md           威胁模型:资产、攻击面、缓解、残余风险
├─ LICENSE                   本项目代码与文档的 MIT 许可证
├─ requirements.txt          运行依赖
├─ requirements-dev.txt      仅打包/评测需要的依赖(PyInstaller、pyarrow)
├─ app/
│  ├─ server.py              路由、会话、锁定、审计、请求来源校验(服务层)
│  ├─ reqguard.py            Host 白名单 / Origin 校验 / 每进程页面令牌
│  ├─ db.py                  SQLite 存储层(审计日志带哈希链)
│  ├─ security.py            密码哈希与登录策略
│  ├─ face.py                人脸检测、对齐、特征、比对、头姿代理值
│  ├─ liveness.py            活体检测:随机动作挑战与姿态采样判定
│  ├─ paths.py               运行形态路径解析(源码运行 / 打包后)
│  ├─ model_paths.py         模型路径解析(非 ASCII 路径自动镜像)
│  ├─ templates/             前端页面:layout.html 公共外壳 + 六张页面(Jinja2 继承,零构建、无外链)
│  └─ run.py                 启动入口(自动开浏览器)
├─ models/                   人脸模型 + 第三方许可证(见 models/README.md)
├─ data/faces.db             用户、人脸模板、审计(自动生成,不入库)
├─ docs/                     量化实验结果(阈值标定报告)
├─ tools/                    验证、诊断、标定、模型下载与打包脚本
├─ dist/FaceLogin/           打包产物(自动生成,不入库)
└─ .venv/                    Python 运行环境(自动生成,不入库)

data/、dist/、build/ 与 .venv/ 都在 .gitignore 里:前者含口令哈希与 生物特征;dist/、build/ 是可由源码重建的构建产物;.venv/ 体积上百 MB 且夹带本机绝对路径。都不该进版本库。

运行依赖

平台:Windows(摄像头使用 cv2.CAP_DSHOW 后端,且启动器是 .bat / .vbs)。 Linux / macOS 需要改动摄像头后端与启动脚本,目前未适配。

  • Python 3.13(缺少 .venv 时启动脚本会自动创建并安装依赖)
  • 依赖见 requirements.txt: Flask 3.1.3 · NumPy 2.5.3 · opencv-python-headless 5.0.0.93 · argon2-cffi 25.1.0

从源码开始

git clone <仓库地址>
cd <仓库目录>

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 然后双击 一键启动-无窗口.vbs,或:
.venv\Scripts\python.exe app\run.py

模型已随仓库提供,不需要额外下载;若确实缺失,运行 python tools\download_models.py。

打包成 exe(免安装,给没装 Python 的人用)

双击项目根的 打包.bat(或执行 .venv\Scripts\python.exe tools\build_exe.py), 约 20 秒后得到 dist\FaceLogin\ 文件夹。直接双击里面的 FaceLogin.exe 即可运行 —— 目标电脑不需要装 Python,也不需要装任何依赖。

dist\FaceLogin\
├─ FaceLogin.exe     双击启动(无控制台窗口)
├─ models/           人脸模型(放在 exe 旁边,可自行替换)
├─ data/             首次运行后自动生成,存 faces.db
├─ launch_log.txt    首次运行后自动生成,排查问题看这个
└─ _internal/        Python 运行时与第三方依赖,不要手动改

分发时把整个 dist\FaceLogin 文件夹压缩发出去即可。两个注意点:

  • models/ 必须跟着走 —— 它刻意不打进 exe 内部,这样模型可替换, 也不会让每次启动都解压一遍上百 MB 的内容。
  • data/ 是使用者自己的账号与人脸特征,不要把自己的 data/ 一起发出去。

打包参数:

参数 作用
无 默认,无控制台窗口
--console 保留控制台窗口,排查启动问题时用
--slim 额外删掉 OpenCV 的 ffmpeg 视频解码后端,省约 30 MB

打包成功后会自动验证(不用你记得)

打包.bat 在构建成功后会紧接着运行 tools\smoke_frozen.py,对着刚打出来的 exe 发真实 HTTP 请求,确认请求来源校验确实进了二进制:

探测 期望 验证的是什么
正常 Host 访问首页 200 服务基本可用
Host: evil.com 403 DNS 重绑定防护在包里
跨站 Origin 打登录接口 403 CSRF 防护在包里
摄像头画面不带页面令牌 403 令牌校验在包里
带正确令牌访问同一接口 200 正向对照

最后一条不能省:只测「该拒的都拒了」的话,服务整个坏掉也会让所有请求返回 403, 看起来像「加固生效」。必须有「带正确凭证要能通过」来对照。

另外还有三项前置检查:5000 端口是否已被别的实例占用(占用就拒绝运行, 否则探测打中的是别人,会给出假的通过)、exe 是否比源码旧(防「改了代码忘了重打包」)、 以及产物目录不是项目根(防把数据写进真实的 data\faces.db)。

任何一项失败,打包.bat 会直接报错退出,不会再提示你「打包成功」。 验证脚本会自己清理运行痕迹(只删它自己产生的),产物保持「首次运行前」的状态。

为什么必须验二进制:PyInstaller 把纯 Python 模块压进 exe 内的 PYZ 归档(zlib 压缩), 所以「在包里找某个 .py」是问不出答案的 —— 按文件名既找不到存在、也找不到不存在。 而所有单元测试跑的都是源码,源码全绿不代表发出去的包是对的。

为什么是 203 MB

打包.bat 默认产出约 203 MB;加上 --slim 裁剪后约 173 MB。 体积几乎不来自 Flask,也不来自本项目代码:

部分 大小 能否省
cv2.pyd(OpenCV 单体模块) 82 MB ❌ 人脸检测/识别的地基,官方 wheel 无法拆分
models/(人脸模型) 37 MB ❌ 必需
numpy 的 OpenBLAS 数值库 20 MB ❌ 矩阵运算必需
libcrypto / libssl 9 MB ❌ 标准库 ssl 依赖,Werkzeug 会 import
Python 运行时 + Flask 等 约 15 MB ❌
OpenCV 的 ffmpeg 后端 30 MB ✅ --slim 可删(默认不裁剪)

本项目自己的代码不到 100 KB。体积基本是 OpenCV 这条技术路线的固有成本 —— 想显著变小只能换人脸识别的实现方式,那会牺牲「零额外模型、离线可跑」这些特性。

打包产物在 dist/、build/ 中,已被 .gitignore 排除,不会进版本库。

人脸模型

随仓库提供,位于 models/(也可用 FACELOGIN_MODELS 指定到别处)。来自 OpenCV Zoo,版权归原作者所有:

文件 用途 许可
face_detection_yunet_2023mar.onnx 人脸检测(YuNet) MIT,Copyright (c) 2020 Shiqi Yu
face_recognition_sface_2021dec.onnx 特征与比对(SFace) Apache-2.0

许可证原文放在 models/LICENSE_yunet.txt 与 models/LICENSE_sface.txt,详情见 models/README.md。再分发时请一并保留这两个文件。

关于中文路径(曾经踩过的坑)

OpenCV 无法从非 ASCII 路径读取 ONNX 模型。 这不是猜测,是本项目实测的:

尝试 结果
把含中文的路径直接交给 cv2.FaceDetectorYN.create() ❌ Can't read ONNX file
改传内存 bytes(C++ 侧有 buffer 重载) ❌ Python 绑定不接受,进程段错误退出
Windows 8.3 短路径(GetShortPathNameW) ❌ 数据卷默认不生成短名,返回的仍是中文路径
把模型镜像到纯 ASCII 目录再加载 ✅ 可行

所以 app/model_paths.py 会在路径含非 ASCII 字符时,自动把模型复制到一个 纯 ASCII 的缓存目录(%LOCALAPPDATA%\FaceLogin\models,退回临时目录), 校验大小与时间戳后复用,你不需要做任何配置。

这也解释了为什么项目里不写死任何绝对路径 —— 每个人把仓库 clone 到哪里都不一样。

需要重新下载模型时(比如 clone 时用了 sparse-checkout):

python tools/download_models.py            # 走 LFS 直链 + SHA-256 校验
python tools/download_models.py --no-proxy # 系统代理失效时

自测

.venv\Scripts\python.exe tools\test_security.py       # 安全加固 + 真分页路由(离线,82 项)
.venv\Scripts\python.exe tools\test_storage.py        # 存储层(21 项)
.venv\Scripts\python.exe tools\test_liveness.py       # 活体检测(47 项)
.venv\Scripts\python.exe tools\test_eval_report.py    # 标定脚本的端到端(21 项)
.venv\Scripts\python.exe tools\verify_audit_chain.py  # 审计链完整性(只读,读正式库)

合计 171 项,全部离线、不需要摄像头。

四个测试脚本自带隔离(数据目录在代码里指向临时目录,与调用方无关), 所以直接跑就是安全的:跑完 data\faces.db 的哈希不会变。 只有 verify_audit_chain.py 是刻意读正式库的 —— 它的用途就是校验你真实的审计日志。

  • test_security.py —— 82 项断言,全离线、不打开摄像头、不碰正式数据库 (FACELOGIN_DATA 自动指向临时目录,face 模块用桩替换,所以不会加载模型): Host 白名单(含「看起来像 localhost 的域名」这种绕过尝试、以及 127.0.0.1:8080.evil.com 这类拼接)、Origin/Referer 校验(含 Origin: null 与「同主机不同端口」)、页面令牌、 六张页面的路由与重定向(未登录 / 已登录但没录人脸 / 已登录且已录人脸,三种状态各查一遍)、 阈值降级必须验口令、以及审计链的篡改检出与断点定位。 最后一节是真机 socket 探测:起一个真实监听端口的服务,用 http.client 发原始请求 —— 因为 test_client() 是进程内直调 WSGI,测不出「值是怎么送进浏览器」这一段。
  • test_storage.py —— 用户创建与去重、密码校验、模板数量上限、失败锁定、审计读写、 模板与用户删除等 21 项断言。
  • test_liveness.py —— 47 项断言,完全离线、确定性:姿态代理值的数学(用合成关键点)、 挑战票据的一次性/过期/会话绑定/随机性、以及采样状态机的全部路径(成功、方向做反、 幅度不足、不回正、无人脸、画面突变、有效帧不足)。不打开摄像头、不需要真人样本。
  • test_eval_report.py —— 17 项,用桩人脸引擎 + 合成 parquet 真跑一遍 eval_threshold.py 的 main(),确认报告能被完整生成(没有残留占位符、表格真有数据行)。 这一层是补出来的:main() 里曾有个局部变量忘了赋值,而所有纯函数测试全绿 —— 纯函数测试测不出「编排层漏接线」。
  • verify_audit_chain.py —— 逐条重算审计日志的哈希链,只读、不自动修复。 退出码 0 = 链条完好,1 = 检测到篡改并打印断点 id 与原因。

阈值标定(不需要摄像头、不需要真人,约 10 秒):

# 先按 tools/eval_threshold.py 头部注释里的命令取一份 LFW parquet(国内走 hf-mirror.com)
.venv\Scripts\python.exe tools\eval_threshold.py --parquet <lfw.parquet>

产出 docs\threshold-report.md 与 docs\threshold-curve.png。比对链路与运行时完全相同 (同一个 FaceEngine),配对种子固定所以数字可复现。报告里写明了方法与全部局限 (自建配对协议 ≠ LFW 官方 6000 对、FAR 的置信上界、身份选取不是随机抽样等), 请连同局限一起引用这些数字。

真机校准与方向核对(需要真人配合,约 30 秒):

.venv\Scripts\python.exe tools\head_pose_probe.py

它会先测 3 秒基线,再依次提示你做 4 个动作,实时打印 yaw / pitch 偏移量,最后汇总结论 —— 既能核对「转头方向 → 数值变化方向」的约定是否成立,也能看出当前阈值是不是偏高或偏低。

当前限制(重要)

  • 活体检测只是轻量反欺骗:能挡住静态照片与预录视频,挡不住实时配合旋转的照片/屏幕, 也挡不住实时换脸。密码回退不能替代真正的活体检测。
  • 登录接口会返回相似度数值,这是为了校准阈值;正式使用时不应把比对细节返回给客户端。
  • 服务用的是 Flask 开发服务器,适合本机实验,不要直接暴露到公网。
  • 单机单用户设计:没有角色 / 权限模型。未登录时页面上只给一个「本机有没有账号」的布尔值, 不回显任何账号名 —— 这是刻意的,避免任何能打开页面的人做一次免费的账号枚举。 后端保留了 /api/users 接口,但当前没有任何页面入口(见后续计划)。
  • 用户名与密码没有找回机制;忘记密码只能删掉 data\faces.db 重来。
  • 阈值已用 LFW 做过量化标定(见标定报告),但那是公开数据集、 且用的是自建配对协议;真实摄像头场景(侧光、逆光、遮挡、大角度)会明显更难, 本机个人样本量也还远不够。默认暂留 0.50(偏严)。
  • 动作挑战虽然不累计失败次数,但每次最多占用摄像头 8 秒,动作不熟练会明显拖慢登录。

部署后登录卡在活体检测?

现象:注册、录入都正常,一登录就卡住 —— 浮层提示「没有检测到指定动作」, 反复重试也不通过,最后只能改走密码登录。

先别怀疑账号或数据。这类失败通常只有两个来源:

  1. 动作窗口期被吃掉 —— 指令和采样几乎同时开始,人还没看清 8 秒就过去了;
  2. 某个姿态轴在这台机器上推不动 —— 摄像头俯拍 / 仰拍,或脸型让该轴的代理值偏移不够。

按下面两层顺序改,先试第一层:它覆盖绝大多数情况,而且不损失安全性。 需要说明的是,这两层的代码改动都没有预先合进仓库 —— 仓库默认是「4 个动作 + 指令与采样连发」, 照下面的说明自己改。

第一层:先出指令,用户点「开始」再计时

先看清现状(对着代码核过):/api/liveness/start 只下发动作、不启动采样; 真正的 8 秒窗口(liveness.MAX_SECONDS)是从 /api/liveness/verify 到达后才开始算的。 问题出在页面上这两个请求是连着发的 —— 点完按钮,指令和采样几乎同时开始, 用户还得读一遍「把头转向你的左侧」、确认左右、再动头,窗口已经过去一半。 摄像头初始化慢、模型首次推理慢的机器,更容易直接超时。

改法是把「出指令」和「开始采样」拆成两次点击:

  1. 点「人脸登录」→ 立即 POST /api/liveness/start,把返回的 action_text (如「把头转向你的左侧」)显示在页面上。此时不发 verify、不计时。
  2. 用户看清后自己点「开始」→ 这时才 POST /api/liveness/verify,8 秒窗口从这里起算。
  3. 失败后不要把用户踢回表单:保留指令、允许原地再点一次即可 (挑战失败不累计登录失败次数,这点已有保证)。

安全性:没有削弱。指令在用户点击之前就已确定,攻击者没法靠「边看边准备」占便宜。

可选加强:每 10 秒换一次动作。 在等待期间定时重新 POST /api/liveness/start, 用新返回的 action_text 覆盖页面上的显示。旧票据不需要手动清理 —— new_challenge() 是一次性消费、CHALLENGE_TTL = 90 秒自动过期、MAX_PENDING = 128 兜住上限。 副作用是屏幕上的指令会自己变,所以换指令时必须给一次明显提示(换字 + 短暂高亮), 否则用户会照着旧指令做反方向、白白超时。

第二层:砍掉抬头 / 低头,只留左右摇头

第一层做完还是过不去,就说明不是「操作速度」问题,而是姿态代理值跟这台机器不适配。 这时收窄动作集合:

# app/liveness.py
ACTIONS = ("left", "right")        # 原为 ("left", "right", "up", "down")

只改 ACTIONS 是安全的:up / down 抽不到,ACTION_TEXT 与 satisfied() 里留着也无副作用。 反过来不行 —— 文案删了而 ACTIONS 仍含 up / down,ACTION_TEXT[action] 会直接 KeyError。

为什么优先砍 pitch 轴:

轴 判定量 实际情况
yaw(左右转头) 鼻尖相对双眼中点的水平偏移 方向经真人验证(右转 → yaw 减小);阈值 0.13 约为空闲噪声底的 3 倍
pitch(抬头 / 低头) 鼻尖在「眼线 → 嘴线」上的相对高度 方向未经真人实证;该比值取决于鼻长与嘴位,人脸型差异大,摄像头俯仰角还会整体平移基线

也就是说,pitch 轴的失败更可能是「这台机器 + 这张脸到不了阈值」,再练动作也没用; 而 yaw 轴的偏移量级更大、更稳。只留左右摇头,登录成功率通常立刻恢复。

代价要讲清楚:动作集合从 4 个缩到 2 个,随机性下降 —— 事先录好的固定素材,猜中概率从 1/4 升到 1/2。所以第二层是可用性优先的降级, 不是等价替换:

  • 部署在自己可控的机器上(个人电脑、实验机),这个代价通常可以接受;
  • 想维持 4 动作的强度,更好的做法是保留 up / down 但调低该轴阈值 (PITCH_TILT 从 0.10 放到 0.06 ~ 0.08),先用 tools\head_pose_probe.py 量出自己抬头 / 低头能把 pitch 推到多少,再据此定值;
  • 无论哪一层,都不建议直接用 FACELOGIN_LIVENESS=0 关掉了事 —— 那等于放弃反照片欺骗能力,只适合自测调试。

改完怎么确认

  • .venv\Scripts\python.exe tools\test_liveness.py —— 47 项离线跑状态机, 改 ACTIONS / 阈值后它会立刻告诉你有没有把判定逻辑改坏。
  • .venv\Scripts\python.exe tools\head_pose_probe.py —— 真人核对一次, 打印 yaw / pitch 的实际偏移量,顺便看出阈值偏松还是偏紧。
  • 失败时的诊断量(各轴偏移区间、耗时、采样数)已经写进审计日志, 排查「到底差多少」看那里比猜更快。

排错

双击启动后弹窗报错? 弹窗里写了原因(启动器会把错误也写进 launch_log.txt)。

双击闪退? 运行 诊断.bat,把 diagnose_result.txt 内容发出来。

弹窗说找不到 app\run.py? 启动脚本路径拼接问题,已修复;若仍出现,请确认脚本和 app 文件夹在同一目录下。

弹窗说摄像头没打开? 微信 / 腾讯会议 / 相机等程序占用了摄像头,关掉它们再重新启动服务。

浏览器没自动打开? 手动访问 http://127.0.0.1:5000/。

提示端口被占用? 先运行 停止服务.bat。

弹窗说找不到模型? 检查项目下的 models\ 里两个 .onnx 是否都在; 缺失就运行 python tools\download_models.py 重新下载。

脚本输出乱码或报错? 查看 launch_log.txt。

人脸登录提示「没有检测到指定动作」? 先照浮层提示做,幅度大一点、保持约 1 秒再转回来。 如果每次都过不去、换台机器也一样,就别反复试了 —— 按 部署后登录卡在活体检测 里的两层改法排查: 第一层把「出指令」与「开始采样」拆成两次点击,第二层只保留左右摇头。 想先确认阈值对你的脸型是不是偏高,跑 tools\head_pose_probe.py, 看你做动作时 yaw / pitch 实际能推到多少,再决定调 YAW_TURN / PITCH_TILT。

提示「动作已识别,但没取到正面画面」? 做完动作后要把头转回正对摄像头停一下, 系统要用那一刻的正面画面做人脸比对。

不想每次登录都做动作? 启动前设 FACELOGIN_LIVENESS=0 关闭活体检测 —— 注意这同时也关掉了反照片欺骗能力,仅供自测与调试。

脚本编写约定(改脚本时注意)

  • .bat / .vbs 必须使用 CRLF 换行,否则 cmd 会解析错乱、窗口瞬间闪退。
  • 路径一律用 %~dp0(bat)或 FileSystemObject.BuildPath(vbs)拼接,不要手写 \,漏一个斜杠就会变成不存在的路径。
  • 脚本内容保持纯 ASCII,避免中文编码在 GBK 控制台下出错。

.gitattributes 已把 *.bat / *.vbs 锁定为 eol=crlf,避免 clone 之后 换行符被规范化成 LF、又踩回同一个坑。

许可证

本项目代码与文档采用 MIT License,Copyright (c) 2026 Durian2005。

models/ 下的两个 ONNX 模型来自 OpenCV Zoo,版权归原作者所有,不属于上述 MIT 授权的范围, 遵循各自的上游许可证(YuNet 为 MIT,SFace 为 Apache-2.0),原文见 models/ 目录下的 LICENSE_yunet.txt 与 LICENSE_sface.txt。再分发时请一并保留。

已知限制与后续计划

已完成:

  • 界面重构 —— 深色玻璃拟态布局,零构建、无外链。
  • 真实分页 —— 单页改成服务端路由的六张页面(欢迎 / 注册 / 登录 / 录入 / 主控台 / 设置), 状态机从"前端置灰"移到服务端重定向;同步改造「关页即停」,页内跳转不再触发退出。
  • 活体检测(轻量版) —— 已实现随机动作挑战。受模型能力限制,YuNet 只输出人脸框与 5 个关键点(不含眼睑),眨眼检测做不了;因此用的是零额外模型的动作挑战方案。 完整的呈现攻击防护仍需专门的活体检测模型。
  • 工程化与打包 —— tools/build_exe.py + 根目录 打包.bat,产出 dist\FaceLogin\ 免安装文件夹(约 203 MB;带 --slim 约 173 MB),目标机无需安装 Python。
  • 安全加固与威胁建模 —— 请求来源校验(Host 白名单 / Origin 校验 / 每进程页面令牌)、 阈值降级需口令确认、审计日志哈希链。完整攻击面、缓解措施与残余风险见 THREAT_MODEL.md。
  • 阈值量化标定 —— 用 LFW 公开数据集标定 FAR/FRR 曲线与等错误率, 比对链路与运行时完全一致。结论与全部局限见 docs/threshold-report.md。

还没做(按重要性):

  • 把默认阈值从 0.50 改掉 —— 标定表明 0.50 偏严(标定集上会拒掉约 9.4% 的本人), 推荐值是 0.375。暂留 0.50 是因为改动一个安全参数的默认值应当是有意为之, 而不是顺手带过;想放宽请在页面「阈值校准」卡片里改(调低需验口令)。
  • 真实摄像头场景的样本 —— 现有标定来自公开数据集(已裁剪、人脸居中), 侧光 / 逆光 / 遮挡 / 大角度明显更难;本机个人样本量也远不够。
  • pitch 轴(抬头 / 低头)的真人实证 —— 目前只有「右转 → yaw 减小」经过真人验证。 核对工具 tools/head_pose_probe.py;若某轴方向反了,只需互换 app/liveness.py 里 satisfied() 对应的两行判定。部署到别的机器上频繁卡在这里时, 按部署后登录卡在活体检测的第二层先只留左右摇头。
  • 安装包 —— 目前是免安装文件夹,没有安装向导 / 开始菜单 / 卸载项; 要做需另引入 Inno Setup 之类。
  • 角色与权限模型 —— 单机单用户设计,所有人登录后权限相同。后端虽保留 /api/users (返回账号名、模板组数、创建时间、上次登录),但界面上没有入口,也没有任何权限分级; 要做需要先定义角色与权限矩阵,再决定这个接口该开放给谁。

About

本地离线人脸识别登录系统:Python + OpenCV (YuNet/SFace) + Flask + SQLite,口令 + 人脸 1:1 验证 + 随机动作挑战反欺骗

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages