# 人脸识别服务DOCKER安装说明

## 1. 简介
本项目基于dlib库实现了一个简单的人脸识别服务，使用FastAPI框架构建API接口，支持通过HTTP请求进行人脸注册和识别。
该服务可以部署在Docker容器中，方便用户快速搭建和使用人脸识别功能。

## 2. 安装部署

[在线安装](在线人脸识别安装服务docker.md)

[离线安装](离线人脸识别安装服务docker.md)

[手工部署](基于DLIB的人脸识别服务-手工部署说明.md)

## 3. 使用说明
### 3.1 启动服务    
进入服务部署目录，执行以下命令启动服务：

```bash
docker-compose up -d
```
### 3.2 停止服务
```bash 
docker-compose down
```
### 3.3 查看日志
```bash     
docker-compose logs -f facerec
```

### 3.4 人脸识别API接口说明

本文档详细描述了人脸识别服务提供的各个API接口，包括接口地址、请求方式、参数说明、返回结果等信息。

#### 3.4.1 人脸识别接口

##### 接口地址
`POST /api/identifyFace`

##### 功能说明
上传图片进行人脸识别，返回匹配的用户信息。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| image | file | 是 | 包含人脸的图片文件 |

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "result": [
        {
          "score": 95.5,
          "group_id": "group",
          "user_id": "用户名",
          "Uid": "用户编码",
          "Name": "用户姓名",
          "IdNum": "身份证号"
        }
      ],
      "log_id": "时间戳",
      "face_token": "唯一标识符",
      "result_num": 1
    }
  },
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/identifyFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@test.jpg"
```

#### 3.4.2 添加人脸数据接口

##### 接口地址
`POST /api/addFace`

##### 功能说明
添加新的人脸数据到系统中，用于后续的人脸识别。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| image | file | 是 | 包含人脸的图片文件 |
| userCode | string | 是 | 用户编码 |
| userName | string | 否 | 用户姓名，默认使用userCode |
| idNum | string | 否 | 身份证号，默认使用userCode |

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "用户数据添加成功",
      "faceUrl": "http://localhost:12316/images/userCode.jpg",
      "faceUrl_Placeholder": "http://^API_BASE_URL^/images/userCode.jpg"
    }
  },
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/addFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@user.jpg" \
     -F "userCode=USER001" \
     -F "userName=张三" \
     -F "idNum=110101199001011234"
```

#### 3.4.3 人脸检测接口

##### 接口地址
`POST /api/detectFace`

