정정지용
프로젝트 목록
백엔드Java

얼굴 인식 기반 출결 관리 REST API

얼굴 특징(feature) 등록·매칭·검색과 Liveness 검증을 제공하는 Spring Boot 기반 얼굴 인식 API 서버

face-api최근 업데이트 2026년 7월 27일

개요

클라이언트가 얼굴 이미지를 업로드하면 추론 서버로부터 feature vector를 받아 PostgreSQL pgvector에 저장하고, 1:1 매칭·1:N 검색·Liveness 검증을 수행합니다. JWT 기반 인증, 클라이언트/계정/얼굴 서버 관리 API, API 이력 기록 인터셉터를 제공하며, Flyway를 통해 스키마 마이그레이션을 관리합니다. Docker Compose로 PostgreSQL과 함께 배포되며, Swagger UI로 API 문서를 자동 생성합니다.

담당 역할

얼굴 인식 추론 서버와의 통신, feature vector 저장 및 유사도 검색 로직, JWT 인증 인터셉터, Flyway 마이그레이션 스크립트 작성 등 백엔드 전반을 담당

아키텍처 다이어그램

레포지토리 분석 결과를 바탕으로 자동 생성된 구조도입니다.

아키텍처

전체 시스템 아키텍처

클라이언트 요청이 Spring Boot API를 거쳐 얼굴 추론 서버와 통신하고, feature를 PostgreSQL pgvector에 저장하는 전체 흐름을 나타냅니다.

다이어그램을 그리는 중…
시퀀스

얼굴 검색(1:N) 시퀀스

이미지를 업로드하면 추론 서버에서 feature를 추출하고, DB에서 pgvector 유사도 검색을 수행해 매칭 결과를 반환하는 과정입니다.

다이어그램을 그리는 중…
데이터 모델

핵심 엔티티 관계

계정(AccountInfos), 클라이언트(ClientInfos), 얼굴 특징(Features), 얼굴 서버(FaceServerInfos) 간의 관계를 보여줍니다.

다이어그램을 그리는 중…

기술스택

각 기술을 이 프로젝트에서 어떤 용도로 썼는지 정리했습니다.

언어

  • Java주 개발 언어(Java 17)

프레임워크

백엔드

데이터베이스

  • PostgreSQL메인 DB 및 pgvector 확장을 통한 feature vector 저장
  • FlywayDB 스키마 버전 관리 및 마이그레이션

도구

  • Gradle빌드 및 의존성 관리
  • SwaggerSpringDoc OpenAPI로 REST API 문서 자동 생성

인프라

  • Docker애플리케이션 컨테이너화 및 Docker Compose 배포

핵심 포인트

  • PostgreSQL pgvector와 Hibernate Vector를 이용해 얼굴 feature vector를 DB에 저장하고 유사도 검색 수행
  • Flyway 마이그레이션으로 스키마 변경 이력을 코드화하고 vector 검색 함수(PLpgSQL)까지 버전 관리
  • JWT 기반 인증 인터셉터와 API 이력 기록 인터셉터를 적용해 모든 요청의 추적 가능성 확보
  • WebClient로 외부 얼굴 추론 서버(inference)와 비동기 통신하여 feature 추출 및 Liveness 검증 연동
  • Docker Compose로 PostgreSQL과 애플리케이션을 함께 배포하고, Swagger UI로 API 문서 제공

문제와 해결

문제얼굴 feature를 DB에서 효율적으로 검색하기 위해 전통적인 RDB 인덱스로는 벡터 유사도 검색 성능이 부족

해결PostgreSQL pgvector 확장과 Hibernate Vector를 도입해 float 배열을 vector 타입으로 변환하고, PLpgSQL 함수를 통해 거리 기반 검색 구현

문제클라이언트별로 다른 얼굴 인식 서버(Face Server)를 사용해야 하는 멀티테넌트 구조

해결ClientInfos와 FaceServerInfos 엔티티를 분리하고, 요청 시 클라이언트 토큰으로 해당 서버 정보를 조회한 뒤 WebClient로 라우팅

문제API 호출 이력을 모든 엔드포인트에서 일관되게 기록해야 하는 요구사항

해결ApiHistoryInterceptor와 ResponseWrapper를 조합해 요청·응답 시각, 상태 코드, 클라이언트 ID를 자동으로 DB에 저장

레포지토리 정보

생성
2026년 7월 27일
최근 커밋
2026년 7월 27일
크기
129 KB
라이선스
없음

언어 구성

  • Java99.1%
  • PLpgSQL0.8%
  • Shell0.1%

이 문서는 2026년 7월 28일 에 자동 분석으로 생성되었습니다.