简体中文
人脸前端
本文记录我在该项目中承担的 Web 前端开发工作。人脸特征提取与比对算法由他人负责,本文不作涉及。该项目的测试部分单独记录在人脸测试一文。
一、项目概况
项目是一套人脸识别业务的管理系统,面向前端使用者的能力分为六块:
- 人脸库。人员信息与人脸照片的录入、维护与查询。
- 分析服务。管理承载分析任务的服务器,以及服务器上的视频流与 FTP 分析任务。
- 数据管理。识别记录与告警记录的查询,数据保留策略与各项阈值的配置。
- 字典管理。部门、人员类型与告警类型的基础数据维护。
- 用户信息。当前登录人员的信息与密码维护。
- 操作记录。全站操作留痕查询。
与反无项目不同,该项目前端从零起步,没有既有骨架。路由、请求封装、状态管理与权限判断均需自行搭建。
二、我的职责与投入
我于 2026 年 3 月 26 日进项目,2026 年 8 月 29 日结束,负责 Web 前端。
具体负责范围包括:人脸库模块、分析服务模块、数据管理模块、字典管理、用户信息、操作记录,以及登录认证、路由守卫、请求层封装与工程化配置。AI 模型参数设置页面不在我的范围内。
仓库累计 311 次提交,其中我提交 99 次,剔除合并提交后为 92 次,共涉及 67 个文件。
三、技术栈
| 分类 | 选型 | 版本 |
|---|---|---|
| 框架 | Vue | 3.5.18 |
| 语言 | TypeScript | 5.8 |
| 构建 | Vite | 7.1.11 |
| UI 组件 | Element Plus | 2.11.8 |
| 路由 | vue-router | 4.5.1 |
| 状态管理 | Pinia | 3.0.3 |
| HTTP | axios | 1.12.0 |
| 加密 | jsencrypt、js-md5 | 3.5.4 / 0.8.3 |
| 其他 | exceljs、dayjs、lodash、codemirror | |
| 运行时 | Node(Volta 锁定) | 20.20.2 |
项目仅配置 dev、build、preview 三个脚本,未配置 lint 与 test,属于工程化欠账。
四、具体工作
4.1 人脸库
人脸库是本项目体量最大的模块,主表格文件一千九百余行,也是我改动次数最多的文件,共 23 次。
人员增删改查部分,新增采用 multipart 提交,data 字段承载 JSON,files 字段承载多张图片。删除统一走批量接口,单条删除同样提交只含一项的数组,使后端只需维护一套逻辑。
人脸录入支持两种方式:按人员 ID 录入,以及按文件名自动匹配。单人最多保存 9 张人脸,录入前需查询已有数量计算剩余额度,超出时按剩余量截断并提示。图片格式限定 JPG 与 PNG,单张不超过 1MB。
删除人脸图片时我确定了先上传后删除的顺序,即新图上传成功之后才移除旧图。反向操作一旦上传失败会导致该人员照片缺失。
批量上传人员信息弹窗包含三项设计:
- 模板由 ExcelJS 在浏览器端生成,表头固定五列,并预填三行示例数据。
- 上传时按表头名称模糊匹配定位列,不依赖列顺序,用户调整过列序仍可正常导入。
- 文件格式限定 xls、xlsx、csv,单文件不超过 10MB,错误最多展示 5 条并附总数。
模板示例数据部分值得单独说明。最初使用随机字符串填充,但该模板面向真实用户,示例值需要具备可信格式,否则用户会误解字段规范。最终采用 crypto.getRandomValues 生成随机数,身份证号按 GB 11643 校验位算法构造,权重表与校验码表均按标准实现,行政区划码取自真实区划表,出生日期限定在 1970 至 2005 年。
此外,按文件名匹配人脸的命名约定统一为姓名加证件号的形式,并写入人脸录入弹窗的操作说明。
4.2 分析服务
该模块采用左右布局,左侧为服务器列表,右侧为所选服务器下的任务列表。
服务器侧完成新增、编辑、删除与状态查询。新增与编辑复用同一弹窗,主机与端口只读自动填充,IP 按 IPv4 格式校验,端口限定 1 到 65535。编辑时密码留空表示不修改,因此提交前需将密码字段整体移除,避免被空值覆盖。服务器条目上展示主服务标记,对应接口的 isLeader 字段。
指标卡展示磁盘、显存、内存、CPU、GPU 使用率与最后心跳时间。
服务器详情采用 30 秒轮询刷新,处理了两个问题:
- 请求竞态。切换服务器时,上一个服务器的响应可能后到并覆盖当前数据。处理方式是引入递增的请求序号,响应返回时先比对序号,不一致则丢弃。
- 状态抖动。单次请求失败不代表服务离线,因此连续 3 次失败才判定为离线。
任务侧完成增删改查、批量删除、开始与停止分析。禁入时段支持按星期与时间区间配置,结束时间必须晚于开始时间,比较时按小时与分钟的字符串顺序处理。任务类型分为视频流与 FTP 文件服务,选择摄像头后自动拼接对应协议地址,预览使用 jessibuca 播放。
选中状态持久化是耗时较多的一项。需求是勾选的任务在翻页与切换服务器后仍然保留。最终实现分三层:表格开启行选择保留并指定行标识;数据加载后比对补选当前页之外的项;同时同步一份到状态管理,供跨页面与批量导出使用。其中补选逻辑是为修复选中行丢失的问题而增加。
批量导入导出方面,导出通过 blob 下载并带时间戳文件名;导入模板由后端下发,导入结果展示成功、重复、失败三个计数以及逐行失败原因。
批量停止分析需按任务数量动态放宽超时时间,否则任务数量较多时会被网关的 60 秒超时中断。
4.3 数据管理
该模块含三个页签:数据库存储、事件分析、摄像头告警设置。
数据库存储页签展示识别记录,我在原有列基础上新增两列。一是人脸分辨率,根据图片地址获取实际宽高。二是人脸质量,按质量分数划分为三档展示,并支持悬浮查看原始数值。该页签同时支持以图搜图查询。
数据保留策略属于强制约束,我在界面层与提交层各做一次校验。原因是输入组件的取值范围限制仅作用于界面,绕过组件直接修改表单对象即可失效。保留天数限定 1 到 180 天,最小剩余磁盘限定 1 到 6144 GB。下限设为 1 是因为取值 0 会导致记录被立即清理。
合并阈值弹窗提供合并开关、合并时间窗口以及确认匹配与疑似匹配两个相似度阈值。交互上采用编辑态切换,取消时重新拉取服务端配置以丢弃本地修改,拉取失败则保留上一次展示值。搜图阈值弹窗采用相同交互模式。
4.4 字典管理
该页面含三个页签:部门字典、人员类型字典、告警类型字典。
前两者为完整增删改查,其中部门名称需做唯一性校验,比较时去除空格并忽略大小写,编辑场景排除自身。告警类型为只读列表。
每次拉取字典数据后同步写入状态管理,使其他页面的下拉选项可直接复用,避免重复请求。
4.5 用户信息与操作记录
用户信息模块完成当前登录人员信息查询、信息修改与密码修改,操作列仅对当前管理员显示。头像固定使用组件库内置图标而非外链图片,原因是内网环境下外链资源无法加载。
操作记录为独立模块,字段包含操作模块、操作动作、操作描述、客户端 IP、执行结果、失败原因、耗时与创建时间。
4.6 登录与密码加密
项目存在两类密码,算法不同。
平台用户账号密码采用 MD5,输出 32 位小写十六进制。分析服务器的主机密码采用 RSA,实现上先请求公钥,并对公钥做缓存与并发去重,保证同一时刻只发起一次请求;加密模块通过动态导入引入,不进入主包体积。
登录流程为表单校验、密码处理、调用登录接口、写入令牌与用户信息,最后按重定向参数返回原页面。
4.7 路由守卫与异常兜底
全局前置守卫承担四项职责:设置页面标题、校验令牌有效期、未登录跳转登录页并携带重定向参数、管理员页面校验角色。
其中登录后回跳为补充实现。原逻辑缺失该能力,导致登录前访问受限页面后无法返回,补充了重定向参数传递。
此外增加了路由级异常处理,用于应对前端重新部署后的资源加载失败。场景为旧标签页持有的入口文件仍指向旧版本资源,点击未加载过的菜单时动态导入失败,且失败的模块被缓存,表现为悬浮正常但点击无响应。处理方式是捕获该类异常后强制整页跳转以拉取最新资源,并通过会话存储记录时间戳做 10 秒防抖,避免反复刷新。
4.8 工程化
开发代理方面,业务接口统一转发到后端服务;配置类接口通过自定义插件转发,目标地址由请求头动态决定,因为不同分析服务器的配置来自不同主机。
部署配置方面,反向代理的读写超时调整到 300 秒,以适配批量停止分析这类长耗时接口;请求体上限调整为 100MB,以支持批量导入 Excel。容器镜像仅包含静态资源与代理配置,构建在外部脚本中完成。
静态检查方面补充了 SonarQube 扫描配置。
文档方面使用代码统计工具对源码做了分语言、分层次、分模块的统计,并整理为项目说明,包含文件规模排名与各目录注释率。源码总量一万行出头,有效代码率约 79.7%。
五、关键问题与处理
5.1 无 mock 数据文件
项目不存在独立的模拟数据文件,唯一的模拟数据生成逻辑嵌在批量上传弹窗内,用于填充模板示例行。前期按目录名查找耗费了较多时间。
5.2 孤儿组件
开发过程中单独抽取过一个二次确认弹窗组件,完成后发现主表格实际使用的是组件库的确认框,该文件未被任何位置引用。
5.3 密码修改未接入后端
密码修改页面在文件头注释中声明依赖加密模块,但实现中并未引入加密逻辑与请求模块,仅做本地校验后直接提示成功,属于未完成功能。
5.4 服务器连接测试缺失
四月中旬曾实现服务器连接测试功能,但当前版本中已无相关按钮与接口,仅保留一处说明性注释。
5.5 工作区配置误读
项目中的 workspace 配置文件并非多包工作区定义,内容仅为依赖安装脚本的白名单,用于放行特定依赖的构建步骤。此外仓库同时存在两套锁文件,包名仍沿用脚手架默认值。
六、量化结果
| 指标 | 数值 |
|---|---|
| 仓库提交总数 | 311 |
| 本人提交数(含合并) | 99 |
| 本人提交数(不含合并) | 92 |
| 涉及文件数 | 67 |
按月份分布:3 月 6 次、4 月 34 次、5 月 24 次、6 月 20 次、7 月 8 次、8 月 7 次。4 月投入最集中,主要对应人脸库与分析服务的接口对接。
按提交类型分布:功能新增 36 次、缺陷修复 34 次、重构 5 次、样式调整 3 次、工程杂项 5 次、文档 3 次,其余 13 次为不规范提交信息。
按文件改动次数排名:人脸库主表格 23 次,数据管理表格 18 次,分析服务任务表格 18 次,用户信息表格 11 次,分析服务详情布局 11 次。
七、遗留问题
一是文档维护。项目说明中的统计信息与架构描述完成于开发中期,后续未持续更新。
二是工程规范。项目缺少 lint 与单元测试配置,静态检查也未纳入持续集成流程。
三是未完成功能。密码修改接口未接入,服务器连接测试功能当前版本缺失。
