cnbbx/face-recognition repository overview

⁠Face Recognition Service - Docker Image

⁠概述

该 Docker 镜像封装了一个 Flask 后端服务，具备以下核心功能：

• 人脸注册/删除/查询（管理人脸库）
• 单人脸检测与 128 维特征编码提取
• 基于特征距离的人脸识别（阈值 0.6）
• 支持跨域访问（CORS）
• 数据持久化（人脸库文件映射到宿主机）

⁠快速开始

⁠1. 运行容器

docker run -d \
  --name cnbbx_facerecognition \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /root/faces:/app/faces \
  cnbbx/face-recognition

⁠参数说明

⁠2. 验证服务

容器启动后，可通过以下命令检查服务状态：

# 查看容器日志
docker logs cnbbx_facerecognition

# 正常输出示例：
# 🔍 加载人脸库（Docker环境）...
# ✅ 共加载0个人脸
# 🚀 Docker版人脸识别服务启动：http://0.0.0.0:8080

访问 http://<服务器IP>:8080/faces 应返回：

{"faces": []}

⁠API 接口文档

⁠1. 人脸库管理

⁠接口地址

/faces

⁠请求参数

⁠请求方法 & 响应示例

⁠🔹 查询所有人脸ID

• 方法：GET
• 请求示例：GET http://localhost:8080/faces
• 成功响应（200）：

  {"faces": ["user1", "user2"]}
  

  Copy

⁠🔹 注册人脸

• 方法：POST
• 请求示例：POST http://localhost:8080/faces?id=user1（FormData 携带图片文件）
• 成功响应（200）：

  {"success": true, "msg": "人脸user1注册成功（Docker）"}
  

  Copy
• 失败响应（400）：

  {"error": "未检测到人脸"}
  

  Copy

⁠🔹 删除人脸

• 方法：DELETE
• 请求示例：DELETE http://localhost:8080/faces?id=user1
• 成功响应（200）：

  {"success": true, "msg": "人脸user1已删除"}
  

  Copy

⁠错误码说明

⁠2. 人脸识别

⁠接口地址

/

⁠请求参数

⁠请求方法 & 响应示例

• 方法：POST
• 请求示例：POST http://localhost:8080/（FormData 携带图片文件）
• 成功响应（200）：

  {
    "count": 1,
    "faces": [
      {"id": "user1", "distance": 0.45}
    ]
  }
  

  Copy
• 无匹配人脸响应（200）：

  {
    "count": 1,
    "faces": []
  }
  

  Copy
• 失败响应（400）：

  {"error": "检测到3张人脸，仅支持单人脸"}
  

  Copy

⁠字段说明

⁠故障排除

⁠1. 容器启动失败

• 查看日志：docker logs cnbbx_facerecognition
• 确认宿主机 8080 端口未被占用：netstat -tulpn | grep 8080

⁠2. 人脸检测失败

• 确保上传的图片为清晰的正面人脸照
• 图片中仅包含单个人脸（代码限制仅支持单人脸）
• 图片格式为 JPG/PNG（其他格式不支持）

⁠3. 数据持久化问题

• 确认挂载目录权限：chmod 777 /root/faces
• 检查容器内目录：docker exec -it cnbbx_facerecognition ls /app/faces

⁠总结

1. 核心运行命令通过 -v 参数实现人脸库持久化，确保容器重启后数据不丢失；
2. 服务提供 GET/POST/DELETE /faces 管理人脸库，POST / 实现人脸识别，接口简洁易用；
3. 人脸识别基于 dlib 的 128 维特征编码，特征距离 ≤ 0.6 判定为匹配成功，是行业通用阈值。