Skip to content

About

Passwordless login from your heartbeat — ECG/PPG biometric authentication with BiLSTM + Attention matching, built as a full-stack Flask + React web app.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

CardioCrypt

基于心电(ECG)/ 光电容积脉搏波(PPG)的无密码身份认证系统

CI 状态 版本 Python 3.9 Flask 3.1 PyTorch 2.8 React 19 Node 22 MongoDB 7

通过蓝牙手环或串口设备采集生理信号,提取时序特征后由 BiLSTM + Attention 模型推理:模型输出一个「与注册样本的重构相似度」分数,与阈值比较后给出判定。分数含义与窗口口径见 判定口径。

本项目为课程实践项目,用于研究与演示生物特征认证的完整链路。

功能概览 · 系统架构 · 技术栈 · 目录结构 · 快速开始 · 配置项 · 判定口径 · 适用边界 · 安全设计 · 贡献者


功能概览

模块 说明
🧬 身份注册 采集多次信号样本,训练专属个人模型
🔐 身份认证 实时采集并比对,输出判定结果与相似度分数(逐窗口评分后取均值)
📡 数据采集 支持 BLE 蓝牙 / 串口 两类设备,带设备扫描与连接向导
📊 用户仪表盘 心率、情绪、告警等级、设备状态与历史趋势
⚙️ 管理后台 注册用户管理、认证记录查看(只读、可筛选分页)、运行时参数(模型 / 验证 / 设备 / 训练)动态配置

系统架构

请求从设备进入、经采集与特征组装、交给模型推理、再由阈值判定落入存储,最后回到前端。 算法层是唯一可以整体缺席的一层:导入失败时 Web 服务照常启动,/healthz 会把这一项标红, 而不是让整个进程起不来。

flowchart TB
    DEV["BLE 手环 / 串口设备"]

    subgraph FE["前端 · React 19 SPA"]
        UI["页面 / 组件"]
        API["lib/api.ts · 请求层 + CSRF"]
    end

    subgraph WEB["Web 层 · Flask 应用工厂"]
        SPA["spa_adapter · GET 转 SPA / POST 走业务"]
        BP["blueprints · auth / device / dashboard / admin"]
        HK["healthcheck · /healthz"]
    end

    subgraph SVC["服务层 · 无状态函数"]
        COL["collection · 设备采集"]
        SIG["signals · 特征组装"]
        STA["stats · 真实统计"]
        HIS["history · 认证历史查询"]
    end

    subgraph ALG["算法层 · 导入失败时降级,服务仍可启动"]
        MDL["BiLSTM + Attention · 重构相似度"]
        LIB["ecgppg_system · 信号处理 / 设备 / 可视化"]
    end

    DB[("MongoDB")]

    UI --> API --> SPA --> BP
    DEV --> COL
    BP --> COL --> SIG --> MDL --> DEC{"阈值比较"}
    DEC --> DB
    BP --> STA --> DB
    BP --> HIS --> DB
    BP --> HK --> DB
    MDL -. 依赖 .-> LIB
Loading

窗口长度这个口径贯穿采集、注册与认证三处(详见 判定口径), 因此在图里 signals 同时被采集与认证两条路径共用,而不是各自算一套。

技术栈

层 技术选型
前端 React 19 · Vite 6 · TypeScript · Tailwind CSS v4 · Framer Motion · React Router 7
后端 Python 3.9 · Flask 3.1 · PyMongo 4.14
算法 PyTorch 2.8(BiLSTM + Attention)· NumPy 2.0 · SciPy 1.13 · PyWavelets · fastdtw · scikit-learn
存储 MongoDB 7

精确版本以 requirements.txt 与 web_auth/frontend/package.json 锁定为准,上表只标主版本。

目录结构

