# faceapp

**Repository Path**: dpp5258/faceapp

## Basic Information

- **Project Name**: faceapp
- **Description**: 基于开源面部模型的简单社交app
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/dpp5258/faceapp
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-05-25
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于人脸识别的桌面应用 — 人脸认证·颜值测评·面部互动·防窥保护

## 技术栈

| 层级 | 技术 |
|------|------|
| 桌面框架 | PyQt6 |
| 计算机视觉 | OpenCV, MediaPipe (Tasks API), face_recognition (dlib) |
| AI 模型 | YuNet ONNX (人脸检测), FaceLandmarker (478关键点), DashScope (通义千问) |
| 数据库 | SQLite (face_system.db) |
| 密码加密 | PBKDF2-HMAC-SHA256（Python 标准库，零依赖） |
| 语言 | Python 3.9+ |

## 项目架构 (MVC+F)

```
├── main.py                          # 应用入口
├── docs/                            # 设计文档
├── tests/                           # 独立测试脚本
├── scripts/                         # 数据库脚本（建表/迁移）
├── databases/                       # SQLite 数据库文件
├── uploads/                         # 用户上传图片/测评截图
│
├── views/                           # V: 视图层 — PyQt6 UI
│   ├── login_window.py              #   登录窗口
│   ├── register_window.py           #   注册窗口
│   ├── main_window.py               #   普通用户主窗口（多页面容器 + 防窥模糊遮罩）
│   ├── admin_window.py              #   管理员后台窗口
│   ├── pages/                       #   主窗口子页面
│   │   ├── home_page.py             #     首页（面部测评入口）
│   │   ├── square_page.py           #     广场（发帖浏览）
│   │   ├── history_page.py          #     历史测评记录
│   │   ├── profile_page.py          #     个人中心（含人脸录入按钮 + 状态显示）
│   │   ├── fun_page.py              #     趣味功能（游戏/匹配/防窥开关 + 仪表盘）
│   │   ├── announcement_management_page.py  # 公告管理（管理员）
│   │   ├── content_audit_page.py    #     内容审核（管理员）
│   │   └── user_audit_page.py       #     用户审核（管理员）
│   ├── dialogs/                     #   弹窗
│   │   ├── change_password_dialog.py
│   │   ├── edit_profile_dialog.py
│   │   ├── face_capture_dialog.py   #    🆕 人脸录入 (摄像头预览 + 实时检测 + 拍照提取)
│   │   ├── publish_dialog.py
│   │   ├── settings_dialog.py
│   │   └── game_window.py
│   ├── fun_windows/                 #   趣味功能独立窗口
│   │   ├── game_window.py           #     吃苹果游戏窗口
│   │   └── match_window.py          #     面部匹配窗口
│   └── styles/                      #   样式管理 (QSS)
│
├── Controllers/                     # C: 控制层 — 业务逻辑编排
│   ├── auth_controller.py           #   注册/登录认证（含登录失败日志 + 明文密码自动升级）
│   ├── assessment_controller.py     #   面部打分（CV→AI→DB 全流程编排）
│   ├── privacy_controller.py        #   屏幕防窥（CameraWorker线程 + 状态机 + 信号桥接）
│   ├── game_controller.py           #   吃苹果游戏控制
│   ├── match_controller.py          #   面部匹配（查库→向量比对）
│   ├── post_controller.py           #   用户发帖
│   ├── user_controller.py           #   用户信息管理（含密码修改/人脸录入/封禁删除）
│   ├── announcement_controller.py   #   公告管理
│   └── workers.py                   #   后台线程（AI流式分析等）
│
├── models/                          # M: 数据层 — ORM/CRUD
│   ├── user_model.py                #   用户表（含128维 face_vector + 密码自动哈希入库）
│   ├── assessments_model.py         #   面部测评记录表
│   ├── announcements_model.py       #   公告表
│   ├── user_posts_model.py          #   用户帖子表
│   └── security_logs_model.py       #   安全日志表
│
├── features/                        # F: 算法层 — 纯逻辑，无 Qt 依赖
│   ├── skin_analysis/               #   面部打分模块
│   │   ├── analyzer.py              #     CV 皮肤分析引擎（MediaPipe + OpenCV）
│   │   ├── agent.py                 #     LLM AI 护肤建议（DashScope 流式）
│   │   ├── config.py                #     评分基准参数 & 权重配置
│   │   └── schemas.py               #     共享数据类型（RegionResult, AnalysisReport 等）
│   ├── face/                        #   面部识别模块
│   │   ├── encoder.py               #     128 维人脸特征提取（dlib/face_recognition）
│   │   ├── matcher.py               #     余弦相似度 1:1 / 1:N 匹配
│   │   └── privacy_guard.py         #     防窥匹配器（加载授权向量，实时帧比对）
│   ├── security/                    #   🆕 安全模块
│   │   └── password.py              #     PBKDF2 密码哈希/验证（含旧明文兼容 & 自动升级）
│   ├── eat_apple/                   #   吃苹果游戏引擎
│   │   ├── detector.py              #     YuNet ONNX 5点人脸检测
│   │   ├── engine.py                #     游戏核心循环 & 状态管理
│   │   ├── collision.py             #     碰撞检测 & 几何计算
│   │   ├── renderer.py              #     游戏画面渲染
│   │   └── yunet.onnx               #     YuNet 人脸检测模型
│   └── model_assets/                #   模型资产
│       └── face_landmarker.task     #     MediaPipe FaceLandmarker 模型
│
└── utils/                           # 工具模块
    ├── image_handler.py             #   图片处理
    └── bgm_manager.py               #   背景音乐管理
```

