📋 프로젝트 개요

안면인식기술을 적용한 출입관리 시스템 (팀명: 뭐든)
전북대학교 캡스톤디자인 프로젝트

작품 필요성

본 프로젝트는 올포랜드(주)와 전북대학교 SW중심대학사업단 간의 산학협력 과제로서, 기존 사무실 출입관리 방식의 여러 문제점을 해결하기 위해 기획되었다. 실제 현장에서는 지문인식기기나 RF카드 기반 출입 시스템이 주로 사용되고 있었지만, 카드 분실로 인한 재발급 비용 발생, 출입카드 관리 인력의 필요, 마지막 퇴실자의 여부를 사람이 육안으로 확인해야 하는 등 운영상 여러 불편함이 지속적으로 제기되었다.

프로젝트 결과

본 프로젝트의 결과로, 얼굴 인식 기능을 중심으로 하는 출입관리 시스템을 기업 환경에 실제로 적용 가능한 수준으로 완성하였다. 얼굴 인식은 사전학습된 ArcFace 모델을 기반으로 K-FACE 데이터셋에 맞춰 파인튜닝하여 정확도를 높였으며, 라즈베리파이를 활용한 실시간 얼굴 촬영과 API 서버 연동을 통해 자동 출입 인증이 가능한 단말기를 구현하였다. 인증된 결과는 Flask 기반 API 서버에서 처리되어 Kafka 메시지 통신을 통해 백엔드로 전달되며, 전체 시스템은 Docker 환경에서 통합적으로 관리된다. 또한, 올포랜드의 기존 웹사이트를 기반으로 제작된 웹페이지를 통해 출입 기록 확인, 외부인 감지 시 실시간 영상 및 이미지 확인, 출근 인원 확인 등의 기능도 구현하였다. 이를 통해 얼굴 인식 → 인증 → 기록 → 웹 조회로 이어지는 전체 출입관리 흐름을 완성하였다.

활용방안

본 시스템은 얼굴 인식 기반 출입통제 및 근태관리 시스템으로, 기존 카드 기반 시스템을 대체하거나 보완하는 형태로 활용될 수 있다. 별도의 장비 없이 얼굴만으로 인증이 가능해 사용자 편의성이 높고, 출입 기록은 자동으로 저장된다. 관리자는 웹 기반 관리자 페이지를 통해 직원의 출입 현황을 실시간으로 확인할 수 있으며, 외부인의 출입 시도는 자동으로 감지되고 이미지와 함께 기록되어 보안이 필요한 공간에서도 효과적으로 대응할 수 있다. 본 시스템은 기업뿐만 아니라 학교, 연구기관, 의료기관 등 다양한 시설에 적용 가능하며, 운영 관리의 효율성과 보안성을 동시에 향상시킬 수 있다.

기대효과

프로젝트를 통해 구현한 출입관리 시스템은 기존의 카드 태깅 방식이나 지문 인식 방식에서 발생할 수 있는 분실, 위생 관리, 비용 등의 문제를 자연스럽게 해결할 수 있다. 얼굴 인식 기반 자동 인증으로 사용자 편의성이 크게 향상되며, 시스템은 별도의 장비 없이 간단히 설치 및 운영이 가능하다. 또한 관리자와 사용자가 모두 웹을 통해 출입 현황을 실시간으로 확인할 수 있어, 인원 통제 및 근태 관리의 정확성과 신뢰도가 높아진다. 외부인 감지 기능과 함께 출입 이력 이미지가 저장되기 때문에 보안적인 측면에서도 강점을 가지며, 출퇴근 데이터가 자동으로 축적되기 때문에 별도의 수기 관리나 확인 절차 없이 정량적이고 투명한 근무 기록 관리가 가능해진다.

🏗️ 시스템 아키텍처

🛠️ 기술 스택

백엔드

프론트엔드

AI/머신러닝

메시지 큐/스트리밍

인프라/클라우드

하드웨어

개발 도구

📚 API 명세서

🔗 Swagger UI로 보기

🔬 모델 성능 분석 결과

