使用 Docker 部署 InsightFace Server
在 CPU 或 CUDA 上自托管 InsightFace Server，安装并验证授权模型，完成首次精确 1:N 搜索，并配置认证与持久化数据保护。
你将完成什么
InsightFace Server 把人脸检测、比对、注册、精确 1:N 人员搜索、多语言 Web UI、REST API、SQLite 和本地推理封装为一个自托管服务。图像、特征、模型和索引均可留在你控制的基础设施中。
本快速入门从完整的 InsightFace 仓库开始，带你完成模型安装和第一次有效搜索，同时覆盖正式部署前必须处理的边界：模型授权、身份验证、HTTPS、数据持久化、安全停止，以及 CUDA 的快速失败诊断。
Server 是面向常见人脸识别流程、重视隐私的自托管方案，但不是兼容 AWS Rekognition 的替代品；它不实现 AWS IAM、SigV4、Region 语义，也不内置 TLS、用户账户或 RBAC。
开始之前
- Linux x86_64 主机上的完整 InsightFace 仓库，以及 Docker Engine 和 Docker Compose。
- CUDA 12 还需要受支持的 NVIDIA GPU、NVIDIA Driver 和 NVIDIA Container Toolkit；主机无需安装 CUDA Toolkit、cuDNN、ONNX Runtime、Python 或 OpenCV。
- 拉取镜像和安装模型时需要联网；模型包就绪后，Server 的正常启动可保持离线。
- 处理生物识别数据的合法授权，以及关于同意、访问、留存、删除、备份和事件响应的书面制度。
1. 选择 CPU 或 CUDA 并安装模型
在完整 InsightFace 仓库的根目录执行命令，并只选择一套 Compose。CPU 最适合快速评估，对外端口为 18097；CUDA 使用 18098，需要兼容的 NVIDIA Driver 和 NVIDIA Container Toolkit，但不需要在主机安装 CUDA 或 cuDNN。
下面的命令特意使用非交互式 --accept-license，并在安装后立即校验 buffalo_l。只有在你的组织已经阅读并接受模型条款后才应执行。安装工具还支持 buffalo_m、buffalo_sc 和 antelopev2。
- Turing、Ampere、Ada、Hopper 需要 R535 或更新 Driver；Blackwell 与 RTX 50 系列需要 570.26 或更新版本。新部署建议采用稳定的 R580 或更新 Driver。
- 公开镜像不包含模型、客户数据、API Key 或生产配置。
- 一次部署不要混用 CPU 与 CUDA Compose 文件；二者的镜像、端口、Provider 和具名数据卷相互独立。
mkdir -p server/.models
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
run --rm models verify buffalo_lmkdir -p server/.models
docker compose -f server/deploy/compose.cuda12.yml pull
docker compose -f server/deploy/compose.cuda12.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cuda12.yml \
run --rm models verify buffalo_l2. 明确模型许可边界
Server 源代码和 Python SDK 采用 MIT 许可，但模型文件与权重不在该 MIT 许可范围内。包括 buffalo_l 在内的 InsightFace 公开模型包，除非 InsightFace 另行授予商业许可，通常仅限非商业学术研究；自托管 Server 并不自动获得模型的商业使用权。
安装会把 manifest.json 和签名 MODEL.LICENSE 写入 server/.models。verify 会校验包身份、许可签名、有效期和当前授权。许可用于标识模型和允许的用途，是合规凭据，不是 DRM，也不是模型文件校验和。
- 不传 --accept-license 时，工具只展示条款并退出，不会下载模型。
- 模型、manifest 和许可文件应一并保留；正常运行时将 /models 只读挂载。
- 商业使用，或部署范围未被公开模型条款明确覆盖时，请在使用前联系 InsightFace。
3. 启动服务并确认就绪
只启动你刚安装的那套 Compose。CPU 访问 http://SERVER:18097/，CUDA 访问 http://SERVER:18098/。health 请求确认 HTTP 服务可响应后，在注册数据前继续查看仪表盘或系统，确认服务、数据库、模型和执行 Provider 均已就绪。
CUDA 部署必须显示 CUDAExecutionProvider。启动时会检查 GPU、Driver、CUDA/cuDNN/ONNX Runtime、真实检测与识别 Session、Provider 放置和 warm-up 推理；任何一项失败都会终止，而不会静默回退到 CPU。
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/healthdocker compose -f server/deploy/compose.cuda12.yml up -d
curl -fsS http://127.0.0.1:18098/v1/health4. 完成第一次 Collection → Person → Search
在 Collections 中创建 employees 之类的稳定 ID。选择系统页实际提供的 search profile，按内存预算设置 capacity，并从默认 raw cosine threshold 0.4 开始。Collection 会固定绑定模型身份、digest、特征维度、预处理版本和检测配置契约。
在 People 中选择该 Collection，用一张或多张清晰的 JPEG、PNG 或 WebP 注册 Person。standard review 很适合作为起点：它要求恰好一张可用脸，并检查尺寸、检测置信度、清晰度、亮度和姿态。批量注册允许部分成功，请逐张查看拒绝原因，不要盲目重传整批。
在 Search 中选择同一 Collection，上传该 Person 的另一张照片。结果按 raw cosine similarity 降序排列；一个 Person 的分数取其所有 FaceSample 的最高分。similarity 不是概率。没有匹配时返回空列表，仍然是成功响应。
- 默认不保留原始上传。可选的人脸存储仅保存缩放为 112×112 的 bounding-box JPEG crop，不是原图，也不是识别模型使用的对齐输入。
- 接受的样本会先提交到 SQLite，再在成功响应前加入内存中的精确索引；重启后索引从 SQLite 重建。
- Detect 没有检测到人脸是合法的空结果；Compare 任一侧没有可用脸时返回 422 face_not_found。
5. 对外联网前先做好安全配置
随附 Compose 为隔离评估场景默认关闭身份验证。在任何其他用户或网络能访问服务之前，启用身份验证，在部署的 secret 环境中设置足够长的随机 API Key，并用这些变量重新启动所选 Compose。Web UI 可仅在当前浏览器标签页的内存中保存 Key。
在可信反向代理终止 HTTPS；不要开放宽泛 CORS，只允许所需 origin；在入口设置速率、请求体和超时限制；严格控制 Docker、/data、/models 和备份的访问。绝不要记录图像、特征、RTSP 凭据或 API Key，所有人脸材料都应按生物识别数据保护。
- 第一阶段只有一个不分角色的 API Key，不是多租户授权系统，也没有内置用户账户或 RBAC。
- 之后使用不同 INSIGHTFACE_API_KEY 启动同一数据卷，会有意轮换当前有效 Key。
- Server 不内置 TLS 或法律合规层；合法处理和部署控制仍由运营方负责。
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cpu.yml up -dexport INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cuda12.yml up -d6. 持久化、备份并安全停止
/data 中的 SQLite 是持久的事实来源，内存中的精确搜索索引可随时重建。Compose 只读挂载模型目录，并把 /data 保存在具名 volume 中。请在停止写入时，或使用 SQLite-safe snapshot 方法，同时备份数据库和已配置的人脸 crop 存储。
使用与你所启动环境一致的完整 down 命令。普通 down 会移除容器和网络，但保留具名数据库卷。绝不要追加 -v：docker compose down -v 会永久删除这个具名数据卷。
- 升级前创建安全快照，保留 /models 及许可文件，并先用数据副本测试新镜像。
- 重启或升级后检查 migration、/v1/health、模型契约以及一条已知搜索。
- 删除 FaceSample 会移除其特征和可选 crop；删除非空 Collection 需要明确 force 确认。
docker compose -f server/deploy/compose.cpu.yml downdocker compose -f server/deploy/compose.cuda12.yml down7. 定位启动与请求故障
先检查 health，再查看系统页、所选 Compose 的容器状态和日志。CUDA 在 Driver、GPU、模型 Session、CUDAExecutionProvider、Provider 审计或 warm-up 失败时会主动终止启动；不会静默回退到 CPU。
每个响应都带 x-request-id，错误正文也包含 request_id。报告问题时请连同相关时间段的日志保留该标识。401 unauthorized 通常表示当前标签页没有 Key 或 Key 已轮换；409 collection_model_mismatch 表示 Collection 属于其他模型契约；422 face_not_found 表示未选出可用脸。
- 确认系统页显示的 CPUExecutionProvider 或 CUDAExecutionProvider 与所选 Compose 文件一致。
- 确认 server/.models 内存在已校验包和签名许可，且 /models 为只读挂载。
- CUDA 故障应修复主机 Driver、GPU 可见性或 NVIDIA Container Toolkit，而不是等待 CPU 回退。
curl -fsS http://127.0.0.1:18097/v1/health
docker compose -f server/deploy/compose.cpu.yml ps
docker compose -f server/deploy/compose.cpu.yml logs --tail=200 servercurl -fsS http://127.0.0.1:18098/v1/health
docker compose -f server/deploy/compose.cuda12.yml ps
docker compose -f server/deploy/compose.cuda12.yml logs --tail=200 server