## 角色权限

| 角色 | 功能 |
|------|------|
| **普通用户** | 面部测评、面部匹配、吃苹果游戏、屏幕防窥、发帖浏览、个人信息管理、人脸录入 |
| **管理员** | 用户审核、内容审核、公告管理、账号管理（封禁/删除/编辑）（无娱乐功能） |

## 核心功能实现

### 1. 面部打分

**流程**: `图片上传 → MediaPipe 478关键点检测 → 4区域分割(额头/左颊/右颊/下巴) → OpenCV 多维度分析(痘痘/毛孔/泛红/均匀度) → 性别差异化加权评分 → LLM AI 流式护肤建议 → 数据库写入`

**关键文件**:

| 文件 | 职责 |
|------|------|
| [features/skin_analysis/analyzer.py](features/skin_analysis/analyzer.py) | CV 引擎：白平衡 → 高光去除 → HSV痘痘检测 / 高斯差分毛孔检测 / LAB泛红检测 / 灰度均匀度 → 评分函数 |
| [features/skin_analysis/agent.py](features/skin_analysis/agent.py) | LLM Agent：构造 System Prompt（皮肤科专家角色）→ DashScope 流式调用 → 解析 core_summary/skin_type/suggestion |
| [features/skin_analysis/config.py](features/skin_analysis/config.py) | 男/女理想基准值 + 四项指标权重(痘痘0.3/毛孔0.3/泛红0.2/均匀0.2) + 四区域权重 |
| [features/skin_analysis/schemas.py](features/skin_analysis/schemas.py) | RegionResult / AnalysisReport / AIAnalysisResult 类型定义 |
| [Controllers/assessment_controller.py](Controllers/assessment_controller.py) | 编排器：保存图片 → CV分析 → 128维特征提取(写DB) → AI Worker 线程(流式) → assessments 表 + security_logs 表写入 |
| [features/model_assets/face_landmarker.task](features/model_assets/face_landmarker.task) | MediaPipe Tasks API 模型 (~3.7MB, 含 tflite + metadata) |

### 2. 屏幕防窥

**流程**: `启用开关 → 加载授权用户128维向量 → CameraWorker后台线程(15fps) → face_recognition 实时人脸检测 → 1:1 余弦相似度比对 → 状态机驱动(正常/围观模糊/锁屏)`

**状态机**:

