通过蓝牙手环或串口设备采集生理信号,提取时序特征后由 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
窗口长度这个口径贯穿采集、注册与认证三处(详见 判定口径),
因此在图里 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一键启动。
需要 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.txtcd web_auth/frontend
npm install
npm run build # 产物输出到 ../static/dist/python web_auth/app.py # 默认 http://127.0.0.1:5000venv\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单元测试覆盖不到"进程真的起得来、页面真的走得通",这部分由 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,虚拟环境放在哪都能跑。
.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 拦不住 (已经推上去了),但对方无法绕过。区间扫描还补了全树扫描看不到的一块 —— 提交说明本身,以及内部文件有没有被混进提交。
部署后给探针、负载均衡与发布脚本用的端点,不在 /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=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 个窗口,一次前向,取均值 |
关于分数,有三点需要说明:
- 这是重构相似度,不是概率。 模型以注册样本为目标值、用
MSELoss回归到1.0训练,因此分数越接近 1.0 表示越像注册时的信号。它不保证落在 [0, 1], 也不代表「有 99% 的把握」—— 界面上不应按百分比解读。 - 阈值 0.8 的含义是「平均每个窗口偏离训练目标不超过 0.2」。阈值可在管理
后台的模型参数中调整(
model_threshold);调低会让更多信号通过一致性自检, 代价是自检对采集质量劣化也更宽容。它衡量的是与注册样本的接近程度, 适用范围见下节「适用边界」。 - 口径随模型一起存档。 每份个人模型的 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 月。 仓库保留了完整的开发提交历史,贡献者名单由提交作者自动统计。
仅用于学习与研究用途。