Skip to content
BranchesTags

Repository files navigation

facial-authentication-system

📄 Xem báo cáo chi tiết: report.pdf

�📁 Xem STRUCTURE.md để tìm hiểu chi tiết về cấu trúc thư mục dự án.


Logo

Static Badge Static Badge Platform Static Badge NGINX DOCKER Redis PostgreSQL MinIO ngrok

HỆ THỐNG NHẬN DIỆN KHUÔN MẶT THEO THỜI GIAN THỰC

Một ứng dụng web sử dụng Trí tuệ Nhân tạo và Công nghệ Nhận diện Khuôn mặt để quản lý xác thực người dùng.

Mục lục (Table of Contents)
  1. Thông tin về dự án
  2. Cài đặt & Hướng dẫn sử dụng
  3. Kiến trúc & Luồng hoạt động
  4. Tính năng chính
  5. Giao diện minh hoạ của dự án
  6. Định hướng phát triển

ℹ️ Thông tin về dự án

Trong các sự kiện hay hội nghị, phương pháp điểm danh truyền thống (sử dụng thẻ cứng, quét mã QR hay đối chiếu danh sách giấy) thường bộc lộ nhiều hạn chế: tốn kém thời gian xác thực, dễ gây ùn tắc tại cửa ra vào và tiềm ẩn rủi ro gian lận (như điểm danh hộ). Hệ thống Điểm danh bằng Nhận diện Khuôn mặt Thời gian thực ra đời nhằm số hóa và thay thế hoàn toàn quy trình thủ công đó bằng công nghệ định danh sinh trắc học hiện đại.

Cách thức tương tác trên thực tế:

  • Giai đoạn trước sự kiện (Đăng ký): Người tham dự sử dụng trình duyệt web trên thiết bị cá nhân để đăng ký tài khoản. Sau đó, họ đăng nhập vào trang Người dùng (User), cấp quyền truy cập webcam để chụp ảnh khuôn mặt và gửi lên hệ thống. Yêu cầu này được đưa vào hàng chờ để Ban tổ chức (Admin) kiểm duyệt và lưu trữ làm dữ liệu gốc bảo mật thông qua pgvector.
  • Giai đoạn trong sự kiện (Check-in): Tại khu vực soát vé, người dùng chỉ cần đứng trước thiết bị có kết nối camera. Hệ thống tự động thu nhận khung hình qua video, trích xuất dữ liệu khuôn mặt và so khớp với ngân hàng dữ liệu đã duyệt trước đó.

Quá trình xác thực và ghi nhận điểm danh diễn ra hoàn toàn theo thời gian thực (Real-time), giúp tối ưu hóa luồng di chuyển của khách mời và nâng cao tối đa tính bảo mật cho sự kiện.

👨‍💻 Thành viên nhóm

Dự án được thực hiện và phát triển bởi:

  • Đỗ Thành Trung - 24022472
  • Đinh Văn Trường - 24022478
  • Nguyễn Gia Phát - 24022424
  • Nguyễn Quang Vinh - 24022490

Phân chia công việc

Các yêu cầu kĩ thuật:

  • Tạo hàng đợi Redis để gửi thông báo: Vinh
  • Cân bằng tải + Database + API giao tiếp DB: Trung
  • Backup Database để fallback khi hệ thống sập: Phát
  • Lựa chọn và triển khai mô hình nhân diện: Trường

Các yêu cầu chung:

  • Frontend, Controller nhận yêu cầu từ frontend và Service xử lý yêu cầu: Cả nhóm
  • Viết báo cáo: Trường + Vinh (chính), Trung + Phát (hỗ trợ)

🔧 Công nghệ sử dụng

Dự án được xây dựng với sự kết hợp của những công nghệ mã nguồn mở mạnh mẽ nhất hiện nay:

python flask postgresql redis opencv html5 css3 nginx docker ngrok

Thành phần Công nghệ sử dụng
Backend Python, Flask, OpenCV
AI / Machine Learning DeepFace (Trích xuất đặc trưng khuôn mặt)
Database & Cache PostgreSQL (với extension pgvector), Redis
Backup & Storage MinIO (S3-compatible Object Storage)
Frontend HTML, CSS, Nginx (Reverse Proxy)
Triển khai Docker, Docker Compose

⚙️ Cài đặt & Hướng dẫn sử dụng

📦 Yêu cầu hệ thống

Hệ thống được thiết kế để chạy mượt mà trên môi trường container. Vì vậy, bạn chỉ cần một công cụ duy nhất:

  • Docker hoặc Docker Desktop cài sẵn trên máy (bao gồm Docker Engine và Docker Compose).

