跳到正文

发布于 2026年11月2日

人脸前端 ​

本文记录我在该项目中承担的 Web 前端开发工作。人脸特征提取与比对算法由他人负责,本文不作涉及。该项目的测试部分单独记录在人脸测试一文。

一、项目概况 ​

项目是一套人脸识别业务的管理系统,面向前端使用者的能力分为六块:

  1. 人脸库。人员信息与人脸照片的录入、维护与查询。
  2. 分析服务。管理承载分析任务的服务器,以及服务器上的视频流与 FTP 分析任务。
  3. 数据管理。识别记录与告警记录的查询,数据保留策略与各项阈值的配置。
  4. 字典管理。部门、人员类型与告警类型的基础数据维护。
  5. 用户信息。当前登录人员的信息与密码维护。
  6. 操作记录。全站操作留痕查询。

与反无项目不同,该项目前端从零起步,没有既有骨架。路由、请求封装、状态管理与权限判断均需自行搭建。

二、我的职责与投入 ​

我于 2026 年 3 月 26 日进项目,2026 年 8 月 29 日结束,负责 Web 前端。

具体负责范围包括:人脸库模块、分析服务模块、数据管理模块、字典管理、用户信息、操作记录,以及登录认证、路由守卫、请求层封装与工程化配置。AI 模型参数设置页面不在我的范围内。

仓库累计 311 次提交,其中我提交 99 次,剔除合并提交后为 92 次,共涉及 67 个文件。

三、技术栈 ​

分类选型版本
框架Vue3.5.18
语言TypeScript5.8
构建Vite7.1.11
UI 组件Element Plus2.11.8
路由vue-router4.5.1
状态管理Pinia3.0.3
HTTPaxios1.12.0
加密jsencrypt、js-md53.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。

删除人脸图片时我确定了先上传后删除的顺序,即新图上传成功之后才移除旧图。反向操作一旦上传失败会导致该人员照片缺失。

批量上传人员信息弹窗包含三项设计:

  1. 模板由 ExcelJS 在浏览器端生成,表头固定五列,并预填三行示例数据。
  2. 上传时按表头名称模糊匹配定位列,不依赖列顺序,用户调整过列序仍可正常导入。
  3. 文件格式限定 xls、xlsx、csv,单文件不超过 10MB,错误最多展示 5 条并附总数。

模板示例数据部分值得单独说明。最初使用随机字符串填充,但该模板面向真实用户,示例值需要具备可信格式,否则用户会误解字段规范。最终采用 crypto.getRandomValues 生成随机数,身份证号按 GB 11643 校验位算法构造,权重表与校验码表均按标准实现,行政区划码取自真实区划表,出生日期限定在 1970 至 2005 年。

此外,按文件名匹配人脸的命名约定统一为姓名加证件号的形式,并写入人脸录入弹窗的操作说明。

4.2 分析服务 ​

该模块采用左右布局,左侧为服务器列表,右侧为所选服务器下的任务列表。

服务器侧完成新增、编辑、删除与状态查询。新增与编辑复用同一弹窗,主机与端口只读自动填充,IP 按 IPv4 格式校验,端口限定 1 到 65535。编辑时密码留空表示不修改,因此提交前需将密码字段整体移除,避免被空值覆盖。服务器条目上展示主服务标记,对应接口的 isLeader 字段。

指标卡展示磁盘、显存、内存、CPU、GPU 使用率与最后心跳时间。

服务器详情采用 30 秒轮询刷新,处理了两个问题:

  1. 请求竞态。切换服务器时,上一个服务器的响应可能后到并覆盖当前数据。处理方式是引入递增的请求序号,响应返回时先比对序号,不一致则丢弃。
  2. 状态抖动。单次请求失败不代表服务离线,因此连续 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 与单元测试配置,静态检查也未纳入持续集成流程。

三是未完成功能。密码修改接口未接入,服务器连接测试功能当前版本缺失。