# Proj_Access-Control

**Repository Path**: BigYellow12138/proj_access_control

## Basic Information

- **Project Name**: Proj_Access-Control
- **Description**: 基于deepface的门禁系统，前端使用React+Typescript构建、后端使用Django+Python搭建。实现的功能：
1、人脸识别
2、人脸检测
3、人脸向量化
4、人脸数据库检索
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-07
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能门禁与人脸识别系统

> 一个基于 Django、React 和 ESP32 构建的，集成了 NFC 刷卡与人脸识别双重验证的智能门禁系统。

本项目是一个全栈的课程设计，旨在演示如何将 Web 技术、物联网硬件和人工智能（人脸识别）结合起来，构建一个真实世界的应用程序。

## ✨ 项目简介

该系统允许用户通过 **NFC 刷卡** + **人脸识别** 的双重验证方式来开门。管理员可以通过一个功能丰富的 Web 界面实时监控设备状态、管理用户和设备、并审查所有访问日志。

-   **核心流程**: 用户刷卡后，系统识别其身份，并触发摄像头进行 1:1 人脸比对。只有在人脸比对成功后，才会向硬件发送开门指令。
-   **实时性**: 前后端、后端与硬件之间均采用 WebSocket 进行实时双向通信。

### 🔄 核心验证流程
![控制流程时序图](./docs/pic/控制流程时序图.drawio.png)

### 📹 管理员视频监控流程
![摄像头时序图](./docs/pic/摄像头时序图.drawio.png)

## 🏛️ 项目架构

系统采用前后端分离的架构，并通过 WebSocket 与硬件设备进行通信。

![门禁系统架构图](./docs/pic/门禁系统架构图.drawio.png)

-   **前端 (Frontend)**: 用户和管理员的交互界面。
-   **后端 (Backend)**: 处理所有业务逻辑、API 请求和实时通信的核心。
-   **硬件 (ESP32)**: 负责物理世界的交互，如读取 NFC 卡和控制门锁。

## 🛠️ 技术栈

-   **后端**: Django, Django REST Framework, Django Channels, DeepFace
-   **前端**: React, Vite, TypeScript, Ant Design
-   **硬件**: ESP32 (Arduino C++), MFRC522 (NFC)
-   **数据库**: SQLite (开发环境), PostgreSQL (生产环境推荐)
-   **实时通信**: WebSocket
-   **人脸识别**: VGG-Face 模型，余弦距离匹配

### 🤖 人脸识别技术
本项目使用 DeepFace 库实现高精度的人脸识别功能，支持 1:1 人脸验证。系统采用 VGG-Face 深度学习模型进行特征提取，通过余弦距离计算实现人脸匹配。

**[📖 查看 DeepFace 技术详解](./docs/backend/DEEPFACE_INTEGRATION.md)** - 包含完整的原理介绍、算法实现和使用指南。

## 📁 项目结构

```
proj_access_control/
├── backend/                    # Django 后端服务
│   ├── access_control/         # 门禁核心应用
│   ├── accounts/               # 用户账户管理
│   ├── face_db/               # 人脸数据库管理
│   ├── config/                # Django 配置
│   ├── media/                 # 媒体文件存储
│   ├── model/                 # DeepFace 模型文件
│   ├── test_script/           # 测试脚本
│   └── requirements.txt       # Python 依赖
│
├── frontend/                   # React 前端应用
│   ├── src/
│   │   ├── components/        # 可复用组件
│   │   ├── pages/            # 页面组件
│   │   ├── contexts/         # React 上下文
│   │   └── utils/            # 工具函数
│   ├── public/               # 静态资源
│   └── package.json          # Node.js 依赖
│
├── esp32_arduino/             # ESP32 硬件固件
│   └── access_control_device/ # 门禁设备代码
│       ├── access_control_device.ino
│       └── compile_test.md
│
├── camera_service/            # 摄像头服务 (FastAPI)
│   ├── main.py               # 主服务文件
│   ├── test_endpoints.py     # 接口测试
│   └── README.md
│
├── docs/                      # 项目文档
│   ├── backend/              # 后端技术文档
│   │   ├── DEEPFACE_INTEGRATION.md  # DeepFace 技术详解
│   │   ├── SECURITY_SETUP.md        # 安全配置
│   │   └── HTTPS_SETUP.md           # HTTPS 配置
│   ├── pic/                  # 架构图和图片
│   ├── SYSTEM_ARCHITECTURE.md       # 系统架构设计文档
│   ├── PROJECT_PLAN.md       # 项目规划
│   ├── REVIEW_REPORT.md      # 项目审查报告
│   └── WSL2_ESP32_NETWORK_SETUP.md # 网络配置指南
│
├── start_services.sh          # 服务启动脚本
├── stop_services.sh           # 服务停止脚本
├── CLAUDE.md                  # Claude Code 开发指导
├── README.md                  # 项目主文档
└── version.md                 # 版本信息
```

### 📚 重要文档链接

| 文档类型 | 链接 | 描述 |
|---------|------|------|
| 🏗️ **系统架构** | [系统架构设计文档](./docs/SYSTEM_ARCHITECTURE.md) | 完整的架构设计和组件交互说明 |
| 📋 **项目规划** | [项目规划文档](./docs/PROJECT_PLAN.md) | 系统设计和开发规划 |
| 📊 **项目状态** | [最新审查报告](./docs/REVIEW_REPORT.md) | 项目进度和功能状态 |
| 🤖 **AI技术** | [DeepFace 技术详解](./docs/backend/DEEPFACE_INTEGRATION.md) | 人脸识别原理和实现 |
| 🔐 **安全配置** | [安全设置指南](./docs/backend/SECURITY_SETUP.md) | 系统安全配置 |
| 🌐 **网络配置** | [WSL2 网络配置](./docs/WSL2_ESP32_NETWORK_SETUP.md) | 开发环境网络设置 |

## 🚀 快速上手

要完整地运行整个系统，你需要分别设置和启动后端、前端，并为硬件刷写固件。

### 启动步骤

1. **🔧 后端服务**: 启动 Django API 服务和 WebSocket 通信 → [`backend/README.md`](./backend/README.md)

2. **🎨 前端界面**: 启动 React 开发服务器 → [`frontend/README.md`](./frontend/README.md)

3. **📟 硬件设备**: 刷写 ESP32 固件代码 → [`esp32_arduino/README.md`](./esp32_arduino/README.md)

4. **📷 摄像头服务** (可选): 启动 Windows 摄像头服务 → [`camera_service/README.md`](./camera_service/README.md)

### 系统管理

- **启动所有服务**: `./start_services.sh`
- **停止所有服务**: `./stop_services.sh`

## 📝 项目当前状态

**“功能完善，蓄势待发”**

目前，项目的所有核心功能均已开发完成。前后端基础框架、硬件固件以及它们之间的通信链路已经完全打通并可正常工作。

-   **双重验证**: 后端已实现NFC刷卡后的二次人脸识别验证逻辑。
-   **实时监控**: 前端管理员界面已实现动态、可选择的实时视频流监控功能。

详细的分析和项目历史，请查阅最新的 **[项目审查报告](./docs/REVIEW_REPORT.md)**。