1. 3가지 얼굴 인식 모델 비교 분석

모델	Accuracy	Precision	Recall	F1-Score	ROC AUC	mAP	비고
dlib	0.9753	0.0666	0.6823	0.1214	0.9164	0.4404	검출 실패 多
FaceNet	0.9650	0.0495	0.7155	0.0926	0.9394	0.3044	높은 재현율
ArcFace	0.9891	0.1525	0.7345	0.2525	0.9769	0.5570	최종 선택

2. 모델별 상세 분석

🔴 dlib 모델

• 치명적 문제: 안면 검출 실패 케이스 104,800개 발생
• 낮은 정밀도: 0.0666으로 실용성 부족
• 결론: 실제 출입관리 시스템 적용 불가

🟡 FaceNet 모델

• 장점: 높은 재현율(Recall: 0.7155)
• 단점: 높은 오탐율로 보안 시스템에 부적합
• 임계값 0.6: FPR 22.41%, TPR 90.72%

🟢 ArcFace 모델 (최종 선택)

• 최고 정확도: 98.91%
• 최적 임계값 0.4: FPR 28.32%, TPR 98.59%
• 보안 중시 임계값 0.6: FPR 1.69%, TPR 78.08%
• 파인튜닝 가능: 추가 학습으로 성능 개선 여지

ArcFace 모델 선택 근거

1. 낮은 오탐율: 보안 시스템에서 중요한 False Positive 최소화
2. 높은 안정성: 전반적으로 가장 균형잡힌 성능
3. 확장 가능성: 파인튜닝을 통한 성능 개선 잠재력

ArcFace 모델 파인튜닝

파인튜닝 목표와 이유

사전 학습된 ms1mv3_arcface_r50_fp16 모델을 한국인 얼굴 데이터에 특화시켜, 국내 환경에서의 얼굴 인식 정확도 및 강건성 향상을 목표

글로벌 데이터셋으로 사전 학습된 모델은 특정 인종에 편향 한국인 고유의 얼굴 특징 및 악세서리에 대한 모델의 이해도를 높여  인종적 편향을 보완하고 성능을 최적화

활용 데이터 셋

K-FACE 데이터셋

K-Face: 다양한 연령대, 표정, 조명 조건, 액세서리(안경, 모자 등) 착용,  촬영 각도 등을 포함하는 고품질 한국인 얼굴 이미지 데이터셋

데이터구성

액세서리: 선글라스를 제외한 5종 조명 세기: 1000 lux, 400 lux 표정: 3종 각도: 3종 (상단 0도 좌측 0도 / 상단 0도 좌측 15도 / 상단 0도 좌측 -15도) 총 이미지 수: 400 ID * 5 액세서리 * 2 LUX * 3 표정 * 3 각도 = 36,000장

파인튜닝 결과

🎬 시연 영상

1.mp4

🛠️ 실행 방법

📋 필요한 장비 및 요구사항

🔧 하드웨어 요구사항

구성요소	사양	용도
🖥️ 서버 PC	RAM 8GB 이상, 저장공간 50GB 이상	백엔드/AI 서버 구동
🍓 Raspberry Pi	Pi 4B (RAM 4GB 권장)	얼굴인식 단말기
📷 웹캠/카메라	USB 웹캠 또는 Pi Camera	실시간 얼굴 촬영
🌐 네트워크	Wi-Fi/이더넷	서버-단말기 통신

💻 소프트웨어 요구사항

• Docker & Docker Compose
• Git
• Python 3.8+ (라즈베리파이용)
• 지원 OS: Windows 10/11, Ubuntu 20.04+, macOS

🚀 1단계: 프로젝트 클론 및 설정

# 프로젝트 클론
git clone https://github.com/your-repo/facialRecognition.git
cd facialRecognition

# Docker 및 Docker Compose 설치 확인
docker --version
docker-compose --version

🔐 2단계: 환경변수 설정

중요: 보안을 위해 환경변수 파일 생성 필수