.
├── web_auth/                  # Web 应用
│   ├── __init__.py            # 应用工厂 create_app()(注册蓝图 / 适配层 / 全局钩子)
│   ├── app.py                 # 开发服务器入口(薄壳,只读 HOST / PORT / DEBUG)
│   ├── config.py              # 配置分层:环境变量读取 + 日志初始化
│   ├── extensions.py          # 扩展实例(PyMongo / 限流器 / CSRF),用于打断循环导入
│   ├── state.py               # 进程内可变状态 + 闲置回收
│   ├── core.py                # 算法层导入与降级、模型缓存、系统初始化、权限装饰器
│   ├── security.py            # 限流器与 CSRF 防护原语
│   ├── demo.py                # 演示模式(DEMO_MODE)的降级出口与合成信号生成
│   ├── blueprints/            # 路由分层
│   │   ├── auth.py            #   首页 / 注册 / 登录登出
│   │   ├── device.py          #   设备扫描连接 / 数据采集 / 认证执行
│   │   ├── dashboard.py       #   用户仪表盘与状态轮询
│   │   ├── admin.py           #   管理后台(用户 / 参数 / 认证记录)
│   │   └── healthcheck.py     #   /healthz 健康检查(供探针 / 负载均衡)
│   ├── services/              # 无状态业务函数
│   │   ├── signals.py         #   信号指标提取与特征组装
│   │   ├── collection.py      #   BLE / 串口数据采集(验证与注册共用)
│   │   ├── health.py          #   心率 / 情绪 / 告警等级计算
│   │   ├── healthcheck.py     #   服务自身健康检查(数据库 / 算法层)
│   │   ├── history.py         #   认证历史只读查询(分页 + 筛选)
│   │   └── stats.py           #   真实统计聚合(认证次数 / 运行时长等)
│   ├── spa_adapter.py         # React SPA 适配层(GET→SPA,POST→原逻辑)
│   ├── frontend/              # React 前端源码
│   │   └── src/
│   │       ├── pages/         # 页面
│   │       ├── components/    # 组件
│   │       └── lib/           # API 客户端与工具
│   ├── static/                # 静态资源(含前端构建产物 dist/)
│   └── templates/             # 旧版 Jinja2 模板(classic 模式保留)
├── ecgppg_system/             # 信号处理 / 设备 / 模型 / 可视化 核心库
├── model_example/             # 模型封装模块(训练、评估、推理)
├── tests/                     # pytest 回归集
├── pytest.ini
└── requirements.txt

后端已从单文件拆分为「工厂 + 分层模块 + 5 个蓝图」:原 app.py 由 3000 余行收缩到 不足 60 行的入口壳,路由按职责分散到 blueprints/,配置、扩展实例、进程内状态与 算法层适配各自独立成模块。改配置或加路由不必再在一个巨文件里翻找。

快速开始

更详细的启动步骤、页面导览、使用场景与常见问题排查,见 使用指南.md。也可直接双击根目录的 start.bat 一键启动。

1. 环境准备

需要 Python 3.9.x。依赖清单已锁定到该版本可安装的精确版本,并按用途分组; 标 sys_platform == "win32" 的 winrt-* 系列是 Windows 上 BLE 的后端,其他平台会自动跳过。

python -m venv venv
venv\Scripts\activate          # Windows
pip install -r requirements.txt