🐳 Các bước chạy bằng Docker

  1. Clone mã nguồn:

    git clone https://username:YOUR_GITHUB_KEY@github.com/TruongDv-006/facial-authentication-system

  2. Chuyển vào thư mục dự án

    cd facial-authentication-system

  3. Khởi chạy hệ thống bằng Docker Compose: Lệnh này sẽ tự động build image, khởi tạo network, chạy Nginx, Database, Redis và Backend Flask. Kịch bản entrypoint.sh cũng sẽ tự động nạp các người dùng mặc định vào CSDL lúc khởi động.

    docker-compose up -d --build

    ⚠️ Lưu ý: Hệ thống có thể mất khoảng 1-2 phút sau khi các container khởi tạo để có thể sử dụng do cần nạp mô hình nhận diện sau khi build docker.

  4. Truy cập ứng dụng:

    • Mở trình duyệt web của bạn và đi đến trang người dùng tại: http://localhost (hoặc tuỳ theo cấu hình nginx.conf).
    • Truy cập trang Admin tại danh mục tương ứng (VD: /admin).

  5. Dừng hoạt động:

    docker-compose down

🏗️ Kiến trúc & Luồng hoạt động

Tech Architecture

Kiến trúc mạnh mẽ chia các service một cách độc lập:

  • Nginx xử lý các file tĩnh (HTML, CSS) và đại diện làm Reverse Proxy trỏ về API Backend (Flask App).
  • Flask App (MainApp.py) tiếp nhận Request, chuyển yêu cầu xử lý từ Controllers (AdminController, UserController) sang Services.
  • Service Trí tuệ Nhân tạo (FaceModel.py, FaceRecognitionService.py) bóc tách ảnh định dạng vector từ khuôn mặt người dùng thành mảng số học (embedding).
  • PGVector (PostgreSQL): PostgreSQL với extension pgvector xử lý tính toán độ gần nhau của hàm Loss (Cosine Similarity hoặc L2 Distance) tốc độ cao, tiết kiệm chi phí Memory hơn so với Load dữ liệu vào phần mềm nhận diện thông thường.
  • Redis dùng để làm Message Broker, Redis Queue cùng Pub/Sub cho các tác vụ trao đổi dữ liệu.

🖥️ Tính năng chính

  • 👩‍💻 Đăng kí danh tính bằng hình ảnh: Sử dụng luồng Webcam tĩnh trên Web hoặc Upload File ảnh có chứa khuôn mặt để đăng ký (Yêu cầu Admin thông qua).
  • 🔐 Cổng xác thực sinh trắc học: Nhận dạng không cần nhập mật khẩu văn bản; sử dụng thuật toán để đảm bảo độ chính xác tới từng đường nét của Face ID.
  • 🕹 Quản trị viên (Admin Cpanel): Xác thực chuyên quyền rõ ràng (decorator như @AdminRequired), Admin có khả năng đọc duyệt hoặc bác bỏ Face ID.
  • ⚡ Nạp dữ liệu tự động (Seed Data): Cơ chế tự trích xuất và đẩy những người có sẵn trong thư mục /img vào db ở lần install đầu thông qua Bash script (entrypoint.sh và IngestData.py).

🖼️ Giao diện minh hoạ của dự án

Phần này gồm 8 mục — mỗi mục có một dòng mô tả nội dung ảnh và chỗ để chèn ảnh minh hoạ từ thư mục UI_img/.

1. Trang chủ (Home)

1 - Trang chủ

2. Trang đăng nhập (Login)

2 - Trang đăng nhập

3. Trang đăng ký

3 - Trang đăng ký

4. Người dùng

4 - Người dùng

5. Người dùng gửi yêu cầu

5 - Người dùng gửi yêu cầu

6. Admin danh sách yêu cầu

6 - Admin danh sách yêu cầu

7. Admin quản lí người dùng

7 - Admin quản lí người dùng

8. Nhận diện khuôn mặt

8 - Nhận diện khuôn mặt

💾 Hệ thống Backup dữ liệu (MinIO)

Hệ thống sao lưu tự động sử dụng MinIO (S3-compatible Object Storage) để lưu trữ bản backup an toàn.

Backup hiện tại chỉ tập trung vào PostgreSQL database: script sẽ xuất toàn bộ DB bằng pg_dump, nén lại thành .sql.gz, upload lên MinIO, rồi xóa các bản quá hạn theo retention policy.

Kiến trúc Backup

┌──────────────┐     pg_dump     ┌───────────────────────┐     S3 API     ┌───────────┐
│  PostgreSQL  │ ──────────────► │   Backup Container    │ ─────────────► │   MinIO   │
│  (pgvector)  │                 │  (Alpine + aws-cli)   │                │  (S3 API) │
└──────────────┘                 └───────────────────────┘                └───────────┘
										  │
							  Dữ liệu được backup:
							  └── Full DB dump (.sql.gz)