##### 功能说明
检测图片中的人脸位置信息，不进行身份识别。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| image | file | 是 | 图片文件 |

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "faces": [
      {
        "location": {
          "left": 100,
          "top": 100,
          "width": 200,
          "height": 200
        }
      }
    ],
    "face_num": 1
  },
  "message": "SUCCESS"
}
```

**坐标信息说明：**
- `left`: 人脸框左上角距离图片左边界的像素距离
- `top`: 人脸框左上角距离图片上边界的像素距离
- `width`: 人脸框的宽度（像素）
- `height`: 人脸框的高度（像素）
这些坐标信息基于图片的左上角为原点(0,0)，向右为X轴正方向，向下为Y轴正方向的坐标系。

##### 示例
```bash
curl -X POST "http://localhost:12316/api/detectFace" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@test.jpg"
```

#### 3.4.4 获取用户人脸图像URL接口

##### 接口地址
`POST /api/getUserFaceUrl`

##### 功能说明
根据用户编码获取用户人脸图像的访问URL。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| userCode | string | 是 | 用户编码 |

##### 返回结果
```json
{
  "code": 200,
  "data": "http://localhost:12316/images/userCode.jpg",
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/getUserFaceUrl" \
     -d "userCode=USER001"
```

#### 3.4.5 删除人脸数据接口

##### 接口地址
`POST /api/delFace`

##### 功能说明
根据用户编码删除指定的人脸数据。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| userCode | string | 是 | 用户编码 |

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "用户数据删除成功"
    }
  },
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/delFace" \
     -d "userCode=USER001"
```

#### 3.4.6 重新加载特征数据接口

##### 接口地址
`POST /api/reloadFeatures`

##### 功能说明
重新从数据库加载所有人脸特征数据到内存中。

##### 请求参数
无

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "log_id": "时间戳",
      "message": "特征数据重新加载成功",
      "count": 10
    }
  },
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/reloadFeatures"
```

#### 3.4.7 查询所有人员数据接口

##### 接口地址
`POST /api/getAllUsers`

##### 功能说明
获取系统中所有已注册用户的信息。

##### 请求参数
无

##### 返回结果
```json
{
  "code": 200,
  "data": {
    "msg": "success",
    "errno": 0,
    "data": {
      "users": [
        {
          "userCode": "USER001",
          "userName": "张三",
          "idNum": "110101199001011234",
          "faceUrl": "http://localhost:12316/images/USER001.jpg",
          "faceUrl_Placeholder": "http://^API_BASE_URL^/images/USER001.jpg"
        }
      ],
      "count": 1
    }
  },
  "message": "SUCCESS"
}
```

##### 示例
```bash
curl -X POST "http://localhost:12316/api/getAllUsers"
```

#### 3.4.8 静态图像文件服务

##### 接口地址
`GET /images/{filename}`

##### 功能说明
提供用户人脸图像的静态文件访问服务。

##### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| filename | string | 是 | 图像文件名 |

##### 返回结果
图像文件二进制数据

##### 示例
```bash
curl -X GET "http://localhost:12316/images/USER001.jpg" -o user_image.jpg
```
### 3.5 简要使用说明

本服务是使用DLIB本的模型进行人脸识别的，精度和速度都比较适中，适合一般的应用场景。使用sqlite数据库存储人脸特征数据，方便部署和维护。
在使用过程中，请注意以下几点：
- 确保上传的图片质量较好，避免模糊或遮挡严重的图片。
- 人脸识别的准确率受多种因素影响，如光照、角度、表情等，建议在多种条件下测试和优化。
- 定期备份数据库文件，防止数据丢失。
- 如果需要更高的识别精度，可以考虑使用更复杂的模型或增加训练数据。

服务在启动时，先把数据库中所有的人脸特征数据加载到内存中，识别时直接在内存中进行比对，速度较快。如果添加或删除了人脸数据，需要调用`/api/reloadFeatures`接口重新加载特征数据。人脸特征数据存储在`rec.db`文件中，位于服务的工作目录下data/db。如需导出，可以直接找到容器的挂载目录下的该文件进行备份或导出。

人脸特征，采用了采集128个特征点保存，即128维的浮点数数组，存储在数据库中。识别时，计算上传图片的人脸特征与数据库中所有特征的欧氏距离，距离越小表示相似度越高。可以根据实际需求调整识别阈值。

人脸特征库表每个记录约131个字段，其不适合存储大量人脸数据。如果需要存储更多人脸数据，建议使用更专业的数据库系统，如MySQL、PostgreSQL等。因为本项目就动时需要据有的人脸数据加载到内存中，所以，人脸数据量不宜过大，建议控制在几千人以内。

### 3.6 人脸识别服务简要测试办法

本人脸识别服务，提供了一个简单的HTML页面用于测试人脸识别功能。可以通过浏览器访问该页面，上传图片进行测试。

下载地址: 

    [测试网页压缩包](https://datacdn.data-it.tech/faceRec/face-dt/face-test.zip)

    [测试网页-未压缩](https://datacdn.data-it.tech/faceRec/face-dt/face-test.html)

解压后，将`face-test.html`文件放在任意目录下，使用浏览器打开该文件。页面中有一个文件上传控件，可以选择包含人脸的图片进行测试。上传后，页面会调用人脸识别服务的API接口，显示识别结果。

如果需要把网页部署到nginx等web服务器上，可以将`face-test.html`文件放在服务器的指定目录下，然后通过浏览器访问服务器的地址即可。
但时要注意，因为网页中调用了摄像头视频，在没有https证书的情况下，只有localhost可开启了权限白名单的情况下，才能正常使用摄像头功能。

***本地测试如何开启权限***

```
Edge
edge://flags/#unsafely-treat-insecure-origin-as-secure
Chrome
chrome://flags/#unsafely-treat-insecure-origin-as-secure
将 Insecure origins treated as secure 设置为 Enabled
```

如果不想开启权限白名单，可以把网页放在nginx等web服务器上，并配置https证书，这样浏览器会认为是安全的来源，就可以正常使用摄像头功能。 


### 3.7 常见问题

- **问题1**: 上传图片后，识别结果为空或不准确。
  - **解决办法**: 确保上传的图片质量较好，避免模糊或遮挡严重的图片。可以尝试不同的图片进行测试。    
- **问题2**: 添加人脸数据时，提示用户已存在。
    - **解决办法**: 确认用户编码是否唯一，如果需要更新用户信息，可以先删除旧数据，再添加新数据。
- **问题3**: 服务启动失败或无法访问。
  - **解决办法**: 检查Docker容器是否正常运行，确认端口是否被正确映射。查看日志获取更多信息。
- **问题4**: 数据库文件损坏或丢失。
  - **解决办法**: 如果有备份，可以恢复备份文件。否则需要重新添加人脸数据。
- **问题5**: 识别速度较慢。
  - **解决办法**: 确认服务器性能是否足够，减少人脸数据量，或优化图片大小和质量。
- **问题6**: 如何调整识别阈值？
  - **解决办法**: 目前代码中没有提供直接调整阈值的接口，可以在代码中修改识别逻辑，调整欧氏距离的阈值。

### 3.8 性能测试报告
![](https://qncdn.tairongkj.com/docs/images/20250930170146.png)
上图为配笔记本电脑环境测

下图为公司的前置工控机环境测试
![](https://qncdn.tairongkj.com/docs/images/c63bc4d2c02a4a8f6676f77d75cca0f6.png)

经过反复测试，平均响应时间在200-300ms之间，峰值时段也能保持在500ms以内，满足一般应用需求。
同时并发要控制在4个以内，同一时间进行识别请求，超过4个时，响应时间会明显增加，延迟响应，响应时间有可能超过秒。如果需要更高的并发处理能力，可以考虑增加服务器资源，部署多个服务做负载均衡。，但对同一个中心，一般一个服务就足够了，毕竟同时识可的可能性太少了。

### 3.9 总结
本项目提供了一个基于DLIB的人脸识别服务，使用FastAPI框架，支持Docker部署。通过RESTful API接口，用户可以方便地进行人脸注册和识别操作。服务性能良好，适合一般应用场景。用户可以根据实际需求进行扩展和优化。