如何从源码构建 InsightFace Server 镜像并用本地镜像启动服务？-育师

如何从源码构建 InsightFace Server 镜像并用本地镜像启动服务？

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

InsightFace Server 是一个自托管的人脸识别服务，把 SCRFD 检测、ArcFace 特征提取、SQLite 存储和 Web UI 打包在一个容器里，提供/v1REST API 和 Web 界面。如果你不想直接拉取官方发布镜像，而是想在完整仓库上修改代码后自行构建镜像、再用构建出的本地镜像启动并验证服务，这篇文章给出仓库文档中的完整操作路径。适用环境是 Linux x86_64 主机，需要 Docker Engine 和 Docker Compose；主机上不需要安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN。

构建前提：完整的仓库 checkout

Dockerfile 会从两个位置拷贝代码：server/全部内容和python-package/insightface/下的部分推理模块（app、model_zoo、utils等），所以完整的 insightface 仓库就是构建上下文，不能只拷server/子目录到别处构建。

server/Makefile 中的build-cpu和build-cuda12目标执行的docker build使用了--platform linux/amd64，构建上下文是..（即仓库根目录），产物分别打上标签：

CPU 镜像：ghcr.io/deepinsight/insightface-server:0.2.0-cpu
CUDA 12 镜像：ghcr.io/deepinsight/insightface-server:0.2.0-cuda12

两个目标还会透传代理相关的 build args 和INSIGHTFACE_SERVER_VERSION（默认0.2.0）。构建使用固定的基础镜像和锁定的依赖文件（如 requirements.cpu.lock），但仍需要网络访问来下载这些输入。

构建过程里 Dockerfile 还会先编译server/native/search下的原生检索库（CPU 版编译libifs_search_cpu.so，CUDA 版编译libifs_search_cuda.so），并运行 ctest 测试，所以构建机上的时间会比普通镜像构建长。

第一步：从源码构建镜像

在仓库根目录执行：

# 构建 CPU 镜像 make -C server build-cpu # 或构建 CUDA 12 镜像（可选分支，需要 NVIDIA GPU） make -C server build-cuda12

如果走 CUDA 分支，主机需要额外满足：受支持的 NVIDIA GPU、NVIDIA 驱动和 NVIDIA Container Toolkit。用户指南给出的驱动要求是：Turing、Ampere、Ada、Hopper 需要 R535 或更新的驱动；Blackwell 和 RTX 50 系列需要 570.26 或更新；新部署建议 R580 或更新。CUDA 镜像内已经包含 CUDA Runtime 12.9.1、cuDNN 9.24.0、Python 3.11 和onnxruntime-gpu==1.27.0，这些都不需要装在主机的容器环境之外。

构建完成后可以用docker images确认存在0.2.0-cpu/0.2.0-cuda12标签的本地镜像。

第二步：用本地镜像安装模型

发布镜像和本地构建的镜像都不包含模型文件。模型通过 Compose 里的models一次性服务安装到仓库下的server/.models目录（compose 文件将其只读挂载为容器内/models）。

关键点是加上--pull never，确保这一步用的是你刚构建的本地镜像，而不是从 registry 拉同名标签的公共镜像：

# CPU 路径 docker compose -f server/deploy/compose.cpu.yml \ run --rm --pull never models install buffalo_l --accept-license # CUDA 12 路径：把 compose.cpu.yml 换成 compose.cuda12.yml

install会在下载前显示模型许可条款；不带--accept-license时工具只打印条款并退出，不下载。安装成功后会在server/.models生成manifest.json和带签名的MODEL.LICENSE。支持的公开模型包有buffalo_l（det_10g.onnx+w600k_r50.onnx）、buffalo_m、buffalo_sc和antelopev2。可以用models verify buffalo_l校验包的标识、签名许可和有效期。

注意许可限制：公开的 InsightFace 预训练模型（包括buffalo_l）仅可用于非商业研究用途，商业使用需要单独授权。

第三步：启动服务

# CPU docker compose -f server/deploy/compose.cpu.yml \ up -d --no-build --pull never # CUDA 12（把 compose 文件换成 compose.cuda12.yml，参数相同）

--no-build --pull never两个参数共同保证 Compose 直接使用本地构建的镜像。Compose 文件里端口映射为 CPU 主机端口18097、CUDA 主机端口18098，都映射到容器内8080。数据持久化在名为insightface-simple-cpu-data（或insightface-simple-cuda12-data）的命名卷中，配置文件 server/config/server.toml 被只读挂载到/etc/insightface/server.toml。

验证构建结果

健康检查：
```
# CPU curl -fsS http://127.0.0.1:18097/v1/health # CUDA 12 curl -fsS http://127.0.0.1:18098/v1/health
```
Dockerfile 中配置的容器级 HEALTHCHECK 也是每 30 秒请求一次http://127.0.0.1:8080/v1/health，连续失败会在docker ps中反映出来。
System 页面：打开http://SERVER:18097/（CPU）或http://SERVER:18098/（CUDA），先查看Dashboard或System。服务、数据库、模型和 provider 都必须处于就绪状态后才能注册数据。CUDA 部署必须报告CUDAExecutionProvider——每次启动时 Server 会检查 GPU 型号、Compute Capability、驱动版本、实际 CUDA/cuDNN/ORT 版本、detector 和 recognizer 的真实 Session 以及真实 warm-up 推理，任一检查失败进程直接终止，不会静默回退到 CPU。
功能验证：按用户指南的首次工作流，依次在 Web UI 创建 Collection、注册一个至少有一张清晰照片的 Person，然后用该 Person 的另一张照片做Search。搜索无匹配时返回空列表，这是正常成功结果，不是服务故障。

限制与后续操作

配置变更：server.toml 只在启动时读取一次，改完（例如[detection]的input_sizes、threshold、nms_threshold）必须重启容器才生效；没有运行时配置 API。
对外暴露前必须开启认证：仓库自带的 Compose 文件默认INSIGHTFACE_AUTH_ENABLED=false，只适合隔离评估。对外提供服务前，在启动前导出INSIGHTFACE_AUTH_ENABLED=true和INSIGHTFACE_API_KEY再执行up -d。API key 以哈希形式存储，之后启动时换一个 key 会主动轮换该数据卷上的有效密钥。
停止与数据：用docker compose ... down（不带-v）保留数据库卷；down -v会永久删除命名数据卷。升级或批量维护前先对/data做 SQLite 安全快照。
能力边界：当前发布是 0.2.0，仅支持 Linux x86_64；不实现 CUDA 11、Jetson、ARM64、Windows 容器、TensorRT、Kubernetes 或多租户授权。