Cấu trúc lưu trữ trên MinIO

s3://facial-auth-backups/
├── postgres/
│   └── 20260525_020000/
│       └── full_dump.sql.gz            # Full database dump (bao gồm pgvector + BYTEA)
└── postgres/.keep                      # Marker để giữ prefix trong bucket

Khởi chạy hệ thống Backup

# Khởi chạy toàn bộ hệ thống (bao gồm MinIO + Backup)
docker-compose up -d --build

# Chỉ khởi chạy backup service
docker-compose up -d backup

Chạy backup thủ công

docker exec face_backup /backup/backup.sh

Nếu bạn đã cấu hình docker-compose.yml để map MINIO_ROOT_USER và MINIO_ROOT_PASSWORD sang AWS_ACCESS_KEY_ID và AWS_SECRET_ACCESS_KEY, thì lúc khôi phục chỉ cần chạy:

docker compose exec backup /backup/restore.sh

Khuyến nghị đặt giá trị thật trong file .env dựa trên .env.example, thay vì ghi trực tiếp vào docker-compose.yml.

Backup service sẽ chạy một bản backup ngay khi container khởi động, sau đó chạy lại theo lịch cron từ BACKUP_SCHEDULE.

Khôi phục dữ liệu (Disaster Recovery)

# Khôi phục bản backup mới nhất
docker exec -it face_backup /backup/restore.sh

# Khôi phục theo timestamp cụ thể
docker exec -it face_backup /backup/restore.sh 20260525_020000

Kiểm tra trạng thái

# Xem log backup
docker logs face_backup

# Truy cập MinIO Console (Web UI)
# URL: http://localhost:9001
# User: minioadmin / Password: minioadmin

# Liệt kê các bản backup
docker exec face_backup aws --endpoint-url http://minio:9000 \
	s3 ls s3://facial-auth-backups/postgres/

Biến môi trường cấu hình

Biến Giá trị mặc định Mô tả
MINIO_ROOT_USER minioadmin Tài khoản root MinIO
MINIO_ROOT_PASSWORD minioadmin Mật khẩu root MinIO
MINIO_BUCKET facial-auth-backups Tên bucket lưu backup
BACKUP_SCHEDULE 0 2 * * * Lịch backup cron, mặc định chạy mỗi ngày lúc 02:00
BACKUP_RETENTION_DAYS 7 Số ngày giữ backup cũ trước khi dọn

Ghi chú vận hành

  • BACKUP_SCHEDULE quyết định tần suất backup; BACKUP_RETENTION_DAYS chỉ quyết định thời gian giữ lại các bản backup cũ.
  • Restore hiện tại khôi phục từ file full_dump.sql.gz, sau đó tạo lại database và nạp dump trở lại.
  • Nếu muốn backup 1 lần mỗi 7 ngày, cần đổi BACKUP_SCHEDULE thành lịch cron tương ứng; mặc định hiện tại là backup mỗi ngày.

📈 Định hướng phát triển

Trong tương lai, nhóm phát triển sẽ hướng tới:

  • Tự động gửi mail thông báo cho người dùng khi đăng ký Face ID thành công hoặc điểm danh hoàn tất.
  • Áp dụng HTTPS/TLS để bảo vệ dữ liệu khi truyền tải và đảm bảo giao tiếp an toàn giữa client và server trong luồng truyền Camera thời gian thực.
  • Triển khai lưu trữ token an toàn bằng cách sử dụng cookie HTTP-only để giảm thiểu rủi ro XSS và tăng cường bảo mật tổng thể.
  • Cải thiện hiệu suất nhận diện trong các tình huống khuôn mặt bị che khuất một phần (ví dụ: đeo khẩu trang, đội mũ, đeo kính, v.v.).
  • Tích hợp kỹ thuật Liveness Detection để tự động loại bỏ các hành vi mạo danh, chống Face Spoof và Replay attack.
  • Bổ sung xác thực phía máy chủ (server-side verification) chặt chẽ cho tất cả các hành động và endpoint nhạy cảm để ngăn chặn truy cập trái phép.
  • Áp dụng các kỹ thuật bảo vệ quyền riêng tư tiên tiến hơn (ví dụ: federated learning, differential privacy, v.v.).

(quay lại đầu trang)

📝 Notes

  • Nếu bạn có thắc mắc hay đóng góp gì, hãy liên hệ với chúng tôi qua email/thông tin liên lạc đã ghi bên trên.
  • Phần mềm này được phát triển với mục đích học tập.
  • Cảm ơn bạn đã quan tâm tới project của chúng tôi

About

Real-time facial recognition platform for contactless user registration, automated event check-in, biometric identity verification, and administrative access control.

Topics

biometricsdeepfaceface-recognitionfacial-authenticationreal-time

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages