Docker로 InsightFace Server 배포

저장소 루트에서 한 가지 명령 블록을 실행하세요. 포함된 Compose 파일을 그대로 사용하며 내려받을 이미지는 해당 파일이 결정합니다. 최신 저장소가 있다면 git clone을 생략하세요.

시작 후 CPU는 http://SERVER:18097/, CUDA 12는 http://SERVER:18098/에 접속하세요. --accept-license는 모델 약관에 동의하는 옵션이므로 실행 전에 확인하세요.

Collections에서 employees 같은 안정적인 ID를 만듭니다. System이 제공하는 search profile을 선택하고 memory budget에 맞게 capacity를 정한 뒤 기본 raw cosine threshold 0.4로 시작합니다. Collection은 모델 identity, digest, embedding dimension, preprocessing과 detection profile contract에 고정됩니다.

People에서 Collection을 선택하고 선명한 JPEG, PNG 또는 WebP, BMP 한 장 이상으로 Person을 등록합니다. standard review는 사용 가능한 얼굴 하나만 허용하고 크기, confidence, 선명도, 밝기와 pose를 검사하므로 좋은 출발점입니다. batch는 일부만 성공할 수 있으므로 각 거부 이유를 확인하세요.

Search에서 같은 Collection을 선택하고 그 Person의 다른 사진을 업로드합니다. 결과는 raw cosine similarity 내림차순이며 Person score는 FaceSample 중 최고값입니다. similarity는 확률이 아닙니다. 일치하지 않는 경우 빈 목록이 정상 결과입니다.

새 배포에서는 위 모델 설치 명령 끝에 --enable-liveness를 추가하세요. 필요한 모델을 검증하고 첫 시작 전에 활성화 설정을 저장합니다.

실행 중인 서비스는 아래 해당 명령을 실행한 뒤 재시작하세요. 일반 설치와 models addons install liveness는 기능을 활성화하지 않습니다.

설치가 성공하면 실행 중인 서비스를 재시작하세요. up -d만으로 기존 컨테이너의 저장된 설정을 다시 읽지 않습니다. 기본값은 꺼짐이며 등록에는 별도 liveness_on_registration 설정이 있습니다.

Server source code와 Python SDK는 MIT license이지만 모델 파일과 weight는 그 MIT license의 적용 대상이 아닙니다. buffalo_l을 포함한 공개 InsightFace 모델 package는 별도 상용 허가가 없으면 일반적으로 비상업 학술 연구용으로 제한되며, 셀프 호스팅이 상용 모델 권한을 부여하지 않습니다.

설치하면 manifest.json과 서명된 MODEL.LICENSE가 server/.models에 기록됩니다. verify는 package identity, 서명, 유효기간과 현재 권한을 확인합니다. 이 license는 모델과 허용 용도를 나타내는 compliance credential이지 DRM이나 모델 파일 checksum이 아닙니다.

buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s, raccoon_l을 지원합니다. Server는 Raccoon의 검출과 인식만 사용하며 PrivateFrame verifier는 로드하지 않습니다. 모델 변경에는 호환되는 Collection과 재등록 또는 데이터 마이그레이션이 필요합니다.

제공 Compose는 격리 평가를 위해 인증이 꺼져 있습니다. 다른 사용자나 네트워크가 접근하기 전에 인증을 켜고 길고 무작위인 API Key를 배포 secret 환경에 설정한 다음 선택한 stack을 다시 시작합니다. Web UI는 현재 tab의 memory에만 Key를 보관할 수 있습니다.

신뢰하는 reverse proxy에서 HTTPS를 종료하고 광범위한 CORS 대신 필요한 origin만 허용하며 edge에 rate/body/time limit를 적용합니다. Docker, /data, /models와 backup 접근을 제한하고 이미지, embedding, RTSP credential 또는 API Key를 log에 남기지 마세요.

/data, 모델, server/config를 영구 보관하세요. 쓰기 중지 상태에서 SQLite와 얼굴 크롭을 함께 백업하거나 SQLite에 안전한 스냅샷을 사용하세요. 생체정보로 보호하고 네트워크 공개 전에 API 키 인증과 HTTPS를 활성화하세요.

시작한 stack에 맞는 전체 down 명령을 사용합니다. 일반 down은 container와 network를 제거해도 named data volume은 보존합니다. 절대로 -v를 붙이지 마세요. docker compose down -v는 해당 data volume을 영구 삭제합니다.

두 컨테이너는 root(0:0)로 실행되며 쓰기 가능한 단일 /models 마운트와 설정 디렉터리를 사용합니다. 모델 디렉터리와 addons/는 필요할 때 자동 생성됩니다. 호스트 UID/GID나 수동 권한 설정이 필요하지 않습니다. 컨테이너 루트 파일시스템은 계속 읽기 전용입니다.

쓰기를 중지하고 데이터베이스와 얼굴 크롭을 백업하세요. 배포 파일을 업데이트하고 사용자 설정을 병합하되 server/config/server.toml, 모델, 기존 프로젝트명과 볼륨명, 포트, API 키를 유지하세요. 해당 Compose 파일을 사용하고 사용자 지정 시 기존 오버라이드 파일과 프로젝트명을 함께 지정하세요.

두 이미지를 내려받아 Server를 다시 만드세요. restart는 새 이미지나 마운트를 적용하지 않습니다. 상태, 실행 공급자, 기존 데이터, 알려진 검색을 확인하세요. 같은 인식 모델과 embedding 계약이면 샘플이 유지되며 모델 변경은 별도 마이그레이션이 필요합니다. SDK도 같은 최신 저장소에서 업데이트하세요.

health부터 확인하고 System, 선택한 Compose의 container 상태와 log를 봅니다. CUDA는 Driver, GPU, 모델 Session, CUDAExecutionProvider, Provider audit 또는 warm-up이 실패하면 의도적으로 시작을 중단하며 CPU로 silent fallback하지 않습니다.

모든 응답에는 x-request-id가 있고 error body에는 request_id가 있습니다. 문제를 보고할 때 관련 log와 함께 보관하세요. 401 unauthorized는 대개 Key 누락 또는 교체, 409 collection_model_mismatch는 다른 모델 contract, 422 face_not_found는 사용 가능한 얼굴을 선택하지 못했음을 뜻합니다.

CUDA 배포는 CUDAExecutionProvider를 표시해야 합니다. 시작할 때 GPU, Driver, CUDA/cuDNN/ONNX Runtime, 실제 detector와 recognizer Session, Provider placement, warm-up을 검증하며 실패하면 CPU로 조용히 전환하지 않고 종료합니다.