项目简介

EduFace - 智慧校园人脸识别平台

概述

EduFace 是一套基于 Django 6.0 + InsightFace 构建的智慧校园人脸识别考勤系统，提供教室识别考勤、图书馆借阅、宿舍出入管理等功能，面向管理员、教师、家长、学生四种角色。

技术栈

  • 后端：Django 6.0 + Django REST Framework 3.17 + djangorestframework-simplejwt
  • 人脸识别：InsightFace (buffalo_l 模型)
  • 数据库：SQLite（开发）/ PostgreSQL（生产）
  • 前端：纯 HTML + CSS + JavaScript（无构建工具）
  • 认证：JWT 双通道（Authorization Bearer + Cookie）

功能模块

  • 人脸识别考勤 - 教室实时人脸识别、出勤记录、统计导出
  • 图书馆管理 - ISBN 扫码借书、人脸识别借阅、借还记录
  • 宿舍管理 - 人脸识别出入记录、方向统计、CSV 导出
  • 用户管理 - 多角色用户（管理员/教师/家长/学生）、权限控制
  • 学生管理 - 学生档案、用户账号关联、自动同步
  • 家长端 - 绑定学生、查看考勤历史
  • 学生端 - 个人信息、头像上传、名称修改、成绩查询

项目结构

FaceSite/
├── apps/                    # Django 应用
│   ├── users/               # 用户管理
│   ├── faces/               # 人脸识别
│   ├── students/            # 学生管理
│   ├── library/             # 图书馆
│   ├── dorm/                # 宿舍管理
│   ├── parent/              # 家长端
│   └── tasks/               # 课程管理
├── config/                  # Django 配置
├── protected_pages/admin/   # 管理后台页面
├── static/                  # 静态资源
│   ├── css/                 # 样式
│   ├── js/                  # 脚本
│   ├── student/             # 学生端
│   └── docs.html            # 文档页
└── media/                   # 用户上传

API 文档

EduFace RESTful API 接口参考

认证

所有 API 请求需携带 JWT Token，支持两种方式：

  • Authorization: Bearer <token>
  • Cookie: access_token=<token>
# 登录获取 Token
POST /api/login
Content-Type: application/json
{"username": "admin", "password": "xxx"}

# 响应
{"token": "eyJ...", "role": "admin"}

用户管理

方法路径说明
POST/api/login用户登录
POST/api/register用户注册
GET/api/users用户列表（支持 role/username 筛选）
POST/api/users创建用户
PUT/api/users/:id更新用户
DELETE/api/users/:id删除用户

人脸识别

方法路径说明
POST/upload/face上传人脸
GET/faces人脸列表
DELETE/faces/:name删除人脸
POST/recognize/face人脸识别
GET/api/recognition/history识别历史
GET/api/recognition/history/export导出 CSV

学生管理

方法路径说明
GET/api/students学生列表
POST/api/students创建学生
PUT/api/students/:id更新学生
DELETE/api/students/:id删除学生
POST/api/students/import批量导入 CSV
GET/api/student/profile学生个人信息
PUT/api/student/profile修改学生名称
POST/api/student/profile上传头像

图书馆

方法路径说明
GET/api/library/books图书列表
POST/api/library/borrow借书（ISBN 扫码 + 人脸）
POST/api/library/return还书
GET/api/library/borrow-records借阅记录

宿舍管理

方法路径说明
POST/api/dorm/record人脸识别出入记录
GET/api/dorm/records出入记录列表
GET/api/dorm/records/export导出 CSV

家长端

方法路径说明
GET/api/parent/bindings已绑定学生列表
POST/api/parent/bind绑定学生
DELETE/api/parent/bind/:face_id解绑学生
GET/api/parent/student/:face_id/history学生考勤历史

部署指南

本地开发与生产部署

环境要求

  • Python 3.10+
  • Node.js 18+（仅文档站开发需要）
  • CMake / Visual Studio Build Tools（InsightFace 编译依赖）

本地开发

# 1. 克隆仓库
git clone <repo-url>
cd FaceSite

# 2. 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# 3. 安装依赖
pip install -r requirements.txt

# 4. 数据库迁移
python manage.py migrate

# 5. 创建管理员
python manage.py createsuperuser

# 6. 启动开发服务器
python manage.py runserver

环境变量

DEBUG=True
SECRET_KEY=your-secret-key
ALLOWED_HOSTS=localhost,127.0.0.1

生产部署

生产环境建议使用 Gunicorn + Nginx 反向代理：

# Gunicorn
pip install gunicorn
gunicorn config.wsgi:application --bind 0.0.0.0:8000

# Nginx 配置示例
server {
    listen 80;
    server_name your-domain.com;

    location /static/ { alias /path/to/FaceSite/staticfiles/; }
    location /media/ { alias /path/to/FaceSite/media/; }
    location / { proxy_pass http://127.0.0.1:8000; }
}

更新日志

所有版本变更记录