# 人脸识别管理系统使用指南 ## 🎯 系统简介 这是一个完整的人脸识别管理系统,支持: - ✅ **Web后台注册**: 通过Web管理后台注册用户 - ✅ **后端存储**: SQLite数据库集中存储用户特征 - ✅ **Android识别**: Android设备直接调用后端识别API - ✅ **统一管理**: 所有设备共享同一个用户库 --- ## 📦 系统架构 ``` ┌─────────────────────────┐ │ Web管理后台 │ │ http://IP:8000/admin │ │ - 注册用户 │ │ - 查看用户列表 │ │ - 删除用户 │ │ - 查看统计 │ └───────────┬─────────────┘ │ ↓ ┌─────────────────────────┐ │ FastAPI后端服务 │ │ - 用户管理API │ │ - 人脸识别API │ │ - SQLite数据库 │ │ - 特征提取引擎 │ └───────────┬─────────────┘ │ ↓ ┌───────┴────────┐ ↓ ↓ ┌─────────┐ ┌─────────┐ │Android1 │ │Android2 │ │ 识别 │ │ 识别 │ └─────────┘ └─────────┘ ``` --- ## 🚀 快速开始 ### 步骤1: 安装后端依赖 ```bash cd E:\face\FaceFeatureExtractorAPI pip install -r requirements.txt ``` ### 步骤2: 启动后端服务 ```bash python app.py ``` **预期输出**: ``` 🚀 启动服务: http://0.0.0.0:8000 📚 API文档: http://0.0.0.0:8000/docs 🎛️ 管理后台: http://0.0.0.0:8000/admin INFO: Uvicorn running on http://0.0.0.0:8000 ✅ 数据库初始化完成 ``` ### 步骤3: 打开Web管理后台 在浏览器中访问: `http://192.168.0.148:8000/admin` 你会看到一个美观的管理界面: - 统计面板(用户数、识别次数等) - 用户注册表单 - 用户列表 ### 步骤4: 注册用户 在Web管理后台: 1. 输入姓名(必填) 2. 输入年龄(可选) 3. 上传人脸照片 4. 点击"注册用户" **提示**: - 照片必须包含清晰的人脸 - 支持jpg/png格式 - 建议正面照,光线充足 ### 步骤5: Android端识别 Android应用**无需修改**,保持原有功能: - 活体检测在本地完成 - 识别时调用后端 `/api/recognize` 接口 - 后端在数据库中查找匹配用户 - 返回识别结果 --- ## 🔧 API接口文档 ### 1. 用户注册 **POST** `/api/users/register` **请求(multipart/form-data)**: ``` name: 张三 (必填) age: 25 (可选) image: [人脸照片文件] (必填) ``` **响应**: ```json { "success": true, "message": "用户 '张三' 注册成功", "user_id": 1, "user": { "id": 1, "name": "张三", "age": 25, "feature_dim": 1024, "photo_filename": "张三_20251020_143022.jpg", "created_at": "2025-10-20T14:30:22", "is_active": true } } ``` --- ### 2. 获取用户列表 **GET** `/api/users/list?skip=0&limit=100&active_only=true` **响应**: ```json { "success": true, "message": "查询成功", "total": 10, "users": [ { "id": 1, "name": "张三", "age": 25, "feature_dim": 1024, "photo_filename": "张三_20251020_143022.jpg", "created_at": "2025-10-20T14:30:22", "is_active": true } ] } ``` --- ### 3. 人脸识别 (核心接口) **POST** `/api/recognize` **请求(multipart/form-data)**: ``` image: [待识别的人脸照片] (必填) device_id: android_001 (可选) threshold: 0.7 (可选,默认0.7) ``` **响应(识别成功)**: ```json { "success": true, "message": "识别成功: 张三", "recognized": true, "user_id": 1, "user_name": "张三", "similarity": 0.8543, "threshold": 0.7, "processing_time": 0.52 } ``` **响应(未识别)**: ```json { "success": true, "message": "未识别到注册用户 (最高相似度: 0.62)", "recognized": false, "similarity": 0.62, "threshold": 0.7, "processing_time": 0.48 } ``` --- ### 4. 同步用户数据 **GET** `/api/users/sync` 返回所有用户的完整数据(包含特征向量),供Android端下载到本地 **响应**: ```json { "success": true, "message": "同步成功", "total": 10, "users": [ { "id": 1, "name": "张三", "age": 25, "feature_dim": 1024, "feature": [0.123, 0.456, ..., 0.789], // 1024维特征向量 "photo_filename": "张三_20251020_143022.jpg", "created_at": "2025-10-20T14:30:22", "is_active": true } ] } ``` --- ### 5. 删除用户 **DELETE** `/api/users/{user_id}` **响应**: ```json { "success": true, "message": "用户 '张三' 已删除" } ``` 注意:这是软删除,用户数据仍保留在数据库中,但`is_active`设置为false --- ### 6. 统计信息 **GET** `/api/stats` **响应**: ```json { "success": true, "stats": { "total_users": 10, "total_recognitions": 100, "successful_recognitions": 85, "recognition_rate": 85.0 } } ``` --- ## 📱 Android端修改(可选) 目前Android端已经兼容后端识别,无需修改。如果需要从Android端注册用户到后端,可以添加以下功能: ### 选项1: 保持当前模式(推荐) - **Web后台注册** → 后端数据库 - **Android识别** → 调用后端 `/api/recognize` ### 选项2: Android也支持注册到后端 修改RegisterActivity.java,在注册成功后调用后端注册API: ```java // 在extractAndRegister方法的onSuccess中添加 NetworkManager.getInstance().registerUserToBackend( bitmap, name, 1, // age new NetworkManager.ApiCallback<>() { @Override public void onSuccess(RegisterResponse result) { Toast.makeText(RegisterActivity.this, "用户已同步到后端", Toast.LENGTH_SHORT).show(); } @Override public void onFailure(String error) { Log.w(TAG, "后端同步失败: " + error); } } ); ``` --- ## 🗂️ 数据库结构 ### users表 ```sql CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(100) NOT NULL UNIQUE, -- 姓名 age INTEGER, -- 年龄 feature_vector BLOB NOT NULL, -- 1024维特征(二进制) feature_dim INTEGER DEFAULT 1024, -- 特征维度 photo_filename VARCHAR(255), -- 照片文件名 created_at TIMESTAMP, -- 创建时间 updated_at TIMESTAMP, -- 更新时间 is_active BOOLEAN DEFAULT TRUE -- 是否激活 ); ``` ### recognition_logs表 ```sql CREATE TABLE recognition_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER, -- 识别到的用户ID user_name VARCHAR(100), -- 识别到的用户姓名 device_id VARCHAR(100), -- 设备ID similarity FLOAT, -- 相似度 threshold FLOAT DEFAULT 0.7, -- 阈值 is_recognized BOOLEAN DEFAULT FALSE, -- 是否识别成功 recognized_at TIMESTAMP, -- 识别时间 photo_filename VARCHAR(255) -- 识别时的照片 ); ``` --- ## 📂 目录结构 ``` FaceFeatureExtractorAPI/ ├── app.py # 主应用(V2.0) ├── database.py # 数据库模型 ├── face_feature_extractor.py # 特征提取器 ├── admin.html # Web管理后台 ├── requirements.txt # Python依赖 ├── face_recognition.db # SQLite数据库(自动生成) └── uploads/ # 上传文件目录(自动生成) ├── photos/ # 用户照片 └── logs/ # 识别记录照片 ``` --- ## 🧪 测试流程 ### 1. 测试后端健康检查 ```bash curl http://192.168.0.148:8000/health ``` 预期: ```json { "status": "healthy", "extractor_loaded": true, "database_connected": true, "total_users": 0 } ``` ### 2. 测试Web注册 1. 打开 `http://192.168.0.148:8000/admin` 2. 填写姓名"测试用户" 3. 上传一张人脸照片 4. 点击"注册用户" 5. 查看用户列表是否显示新用户 ### 3. 测试API注册(使用Postman或curl) ```bash curl -X POST http://192.168.0.148:8000/api/users/register \ -F "name=测试用户" \ -F "age=25" \ -F "image=@/path/to/face.jpg" ``` ### 4. 测试识别API ```bash curl -X POST http://192.168.0.148:8000/api/recognize \ -F "image=@/path/to/face.jpg" \ -F "device_id=test_device" \ -F "threshold=0.7" ``` ### 5. 测试Android端 1. 确保Android设备和电脑在同一WiFi 2. 打开Android应用 3. 点击"人脸识别" 4. 对准摄像头 5. 活体检测通过后自动识别 6. 查看是否显示注册的用户姓名 --- ## ⚙️ 配置选项 ### 修改识别阈值 在 `app.py` 中搜索 `threshold`,修改默认值: ```python threshold: float = Form(0.7, description="识别阈值"), ``` 或者在调用 `/api/recognize` 时传递自定义阈值: ``` threshold=0.75 ``` ### 修改数据库路径 在 `database.py` 中修改: ```python DATABASE_URL = "sqlite:///./face_recognition.db" ``` ### 修改照片存储路径 在 `app.py` 中修改: ```python UPLOAD_DIR = Path("uploads") PHOTOS_DIR = UPLOAD_DIR / "photos" ``` --- ## 🔒 生产环境建议 1. **使用HTTPS**: 配置SSL证书,保护数据传输 2. **使用PostgreSQL**: 替换SQLite,提高并发性能 3. **添加身份验证**: API添加Token验证 4. **数据备份**: 定期备份数据库和照片 5. **日志监控**: 记录所有API请求和识别记录 6. **限流保护**: 防止恶意请求 --- ## 🐛 故障排除 ### 问题1: 数据库初始化失败 **现象**: 启动时报错 `ImportError: cannot import name 'User' from 'database'` **解决**: ```bash # 确保database.py存在且无语法错误 python -c "from database import User, init_database; init_database()" ``` ### 问题2: 识别总是失败 **检查**: 1. 后端是否有注册用户: 访问 `/api/users/list` 2. 识别阈值是否过高: 尝试降低到 0.6 3. 照片质量是否合格: 确保光线充足,人脸清晰 ### 问题3: Android无法连接后端 **检查**: 1. 电脑防火墙是否开放8000端口 2. Android和电脑是否在同一WiFi 3. IP地址是否正确配置 4. Web API是否正在运行 --- ## 📊 性能优化 ### 数据库优化 ```sql -- 为常用查询添加索引 CREATE INDEX idx_users_name ON users(name); CREATE INDEX idx_users_active ON users(is_active); CREATE INDEX idx_logs_recognized_at ON recognition_logs(recognized_at); ``` ### 特征向量缓存 ```python # 在app.py中添加缓存(可选) from functools import lru_cache @lru_cache(maxsize=100) def get_user_features_cached(user_id): # 缓存用户特征向量 pass ``` --- ## 📝 更新日志 ### V2.0.0 (2025-10-20) - ✅ 添加SQLite数据库支持 - ✅ 实现用户注册API - ✅ 实现后端识别API - ✅ 创建Web管理后台 - ✅ 添加识别日志记录 - ✅ 支持统计功能 - ✅ 支持用户同步 ### V1.0.0 - ✅ 基础特征提取API - ✅ 特征对比API - ✅ 无状态服务 --- ## 🆘 获取帮助 如果遇到问题: 1. 查看后端日志: 终端输出 2. 查看API文档: `http://192.168.0.148:8000/docs` 3. 检查数据库: 使用SQLite浏览器打开 `face_recognition.db` 4. 查看识别记录: 查询 `recognition_logs` 表 --- ## 🎉 快速测试命令 ```bash # 1. 安装依赖 cd E:\face\FaceFeatureExtractorAPI pip install -r requirements.txt # 2. 启动服务 python app.py # 3. 在浏览器打开管理后台 start http://192.168.0.148:8000/admin # 4. 测试健康检查 curl http://192.168.0.148:8000/health # 5. 查看用户列表 curl http://192.168.0.148:8000/api/users/list # 6. 查看统计 curl http://192.168.0.148:8000/api/stats ``` **现在可以开始使用了!** 🚀