简体中文

FC Face Service is a self-hosted face-recognition REST service for CPR. It combines SeetaFace6 for on-host face detection, alignment, feature extraction, and silent liveness checks; pgvector for organization-isolated 1:N search; and Alibaba Cloud Facebody as a cautious 1:1 fallback.

Repository short description: Self-hosted face recognition REST service powered by SeetaFace6, pgvector, and Alibaba Cloud Facebody fallback.

This service moves the Android-side face-login capability into a backend service. Its state is isolated within this service: pgvector stores face embeddings and SeetaFace6 models are mounted at runtime. It does not access or modify the legacy business backend database.

Android (public)
  │ probe OSS key + org_id
  ▼
Business backend (private)
  │ internal REST call
  ▼
FC Face Service (default: 127.0.0.1:8090)
  ├─ fetches probe images from OSS
  ├─ SeetaFace6: detect, align, silent-liveness gate, and 512-dimensional embedding
  ├─ pgvector: organization-scoped cosine Top-1 search
  └─ Alibaba Cloud Facebody: 1:1 review for uncertain results

• Organization isolation: every embedding has an org_id; searches are constrained to that organization.
• Liveness protection: a live probe must be classified as REAL before matching. SPOOF and FUZZY probes are rejected or reviewed according to configuration.
• Fallback: Facebody is called only for a score in the configured fuzzy interval or when the local engine cannot extract an embedding.

cmd/server/main.go            Application entry point
internal/config               Environment-based configuration
internal/engine               Engine interface, SeetaFace6 CGO implementation, and non-native stub
internal/store                pgvector persistence and organization-scoped 1:N retrieval
internal/oss                  OSS image retrieval and presigned URLs
internal/fallback             Alibaba Cloud Facebody 1:1 fallback
internal/service              Recognition workflow orchestration
internal/httpapi              REST routing and handlers
Dockerfile / docker-compose   Containerized deployment
models/                       Six runtime-mounted SeetaFace6 .csta files (not committed)

Requests and responses use application/json. When FACE_API_TOKEN is configured, every endpoint except /healthz requires the X-Face-Token header.

// Request
{ "org_id": "1024", "probe_key": "photo/probe-xxx.jpg" }

// Match response
{ "matched": true, "subject_id": "88", "score": 0.71, "liveness": "real", "via": "engine" }

// No-match response
{ "matched": false, "reason": "liveness_spoof", "liveness": "spoof", "score": 0, "via": "engine" }

Possible reason values include no_face, liveness_spoof, liveness_fuzzy, and empty_library. via is either engine or fallback.

{ "key_a": "photo/a.jpg", "key_b": "photo/b.jpg" }
// { "match": true, "score": 0.68, "via": "engine" }

Provide all (subject_id, oss_key) pairs for one organization. The service downloads each image, extracts embeddings, and transactionally replaces that organization's library. Entries that cannot be processed are reported in failures without preventing other entries from being enrolled.

// Request
{
  "entries": [
    { "subject_id": "88", "oss_key": "photo/88.jpg" },
    { "subject_id": "91", "oss_key": "FunSki/91.jpg" }
  ]
}

// Response
{ "org_id": "1024", "total": 2, "enrolled": 2, "failed": 0, "failures": [] }

POST   /faces    Add or update one face: { org_id, subject_id, oss_key }
DELETE /faces    Delete one face:         { org_id, subject_id }
GET    /healthz  Health check; no authentication required

1. Put the six SeetaFace6 .csta model files in ./models/: face_detector, face_landmarker_pts5, face_recognizer_light, fas_first, fas_second, and quality_lbn.

2. Create local configuration: cp .env.example .env, then enter least-privilege Alibaba Cloud RAM credentials. Never commit .env.

3. Start the service and pgvector:

   docker compose up -d --build

4. Verify it:

   curl -s http://localhost:8090/healthz

   The response should be ok.

5. Populate each organization's library through POST /sync/{org_id}.

For local development without the native SDK, use the default stub engine:

go build ./cmd/server
go test ./...
go vet ./...

Build with -tags seeta only after the required SeetaFace6 headers, libraries, and models are installed locally.

• The service is intended for private-network deployment. pgvector is not exposed by Compose; review any additional host bindings before production use.
• The configured OSS endpoint is public Hangzhou OSS because the target host cannot reach the internal endpoint.
• Alibaba Cloud Facebody fallback uses the Shanghai region. The staging bucket, when configured, is used to supply Facebody-compatible URLs and should have a short lifecycle policy.
• Confirm SeetaFace6 commercial licensing with the deploying organization.

Keep credentials only in .env, begin with .env.example, and use least-privilege RAM credentials. Do not commit SeetaFace models, generated runtime data, or biometric data.