# face-recognition-system **Repository Path**: hu0670/face-recognition-system ## Basic Information - **Project Name**: face-recognition-system - **Description**: AI-Face-Hub: 全栈人脸识别与向量检索系统本项目是一个基于 深度学习特征提取 与 向量数据库检索 实现的端到端人脸识别解决方案。 - **Primary Language**: Java - **License**: Artistic-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-20 - **Last Updated**: 2026-03-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 人脸识别系统 (Face Recognition System) 基于领域驱动设计（DDD）架构的智能人脸识别系统，采用微服务架构，实现人脸注册、识别、考勤等核心功能。 [![Java](https://img.shields.io/badge/Java-17-orange)](https://openjdk.org/) [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.11-brightgreen)](https://spring.io/projects/spring-boot) [![Vue](https://img.shields.io/badge/Vue-3.5-42b883)](https://vuejs.org/) [![Python](https://img.shields.io/badge/Python-3.9+-blue)](https://www.python.org/) [![Elasticsearch](https://img.shields.io/badge/Elasticsearch-8.17.1-003F9C)](https://www.elastic.co/) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ## 📋 目录 - [项目简介](#项目简介) - [系统架构](#系统架构) - [技术栈](#技术栈) - [核心特性](#核心特性) - [模块说明](#模块说明) - [快速开始](#快速开始) - [API 文档](#api-文档) - [部署指南](#部署指南) - [开发指南](#开发指南) - [常见问题](#常见问题) --- ## 项目简介 本系统是一个完整的人脸识别解决方案，支持： - 🎯 **人脸注册**：上传人脸图片，提取 512 维特征向量并存储 - 🔍 **人脸识别**：实时抓拍人脸，通过 kNN 算法快速匹配用户 - 📊 **考勤管理**：基于人脸识别的考勤记录 - 🌐 **Web 界面**：现代化的 Vue 3 前端界面 --- ## 系统架构 ### 整体架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Vue 3 前端 │ │ 移动端 App │ │ 第三方系统 │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ └─────────┼──────────────────┼──────────────────┼────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Spring Boot 后端 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ face-ui │ │ │ │ │ │ │ │ (REST API) │→ │ FaceController│ │ UserController│ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ ┌──────▼──────────────────▼──────────────────▼───────┐ │ │ │ face-application (应用层) │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ FaceRegistration │ │ FaceRecognition │ │ │ │ │ │ Service │ │ Service │ │ │ │ └─────────────────────┘ └───────────────────┘ │ │ │ └──────────────────────────┬─────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────┐ │ │ │ face-infrastructure (基础设施层) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │ │ │ │ │ UserRepository│ │AiEngineClient│ │PostgreSQL │ │ │ │ │ │ Impl │ │ │ │ Client │ │ │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬────┘ │ │ │ │ │ │ │ │ │ │ └─────────┼──────────────────┼──────────────────┼──────┘ │ │ │ │ │ │ └────────────┼──────────────────┼──────────────────┼─────────┘ │ │ │ ▼ ▼ ▼ ┌────────────────────────────────────────────────────────────┐ │ 外部依赖服务 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ PostgreSQL │ │Elasticsearch │ │ FastAPI │ │ │ │ (17.5) │ │ (8.17.1) │ │ AI Engine │ │ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ │ │ │ │ 512 维向量索引 │ └────────────────────────────┴────────────────────────────────┘ ``` ### DDD 分层架构 ``` ┌─────────────────────────────────────────────────────────┐ │ face-ui (展示层) │ │ • REST Controllers │ │ • 请求/响应 DTO │ │ • 配置文件 (application.yml) │ └────────────────┬────────────────────────────────────────┘ │ runtimeOnly ┌────────────────▼────────────────────────────────────────┐ │ face-application (应用层) │ │ • 应用服务 (Application Services) │ │ • 用例编排 (Use Case Orchestration) │ │ • 依赖 face-domain │ └────────────────┬────────────────────────────────────────┘ │ implementation ┌────────────────▼────────────────────────────────────────┐ │ face-infrastructure (基础设施层) │ │ • 仓储实现 (Repository Implementations) │ │ • 外部服务客户端 (AiEngineClient) │ │ • 持久化 (PostgreSQL, Elasticsearch) │ │ • 依赖 face-domain │ └────────────────┬────────────────────────────────────────┘ │ ┌────────────────▼────────────────────────────────────────┐ │ face-domain (领域层) │ │ • 聚合根 (User, RecognitionLog) │ │ • 值对象 (FeatureVector) │ │ • 仓储接口 (UserRepository, FaceSearchRepository) │ │ • 领域服务接口 (FeatureExtractor) │ │ • 无外部依赖 │ └──────────────────────────────────────────────────────────┘ ``` --- ## 技术栈 ### 后端技术栈 | 技术 | 版本 | 说明 | |------|------|------| | **Java** | 17 | 编程语言 | | **Spring Boot** | 3.5.11 | 应用框架 | | **PostgreSQL** | 17.5 | 关系型数据库 | | **Elasticsearch** | 8.17.1 | 向量搜索引擎 (kNN) | | **Druid** | 1.2.24 | 数据库连接池 | | **Flyway** | Latest | 数据库迁移工具 | | **Lombok** | 1.18.34 | 简化 Java 代码 | | **MapStruct** | 1.5.5.Final | 对象映射工具 | | **Gradle** | 8.x | 构建工具 | ### Python AI 引擎 | 技术 | 版本 | 说明 | |------|------|------| | **Python** | 3.9+ | 编程语言 | | **FastAPI** | Latest | Web 框架 | | **InsightFace** | Latest | 人脸识别库 | | **ONNX Runtime** | Latest | 模型推理引擎 | ### 前端技术栈 | 技术 | 版本 | 说明 | |------|------|------| | **Vue** | 3.5 | 前端框架 (Composition API) | | **Vite** | Latest | 构建工具 | | **Axios** | Latest | HTTP 客户端 | | **Lucide** | Latest | 图标库 | --- ## 核心特性 ### 🎯 人脸特征提取 - 使用 InsightFace 深度学习模型 - 提取 512 维特征向量 - 支持人脸检测和质量评估 ### 🔍 向量相似度搜索 - 基于 Elasticsearch 8.x kNN 算法 - HNSW 索引结构，毫秒级响应 - 支持余弦相似度计算 - 可配置匹配阈值（默认 0.65） ### 🏗️ 领域驱动设计 - 严格的 DDD 分层架构 - 依赖倒置原则（DIP） - 六边形架构（Hexagonal Architecture） - 聚合根模式 ### 📊 数据持久化 - **PostgreSQL**: 存储用户元数据和识别日志 - **Elasticsearch**: 索引和搜索 512 维特征向量 - **Flyway**: 自动化数据库迁移 --- ## 模块说明 ### face-domain (领域层) **职责**：核心业务逻辑和领域模型 **关键内容**： - `User` - 用户聚合根 - `RecognitionLog` - 识别日志聚合根 - `FeatureVector` - 特征向量值对象 (512 维) - `UserRepository` - 用户仓储接口 - `FaceSearchRepository` - 人脸搜索仓储接口 - `FeatureExtractor` - 特征提取器接口 **依赖**：无（纯业务逻辑，仅使用 Lombok） ### face-application (应用层) **职责**：用例编排和业务流程协调 **关键内容**： - `FaceRegistrationService` - 人脸注册服务 - `FaceRecognitionService` - 人脸识别服务 - `UserApplicationService` - 用户应用服务 **依赖**：仅依赖 `face-domain` ### face-infrastructure (基础设施层) **职责**：技术实现和外部集成 **关键内容**： - `UserRepositoryImpl` - 用户仓储实现（PostgreSQL + ES） - `AiEngineClient` - AI 引擎客户端（调用 FastAPI） - `SysUserEntity` - JPA 实体 - `SysUserJpaRepository` - Spring Data JPA 仓储 - `ElasticsearchIndexInitializer` - ES 索引初始化器 **依赖**：`face-domain`、PostgreSQL 驱动、Elasticsearch Java Client ### face-ui (展示层) **职责**：REST API 和应用入口 **关键内容**： - `FaceRecognitionApplication` - Spring Boot 主类 - `FaceController` - 人脸识别/注册 API - `UserController` - 用户管理 API - `application.yml` - 应用配置 **依赖**：`face-application`、`face-domain`、`face-infrastructure` (runtimeOnly) ### face-recognition-web (前端) **职责**：用户界面和交互 **关键内容**： - `FaceCamera.vue` - 摄像头组件 - `faceApi.js` - API 接口封装 - `App.vue` - 根组件 **依赖**：Vue 3、Axios、Lucide Icons --- ## 快速开始 ### 前置要求 - **JDK 17** - **Node.js 18+** - **PostgreSQL 17.5** - **Elasticsearch 8.17.1** - **Python 3.9+** (AI 引擎) ### 1. 克隆项目 ```bash git clone cd face-recognition-system ``` ### 2. 启动基础设施 #### PostgreSQL ```bash # Docker 方式 docker run -d \ --name postgres-face \ -e POSTGRES_PASSWORD=postgres \ -e POSTGRES_DB=face_db \ -p 15432:5432 \ postgres:17.5 ``` #### Elasticsearch ```bash # Docker 方式 docker run -d \ --name elasticsearch-face \ -p 9200:9200 \ -p 9300:9300 \ -e "discovery.type=single-node" \ -e "xpack.security.enabled=false" \ docker.elastic.co/elasticsearch/elasticsearch:8.17.1 ``` ### 3. 构建后端项目 ```bash # Windows gradlew.bat clean build # Linux/Mac ./gradlew clean build ``` ### 4. 启动后端服务 ```bash # Windows gradlew.bat :face-ui:bootRun # Linux/Mac ./gradlew :face-ui:bootRun ``` 服务将在 `http://localhost:8080` 启动 ### 5. 启动前端应用 ```bash cd face-recognition-web npm install npm run dev ``` 应用将在 `http://localhost:5173` 启动 --- ## API 文档 ### 人脸注册 ```http POST /api/v1/faces/register Content-Type: multipart/form-data userId: user123 userName: 张三 department: 技术部 file: <人脸图片> ``` **响应示例**： ```json { "success": true, "message": "人脸注册成功", "data": { "userId": "user123", "userName": "张三", "department": "技术部", "registerTime": "2025-01-15T10:30:00", "hasFeatureVector": true } } ``` ### 人脸识别 ```http POST /api/v1/faces/recognize Content-Type: multipart/form-data file: <人脸图片> ``` **响应示例（成功）**： ```json { "matched": true, "userId": "user123", "userName": "张三", "department": "技术部", "score": 0.85, "message": "识别成功" } ``` **响应示例（失败）**： ```json { "matched": false, "message": "未找到匹配的用户" } ``` --- ## 部署指南 ### 生产环境配置 参考配置文件： - `INFRASTRUCTURE_SETUP.md` - 基础设施安装指南 - `API_GUIDE.md` - REST API 测试指南 ### Docker 部署（TODO） ```bash # 构建镜像 docker-compose build # 启动服务 docker-compose up -d ``` --- ## 开发指南 ### 代码规范 - **Java**: 遵循阿里巴巴 Java 开发手册 - **Python**: 遵循 PEP 8 规范 - **Vue**: 遵循 Vue 3 风格指南 ### 提交规范 ```bash # 功能开发 git commit -m "feat: 添加人脸批量导入功能" # Bug 修复 git commit -m "fix: 修复 Elasticsearch 连接超时问题" # 文档更新 git commit -m "docs: 更新 API 文档" ``` ### 测试 ```bash # 运行所有测试 ./gradlew test # 运行特定模块测试 ./gradlew :face-domain:test ``` --- ## 常见问题 ### 1. Elasticsearch 连接失败？ **检查**： - Elasticsearch 是否正常运行：`curl http://localhost:9200` - 配置文件中的地址和端口是否正确 - 防火墙是否开放 9200 端口 ### 2. 人脸识别失败？ **可能原因**： - AI 引擎服务未启动 - 图片中没有清晰人脸 - 特征向量维度不匹配 - 匹配阈值设置过高 ### 3. 前端跨域问题？ **解决方案**： - 已配置 Vite 代理，无需额外处理 - 检查 `vite.config.js` 代理配置 --- ## 项目文档 - [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - 详细技术文档 - [INFRASTRUCTURE_SETUP.md](INFRASTRUCTURE_SETUP.md) - 基础设施安装 - [API_GUIDE.md](API_GUIDE.md) - API 测试指南 - [CLAUDE.md](CLAUDE.md) - Claude Code 项目指南 --- ## 贡献指南 欢迎提交 Issue 和 Pull Request！ --- ## 许可证 MIT License --- ## 联系方式 **AI Face Team** --- ## 致谢 - [Spring Boot](https://spring.io/projects/spring-boot) - [Elasticsearch](https://www.elastic.co/) - [Vue.js](https://vuejs.org/) - [InsightFace](https://github.com/deepinsight/insightface)