需要本地运行 MongoDB(默认 mongodb://localhost:27017)。

如果要运行测试,改装 requirements-dev.txt —— 它通过 -r 引入运行时依赖,并额外提供 pytest:

pip install -r requirements-dev.txt

2. 构建前端

cd web_auth/frontend
npm install
npm run build                  # 产物输出到 ../static/dist/

3. 启动服务

python web_auth/app.py         # 默认 http://127.0.0.1:5000

4. 运行测试

venv\Scripts\python.exe -m pytest

测试通过环境变量把 MONGO_URI 指向独立临时库 ecg_auth_db_pytest (在 tests/conftest.py 顶部注入,必须早于 import web_auth),不会读写开发库 ecg_auth_db。运行前请确保本地 MongoDB 可用。

文件 覆盖范围
tests/test_security.py 限流器边界与窗口滑动、CSRF 令牌的生成 / 轮换 / 会话绑定
tests/test_auth_flow.py 登录 / 注册 / 登出流程、反用户枚举、会话固定防护、判定结论完整性
tests/test_authentication.py 信号相似度的性质型断言,并固定两处已知缺陷
tests/test_model_authentication.py 认证实现的判定契约:EER 不随阈值变化、推理失败与判定不通过可区分、融合结果内部自洽
tests/test_admin_api.py 管理接口的权限边界、口令长度与限流、响应字段脱敏
tests/test_spa.py SPA 适配层的会话投影、令牌下发、未知路径仍返回真 404
tests/test_demo_mode.py 演示模式:默认关闭时采集不到数据必须判失败,开启后结果带 demo 标记且判定规则不变
tests/test_dashboard.py 仪表盘真实统计与示意字段标注、字段名与消费者一致
tests/test_auth_history.py 认证历史的写入闭环、终态归并、演示标记、轮询不重复、写库失败不影响结论
tests/test_model_io.py 模型存档读写、按存档重建结构、模板窗口与 metadata 契约
tests/test_refactor_contracts.py 分层重构后各模块的行为契约(默认配置隔离、状态回收、删除流程一致性等)
tests/test_signal_morphology.py 形态参数派生稳定性、默认波形逐点等价、跨主体相异
tests/test_deployment_guard.py 部署形态护栏:默认口令 + 对外监听必须拒绝启动,回环地址与显式口令下不受影响
tests/test_healthz.py /healthz 的契约:免登录可访问、依赖异常转 503、响应不泄漏部署细节、只读、不缓存
tests/test_admin_history.py 认证历史查看页:登录保护、筛选与「当天」边界、分页夹取、查询失败不画成空表、只读

前端另有基于 Vitest 的单元测试,覆盖请求层 src/lib/api.ts 的行为契约 —— 4xx/5xx 带 JSON 体不能当作成功、读超时、CSRF 令牌获取与 403 重试、数组表单编码:

cd web_auth/frontend
npm test

5. 端到端验证

单元测试覆盖不到"进程真的起得来、页面真的走得通",这部分由 scripts/verify/ 下的脚本承担。它们各自在独立临时库上运行、结束时 drop,日志与结构化结果写到 系统临时目录下的 cardiocrypt-verify/,不污染仓库。

python scripts/verify/run_all.py              # 全部(含启停服务)
python scripts/verify/run_all.py --quick      # 只跑不需要起服务的部分
python scripts/verify/run_all.py --only demo_mode_e2e.py
脚本 覆盖范围
healthz_e2e.py 健康检查全链路:正常实例 200 / JSON 未被 SPA 兜底、降级实例 503 且快速失败、响应体不泄漏
p2_perf_equivalence.py 算法层收尾优化的等价性对照:分位数、比较结果复用、相关系数矩阵、绘图路径
demo_mode_e2e.py 演示模式全链路:默认关闭时判失败、开启后带标记且判定规则不变
batch2_e2e.py 仪表盘真实/示意字段标注、请求层超时与 res.ok 判定、字段名一致性
c_tier_regression.py 启动路径与 SPA / classic 双渲染模式回归
run_p0_with_service.py 认证链路端到端:自行拉起全新 classic 服务后验证并回收
desensitize_scan.py 公开产物脱敏扫描(tree / worktree / commits / selftest 四种模式)

前置条件只有一项:MongoDB 可达(默认 mongodb://localhost:27017,可用 VERIFY_MONGO_BASE 覆盖)。脚本一律用 sys.executable,虚拟环境放在哪都能跑。

6. 持续集成

.github/workflows/ci.yml 在每次推送与 PR 上跑三组作业:

作业 内容
后端 pytest(MongoDB service)、pyflakes、脱敏扫描器自检、全树扫描与推送区间扫描、忽略规则护栏
前端 npm ci、tsc --noEmit、vitest run、vite build,并校验构建产物与仓库内容一致
端到端 scripts/verify/run_all.py,失败时回显各脚本日志

运行器镜像显式钉在 ubuntu-24.04,不用 ubuntu-latest:后者已迁到 Ubuntu 26.04, 而 actions/python-versions 没有为 26.04 提供 CPython 3.9 的预编译包(3.9 只到 24.04), setup-python 会在拉解释器这一步直接失败。等本项目不再需要 3.9 时再解除钉定。

其中两条是本项目踩过的坑,现在由流水线而不是口头约定兜住:

  • 产物一致性:web_auth/static/dist/ 必须入库,且必须与 web_auth/frontend/src 的当前内容同源。改了前端源码忘记 build,CI 会直接失败并提示重建。
  • 忽略规则护栏:.gitignore 的误伤是双向的,两个方向都由流水线拦住 —— 一是「已跟踪却仍被忽略命中」(通常是目录规则缺少根目录锚定,如 models/ 命中 ecgppg_system/models/);二是「源码 / 测试文件被忽略规则吞掉」(*.test.* 就曾把前端的 *.test.ts 一并吃掉)。两者都不报错,文件只是"在磁盘上但 git 看不见"。

推送前检查(本地钩子)

CI 跑在推送之后,发现问题时内容已经公开了。所以脱敏扫描还有一道前置闸: scripts/git-hooks/pre-push 会在 git push 真正发出前扫一遍即将推送的区间 (包含提交说明),扫出严格项就直接拦下。钩子随代码入库,换台机器启用一次即可:

git config core.hooksPath scripts/git-hooks

它只在真的扫出问题时阻断推送。解释器找不到、远端基准不在本地这类环境问题一律放行 并打印警告 —— 把干净的推送流程卡死,比漏扫一次更糟,而且会让人养成随手加 --no-verify 的习惯,最后连真问题一起绕过。确认是误判时仍可 git push --no-verify, 那就只剩 CI 一道检查。

两道闸分工不同,缺一不可:本地钩子能拦住,但只在装了钩子的机器上生效;CI 拦不住 (已经推上去了),但对方无法绕过。区间扫描还补了全树扫描看不到的一块 —— 提交说明本身,以及内部文件有没有被混进提交。

7. 健康检查

部署后给探针、负载均衡与发布脚本用的端点,不在 /api/ 下,也不需要登录:

curl -s http://127.0.0.1:5000/healthz
{
  "status": "ok",
  "uptime_seconds": 1234,
  "demo_mode": false,
  "frontend_mode": "spa",
  "checks": {
    "database": {"ok": true, "latency_ms": 1.2},
    "algorithm_layer": {"ok": true}
  }
}
状态码 含义
200 依赖都正常(status: ok)
503 有依赖异常(status: degraded),checks 里指明是哪一项、失败原因是什么

四项刻意取舍:

  • 没有鉴权,因此响应体必须干净:不含连接串、库名、文件路径、模型名; 出错时只回异常类型名 —— PyMongo 的异常文本带 host:port,属于部署细节。
  • 只读:不写库、不加载模型、不建会话,探针可以放心高频调用。
  • Cache-Control: no-store:避免中间层把"已经挂了"缓存成"还是好的"。
  • 最坏耗时等于 MONGO_SERVER_SELECTION_TIMEOUT_MS(默认 5 秒):探针自身的 超时要大于这个值,否则数据库故障会被误读成"探针超时"而不是"依赖不可用"。

algorithm_layer 之所以也是检查项:算法模块导入失败时服务仍会启动(这是刻意的 降级设计,见 web_auth/core.py),但注册与认证必然失败。少了这一项,就会出现 "进程活着、监控全绿、业务全红"。

配置项(环境变量)

变量 默认值 说明
MONGO_URI mongodb://localhost:27017/ecg_auth_db MongoDB 连接串
ADMIN_USERNAME admin 管理后台账号
ADMIN_PASSWORD admin123 管理后台口令 —— 部署前必须修改。未设置且监听地址不是回环地址时,服务会拒绝启动(见下方安全提示)
FLASK_SECRET_KEY 自动生成并持久化到 web_auth/.flask_secret_key 会话签名密钥。未设置时自动生成一份本地密钥文件,使同一部署内的多个进程共享同一密钥
FLASK_DEBUG 0 设为 1 开启调试模式。会暴露可执行任意代码的调试器,仅限本机临时使用
FLASK_HOST 127.0.0.1 监听地址。默认只允许本机访问;改为 0.0.0.0 需自行确认网络环境可信
FLASK_PORT 5000 监听端口
FRONTEND_MODE spa spa 使用 React 前端;classic 回退 Jinja2 模板
LOG_LEVEL INFO 日志级别。DEBUG 会连带打印请求体等敏感内容,仅限本机排障临时开启
LOG_FILE 空(只输出到控制台) 设置后额外写入日志文件并自动轮转(5MB × 3)。相对路径按 web_auth/logs/ 解析
MAX_CONTENT_LENGTH 16777216(16MB) 请求体大小上限
MONGO_SERVER_SELECTION_TIMEOUT_MS 5000 数据库选择超时。MONGO_URI 中已指定时以 URI 为准
CSRF_ENABLED 1 写操作的 CSRF 校验开关。默认开启,不建议关闭
DEMO_MODE 0 演示模式。开启后,采集不到真实设备信号时改用合成数据把流程走完,并在日志、接口与界面上逐处标注。详见下节
STATE_TTL_SECONDS 3600 内存中注册 / 验证状态的闲置回收时长(秒)
STATE_CLEANUP_INTERVAL 300 闲置状态的扫描间隔(秒)
MAX_CACHED_MODELS 50 内存中缓存的用户模型上限

管理后台入口:/manage/login

⚠️ 安全提示:默认管理员口令仅用于本地开发。请通过环境变量覆盖后再部署。

这条约束由代码强制,不靠自觉:应用工厂在组装的第一步校验「监听地址 + 管理员口令」 组合,FLASK_HOST 指向非回环地址而 ADMIN_PASSWORD 仍为默认值时直接抛错拒绝启动, 覆盖本地开发服务器与 web_auth:create_app() 两条入口。仅本机试用时保持 FLASK_HOST=127.0.0.1 即可,不受影响。

调试模式默认关闭:app.run() 只是本地开发入口。调试模式一旦开启,Werkzeug 会暴露 可执行任意代码的交互式调试器,并显示完整堆栈与配置(含数据库连接串)。 生产环境请改用 WSGI 服务器,并保持 FLASK_DEBUG=0:

gunicorn -w 1 --threads 8 -b 127.0.0.1:5000 'web_auth:create_app()'

其余 WSGI 服务器同理,加载目标为应用工厂 web_auth:create_app()(web_auth.app:app 作为开发入口也仍然可用)。

说明:本项目使用进程内的设备连接状态与模型缓存,因此建议单进程多线程(-w 1 --threads N)。 会话密钥未显式配置时会自动生成并持久化到 web_auth/.flask_secret_key,同一部署内的多个进程 因此共享同一密钥、不会出现登录状态随机失效;生产环境仍建议显式配置 FLASK_SECRET_KEY。

CSRF 防护默认开启:所有写操作(POST/PUT/PATCH/DELETE)都必须携带与会话绑定的令牌。 页面由后端渲染时令牌会自动注入(隐藏字段 + meta 标签 + ajax 全局请求头)。 若自行编写脚本调用写接口,需先 GET /api/csrf-token 取令牌,再以 X-CSRFToken 请求头(或表单字段 csrf_token)提交;GET 等安全方法不受影响。

数据库索引(含 username 唯一索引)在进程启动时自动创建,与使用开发服务器还是 WSGI 服务器无关。 若启动日志出现「系统初始化未完成」,说明当时数据库不可达、索引未建立 —— 请确认 MongoDB 可访问后重启。

内存中的注册 / 验证状态会按 STATE_TTL_SECONDS 自动回收闲置条目; 前端轮询状态接口时会刷新活跃时间,因此进行中的流程不会被误清。

演示模式(DEMO_MODE)

采集依赖真实硬件:注册与验证都要求先扫描到设备、再采到信号。没有硬件时这两条 流程走不完 —— 而这恰恰是功能演示最常见的场景。

DEMO_MODE=1 提供一条显式的演示通路:采集不到真实数据时,改用合成信号把 流程走完。默认关闭,且开启后不能放宽任何判定。

DEMO_MODE=1 venv\Scripts\python.exe web_auth\app.py

它改的是数据从哪来,不是判定怎么下:

  • 合成信号照常送入模型比对,照样可能不通过 —— 它不会把「不通过」改写成「通过」;
  • 用户模型不会被伪造。算法层不可用时注册直接中止,既不写占位模型文件,也不写入用户;
  • 每一次降级都留痕:日志以 [DEMO] 前缀记 WARNING,验证与注册的接口返回 demo: true 及降级原因,SPA 与 classic 界面都会显示醒目的提示条。

开启后,设备扫描步骤会多出一个「演示模式:跳过设备,使用合成数据」入口。 用它跑出来的任何结果都不代表真实生物特征比对,请勿用于验收或模型评估。

判定口径

注册训练与身份认证必须使用同一个窗口长度,否则同一条信号会落在完全不同的 分数区间。这个长度定义在 web_auth/services/signals.py::MODEL_WINDOW_LENGTH, 训练、注册自检与身份认证三处共用同一个常量。

环节 输入形状 说明
注册训练 [N, 10, 1] 每个训练样本含 10 个采样点
注册自检 每次自检一个窗口 自检 N 次,得到 N 个窗口分数
身份认证 对齐到 600 点 → [60, 10, 1] 切成 60 个窗口,一次前向,取均值

关于分数,有三点需要说明:

  1. 这是重构相似度,不是概率。 模型以注册样本为目标值、用 MSELoss 回归到 1.0 训练,因此分数越接近 1.0 表示越像注册时的信号。它不保证落在 [0, 1], 也不代表「有 99% 的把握」—— 界面上不应按百分比解读。
  2. 阈值 0.8 的含义是「平均每个窗口偏离训练目标不超过 0.2」。阈值可在管理 后台的模型参数中调整(model_threshold);调低会让更多信号通过一致性自检, 代价是自检对采集质量劣化也更宽容。它衡量的是与注册样本的接近程度, 适用范围见下节「适用边界」。
  3. 口径随模型一起存档。 每份个人模型的 metadata 记录 scoring (window_length / aggregation / semantics / target_value), 换口径后仍可追溯某个历史分数是按什么标准算出来的。

输入长度与训练窗口不一致时(例如把整段 600 点一次性送入),模型照样会给出 一个数,但分数会系统性偏离训练目标,阈值也就失去了参照。LSTM 接受任意序列 长度,这类输入不会报错 —— 口径一致只能靠约定保证,不能靠模型结构兜底。

适用边界

当前口径回答的是「这段信号像不像本人登记时的那段」:模型以注册样本为训练 目标,输出重构相似度,用于验证同一用户前后采集的一致性,以及采集质量是否明显 劣化(欠拟合或噪声过大时注册自检不通过)。

当前覆盖 不在当前覆盖范围内
同一主体重复采集与注册样本的一致性 不同主体之间的区分
采集 / 训练质量下降时的自检拦截 真实场景的误受率(FAR)与误拒率(FRR)

边界来自数据表示:注册与验证统一为 10Hz 采样、10 点/窗,一个窗口里 QRS 复合波 最多占 1 个采样点,主体间的形态差异在这套表示上被抹平。因此阈值 0.8 是 一致性自检的容差,不应解读为「能挡住他人」;要评估区分能力,前提是取得 多人、多次、含同人不同状态的真实采集数据。

后续演进(课程实践范围外):一次性可行性探针已验证,采样率提高到 100Hz、 以 R 峰做相位对齐并降噪后,形态参数能够进入表示 —— 模板比对在该条件下由不可分 变为完全可分(Pearson AUC 0.54 → 1.00),r_amp 敏感度由 0 变为 0.0677。 要把它落到生产链路,需要同步升级窗口口径与判定通路,并重新标定阈值;现有仅用 正样本回归到 1.0 的模型通路无法直接承接新的表示。以上均为合成信号上的可行性 结论,不代表真实 FAR/FRR。

安全设计

下表列出各项防护的设计意图与已知边界。写清楚边界和写清楚措施同样重要 —— 一个「看起来有防护、实际在多进程下打折」的限流器,比没有限流器更容易让人误判。

措施 设计意图 已知边界 / 代价
认证前清空会话 防会话固定攻击:攻击者预先植入的会话 ID 在认证成功后失效 清空前会保留 CSRF 令牌(clear_session_keep_csrf),否则紧随其后的表单提交必然失败
CSRF 双层令牌 令牌与会话绑定,覆盖 JSON 请求头(SPA)与隐藏表单字段(原生页面)两条通路 令牌与会话共存亡;脚本调用写接口前必须先 GET /api/csrf-token
登录频率限制 同一 IP 每分钟 10 次;管理登录使用独立配额,避免两者互相挤占 进程内滑动窗口。多 worker 部署时各自计数,等效配额为 N × 10;只有单进程多线程下语义才完全成立
统一失败措辞 不区分「用户不存在」与「口令错误」,消除用户名枚举 用户拿不到具体原因,排障需查服务端日志
判定结论唯一来源 判定只由算法输出决定,不提供任何可以覆盖结果的请求参数 副作用是无真实硬件时注册 / 认证流程走不通,必须接入设备才能完整演示
上传体积上限 MAX_CONTENT_LENGTH 默认 16MB,避免超长请求体拖垮进程 超限直接返回 413,长信号需自行分段
错误信息不泄漏路径 管理接口只返回模型文件名,不下发本机绝对路径 该字段仍被两个管理页渲染,改名会连带影响前端与模板
密钥可持久化 未显式配置时自动生成并写入 web_auth/.flask_secret_key,使同机多进程共享密钥 生产环境仍应显式配置 FLASK_SECRET_KEY;密钥文件在文件系统不可写时退回进程内随机值并打印告警
健康检查免鉴权 探针拿不到会话,/healthz 不做登录校验;作为交换,响应体不含连接串、库名、路径与模型名,失败只回异常类型名 端点本身可被任意来源访问,等于对外公开「服务是否可用」这一事实;需要隐藏可用性时应在反向代理层限制来源

部署形态约束:设备连接状态、验证结果与模型缓存都是进程内状态, 因此必须单进程多线程运行(-w 1 --threads N)。多进程会让请求落到互不相见的副本上 —— 限流计数、设备状态、进行中的采集流程各算各的。

后续规划:把设备会话、验证结果与模型缓存挪到进程外(Redis 或独立设备服务), 是支持多用户并发的真正前提;本项目按课程实践范围暂不实施。

说明

  • 版本与变更记录:当前版本 2.0.0,按时间顺序的变更见 CHANGELOG.md。
  • 模型权重不入库:*.pth 已加入 .gitignore。个人模型在用户完成注册采集后由训练流程生成,可用仓库内训练脚本复现。
  • 前端适配层:spa_adapter.py 采用「包装既有视图函数」的方式,使 GET 请求返回 SPA、POST 请求保持原有表单语义,后端业务逻辑无需改动。设置 FRONTEND_MODE=classic 可随时切回 Jinja2 页面。
  • 一份已废弃的认证实现:ecgppg_system/utils/authentication.py 是早期原型的认证实现,已被 model_example/authentication.py 取代,当前没有任何调用方。已在模块头标注废弃并保留实现 —— 保留是为了不抹去原始贡献者的代码与提交历史;该模块存在若干已知限制,详见其 docstring。
  • 算法层可降级:ecgppg_system / model_example 导入失败时,Web 应用仍能启动并给出明确报错,而不是让 import 直接炸掉整个进程,便于单独调试 Web 层。

贡献者

贡献者 主要贡献
@Zzthird 项目原始原型:设备接入(BLE 蓝牙 / 串口)、信号采集与预处理流水线、BiLSTM + Attention 模型训练与认证比对逻辑、MongoDB 存储层
@Durian2005 前端重构、安全加固与工程整理:React SPA 全站重建与 Flask 适配层;CSRF 防护与登录限流、会话与密钥管理、数据库索引随进程启动初始化;应用工厂与蓝图分层重构、pytest 回归集(253 例);依赖清单治理、演示模式开关、项目脱敏、文档与发布维护

原始原型完成于 2025 年 8 月;前端重构、安全加固与工程整理完成于 2026 年 9 月。 仓库保留了完整的开发提交历史,贡献者名单由提交作者自动统计。

许可

仅用于学习与研究用途。

About

Passwordless login from your heartbeat — ECG/PPG biometric authentication with BiLSTM + Attention matching, built as a full-stack Flask + React web app.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages