CompreFace开发环境搭建：Windows/Linux/MacOS平台教程

CompreFace开发环境搭建：Windows/Linux/MacOS平台教程

【免费下载链接】CompreFace Leading free and open-source face recognition system 项目地址: https://gitcode.com/gh_mirrors/co/CompreFace

前言

你是否在寻找一个功能完备、部署灵活的开源人脸识别系统？CompreFace作为领先的免费开源人脸识别系统（Leading free and open-source face recognition system），提供了开箱即用的人脸检测、识别、验证等功能，并支持多平台部署。本文将详细介绍如何在Windows、Linux和macOS系统中搭建CompreFace开发环境，让你快速投入人脸识别应用的开发。

读完本文后，你将能够：

• 了解CompreFace的三种部署方案及其适用场景
• 在不同操作系统上完成开发环境的搭建
• 启动并验证CompreFace服务
• 进行基础的开发调试工作

部署方案对比

CompreFace提供三种主要部署方案，各有优缺点，适用于不同场景：

部署方案	优点	缺点	适用场景
Docker Compose（默认）	配置简单、启动方便、通过QA测试	需要Docker Compose、仅单机器运行	本地开发环境
Kubernetes	易于扩展	需要Kubernetes集群	生产环境
单Docker容器	配置简单、启动方便	可靠性低、仅单机器运行	Docker Compose不支持时的本地开发

本文将重点介绍最适合开发环境的Docker Compose方案，该方案配置简单且易于调试。

环境准备

硬件要求

• CPU：x86架构处理器，支持AVX指令集
• 内存：至少4GB RAM（推荐8GB及以上）
• 硬盘：至少10GB可用空间

软件要求

操作系统	必需软件	可选软件
Windows	Docker Desktop、Git	Git Bash（推荐）
Linux	Docker、Docker Compose、Git	-
macOS	Docker Desktop、Git	-

处理器AVX支持检查

CompreFace需要CPU支持AVX指令集，可通过以下命令检查：

# Linux系统
lscpu | grep avx

# Windows系统（PowerShell）
(Get-CimInstance Win32_Processor).Feature | Where-Object { $_ -match 'AVX' }

# macOS系统
sysctl -a | grep avx

若命令输出包含"avx"相关内容，则说明CPU支持AVX指令集。

安装步骤

1. 安装基础软件

Windows系统

1. 安装Docker Desktop

   • 访问Docker官网下载安装包
   • 安装时勾选"Use WSL 2 instead of Hyper-V"（推荐）
   • 安装完成后启动Docker Desktop，等待服务启动完成

2. 安装Git

   • 访问Git官网下载安装包
   • 安装时选择"Use Git from Git Bash only"，其他选项保持默认

Linux系统

以Ubuntu为例：

# 安装Docker
sudo apt update
sudo apt install -y docker.io docker-compose git

# 启动Docker服务并设置开机自启
sudo systemctl enable --now docker

# 将当前用户添加到docker组（避免每次使用sudo）
sudo usermod -aG docker $USER
# 注意：添加用户组后需要注销并重新登录才能生效

macOS系统

1. 安装Docker Desktop

   • 访问Docker官网下载Mac版安装包
   • 将Docker拖入Applications文件夹并启动

2. 安装Git

   • 通过Homebrew安装：brew install git
   • 或从Git官网下载安装包

2. 获取CompreFace源码

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/co/CompreFace.git
cd CompreFace

3. 启动CompreFace服务

Windows系统（Git Bash）

# 进入项目目录
cd /path/to/CompreFace

# 启动服务
docker-compose up -d

Windows系统（命令提示符/ PowerShell）

# 进入项目目录
cd C:\path\to\CompreFace

# 启动服务
docker-compose up -d

Linux/macOS系统

# 进入项目目录
cd /path/to/CompreFace

# 启动服务
docker-compose up -d

4. 服务启动验证

启动命令执行后，CompreFace会下载所需镜像并启动服务，首次启动可能需要5-10分钟。可以通过以下命令检查服务状态：

# 查看所有服务状态
docker-compose ps

# 查看服务日志（例如查看core服务日志）
docker-compose logs -f compreface-core