# env.example 파일을 복사하여 .env.prod 파일 생성
cp env.example .env.prod

# .env.prod 파일을 편집하여 실제 값 입력
# 다음 항목들을 실제 값으로 변경해주세요:
# - POSTGRES_PASSWORD: PostgreSQL 데이터베이스 비밀번호
# - AWS_ACCESS_KEY: AWS 액세스 키
# - AWS_SECRET_KEY: AWS 시크릿 키  
# - AWS_S3_BUCKET: S3 버킷 이름
# - JWT_SECRET: JWT 시크릿 키 (보안을 위해 복잡한 문자열로 변경)

⚠️ 보안 주의사항:

• .env.prod 파일은 실제 프로덕션 환경의 민감한 정보를 포함합니다
• 이 파일을 Git에 커밋하지 마세요 (.gitignore에 추가됨)
• AWS 키는 최소 권한 원칙에 따라 S3 접근 권한만 부여하세요

🏗️ 3단계: 시스템 전체 실행

자동 실행 (권장)

# 실행 스크립트에 실행 권한 부여
chmod +x start-full-system.sh
chmod +x stop-full-system.sh

# 전체 시스템 자동 시작 (환경변수 파일 자동 로드)
./start-full-system.sh

수동 실행

# 환경변수 파일 로드
export $(grep -v '^#' .env.prod | xargs)

# 기존 컨테이너 정리
docker-compose -f docker-compose.full.yml down

# 전체 시스템 빌드 및 시작
docker-compose -f docker-compose.full.yml up --build -d

# 로그 확인
docker-compose -f docker-compose.full.yml logs -f

시스템 종료

# 자동 종료 (권장)
./stop-full-system.sh

# 수동 종료
export $(grep -v '^#' .env.prod | xargs) && docker-compose -f docker-compose.full.yml down

📱 4단계: 라즈베리파이 설정

라즈베리파이에서 실행:

# 프로젝트 클론 (라즈베리파이에서)
git clone https://github.com/your-repo/facialRecognition.git
cd facialRecognition/RaspberryPi

# Python 패키지 설치
pip install -r requirements.txt

# 얼굴인식 단말기 실행
python face_detector.py --resolution 720p --type check_in

실행 옵션:

# 출근 모드
python face_detector.py --type check_in --confidence 0.5

# 퇴근 모드  
python face_detector.py --type check_out --resolution 1080p

# 디버그 모드
python face_detector.py --debug --interval 1.0

🌐 접속 정보

시스템이 성공적으로 시작되면 다음 주소로 접속할 수 있습니다:

서비스	포트	설명
🌐 웹 관리자 페이지	3000	메인 관리 시스템
🔧 백엔드 API	8080	REST API 서버
🎯 ArcFace API	5000	얼굴인식 AI 서버
📡 WebSocket	8765	실시간 알림 서버
📊 Kafka UI	8090	메시지 큐 관리
💾 PostgreSQL	5432	데이터베이스

🔍 시스템 상태 확인

# 전체 서비스 상태 확인
docker-compose -f docker-compose.full.yml ps

# 특정 서비스 로그 확인
docker-compose -f docker-compose.full.yml logs backend
docker-compose -f docker-compose.full.yml logs arcface

# 리소스 사용량 확인
docker stats

🛑 시스템 종료

# 전체 시스템 종료
docker-compose -f docker-compose.full.yml down

# 볼륨까지 완전 삭제
docker-compose -f docker-compose.full.yml down -v

⚠️ 문제 해결

🔴 일반적인 문제들:

문제	해결방법
포트 충돌	docker-compose down 후 다른 프로그램 종료
메모리 부족	Docker Desktop 메모리 할당량 증가
카메라 미작동	USB 권한 확인 또는 카메라 연결 상태 점검
네트워크 오류	방화벽 설정 확인 (포트 3000, 8080, 5000)

🔍 디버그 명령어:

# Docker 컨테이너 상태 확인
docker ps -a

# 특정 컨테이너 접속
docker exec -it backend-app bash
docker exec -it arcface-api bash

