如何备份和恢复 InsightFace Server 的 /data SQLite 数据与人脸裁剪文件？

如何备份和恢复 InsightFace Server 的 /data SQLite 数据与人脸裁剪文件？

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

如果你在用 InsightFace Server 运行人脸比对与 1:N 检索，那么所有 Collection、Person、FaceSample 的 embedding、Collection 配置、Monitor 配置、API Key 哈希、加密的 RTSP 凭据，都持久化在容器内的/data里；启用了人脸裁剪存储时，112×112 的 bounding-box JPEG 裁剪图也保存在/data。/data是唯一的持久可写区域，而内存中的精确检索索引只是可随时丢弃的投影——重启后索引会从 SQLite 重建，SQLite 才是权威数据源（见 maintainer guide 第 9 节）。因此备份与恢复的对象就是/data：把其中的 SQLite 数据库和已启用的裁剪存储一起保存，就能在新容器或升级后的镜像上完整恢复。

本文适用于 Linux x86_64 上通过 Docker Compose 部署的 InsightFace Server（公开镜像0.2.0-cpu/0.2.0-cuda12），依据是 server/README.md 与 用户指南。

先弄清 /data 里有什么、/models 为什么不需要备份

Compose 定义了两个容器内路径：

• /data：命名卷（CPU 部署为insightface-simple-cpu-data，CUDA 部署为insightface-simple-cuda12-data），持久化，存放 SQLite 数据库（使用 WAL、外键、写锁）及按 Collection 可选开启的裁剪图存储；
• /models：只读绑定挂载自仓库的server/.models，存放模型包与签名许可文件。

用户指南第 9 节的要求是：持久化/data，/models只读挂载；第 15 节在升级场景中明确要求“保留/models和许可文件”。也就是说/models不是备份对象，升级或换机时只要模型目录和许可文件还在，恢复后模型契约（model_id、embedding 维度、预处理版本）依然成立。

文档原文给出的备份原则只有一条，但它覆盖了数据库与裁剪图两类文件：

Back up the SQLite database and configured crop storage together while writes are stopped or by using a SQLite-safe snapshot method. ——server/docs/user-guide.md 第 9 节

中文指南同节表述为：“停止写入后备份 SQLite 和裁剪图目录，或使用 SQLite 安全快照方式。”即两种被文档认可的方式二选一：

1. 停止写入后整体备份：先停掉 Server（不再有 enrollment/search/删除写入），再对/data内全部文件做拷贝。文档未给出具体快照命令，只给出原则；
2. SQLite 安全快照：不停写，用 SQLite 自身的快照机制（如 online backup API 或sqlite3的VACUUM INTO一类做法）拿到一致性库文件，再连同裁剪文件一起归档。

一个容易被忽略的点：裁剪存储（save_face_crops）默认关闭，且按 Collection 解析。如果当前 Collection 没有开启裁剪，/data里可能只有 SQLite 相关文件和/data/cursor.key等键文件；开启后才会写入 JPEG BLOB。备份时无需区分，整卷备份即可，但恢复后不要假设存在裁剪文件。

备份步骤（CPU 与 CUDA 部署通用）

前提：Server 已按 server/README.md 的 Quick start 跑起来，模型已安装到server/.models，并且至少完成过一次 Collection 创建与 Person 注册，这样备份内容才不是空库。

1. 确认当前部署用的是哪个 Compose 文件与卷名。CPU 用 server/deploy/compose.cpu.yml（端口 18097，卷insightface-simple-cpu-data），CUDA 用 server/deploy/compose.cuda12.yml（端口 18098，卷insightface-simple-cuda12-data）。

2. 按文档原则停止写入：停掉 Server 容器（docker compose ... down，不要带-v，见下文“危险操作”），或保持运行并改用 SQLite 安全快照。

3. 对数据卷做整体归档。卷名已在上一步确认，归档命令按你自己主机上可用的方式执行；文档只要求“SQLite 与裁剪存储一起备份”，不指定归档工具。示例（读者自行按卷名与目标路径执行）：

   # 以 CPU 部署为例；CUDA 部署把卷名换成 insightface-simple-cuda12-data docker run --rm -v insightface-simple-cpu-data:/data -v "$HOME/backups/ifs-20260911":/out alpine \ tar czf /out/ifs-data-20260911.tar.gz -C /data .

   该命令只读数据卷并写备份目录，不修改 Server 本身；卷名与时间戳标记按需替换。

