# 基于OpenCV和Python的人脸识别系统

**Repository Path**: comeyuan/face_recognition

## Basic Information

- **Project Name**: 基于OpenCV和Python的人脸识别系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 校园人脸识别管理系统

> 当前升级路线与工程治理约定见 [校园入口人脸识别系统实施计划](docs/IMPLEMENTATION_PLAN.md)。

> 已实现功能和待办见 [当前实现状态](docs/IMPLEMENTATION_STATUS.md)。

这是一个 B/S 架构的校园入口人脸识别通行系统：Vue 3 运行在浏览器中，Django 提供本地或校园内网服务，OpenCV 在服务端离线完成人脸检测与比对。人脸照片不会发送给第三方。

当前版本为2.1.1，默认使用预训练YuNet + SFace本地深度特征识别，未自行训练其网络权重，保留Haar + LBPH作教学对照。后台已包含通行工作台、入口管理、权限管理、通行记录与识别参数测试。公开演示数据和真实人员批量导入方式见 [演示数据与导入说明](docs/DEMO_DATA.md)，比赛前的完成条件见 [比赛交付核对清单](docs/COMPETITION_READINESS.md)。

## 快速开始

要求：macOS/Linux、`uv`、Node.js/npm。

```bash
./scripts/setup.sh
uv run python server_code/run_server.py
```

打开启动窗口显示的地址，默认是 `http://127.0.0.1:8080/manage/`，端口占用时自动选择空闲端口。首次运行的管理员为 `admin`，初始密码为 `Campus@123`；登录后请立即修改。

校门识别界面地址是启动地址加`#/terminal`，例如`http://127.0.0.1:8080/manage/#/terminal`；管理后台也可从“人脸识别 → 人脸识别中心”进入。首次识别前，先在“校园人员”中建档，再在“通行权限”授予相应入口权限。初始管理员没有人脸档案，不能直接作为被识别人员；已建档但没有通行权限也不会开门。

环境和依赖统一由根目录`pyproject.toml`与`uv.lock`管理，数据库由Django迁移初始化。不再使用旧版Django 2.0安装批处理、`init.py`或手工导入旧SQL。

## 开发运行

```bash
# 后端
uv run python server_code/manage.py runserver 0.0.0.0:8080

# 另一个终端运行前端
npm --prefix manage_code run serve
```

默认使用 SQLite；如需 MySQL，复制 `.env.example` 为 `.env` 并修改 `DB_*` 配置。

## Ubuntu服务器部署（Docker）

完整流程见[Ubuntu Docker部署手册](docs/DEPLOYMENT_DOCKER.md)，包含Docker安装、源码上传、HTTPS、摄像头、备份、升级和故障处理。

在具有Docker Compose和域名的服务器项目目录中：

```bash
python3 deploy/init_env.py --domain 你的实际域名
./deploy/compose.sh config --quiet
./deploy/compose.sh --profile https up -d --build --wait --wait-timeout 300
```

设备密钥和随机初始管理员密码在私有`.env.docker`中，不是桌面版默认密码；先登录管理员，再打开`https://你的域名/manage/#/terminal`。数据库和照片由独立数据卷保留，默认不导入本地演示人员。远程摄像头需要HTTPS，没有域名时可按手册使用SSH隧道临时验证。

当前新增Docker部署文件尚未推送Gitee；可运行`./deploy/package_source.sh`生成排除密钥与运行数据的源码包上传，不能直接把macOS程序当作Ubuntu程序使用。

## 校园入口通行 API

新的门禁业务位于独立的 `campus_access` 模块，不再继续堆入旧的 CRUD 视图。初始化后会创建默认入口“学校正门”：

```bash
uv run python server_code/manage.py migrate
uv run python server_code/manage.py bootstrap_campus
```

核心接口：

- `POST /campus/access/recognize`：识别、权限判断、模拟开门并保存通行事件。
- `GET /campus/access/events`：管理员查询通行事件。
- `GET /campus/access/dashboard`：管理员查询今日通行统计。
- `GET/POST /campus/access/gates`：入口查询与维护。
- `GET/POST /campus/access/permissions`：人员通行授权与停用。
- `GET/POST /campus/access/configuration`：切换本地引擎、保存识别阈值。
- `POST /campus/access/experiment`：单张照片分数分析，不开门、不写通行事件。

终端本机调试时可以直接调用识别接口。局域网或服务器部署须设置`TERMINAL_DEVICE_TOKEN`，独立设备通过`X-Device-Token`请求头传递凭证；浏览器终端使用签名的管理员登录Token，不把设备密钥编译进网页。人员需要拥有“学校正门”的有效通行权限，识别成功后才会模拟开门。

提交代码前可运行统一检查：

```bash
./scripts/check.sh
```

## 打包

```bash
./scripts/build_release.sh
```

脚本会用 `uv` 同步虚拟环境、构建 Vue、执行检查与测试，再通过 PyInstaller 生成当前平台的发布包。macOS 不能直接交叉打包 Windows 程序，Windows 版需在 Windows 机器上运行同类打包流程。

当前macOS ARM64发布包位于 `dist/campus-face-system-2.1.1-macos-arm64.tar.gz`，目录为`dist/release-2.1.1/`。版本来自`pyproject.toml`，包名自动包含构建平台和架构。打包前需要按照演示数据说明准备公开数据集，模型文件和来源许可会随包提供，不复制开发环境的数据库和密钥。

打包流程会执行代码检查、测试、前端构建，以及全新临时目录中的实际启动和四类通行验证，通过后才生成压缩包。若同版本发布目录已存在，脚本会停止，不覆盖其中可能存在的使用数据。

解压 macOS 发布包后，双击“启动校园人脸识别系统.command”即可。首次启动需初始化 OpenCV 和数据库，可能需要等待约 30 秒。

双击“启动校园演示.command”会在首次运行时导入包内30名演示人员，另外保留10个陌生身份用于测试；无需联网下载模型或图片。

首次演示初始化还会校验400张照片并运行标定，在新目录中可能需要1至2分钟。后续启动保留已有数据，不再重复导入。

默认只监听本机。如要在校园内网访问，可在发布目录新建 `.env`，设置 `SERVER_HOST=0.0.0.0` 并正确配置 `DJANGO_ALLOWED_HOSTS`。

## 人脸录入建议

- 每人可上传1至5张清晰单人照片，建议包含不同光线与轻微角度变化。
- 摄像头登录要求浏览器允许摄像头权限。
- 默认SFace展示分数阈值为75，后台保存后立即生效；该分数不是身份正确概率。后续应使用学生照片和实际摄像头重新校准。
- 当前版本是身份验证，不包含专业活体检测，不应直接用于高安全门禁。