成功启动后，应看到5个服务都处于"Up"状态：

• compreface-core
• compreface-api
• compreface-admin
• compreface-ui
• compreface-postgres-db

访问CompreFace

服务启动后，打开浏览器访问以下地址：

• Web界面：http://localhost:8000/login
• API接口：http://localhost:8000/api/v1

首次访问时，使用默认管理员账号登录：

• 用户名：admin@example.com
• 密码：admin

开发环境配置

项目结构概览

CompreFace/
├── dev/                 # 开发相关配置
├── embedding-calculator/ # 人脸特征计算服务
├── java/                # 后端服务代码
│   ├── admin/           # 管理服务
│   ├── api/             # API服务
│   └── common/          # 公共代码
├── ui/                  # 前端代码（Angular）
└── docker-compose.yml   # 默认Docker Compose配置

开发模式启动

对于需要修改源代码的开发场景，可以使用开发模式启动：

# 进入dev目录
cd dev

# 启动开发模式
sh start.sh

开发模式启动后，会自动构建并启动所有服务，包括：

• 后端服务（热重载）
• 前端服务（默认在4200端口，支持热重载）
• 数据库服务

前端开发

# 进入ui目录
cd ui

# 安装依赖
npm install

# 启动开发服务器
npm start

前端开发服务器启动后，访问http://localhost:4200即可查看前端界面，代码修改会实时反映到界面上。

后端开发

后端服务使用Java开发，主要包含admin和api两个模块：

• admin：管理服务，处理用户、权限等管理相关功能
• api：API服务，处理人脸识别相关的核心功能

修改后端代码后，开发模式下会自动重新编译并重启服务。

常见问题解决

1. 服务启动失败

问题描述：compreface-core服务启动失败或不断重启

可能原因：CPU不支持AVX指令集或Docker资源配置不足

解决方案：

• 确认CPU支持AVX指令集
• 调整Docker资源配置（增加内存和CPU分配）

问题描述：数据库相关服务启动失败

解决方案：

# 清理数据库数据
docker-compose down -v

# 重新启动
docker-compose up -d

2. 服务启动缓慢

解决方案：

• 检查网络连接，确保Docker镜像下载速度正常
• 增加Docker资源分配（推荐至少分配4GB内存）

3. Windows系统下start.sh执行失败

问题描述：在Windows命令提示符中执行sh start.sh提示"sh不是内部或外部命令"

解决方案：

• 使用Git Bash执行脚本
• 或手动执行脚本中的命令：

  docker-compose -f docker-compose.yml -f docker-compose.dev.ui.yml up --build &
  cd ../ui && npm run start
  

4. 端口冲突

问题描述：启动时提示端口已被占用

解决方案： 修改docker-compose.yml文件中的端口映射，例如将8000端口改为其他端口：

services:
  compreface-fe:
    ports:
      - "8001:80"  # 将8000改为8001

服务管理命令

基本命令

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 停止服务并删除数据卷（重置环境）
docker-compose down -v

# 查看日志
docker-compose logs -f [服务名]

# 重启服务
docker-compose restart [服务名]

开发模式命令

# 进入开发目录
cd dev

# 启动开发模式
sh start.sh

# 停止开发模式服务
docker-compose down

总结

本文详细介绍了在Windows、Linux和macOS系统上搭建CompreFace开发环境的步骤，包括环境准备、安装部署、开发配置和常见问题解决。通过本文的指导，你应该已经成功搭建了CompreFace开发环境，并能够开始进行人脸识别应用的开发工作。

CompreFace作为开源的人脸识别系统，提供了丰富的功能和灵活的部署选项，适合从个人项目到企业应用的各种场景。如果你在使用过程中遇到问题，可以查阅官方文档或参与社区讨论获取帮助。

附录：开发资源

• 官方文档：项目内docs目录
• API文档：http://localhost:8000/swagger-ui.html
• 前端组件文档：ui/src/app目录下的组件说明
• 贡献指南：项目根目录下的CONTRIBUTING.md

【免费下载链接】CompreFace Leading free and open-source face recognition system 项目地址: https://gitcode.com/gh_mirrors/co/CompreFace