```
face_count ≥ 2  → 🚨 围观 → MainWindow 全屏模糊遮罩
face_count = 1 + 本人   → ✅ 正常 → 清除遮罩
face_count = 1 + 陌生人 → ❌ 累计 fail_count
fail_count ≥ 3  → 🔒 Windows LockWorkStation() 锁屏
face_count = 0  → 忽略（可能暂时离开）
```

**关键文件**:

| 文件 | 职责 |
|------|------|
| [features/face/privacy_guard.py](features/face/privacy_guard.py) | PrivacyMatcher：从DB加载授权用户128维向量，常驻内存，对每帧执行 face_locations + face_encodings + compare_faces |
| [Controllers/privacy_controller.py](Controllers/privacy_controller.py) | CameraWorker(QThread) + PrivacyController(状态机+信号中枢)：发射 blur_show/blur_hide/lock_screen/status_updated 四个信号 |
| [features/face/encoder.py](features/face/encoder.py) | 从 BGR 图片提取 128 维 dlib encoding |
| [features/face/matcher.py](features/face/matcher.py) | text→向量还原 + 余弦相似度计算 + 1:N 匹配 |
| [views/main_window.py](views/main_window.py) | blur_overlay 全屏遮罩层，接收防窥信号显示/隐藏 |
| [views/pages/fun_page.py](views/pages/fun_page.py) | 防窥开关复选框 + QScrollArea 实时状态仪表盘（事件日志） |

### 3. 面部匹配

**流程**: `获取当前用户128维向量 → 查DB获取所有已录入特征的用户 → 排除自己 → find_similar_users() 余弦相似度 1:N → 按相似度降序返回`

**关键文件**:

| 文件 | 职责 |
|------|------|
| [features/face/matcher.py](features/face/matcher.py) | find_similar_users()：文本还原 → 过滤 → 余弦相似度 → 排序 |
| [Controllers/match_controller.py](Controllers/match_controller.py) | 编排查库 + 调用匹配函数 |
| [views/fun_windows/match_window.py](views/fun_windows/match_window.py) | 匹配结果展示 UI |

### 4. 吃苹果游戏

**流程**: `摄像头实时帧 → YuNet ONNX 5点人脸检测(左右眼/鼻尖/左右嘴角) → 头部姿态映射游戏坐标 → 碰撞检测 → 得分/扣分 → 通关判定`

**关键文件**:

| 文件 | 职责 |
|------|------|
| [features/eat_apple/detector.py](features/eat_apple/detector.py) | FivePointExtractor：cv2.FaceDetectorYN 加载 YuNet ONNX → 5点输出 |
| [features/eat_apple/engine.py](features/eat_apple/engine.py) | GameEngine：游戏主循环(状态机/计时/苹果生成/得分) |
| [features/eat_apple/collision.py](features/eat_apple/collision.py) | 碰撞检测 + PNG 叠加 |
| [features/eat_apple/renderer.py](features/eat_apple/renderer.py) | GameRenderer：画面渲染 |
| [Controllers/game_controller.py](Controllers/game_controller.py) | 游戏控制器 → 对接 UI 窗口 |

### 5. 🆕 人脸录入

**流程**: `个人中心点击「录入人脸」→ FaceCaptureDialog 摄像头弹窗 → Haar 级联实时检测（单人=绿框可拍 / 多人=橙框警告 / 无人=禁止）→ 拍照 → extract_face_encoding() 128维向量 → UserController.update_face_vector() → DB + security_logs`

**两种录入途径**:

| 途径 | 触发位置 | 说明 |
|------|---------|------|
| 人脸录入弹窗 | 个人中心 → 🧠 录入人脸 | 独立采集，Haar 实时检测 + 拍照提取 |
| 面部测评附带 | 首页 → 面部测评 | 测评过程中自动提取（stage 2.5） |

**关键文件**:

| 文件 | 职责 |
|------|------|
| [views/dialogs/face_capture_dialog.py](views/dialogs/face_capture_dialog.py) | 摄像头预览 → Haar 人脸检测 → 拍照 → 调用 encoder |
| [views/pages/profile_page.py](views/pages/profile_page.py) | 人脸状态标签（🟢已录入 / 🔴未录入）+ 录入按钮 |
| [features/face/encoder.py](features/face/encoder.py) | BGR → RGB → face_locations + face_encodings → 128维 list |

### 6. 🆕 密码安全

**加密方案**: PBKDF2-HMAC-SHA256，100,000 次迭代，16 字节随机盐值，Python 标准库零依赖。

**存储格式**: `{hex_salt}${hex_hash}`（例: `a1b2c3...$d4e5f6...`，共 97 字符）

**旧明文迁移**: 用户登录时自动检测 → 明文比对成功后自动 re-hash 写回 DB → 用户无感知。

| 文件 | 职责 |
|------|------|
| [features/security/password.py](features/security/password.py) | hash_password() / verify_password() / is_hashed() |
| [models/user_model.py](models/user_model.py) | create_user / update_password 入库前自动 hash |
| [Controllers/auth_controller.py](Controllers/auth_controller.py) | 登录 verify_password + 明文自动升级 + 登录失败日志 |
| [Controllers/user_controller.py](Controllers/user_controller.py) | 改密码时 verify_password 校验旧密码 |

## 安全日志 (security_logs)

所有关键操作均写入 `security_logs` 表，可追溯审计：

| log_type | 触发操作 | 记录位置 |
|----------|---------|---------|
| `register` | 用户注册 | auth_controller |
| `login` / `login_failed` | 登录成功/失败 | auth_controller |
| `change_password` | 修改密码 | user_controller |
| `update_username` / `update_phone` | 修改资料 | user_controller |
| `update_avatar` | 更换头像 | user_controller |
| `update_face` / `face_feature` | 人脸录入/测评提取 | user_controller / assessment_controller |
| `user_approved` / `user_rejected` | 审核用户 | user_controller |
| `user_banned` / `user_unbanned` / `user_deleted` | 封禁/解封/删除 | user_controller |
| `publish_announcement` / `edit_announcement` / `delete_announcement` | 公告管理 | announcement_controller |
| `privacy_lock` | 防窥锁屏 | privacy_controller |
| `admin_edit_user` | 管理员编辑用户 | user_audit_page |

## 数据库表结构

| 表 | 关键字段 | 说明 |
|----|---------|------|
| `users` | id, username, password, phone, **face_vector**(TEXT), role, status | 用户表（密码 PBKDF2 加密；128维特征向量以逗号分隔文本存储） |
| `assessments` | id, user_id(FK), beauty_score, skin_type, suggestion, image_path | 面部测评记录 |
| `security_logs` | id, user_id(FK), log_type, details, create_time | 安全日志（全操作审计） |
| `announcements` | id, title, content, create_time | 平台公告 |
| `user_posts` | id, user_id(FK), content, image_path, status | 用户帖子（需审核） |

## 关键设计要点

1. **密码安全**: PBKDF2-HMAC-SHA256 加密存储，旧明文密码登录时自动升级，`get_user_info()` 不返回密码字段
2. **中文路径避免**: MediaPipe C++ 底层不支持含中文路径，使用 `BaseOptions(model_asset_buffer=bytes)` 将模型以内存数据传入，绕开文件路径解析
3. **CUDA 禁用**: `main.py` 入口设置 `CUDA_VISIBLE_DEVICES=""`，避免 dlib 在无 NVIDIA GPU 机器上每帧抛 `cudaGetDevice` 异常
4. **Features 层零依赖**: 所有 features/ 模块纯函数设计，不依赖 PyQt，可独立测试（见 tests/）
5. **face_vector 依赖链**: 面部匹配和屏幕防窥依赖用户已录入128维特征向量，可通过人脸录入弹窗独立采集，也可通过面部测评附带提取

## 运行方式

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

# 初始化数据库
python scripts/create_tables.py

# 创建管理员账号
python scripts/migrate.py

# 启动应用
python main.py

# 独立测试
python tests/test_face_scoring.py          # 面部打分CV测试
python tests/test_face_scoring.py "图片.jpg" female
python tests/test_privacy.py               # 屏幕防窥测试
```