10分钟上手！CompreFace开源人脸识别系统零代码安装与配置指南

CompreFace是一款领先的免费开源人脸识别系统，支持人脸识别、验证、检测等多种功能，无需机器学习背景即可快速部署。本文将详细介绍两种最便捷的安装方式，帮助普通用户和运营人员在本地环境中快速搭建这套强大的人脸识别服务。

安装方式对比

CompreFace提供三种部署方案，适合不同使用场景：

部署方式	优势	劣势	适用场景
Docker Compose（推荐）	配置简单、服务独立、支持扩展	需要Docker Compose环境	本地开发/生产环境
单Docker容器	一键启动、配置极简	服务耦合、不易维护	快速测试/资源受限环境
Kubernetes	易于横向扩展	需要K8s集群	大规模生产部署

官方文档：docs/Installation-options.md 提供了完整部署方案，本文重点介绍前两种适合普通用户的安装方式。

准备工作

系统要求

• 支持x86架构的CPU，并开启AVX指令集（Linux用户可通过lscpu | grep avx命令验证）
• Docker环境：Windows和Mac用户需安装Docker Desktop，Linux用户需安装Docker和Docker Compose

环境验证

# 验证Docker是否安装成功
docker --version
# 验证Docker Compose是否安装成功
docker-compose --version

方式一：Docker Compose安装（推荐）

安装步骤

1. 获取项目代码

git clone https://gitcode.com/gh_mirrors/co/CompreFace
cd CompreFace

2. 启动服务

# 使用默认配置启动（CPU版本）
docker-compose up -d

3. 验证服务状态

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

正常情况下会显示5个运行中的服务：compreface-core、compreface-api、compreface-admin、compreface-ui、compreface-postgres-db

4. 访问系统 打开浏览器访问 http://localhost:8000/login，首次登录使用默认管理员账号：

• 用户名：[e-mail]
• 密码：admin

维护与配置

服务管理

# 停止服务
docker-compose stop
# 重启服务
docker-compose restart
# 查看服务日志
docker-compose logs -f compreface-core

数据持久化

所有数据存储在Docker卷中，即使删除容器也不会丢失。卷名称格式为<项目目录>_postgres-data，可通过以下命令查看：

docker volume ls | grep postgres-data

版本更新

# 下载最新配置文件
wget https://gitcode.com/gh_mirrors/co/CompreFace/raw/master/docker-compose.yml -O docker-compose.yml
# 重启服务
docker-compose down
docker-compose up -d

方式二：单Docker容器安装（快速测试）

一键启动

# 启动默认版本（CPU）
docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface

自定义配置

指定版本

# 启动特定版本
docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface:1.0.0

GPU加速（需安装NVIDIA Docker）

# 启动GPU版本
docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runtime=nvidia -p 8000:80 exadel/compreface:1.0.0-arcface-r100-gpu

自动重启

# 添加自动重启参数
docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface

服务验证

# 查看容器日志
docker logs CompreFace -f

当看到exited: startup (exit status 0; expected)日志时，表示启动完成

界面快速上手

主要功能界面

CompreFace提供直观的Web管理界面，主要功能区域包括：

1. 控制面板

2. 人脸识别界面

3. 服务管理界面

通过【Face Services】菜单可以配置各种人脸识别服务，包括：

• 人脸检测
• 人脸识别
• 人脸验证
• 特征点检测
• 口罩检测插件

服务配置文档：docs/Face-services-and-plugins.md

快速体验人脸识别

1. 创建应用：在【Applications】页面点击【Create Application】
2. 添加人脸集合：在应用详情页创建人脸集合（Collection）
3. 上传人脸照片：点击【Add Subject】上传人脸样本
4. 测试识别：在【Test】标签页上传照片进行识别测试

识别阈值设置指南：docs/Face-Recognition-Similarity-Threshold.md

常见问题解决

1. compreface-core服务无法启动

问题原因：CPU不支持AVX指令集或使用了不兼容的架构（如ARM） 解决方案：

• 确认CPU支持AVX：lscpu | grep avx
• 尝试使用无AVX依赖的自定义构建：custom-builds/

2. 服务启动后无法访问UI

排查步骤：

# 检查compreface-ui服务日志
docker-compose logs compreface-ui
# 检查端口占用情况
netstat -tulpn | grep 8000

3. 数据库锁问题

当出现Waiting for changelog lock....日志时，需要清理数据库卷：

# 停止服务
docker-compose stop
# 删除数据库卷
docker volume rm compreface_postgres-data
# 重新启动
docker-compose up -d

完整故障排除指南：docs/Installation-options.md#Troubleshooting

高级配置

自定义模型

CompreFace支持多种人脸识别模型，可通过修改docker-compose.yml文件切换：

• MobileNet（默认，轻量级）
• FaceNet（高精度）
• ArcFace（高精度）

模型配置示例：custom-builds/Mobilenet/ 和 custom-builds/SubCenter-ArcFace-r100/

性能优化

通过修改.env文件调整JVM参数优化性能：

# 增加API服务内存
API_JAVA_OPTS=-Xmx8g
# 增加Core服务内存
CORE_JAVA_OPTS=-Xmx4g

配置文档：docs/Configuration.md

总结

通过本文介绍的两种安装方式，您可以在10分钟内搭建起一套功能完善的人脸识别系统。Docker Compose方式适合长期使用，单容器方式适合快速测试。

项目源码：embedding-calculator/src/ 包含核心人脸识别算法实现，感兴趣的开发者可以深入研究。

官方教程：docs/How-to-Use-CompreFace.md 提供了更详细的功能使用指南，建议安装完成后进一步学习。

如需扩展系统规模，可参考架构文档：docs/Architecture-and-scalability.md 进行分布式部署。