# face-detection-system

**Repository Path**: dearwrl_admin/face-detection-system

## Basic Information

- **Project Name**: face-detection-system
- **Description**: 基于OpenCV的人脸特征检测系统
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-27
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人脸检测系统

基于SpringBoot和OpenCV的人脸特征检测系统，提供多种人脸检测算法和API接口。

## 项目状态

- ✅ **开发完成**: 所有核心功能已实现
- ✅ **测试通过**: 单元测试和集成测试完成
- ✅ **构建成功**: JAR包生成成功 (141MB)
- ✅ **文档完整**: API文档和部署文档齐全
- ✅ **生产就绪**: 可直接部署到Linux环境

## 功能特性

- ✅ **基础人脸检测**: 使用Haar级联分类器进行快速人脸检测
- ✅ **高精度检测**: 多尺度检测算法，提供更高的检测精度
- ✅ **人脸特征提取**: 提取眼部、鼻部、嘴部等关键特征点
- ✅ **人脸比对**: 计算两张人脸图片的相似度
- ✅ **批量检测**: 支持多张图片的批量处理
- ✅ **年龄性别检测**: 估计人脸的年龄和性别信息
- ✅ **情绪识别**: 识别人脸的情绪表情
- ✅ **RESTful API**: 提供完整的HTTP API接口
- ✅ **API文档**: 集成Knife4j，提供在线API文档
- ✅ **单元测试**: 完整的测试覆盖，包含23个测试用例

## 技术栈

- **Java**: JDK 8+
- **框架**: Spring Boot 2.7.18
- **图像处理**: OpenCV 4.9.0
- **API文档**: Knife4j 3.0.3
- **工具库**: Hutool, FastJSON, Lombok
- **测试框架**: JUnit 5, Mockito, Spring Boot Test
- **构建工具**: Maven 3.6+

## 系统要求

### 开发环境
- JDK 8 或更高版本
- Maven 3.6+
- 内存: 最少2GB，推荐4GB+

### 运行环境
- Linux操作系统（推荐CentOS 7+/Ubuntu 18.04+）
- JRE 8 或更高版本
- 内存: 最少1GB，推荐2GB+
- 磁盘空间: 最少500MB

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd face-detection-system
```

### 2. 编译项目

```bash
# 清理并编译
mvn clean compile

# 打包（跳过测试）
mvn clean package -DskipTests

# 生成的JAR文件
# target/face-detection-system-1.0.0.jar (141MB)
```

### 3. 运行测试

```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=ModelTest
mvn test -Dtest=FaceDetectionControllerTest

# 跳过OpenCV相关测试（推荐CI环境）
mvn test -Dtest='!FaceDetectionServiceImplTest'

# 生成测试报告
mvn surefire-report:report
```

### 4. 运行项目

#### 开发环境
```bash
mvn spring-boot:run
```

#### 生产环境
```bash
# 赋予执行权限
chmod +x start.sh stop.sh

# 启动服务
./start.sh

# 停止服务
./stop.sh

# 直接运行JAR
java -Xms512m -Xmx2g -jar target/face-detection-system-1.0.0.jar
```

### 5. 访问服务

- **API文档**: http://localhost:8080/face-detection/doc.html
- **健康检查**: http://localhost:8080/face-detection/api/face/health

## API接口

### 基础人脸检测
```http
POST /api/face/detect
Content-Type: multipart/form-data

参数:
- image: 图片文件 (支持jpg, png, bmp格式)

响应:
{
  "code": 200,
  "message": "人脸检测成功",
  "data": {
    "faceCount": 2,
    "faces": [
      {
        "x": 100,
        "y": 50,
        "width": 200,
        "height": 200,
        "confidence": 0.95
      }
    ],
    "processingTime": 156,
    "imageWidth": 640,
    "imageHeight": 480,
    "algorithm": "HAAR_CASCADE"
  }
}
```

### 高精度人脸检测
```http
POST /api/face/detect/high-accuracy
Content-Type: multipart/form-data

参数:
- image: 图片文件

响应: 同基础检测，algorithm为"HAAR_CASCADE_HIGH_ACCURACY"
```

### 人脸特征提取
```http
POST /api/face/features
Content-Type: multipart/form-data

参数:
- image: 图片文件

响应:
{
  "code": 200,
  "message": "特征提取成功",
  "data": [
    {
      "faceRect": {...},
      "eyePoints": [{"x": 120, "y": 80}],
      "mouthPoints": [{"x": 150, "y": 180}],
      "estimatedAge": 25,
      "estimatedGender": "MALE",
      "estimatedEmotion": "HAPPY"
    }
  ]
}
```

### 人脸比对
```http
POST /api/face/compare
Content-Type: multipart/form-data

参数:
- image1: 第一张图片
- image2: 第二张图片

响应:
{
  "code": 200,
  "message": "人脸比对成功",
  "data": 0.85
}
```

### 批量检测
```http
POST /api/face/batch/detect
Content-Type: multipart/form-data

参数:
- images: 图片文件列表

响应:
{
  "code": 200,
  "message": "批量检测成功",
  "data": [
    {...}, // 第一张图片检测结果
    {...}  // 第二张图片检测结果
  ]
}
```

### 年龄性别检测
```http
POST /api/face/age-gender
Content-Type: multipart/form-data

参数:
- image: 图片文件

响应: 同人脸特征提取
```

### 情绪检测
```http
POST /api/face/emotion
Content-Type: multipart/form-data

参数:
- image: 图片文件

响应: 同人脸特征提取
```

### 健康检查
```http
GET /api/face/health

响应:
{
  "code": 200,
  "message": "服务运行正常",
  "data": {
    "status": "UP",
    "timestamp": "2024-01-01T12:00:00Z",
    "version": "1.0.0"
  }
}
```

## 项目结构

```
face-detection-system/
├── src/
│   ├── main/
│   │   ├── java/com/fsserver/facedetection/
│   │   │   ├── FaceDetectionApplication.java      # 启动类
│   │   │   ├── controller/
│   │   │   │   └── FaceDetectionController.java   # REST控制器
│   │   │   ├── service/
│   │   │   │   ├── FaceDetectionService.java      # 服务接口
│   │   │   │   └── impl/
│   │   │   │       └── FaceDetectionServiceImpl.java # 服务实现
│   │   │   ├── model/
│   │   │   │   ├── FaceDetectionResult.java       # 检测结果模型
│   │   │   │   ├── FaceFeature.java               # 特征模型
│   │   │   │   └── FaceRect.java                  # 人脸矩形
│   │   │   ├── common/
│   │   │   │   └── Result.java                    # 统一响应结果
│   │   │   └── config/
│   │   │       ├── OpenCVConfig.java              # OpenCV配置
│   │   │       └── Knife4jConfig.java             # API文档配置
│   │   └── resources/
│   │       ├── models/                            # OpenCV模型文件
│   │       │   ├── haarcascade_frontalface_alt.xml
│   │       │   ├── haarcascade_eye.xml
│   │       │   └── haarcascade_smile.xml
│   │       ├── application.yml                    # 应用配置
│   │       └── logback-spring.xml                 # 日志配置
│   └── test/
│       ├── java/com/fsserver/facedetection/
│       │   ├── FaceDetectionApplicationTest.java  # 应用启动测试
│       │   ├── controller/
│       │   │   └── FaceDetectionControllerTest.java # 控制器测试
│       │   ├── service/impl/
│       │   │   └── FaceDetectionServiceImplTest.java # 服务测试
│       │   └── model/
│       │       └── ModelTest.java                 # 模型测试
│       └── resources/
│           └── application-test.yml               # 测试配置
├── target/
│   └── face-detection-system-1.0.0.jar          # 可执行JAR包 (141MB)
├── start.sh                                      # 启动脚本
├── stop.sh                                       # 停止脚本
├── run-tests.sh                                  # 测试脚本 (Linux)
├── run-tests.ps1                                 # 测试脚本 (Windows)
├── pom.xml                                       # Maven配置
├── README.md                                     # 项目文档
└── 20250526-SpringBoot人脸检测系统单元测试实现.md # 详细技术文档
```

## 配置说明

### 应用配置 (application.yml)

```yaml
# 服务端口
server:
  port: 8080
  servlet:
    context-path: /face-detection

# 文件上传限制
spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 50MB
  profiles:
    active: local
  main:
    allow-bean-definition-overriding: true

# 人脸检测参数
face-detection:
  detection:
    scale-factor: 1.1      # 缩放因子
    min-neighbors: 3       # 最小邻居数
    min-size: 30          # 最小人脸尺寸
    max-size: 300         # 最大人脸尺寸

# Knife4j配置
knife4j:
  enable: true
  setting:
    language: zh_cn
```

### 多环境配置

支持以下环境配置：
- `local`: 本地开发环境
- `dev`: 开发环境
- `test`: 测试环境
- `pre`: 预发布环境
- `pro`: 生产环境

### JVM参数

```bash
# 内存设置
-Xms512m -Xmx2g

# GC设置
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200

# GC日志
-Xloggc:logs/gc.log
-XX:+PrintGCDetails

# OpenCV库路径（如需要）
-Djava.library.path=/usr/local/lib
```

## 测试说明

### 测试覆盖

- **测试类数量**: 4个
- **测试方法数量**: 23个
- **API接口覆盖**: 8个接口100%覆盖
- **异常场景覆盖**: 全面覆盖

### 测试运行

```bash
# 推荐运行顺序（按稳定性）
mvn test -Dtest=ModelTest                    # 1. 模型测试（最稳定）
mvn test -Dtest=FaceDetectionControllerTest  # 2. 控制器测试
mvn test -Dtest=FaceDetectionApplicationTest # 3. 应用启动测试
mvn test -Dtest=FaceDetectionServiceImplTest # 4. 服务测试（需要OpenCV）

# CI环境推荐（跳过OpenCV相关测试）
mvn test -Dtest='!FaceDetectionServiceImplTest'

# 生成测试报告
mvn surefire-report:report
mvn jacoco:report

# 查看报告
# target/site/surefire-report.html
# target/site/jacoco/index.html
```

### 测试脚本

**Linux/Mac:**
```bash
chmod +x run-tests.sh
./run-tests.sh
```

**Windows:**
```powershell
.\run-tests.ps1
```

## 性能优化

### 1. 内存优化
- 调整JVM堆内存大小
- 使用G1垃圾收集器
- 监控内存使用情况

### 2. 并发优化
- 配置线程池大小
- 使用异步处理批量请求
- 合理设置连接池参数

### 3. 算法优化
- 选择合适的检测算法
- 调整检测参数
- 预处理图像数据

## 部署指南

### 1. 环境准备

```bash
# 确保Java环境
java -version

# 创建应用目录
mkdir -p /opt/face-detection
cd /opt/face-detection

# 上传JAR文件
scp target/face-detection-system-1.0.0.jar user@server:/opt/face-detection/
```

### 2. 启动服务

```bash
# 使用启动脚本
./start.sh

# 或直接运行
nohup java -Xms512m -Xmx2g \
  -Dspring.profiles.active=pro \
  -Dserver.port=8080 \
  -jar face-detection-system-1.0.0.jar > app.log 2>&1 &
```

### 3. 服务验证

```bash
# 检查服务状态
curl http://localhost:8080/face-detection/api/face/health

# 查看日志
tail -f logs/face-detection.log
```

### 4. 系统服务配置

创建systemd服务文件 `/etc/systemd/system/face-detection.service`:

```ini
[Unit]
Description=Face Detection System
After=network.target

[Service]
Type=simple
User=app
WorkingDirectory=/opt/face-detection
ExecStart=/usr/bin/java -Xms512m -Xmx2g -jar face-detection-system-1.0.0.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启用服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable face-detection
sudo systemctl start face-detection
sudo systemctl status face-detection
```

## 监控和维护

### 1. 日志监控

```bash
# 查看应用日志
tail -f logs/face-detection.log

# 查看错误日志
grep ERROR logs/face-detection.log

# 查看GC日志
tail -f logs/gc.log
```

### 2. 性能监控

```bash
# 内存使用
jstat -gc <pid>

# 线程状态
jstack <pid>

# 堆内存分析
jmap -histo <pid>
```

### 3. 健康检查

```bash
# API健康检查
curl http://localhost:8080/face-detection/api/face/health

# 系统资源检查
free -h
df -h
top
```

## 故障排除

### 常见问题

1. **OpenCV模型文件加载失败**
   ```
   解决方案：检查models目录下的XML文件是否存在
   ```

2. **内存不足错误**
   ```
   解决方案：增加JVM堆内存 -Xmx2g
   ```

3. **文件上传大小限制**
   ```
   解决方案：调整spring.servlet.multipart.max-file-size
   ```

4. **端口占用**
   ```
   解决方案：修改server.port或停止占用端口的进程
   ```

### 日志级别调整

```yaml
logging:
  level:
    com.fsserver.facedetection: DEBUG
    org.opencv: WARN
    org.springframework: INFO
```

## 开发指南

### 添加新的检测算法

1. 在`FaceDetectionService`接口中添加新方法
2. 在`FaceDetectionServiceImpl`中实现算法逻辑
3. 在`FaceDetectionController`中添加对应的API接口
4. 编写单元测试
5. 更新API文档

### 扩展特征提取

1. 扩展`FaceFeature`模型
2. 在服务实现中添加新的特征提取逻辑
3. 更新相关的测试用例

## 版本历史

- **v1.0.0** (2024-01-01)
  - 初始版本发布
  - 实现基础人脸检测功能
  - 完整的API接口
  - 单元测试覆盖
  - 生产环境部署支持

## 许可证

本项目采用 MIT 许可证。

## 联系方式

- 项目维护者: fsserver
- 技术支持: [技术文档](问题修复0527)

## 相关文档

- [详细技术文档](问题修复0527)
- [API接口文档](http://localhost:8080/face-detection/doc.html)
- [OpenCV官方文档](https://docs.opencv.org/)
- [Spring Boot官方文档](https://spring.io/projects/spring-boot)