# eh-Face-Recognition

**Repository Path**: MISSMYSEIF/eh-face-recognition

## Basic Information

- **Project Name**: eh-Face-Recognition
- **Description**: 这是一个人脸识别项目，不仅能够通过摄像头实时采集视频中的人脸数据，还能对批量输入的图片进行自动化人脸识别。本系统可以实现对视频中的人脸进行跟踪，标注姓名、性别、情绪（开心、生气、自然）等信息，对进入视频的陌生人实施报警，可以通过对人眼状态的监测，对疲劳驾驶情况发出警报，还可以通过对深度神经网络的训练，进行活体检测。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-05-01
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EH Face Recognition - 人脸识别系统

> 基于 Spring Cloud 微服务 + Vue 3 的人脸识别系统，支持实时视频人脸采集与跟踪、批量图片识别、陌生人报警、疲劳驾驶检测及活体检测。采用 SaaS 多租户设计，默认使用 SQLite 数据库开箱即用。
>
> [English](./README.en.md) ｜ [文档中心](./docs/README.md)

---

## ✨ 核心功能

| 功能模块 | 描述 |
|---------|------|
| 实时视频采集 | 真实 RTSP 视频流接入（JavaCV 拉流）、WebSocket 二进制帧推送、多路并发、断连自动重连、摄像头 CRUD 管理 |
| 实时视频页面 | 后端 RTSP 帧实时渲染 + 人脸标注叠加；未配置 RTSP 时回退本地摄像头 |
| 人脸跟踪与标注 | 标注姓名/性别/情绪（开心/生气/自然）、疲劳标记（WebSocket 推送）；识别结果实时回传（相似度/命中状态），陌生人自动标红并展示比对数值 |
| 人脸白名单 | 白名单人员注册/管理（分组筛选、批量启停/删除），识别与白名单相似度比对并判定陌生人；注册照片质量检测（分辨率/亮度/模糊三维度拦截）；zip 批量导入支持分组列，进度按分组可视化汇总，失败明细含分组 |
| 真实模型推理 | 特征提取可插拔：本地确定性引擎（默认）或 gRPC 接入外部真实模型（ONNX/TensorRT），支持按灰度比例路由分流 |
| 陌生人报警 | 特征库比对、Redis 分布式去重、RabbitMQ 异步推送、处理/忽略留痕、SSE 实时推送（Redis pub/sub 多实例广播）+ 提示音提醒；报警指派处理人与截止时间，超时自动升级并全渠道通知（邮件/Webhook/钉钉/企微/短信），工单 Excel 导出（筛选与列表口径一致，含指派/截止/超时列），支持平均处理时长/超时未处理统计 |
| 疲劳驾驶检测 | PERCLOS 计算、眨眼频率监测、连续帧判定 |
| 活体检测 | 确定性规则引擎：肤色 + 图像细节置信度判定活体，标准/严格双阈值 |
| 批量图片识别 | 异步任务调度、MinIO 文件存储、SSE 实时进度（Redis pub/sub 多实例广播）、汇总报告生成 |
| 向量检索 | 白名单 1:N 比对走 Qdrant 向量数据库（HNSW 索引），不可用时自动降级 MySQL 内存索引扫描；10 万级白名单单次识别 P95=67ms |
| 用户与权限管理 | RBAC 角色权限控制（admin/user）、租户内用户 CRUD（创建/编辑/启停/重置密码/删除） |
| 安全加固 | 图形验证码、登录失败锁定、网关限流与熔断、密码强度策略、JWT 生产密钥 fail-fast、服务间内部签名认证 |
| 数据治理 | 审计/告警数据保留策略（定期批量物理清理，保留天数可配置）、审计日志与统计报表 Excel 导出 |
| 可视化仪表盘 | 聚合 KPI（白名单规模/今日报警/活跃会话/识别成功率）+ ECharts 报警趋势与类型分布图表 + 近 24 小时识别/报警链路趋势（小时级聚合：请求数/成功数/平均耗时/报警量） |
| 可观测性 | Prometheus 指标、Grafana 仪表盘与告警规则（provisioning 三件套：规则/联络点/通知策略）、Zipkin 链路追踪、审计日志 |
| 前端优化 | element-plus 按需引入（unplugin），大幅缩小打包体积、按页拆包 |
| 容器化部署 | Docker 多阶段构建 + Docker Compose 一键拉起全部微服务 |

## 🧩 技术栈

**前端**：Vue 3 + TypeScript + Vite + Element Plus + Pinia + WebSocket（二进制帧 + JSON 标注）

**后端**：Java 21 + Spring Boot 3.5 + Spring Cloud 2025 + Spring Cloud Alibaba 2025 + MyBatis-Plus 3.5 + JWT + gRPC（远程推理）

