# arcface

**Repository Path**: liuhuayun/arcface

## Basic Information

- **Project Name**: arcface
- **Description**: 虹软人脸sdk集成
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArcFace Pro - 人脸识别管理平台

基于虹软 (ArcSoft) ArcFace Pro v5.0 算法引擎构建的企业级人脸识别服务系统，提供人脸检测、注册、检索、比对、活体检测、属性分析等功能，配套 Vue 3 管理后台。同时提供无需认证的 OpenAPI 接口供外部业务系统调用。

## 技术架构

```
arcface-admin/          # Vue 3 前端管理面板
    ├── Vue 3.5 + TypeScript + Vite 8
    ├── Element Plus 2.x (UI 组件库)
    ├── ECharts 6.x (图表)
    ├── Pinia 4.x (状态管理)
    ├── Vue Router 5.x (路由)
    └── Axios (HTTP 客户端)

arcface-api/            # Spring Boot 3.2 REST API 服务
arcface-common/         # 公共模块 (枚举、异常、统一返回)
arcface-dao/            # 数据访问层 (MyBatis-Plus 3.5 + PostgreSQL)
arcface-sdk/            # ArcFace SDK 封装 (引擎池、检测/特征/比对/检索等服务)
```

### 核心依赖

| 组件 | 版本 |
|------|------|
| Java | 17 |
| Spring Boot | 3.2.0 |
| MyBatis-Plus | 3.5.5 |
| Sa-Token | 1.37.0 |
| SpringDoc OpenAPI | 2.3.0 |
| Hutool | 5.8.25 |
| PostgreSQL | 16 |
| ArcFace SDK | 1.0.0.1 |
| Vue | 3.5 |
| Element Plus | 2.14 |
| ECharts | 6.1 |
| TypeScript | ~6.0 |

## 功能特性

### 人脸业务
- **人脸检测** — 检测图片中人脸位置及数量，支持质量评分
- **人脸注册** — 将人脸特征录入指定库
- **人脸检索 (1:N)** — 在指定库中搜索相似人脸，返回 Top-K 结果（支持特征值检索）
- **人脸比对 (1:1)** — 两张人脸图片相似度比较
- **活体检测** — RGB 活体检测，防止照片/视频攻击
- **属性检测** — 年龄、性别、口罩检测
- **人脸更新** — 按 ID 或按名称更新已注册人员的人脸特征
- **人脸删除** — 按 ID 或按名称删除已注册人员（含引擎特征和数据库记录）
- **特征提取** — 提取人脸特征值（hex 编码）

### 开放 API (OpenAPI)
提供无需认证的对外接口：
- `POST /api/open/register` — 人脸注册
- `POST /api/open/recognize` — 人脸识别 (1:N)，返回 Top-K 匹配结果（不含图片数据）
- `POST /api/open/recognizeByFeature` — 根据特征值 hex 检索
- `PUT /api/open/update` — 按名称更新人脸
- `DELETE /api/open/delete` — 按名称删除人员
- `POST /api/open/attribute` — 属性检测
- `POST /api/open/feature` — 提取特征值
- `GET /api/open/image` — 获取人员照片

### 系统管理
- **仪表盘** — 系统概览统计（库数、人脸数、今日检索数）
- **人脸库管理** — 创建/删除/启停人脸库，查看库内人员
- **用户管理** — 系统用户增删改查、重置密码、修改密码
- **操作日志** — 记录所有人脸操作日志，支持多条件筛选

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- Node.js 18+ / npm 9+
- PostgreSQL 16

### 1. 数据库初始化

```bash
psql -h <host> -U <user> -d s_arcface -f arcface-docs/script/sql/s_arcface_20260812_v0.5.sql
```

数据库连接信息见各环境配置文件（`application-dev.yml` / `application-prod.yml` / `application-test.yml`）。初始管理员账号 `admin`，密码 `admin123`。

### 2. 启动后端服务

```bash
# 编译安装（首次或依赖变更时）
mvn clean install -DskipTests

# 启动 API 服务（默认 dev 环境，端口 9705）
cd arcface-api
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# 或
java -jar target/arcface-api-0.5.0.jar --spring.profiles.active=dev
```

后端 API 运行在：`http://localhost:9705`

### 3. 启动前端管理面板

```bash
cd arcface-admin
npm install
npm run dev
```

前端开发服务器运行在：`http://localhost:9706`

开发模式下 API 请求通过 Vite 代理自动转发到 `http://127.0.0.1:9705`。

### 4. 生产构建

```bash
cd arcface-admin
npm run build
```

构建产物在 `arcface-admin/dist/`，通过 Docker + Nginx 部署（见 `arcface-admin/Dockerfile`）。

## 项目结构

