一个跑在自己电脑上的轻量人脸识别登录实验项目。识别、存储全部在本机完成,人脸图像不上传。
这是教学 / 实验项目,请勿用于真实的门禁、考勤或身份认证场景。
- 只有轻量反欺骗,不是完整的活体检测。 人脸登录前需要完成一次随机动作挑战 (转头 / 抬头 / 低头)。这能挡住静态照片与事先录好的视频 —— 挑战由服务端随机生成、 一次性、带有效期,预录素材对不上指令。但挡不住攻击者拿着照片或手机屏实时配合动作 旋转,也挡不住实时换脸 / 深度伪造。它把门槛从「举张照片」提高到「必须实时配合随机动作」,仅此而已。
- 相似度阈值默认
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。
双击项目根的 打包.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」是问不出答案的 —— 按文件名既找不到存在、也找不到不存在。 而所有单元测试跑的都是源码,源码全绿不代表发出去的包是对的。
打包.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 秒,动作不熟练会明显拖慢登录。
现象:注册、录入都正常,一登录就卡住 —— 浮层提示「没有检测到指定动作」, 反复重试也不通过,最后只能改走密码登录。
先别怀疑账号或数据。这类失败通常只有两个来源:
- 动作窗口期被吃掉 —— 指令和采样几乎同时开始,人还没看清 8 秒就过去了;
- 某个姿态轴在这台机器上推不动 —— 摄像头俯拍 / 仰拍,或脸型让该轴的代理值偏移不够。
按下面两层顺序改,先试第一层:它覆盖绝大多数情况,而且不损失安全性。 需要说明的是,这两层的代码改动都没有预先合进仓库 —— 仓库默认是「4 个动作 + 指令与采样连发」, 照下面的说明自己改。
先看清现状(对着代码核过):/api/liveness/start 只下发动作、不启动采样;
真正的 8 秒窗口(liveness.MAX_SECONDS)是从 /api/liveness/verify 到达后才开始算的。
问题出在页面上这两个请求是连着发的 —— 点完按钮,指令和采样几乎同时开始,
用户还得读一遍「把头转向你的左侧」、确认左右、再动头,窗口已经过去一半。
摄像头初始化慢、模型首次推理慢的机器,更容易直接超时。
改法是把「出指令」和「开始采样」拆成两次点击:
- 点「人脸登录」→ 立即
POST /api/liveness/start,把返回的action_text(如「把头转向你的左侧」)显示在页面上。此时不发 verify、不计时。 - 用户看清后自己点「开始」→ 这时才
POST /api/liveness/verify,8 秒窗口从这里起算。 - 失败后不要把用户踢回表单:保留指令、允许原地再点一次即可 (挑战失败不累计登录失败次数,这点已有保证)。
安全性:没有削弱。指令在用户点击之前就已确定,攻击者没法靠「边看边准备」占便宜。
可选加强:每 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(返回账号名、模板组数、创建时间、上次登录),但界面上没有入口,也没有任何权限分级; 要做需要先定义角色与权限矩阵,再决定这个接口该开放给谁。