**基础设施**：Nacos（服务发现/配置）｜ Redis（缓存）｜ RabbitMQ（消息队列，含死信/重试）｜ MinIO（对象存储）｜ Qdrant（向量数据库，v1.12，HNSW 索引）｜ 多数据库（SQLite 默认 / MySQL / PostgreSQL + Flyway）｜ JavaCV/FFmpeg（RTSP 拉流）｜ Resilience4j（熔断）｜ Prometheus + Grafana + Zipkin（可观测性）

> 依赖版本已对照官方发布核对升级，避免使用存在安全问题的旧版本（详见 [部署文档](./docs/deployment/deployment.md)）。

## 📁 项目结构

```
eh-face-recognition/
├── eh-face-web/              # 前端 - Vue 3 + Element Plus
├── eh-face-common/           # 公共模块 - 统一响应/异常/租户/JWT/分页
├── eh-face-gateway/          # API 网关 - 路由/鉴权/租户注入/限流/熔断/WebSocket 代理
├── eh-face-auth/             # 认证服务 - 登录/JWT/userinfo/租户校验
├── eh-face-capture/          # 视频采集服务 - 摄像头/会话/RTSP 拉流/WebSocket 帧推送
├── eh-face-recognition/      # 识别服务 - 特征提取(local/gRPC)/比对/活体检测
├── eh-face-batch/            # 批量识别服务 - MinIO 上传/任务/报告
├── eh-face-alert/            # 报警服务 - 消息消费/去重/持久化
├── eh-face-admin/            # 管理服务 - 系统配置/模型/监控指标
├── sql/                      # MySQL/PostgreSQL 初始化脚本
├── docker/                   # 微服务容器化：Dockerfile 多阶段构建
├── docs/                     # 项目文档中心（架构/API/开发/部署/数据库/第三方教程）
├── tests/                    # Python 自动化测试（覆盖全模块，接入真实数据）
├── docker-compose.yml        # 基础设施 + 微服务编排（--profile app 拉起服务）
├── start.bat / stop.bat      # Windows 一键启动 / 一键暂停
├── LICENSE                   # MIT 开源协议
└── pom.xml                   # Maven 父工程（eh-face-parent）
```

## 🚀 快速开始

### 环境要求

| 软件 | 版本 |
|------|------|
| JDK | 21+ |
| Maven | 3.8+ |
| Node.js | 18+ |
| Docker | 20+（可选，用于一键拉起基础设施） |
| Python | 3.9+（可选，运行自动化测试） |

### 1. 一键启动（Windows）

```bat
start.bat
```

脚本会自动拉起基础设施（Docker Compose）、启动全部后端微服务与前端。

### 2. 手动启动

#### 2.1 后端启动教程（详细）

**Step 1：环境准备**

| 软件 | 版本 | 说明 |
|------|------|------|
| JDK | 21+（LTS） | 后端编译运行（Java 21 语法） |
| Maven | 3.8+ | 依赖管理与构建 |
| Docker | 20+ | 一键拉起基础设施（也可本机安装各中间件） |

确认环境：

```bash
java -version   # 应为 21+
mvn -v
docker --version
```

**Step 2：启动基础设施**

```bash
# 一键拉起 Nacos / Redis / RabbitMQ / MinIO（首次会自动拉取镜像）
docker compose up -d
# 等待 Nacos 就绪（约 30~60 秒，可在 Nacos 控制台 http://localhost:8848/nacos 确认）
```

> 不使用 Docker 时，需在本机分别安装并启动 Nacos / Redis / RabbitMQ / MinIO，端口与默认账号见[部署文档](./docs/deployment/deployment.md)。

**Step 3：编译后端**

```bash
# 在项目根目录执行，编译全部模块（跳过测试以加快首次编译）
mvn -DskipTests package
```

**Step 4：按顺序启动各微服务（建议使用 IDE 逐个启动，便于调试）**

```bash
# 网关（入口，必先启动）→ 认证 → 采集 → 识别 → 批量 → 报警 → 管理
mvn -pl eh-face-gateway spring-boot:run       # 8080 网关（路由/JWT鉴权/租户注入/限流/熔断/WebSocket）
mvn -pl eh-face-auth spring-boot:run          # 8081 认证（登录/验证码/密码策略）
mvn -pl eh-face-capture spring-boot:run       # 8082 采集（摄像头/会话/RTSP 拉流/WebSocket 帧推送）
mvn -pl eh-face-recognition spring-boot:run   # 8083 识别（特征提取 local/gRPC/白名单比对/活体）
mvn -pl eh-face-batch spring-boot:run         # 8084 批量（MinIO 上传/任务/报告）
mvn -pl eh-face-alert spring-boot:run         # 8085 报警（MQ 消费/去重/持久化/通知）
mvn -pl eh-face-admin spring-boot:run         # 8086 管理（系统配置/模型/指标/审计）
```