```
.
├── arcface-admin/            # Vue 3 前端
│   ├── Dockerfile
│   ├── nginx.conf
│   └── src/
│       ├── api/              # API 接口封装
│       │   ├── index.ts      # Axios 实例配置
│       │   ├── auth.ts       # 登录/登出/验证码
│       │   ├── face.ts       # 人脸业务
│       │   ├── library.ts    # 人脸库管理
│       │   └── user.ts       # 用户管理
│       ├── router/           # 路由配置 (含 Auth Guard)
│       ├── stores/           # Pinia 状态管理
│       └── views/            # 页面组件
│           ├── Login.vue     # 登录（SVG 验证码 + 动画）
│           ├── Layout.vue    # 布局（顶栏 + 侧栏）
│           ├── Dashboard.vue # 仪表盘（ECharts 统计）
│           ├── face/         # 人脸业务 (注册/检索/比对/活体/属性)
│           ├── library/      # 人脸库管理 (列表/详情)
│           └── system/       # 系统管理 (用户/日志)
├── arcface-api/              # Spring Boot REST API
│   └── src/main/java/com/arcface/api/
│       ├── controller/       # Auth | Captcha | Face | OpenApi | Library | Person | User | Dashboard | Log | Test
│       ├── service/          # Auth | Captcha | Face | Library | User
│       ├── dto/              # 请求/响应 DTO
│       └── config/           # 全局异常处理 | Sa-Token 配置 | Swagger 配置 | BasicAuth 过滤器
├── arcface-common/           # 公共模块
│   └── src/main/java/com/arcface/common/
│       ├── enums/            # LibraryStatus | OperationType | PersonStatus
│       ├── exception/        # BusinessException
│       └── result/           # Result\<T\> | ResultCode
├── arcface-dao/              # 数据访问层
│   └── src/main/java/com/arcface/dao/
│       ├── entity/           # FaceLibrary | Person | SysUser | FaceLog
│       ├── mapper/           # MyBatis-Plus Mapper 接口
│       ├── handler/          # JsonbTypeHandler | MyMetaObjectHandler
│       └── config/           # MybatisPlusConfig（分页插件）
├── arcface-sdk/              # ArcFace SDK 封装
│   └── src/main/java/com/arcface/sdk/
│       ├── config/           # ArcFaceProperties 配置类
│       ├── pool/             # 引擎池管理 (EnginePool | EnginePoolImpl | EngineWrapper)
│       └── service/          # 人脸检测/特征/比对/检索/活体/属性/图片服务
├── arcface-docs/             # 文档与运维
│   ├── doc/                  # ArcFace SDK 开发者指南 / 服务协议 / 隐私政策
│   ├── samplecode/           # SDK 独立测试示例代码
│   └── script/               # deploy.sh / config/ (外部化配置) / sql/ (建表脚本) / 部署说明 / libstdc++.so.6.0.26
└── pom.xml                   # Maven 父 POM (version: 0.5.0)
```

## API 接口概览

### 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 用户登录（需验证码） |
| POST | `/api/auth/logout` | 用户登出 |
| GET | `/api/auth/userinfo` | 获取当前用户信息 |
| GET | `/api/auth/captcha` | 获取图形验证码 (SVG) |

### 人脸业务（需登录）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/face/detect` | 人脸检测 |
| POST | `/api/face/register` | 人脸注册 |
| POST | `/api/face/search` | 人脸检索 (1:N) |
| POST | `/api/face/compare` | 人脸比对 (1:1) |
| POST | `/api/face/liveness` | 活体检测 |
| POST | `/api/face/attribute` | 属性检测 |
| PUT | `/api/face/{id}` | 更新已注册人员人脸 |
| DELETE | `/api/face/{id}` | 删除已注册人员 |
| GET | `/api/face/image/{personId}` | 获取人员照片 |

### 开放 API（无需认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/open/register` | 人脸注册 |
| POST | `/api/open/recognize` | 人脸识别 (1:N) |
| POST | `/api/open/recognizeByFeature` | 特征值 1:N 检索 |
| PUT | `/api/open/update` | 按名称更新人脸 |
| DELETE | `/api/open/delete` | 按名称删除人员 |
| POST | `/api/open/attribute` | 属性检测 |
| POST | `/api/open/feature` | 提取特征值 |
| GET | `/api/open/image` | 获取人员照片 |

### 系统管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/dashboard/stats` | 仪表盘统计 |
| GET | `/api/library` | 人脸库列表 (分页) |
| POST | `/api/library` | 创建人脸库 |
| GET | `/api/library/{id}` | 人脸库详情 |
| PATCH | `/api/library/{id}/status` | 启停人脸库 |
| DELETE | `/api/library/{id}` | 删除人脸库 |
| GET | `/api/person` | 人员列表 (按库分页) |
| GET | `/api/user` | 用户列表 (分页) |
| POST | `/api/user` | 创建用户 |
| GET | `/api/user/{id}` | 用户详情 |
| PUT | `/api/user/{id}` | 更新用户 |
| PUT | `/api/user/{id}/reset-password` | 重置密码 |
| PUT | `/api/user/change-password` | 修改密码 |
| DELETE | `/api/user/{id}` | 删除用户 |
| GET | `/api/log` | 操作日志 (分页+筛选) |

