使用 Docker 部署 InsightFace Server

选择一组命令，在仓库根目录执行。直接使用仓库提供的 Compose 文件，拉取的镜像由该文件指定。已有最新 checkout 时，跳过 git clone 并进入仓库根目录。

启动后，CPU 访问 http://SERVER:18097/，CUDA 12 访问 http://SERVER:18098/。安装命令使用 --accept-license 接受模型条款，执行前请先阅读并确认接受。

在 Collections 中创建 employees 之类的稳定 ID。选择系统页实际提供的 search profile，按内存预算设置 capacity，并从默认 raw cosine threshold 0.4 开始。Collection 会固定绑定模型身份、digest、特征维度、预处理版本和检测配置契约。

在 People 中选择该 Collection，用一张或多张清晰的 JPEG、PNG、WebP 或 BMP 注册 Person。standard review 很适合作为起点：它要求恰好一张可用脸，并检查尺寸、检测置信度、清晰度、亮度和姿态。批量注册允许部分成功，请逐张查看拒绝原因，不要盲目重传整批。

在 Search 中选择同一 Collection，上传该 Person 的另一张照片。结果按 raw cosine similarity 降序排列；一个 Person 的分数取其所有 FaceSample 的最高分。similarity 不是概率。没有匹配时返回空列表，仍然是成功响应。

全新部署只需在上方模型安装命令末尾加上 --enable-liveness。安装器会校验所需模型，并在首次启动前保存启用设置。

已有部署使用下方对应命令安装，然后重启服务。普通模型安装及 models addons install liveness 仅安装模型，不会自动启用活体。

安装成功后重启正在运行的服务。仅执行 up -d 不会让已有容器重新加载保存的设置。活体默认关闭，注册流程另有 liveness_on_registration 开关。

Server 源代码和 Python SDK 采用 MIT 许可，但模型文件与权重不在该 MIT 许可范围内。包括 buffalo_l 在内的 InsightFace 公开模型包，除非 InsightFace 另行授予商业许可，通常仅限非商业学术研究；自托管 Server 并不自动获得模型的商业使用权。

安装会把 manifest.json 和签名 MODEL.LICENSE 写入 server/.models。verify 会校验包身份、许可签名、有效期和当前授权。许可用于标识模型和允许的用途，是合规凭据，不是 DRM，也不是模型文件校验和。

安装器支持 buffalo_l、buffalo_m、buffalo_s、buffalo_sc、antelopev2、raccoon_s 和 raccoon_l。Server 仅使用 Raccoon 的检测与识别模型，不加载 PrivateFrame verifier。切换模型需要匹配的 Collection，并重新注册或单独迁移数据。

随附 Compose 为隔离评估场景默认关闭身份验证。在任何其他用户或网络能访问服务之前，启用身份验证，在部署的 secret 环境中设置足够长的随机 API Key，并用这些变量重新启动所选 Compose。Web UI 可仅在当前浏览器标签页的内存中保存 Key。

在可信反向代理终止 HTTPS；不要开放宽泛 CORS，只允许所需 origin；在入口设置速率、请求体和超时限制；严格控制 Docker、/data、/models 和备份的访问。绝不要记录图像、特征、RTSP 凭据或 API Key，所有人脸材料都应按生物识别数据保护。

持久化保存 /data、模型和 server/config。停止写入后一起备份 SQLite 与已配置的人脸裁剪图，或使用 SQLite 安全快照。目录与备份均按生物特征数据保护；对外开放前启用 API key 认证和 HTTPS。

使用与你所启动环境一致的完整 down 命令。普通 down 会移除容器和网络，但保留具名数据库卷。绝不要追加 -v：docker compose down -v 会永久删除这个具名数据卷。

默认容器以 root（0:0）运行，使用单个可写 /models 挂载和可写配置目录。Compose 自动创建模型根目录，安装插件时按需创建 addons/，无需传入宿主机 UID/GID 或手动设置权限。容器根文件系统仍为只读。

先停止写入并备份数据库及已保存的裁剪图。更新仓库部署文件、合并自定义设置，同时保留 server/config/server.toml、模型、原项目名及数据卷名、端口和 API key。下方使用对应的原始 Compose 文件；自定义部署需带上原有覆盖文件和项目名。

拉取两个服务的镜像并重新创建 Server。仅 restart 不会应用新镜像或挂载变更。检查健康状态、执行提供程序、已有 Collection 和 Person，并执行一次已知图片搜索。保持识别模型与 embedding 契约不变即可保留样本；切换模型需单独迁移。Python SDK 也从同一份最新 checkout 更新。

先检查 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 表示未选出可用脸。

CUDA 部署必须显示 CUDAExecutionProvider。启动时会检查 GPU、Driver、CUDA/cuDNN/ONNX Runtime、真实检测与识别 Session、Provider 放置和 warm-up 推理；任何一项失败都会终止，而不会静默回退到 CPU。