> 服务启动顺序：**网关必须最先启动**，其余服务无严格先后，但需在 Nacos 就绪后启动。
> 各服务通过 Nacos 自动注册与发现（默认 `localhost:8848`），无需手工配置地址。

**Step 5：验证后端**

```bash
# 网关健康检查（各服务同样暴露 /actuator/health）
curl http://localhost:8080/actuator/health
# 各服务已注册后可访问 Nacos 控制台 http://localhost:8848/nacos 查看服务列表
```

**常用配置（环境变量覆盖，均有本地默认值）**

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `JWT_SECRET` | 内置开发密钥 | 各服务 JWT 签名密钥，生产必须显式注入 |
| `EH_FACE_DB_PATH` | `eh_face.db` | SQLite 数据库文件路径 |
| `NACOS_SERVER_ADDR` | `localhost:8848` | 注册中心地址 |
| `REDIS_HOST/PORT` | `localhost/6379` | 缓存 |
| `RABBITMQ_HOST/PORT` | `localhost/5672` | 消息队列 |
| `MINIO_ENDPOINT/ACCESS_KEY/SECRET_KEY` | `localhost:9000/minioadmin` | 对象存储 |
| `INFERENCE_MODE` | `local` | 识别特征模式：`local` / `grpc`（远程真实模型） |
| `INTERNAL_API_KEY` | 空（兼容模式） | 服务间内部签名密钥，生产必须注入（各服务保持一致） |
| `EH_FACE_ENV` | 空 | 置为 `production` 触发生产安全守卫（弱配置启动失败） |

> 默认使用 **SQLite**（零依赖），服务启动时自动建表并初始化数据（默认账号 admin/admin123）。
> 切换 MySQL/PostgreSQL：`docker compose up -d mysql` 后以 `--spring.profiles.active=mysql` 启动。

#### 2.2 启动前端

```bash
cd eh-face-web
npm install
npm run dev    # 浏览器访问 http://localhost:5173（Vite 代理 /api 与 /ws 到网关 8080）
```

### 3. 默认账号

| 账号 | 密码 | 租户编码 | 角色 |
|------|------|----------|------|
| admin | admin123 | DEFAULT | 管理员 |

## 🧪 自动化测试

```bash
cd tests
pip install -r requirements.txt
python run_all_tests.py
```

测试通过 HTTP 调用真实服务与真实数据（默认 SQLite），覆盖网关、认证、采集、识别、批量、报警、管理全模块。详见 [测试说明](./tests/README.md)。

## 📚 文档中心

| 文档 | 路径 |
|------|------|
| 架构设计 | [docs/architecture/architecture.md](./docs/architecture/architecture.md) |
| API 文档 | [docs/api/api.md](./docs/api/api.md) |
| 开发指南 | [docs/development/dev-guide.md](./docs/development/dev-guide.md) |
| 部署文档 | [docs/deployment/deployment.md](./docs/deployment/deployment.md) |
| 数据库文档 | [docs/database/database.md](./docs/database/database.md) |
| 第三方对接教程 | [docs/integrations/third-party-integration.md](./docs/integrations/third-party-integration.md) |
| 变更日志 | [docs/CHANGELOG.md](./docs/CHANGELOG.md) |

## 🏗️ 系统架构

```
┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser    │────▶│  API Gateway     │────▶│  Microservices  │
│  (Vue 3)    │◀────│  (8080)          │◀────│  auth/capture/  │
│  WebSocket  │     │  - JWT Auth      │     │  recognition/   │
└─────────────┘     │  - Tenant Inject │     │  batch/alert/   │
                    │  - Router        │     │  admin          │
                    └──────────────────┘     └────────┬────────┘
                    ┌──────────────────┐              │
                    │  Infrastructure  │◀─────────────┘
                    │  Nacos/Redis/    │
                    │  RabbitMQ/MinIO  │
                    │  SQLite/MySQL/PG │
                    └──────────────────┘
```

## 🔒 安全与合规

- **MIT 开源协议**：见 [LICENSE](./LICENSE)。
- **密钥管理**：JWT 密钥、服务间签名密钥（INTERNAL_API_KEY）、数据库口令等通过环境变量注入，默认值仅限本地开发；`EH_FACE_ENV=production` 时启动守卫强制校验，弱配置直接启动失败。
- **多租户隔离**：MyBatis-Plus 租户插件 + 网关租户头注入，数据按 `tenant_id` 隔离。
- **版本安全**：依赖版本已升级至官方稳定且修复安全问题的版本。

## 🤝 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码（推送前更新 [CHANGELOG.md](./docs/CHANGELOG.md)）
4. 新建 Pull Request

> 非项目所需文件（IDE/AI/编译产物、本地进度文档）不会推送至远程仓库。