4. 记录/models的状态：确认server/.models中有manifest.json和签名的MODEL.LICENSE。文档提供的校验方式是：

   docker compose -f server/deploy/compose.cpu.yml \ run --rm models verify buffalo_l

   models verify校验包身份、签名许可、有效期与当前授权状态。这一步不是备份动作，但恢复后核对模型契约要用到同一依据。

恢复步骤：新卷、原数据、验证契约

适用场景：换机部署、误操作后回滚、或按第 15 节“先用数据副本启动新镜像”的升级路径。

1. 不要覆盖正在使用的卷。文档要求“先用数据副本启动新容器”（start the new container against a copy first），即恢复应在一个独立的数据卷/目录上进行，验证通过后再作为正式数据使用。

2. 把第 3 步归档的内容还原到目标数据卷（或对应的持久化目录）中，保证/data下恢复出与备份一致的 SQLite 文件与裁剪存储；/models保持只读挂载不变。

3. 启动新容器：

   docker compose -f server/deploy/compose.cpu.yml up -d

   CUDA 部署同理换用compose.cuda12.yml。如果升级镜像，文档建议 Compose 命令加--pull never使用本地构建镜像。

4. 按文档给出的四项验证（原文：“check migrations and/v1/health, then verify the model contract and a known search”）：

   # CPU 部署 18097；CUDA 部署为 18098 curl -fsS http://127.0.0.1:18097/v1/health

   • /v1/health正常返回，说明存储与模型就绪（文档定义 readiness 在存储和模型就绪后才为 healthy）；
   • 在 Web UI 打开Dashboard或System，确认 service、database、model、provider 均就绪；CUDA 部署必须报告CUDAExecutionProvider，不会静默回退 CPU；
   • 核对恢复出的 Collection 的模型契约：如果 Collection 创建时用的是另一套模型，enrollment/search 会返回collection_model_mismatch（HTTP 409）——恢复后若出现该错误，说明/models与备份不匹配；
   • 用一张已知照片对已知 Person 做一次 Search，确认能命中，完成“known search”验证。搜索请求不能改变 Collection 固定的 search profile，查询用默认 limit 即可。

文档没有给出恢复成功的固定日志格式或数值判据，以上四项就是 server/docs/user-guide.md 第 15 节明确列出的检查项，逐项通过即视为恢复完成。

危险操作与边界限制

• docker compose down -v会永久删除命名数据卷。用户指南在 Quick start 与第 15 节两次强调：停止一律用不带-v的docker compose ... down；只有确认备份完成且不再需要该卷时才允许-v。
• API Key 与 RTSP 凭据都在卷里：API Key 以加盐 scrypt 哈希存储，RTSP 凭据用数据卷密钥加密在/data且 API 永不回传。备份了/data就同时备份了这些秘密；但注意，后续启动时传入不同的INSIGHTFACE_API_KEY会主动轮换该数据卷的活跃密钥——恢复后若要沿用旧密钥，必须使用原值。
• 逻辑删除不等于抹除：删除 FaceSample 只会从权威库删除记录，WAL、快照和备份中仍可能残留。文档原文明确“Logical deletion is not forensic erasure from WAL, snapshots, or backups”——如果合规要求彻底清除某条人脸数据，需要连同旧备份一起处理，这超出单次恢复的范围。
• 备份与数据保护义务：文档要求把数据卷及备份按生物识别数据（biometric data）保护，不记录图片、embedding 或密钥；Server 本身不提供内置 TLS、RBAC 或合规层，网络暴露时需由可信反向代理终止 HTTPS。
• 本阶段不支持的环境：Windows 容器、ARM64、Jetson、Kubernetes 均不在当前 0.2.0 发布范围内，本文的卷名与端口仅对应 CPU/CUDA 两个 Compose 文件。

下一步

恢复验证通过后，常规维护仍遵循同一原则：任何批量或破坏性操作（删除 FaceSample、强制删除非空 Collection、升级镜像）之前，先按第 9 节的方式再备一份/data。API 行为细节以 server/docs/api.md 为准，运维与架构细节以 server/docs/maintainer-guide.md 为准。

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