### 测试接口（无需认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/test/activate` | SDK 激活测试 |
| POST | `/api/test/device-info` | 设备信息查询 |
| POST | `/api/test/init` | 引擎初始化测试 |
| POST | `/api/test/detect` | 人脸检测测试 |

### 接口文档

- Swagger UI：`http://localhost:9705/swagger-ui.html`
- OpenAPI JSON：`http://localhost:9705/v3/api-docs`
- Swagger Basic Auth：用户名 `comtom`，密码 `Comtom@2026`

## 数据库表

| 表名 | 说明 |
|------|------|
| `face_library` | 人脸库 (name, code, engine_path, face_count, max_face_count, status) |
| `person` | 注册人员 (library_id, name, search_id, face_feature_hex, face_image, face_image_thumbnail, gender, status) |
| `sys_user` | 系统用户 (username, password, nickname, role, status, last_login_at) |
| `face_log` | 操作日志 (library_id, person_name, operation, result, score, detail JSONB, operator_id) |

> **person 表**：人脸注册照片以 BYTEA 二进制存储于 `face_image`，缩略图以 Base64 存储于 `face_image_thumbnail` 供前端预览。

## 认证与鉴权

### 认证链路

- Sa-Token JWT 简单模式（无状态）
- Token 名：`Authorization`（无 Bearer 前缀，直接放 Header）
- 超时时间：86400 秒（24 小时）
- 白名单路径：`/api/auth/login`、`/api/auth/captcha`、`/api/open/**`、`/api/test/**`、Swagger 相关路径
- 登录需要验证码（纯 SVG，无 AWT 依赖，60s TTL）
- 密码使用 BCrypt 加密（Hutool）

### 权限模型

简单角色模型：
- `sys_user.role`：`ADMIN`（超级管理员）/ `OPERATOR`（操作员）
- 目前仅做登录状态校验，未实现细粒度 RBAC

## 引擎池设计

- **每库一个 FaceEngine**：`ConcurrentHashMap<Long, EngineWrapper>` 存储
- **并发控制**：每个 `EngineWrapper` 持有 `ReentrantLock`，引擎操作必须 `lock()/unlock()`
- **平台兼容**：Windows 环境跳过 SDK 初始化，仅 Linux 生产环境初始化引擎
- **启动恢复**：恢复所有 RUNNING 状态的人脸库，重新注册 ACTIVE 人员的 hex 特征
- **引擎数据持久化**：引擎数据目录 `${engineDataRoot}/lib_{code}`，特征以 hex 存储于 `person.face_feature_hex`

## 部署

### 服务端口

| 服务 | 端口 | 说明 |
|------|:----:|------|
| arcface-api (Spring Boot) | 9705 | 后端 REST API |
| arcface-admin (Nginx) | 9706 | 前端静态页面，反向代理 `/api` → 9705 |

### 后端部署

使用 `arcface-docs/script/deploy.sh`：

```bash
# CentOS 7 首次部署：初始化 C++ 标准库 + 下载 ArcFace SDK
./deploy.sh init

# 启动/停止/重启
./deploy.sh start
./deploy.sh stop
./deploy.sh restart
```

- JAR：`arcface-api-0.5.0.jar`（`mvn package` 时由 antrun 插件自动拷贝到 `arcface-docs/script/`）
- JVM：`-Xms512m -Xmx1024m`（可通过 `JAVA_OPTS` 环境变量覆盖）
- Profile：默认 `dev`，可通过 `-p prod|test` 或 `SPRING_PROFILES_ACTIVE` 覆盖
- 外部化配置：`arcface-docs/script/config/`（通过 `--spring.config.additional-location` 加载）
- LD_LIBRARY_PATH：`/usr/local/libs/cpp:/usr/local/libs/Linux`

### 前端 Docker 部署

```bash
docker run -itd --name sport-arcface-web --restart always --net host registry.comtom.cn:2443/ai-sport-dev/arcface-admin:<TAG>
```

环境变量：`PORT`（默认 9706），`BACKEND_PROXY_SOCKET`（默认 `http://127.0.0.1:9705`）。

### CI/CD

GitLab CI（`.gitlab-ci.yml`，仅手动/web触发）：
1. **compile**：Node 22，`npm install` + `npm run build`
2. **build_image**：Docker buildx 多平台（amd64/arm64），推送到 Harbor
3. **notify**：企业微信 Webhook 通知

镜像 Tag 格式：`{APP_VER}-alpha.{PIPELINE_IID}-{COMMIT_SHORT_SHA}`

## 许可证

本项目基于虹软 ArcFace SDK 开发，使用虹软 SDK 须遵守 [虹软视觉开放平台服务协议](arcface-docs/doc/虹软视觉开放平台服务协议.pdf)。

## 项目接口人

- 作者：comtom liuhy
- 团队：康跑智能科技（湖南）