# 네트워크 확인
docker network ls
docker network inspect facialrecognition_facial-recognition-network

📝 Git Commit 규칙

graph LR
    subgraph "🏷️ Commit Types"
        A[feat]
        B[fix]
        C[docs]
        D[style]
        E[test]
        F[refactor]
    end

    style A fill:#28a745,color:#fff
    style B fill:#dc3545,color:#fff
    style C fill:#17a2b8,color:#fff
    style D fill:#ffc107,color:#000
    style E fill:#6f42c1,color:#fff
    style F fill:#fd7e14,color:#fff

Loading

🏷️ Type	📝 활용상황	💡 예제
feat	새로운 기능 추가	feat: 사용자 로그인 기능 추가
fix	버그 수정	fix: 잘못된 계산 로직 수정
docs	문서 수정	docs: README 파일에 설치 방법 추가
style	코드 스타일 변경	style: 코드에서 불필요한 세미콜론 제거
design	UI 디자인 변경	design: 메인 페이지 버튼 스타일 변경
test	테스트 코드 추가/수정	test: 로그인 기능에 대한 단위 테스트 추가
refactor	리팩토링	refactor: 중복된 코드 함수로 리팩토링
build	빌드 파일 수정	build: Webpack 설정 파일 수정
ci	CI 설정 파일 수정	ci: GitHub Actions 워크플로우 파일 수정
perf	성능 개선	perf: API 응답 속도 향상을 위한 쿼리 최적화
chore	자잘한 수정이나 빌드 업데이트	chore: 패키지 버전 업데이트
rename	파일/폴더명 수정	rename: login.js 파일명을 auth.js로 변경
remove	파일 삭제	remove: 사용되지 않는 old_styles.css 파일 삭제

🌳 Git Branch 전략

graph TD
    C[feature/login] --> B[develop]
    D[feature/ui] --> B
    B --> A[main]
    G[hotfix/critical] --> A
    A --> E[release/1.0.0]
    E --> F[v1.0.0]

    style A fill:#ff6b6b,color:#fff
    style B fill:#4ecdc4,color:#fff
    style C fill:#45b7d1,color:#fff
    style D fill:#96ceb4,color:#fff
    style E fill:#ffeaa7,color:#000
    style F fill:#6c5ce7,color:#fff
    style G fill:#fd79a8,color:#fff

Loading

🔄 브랜치 설명

• main : 배포 가능한 안정적인 버전 (보호 규칙 적용, PR로만 병합)
• develop : 개발 중인 최신 코드가 포함된 브랜치
• feature/* : 새로운 기능을 개발하는 브랜치
• release/* : 배포 준비 단계에서 사용하는 브랜치
• hotfix/* : 배포된 코드에서 긴급한 수정이 필요할 때 사용하는 브랜치

📋 브랜치 네이밍 규칙

🌿 브랜치 유형	🏷️ 네이밍 규칙	💡 예시
🏠 메인 브랜치	main	main
🔧 개발 브랜치	develop	develop
✨ 기능 개발	feature/기능-이름	feature/login-system
🐛 버그 수정	bugfix/버그-설명	bugfix/fix-login-error
🚨 긴급 수정	hotfix/이슈-설명	hotfix/critical-payment-bug
🚀 배포 준비	release/버전번호	release/1.2.0

회의기록

• 캡스톤 1주차 회의기록
• 캡스톤 2주차 회의기록
• 캡스톤 3주차 회의기록
• 캡스톤 4주차 회의기록
• 캡스톤 5주차 회의기록
• 캡스톤 6주차 회의기록
• 캡스톤 7주차 회의기록
• 캡스톤 8주차 회의기록
• 캡스톤 9주차 회의기록
• 캡스톤 10주차 회의기록
• 캡스톤 결과보고서

참고자료

• 기계 학습(Machine Learning, 머신 러닝)은 즐겁다! Part 4
• [AI] 분류 성능 평가 지표
• IoU, NMS, AP, mAP 간단 설명, 코드
• GitHub에 Swagger API 문서를 공유하기