1 line
34 KiB
JSON
1 line
34 KiB
JSON
{"repo": "cai-0312/faceattendancesystem", "files": {"DEPLOYMENT.md": {"44a1020b555497ae4d618447b123512b472ae462": {"t": 1785746624.420752, "n": 12481, "h": "507d900b2c999035", "c": "# FaceAttendanceSystem 部署指南\n\n## 📋 系统需求\n\n### 硬件要求\n\n#### 客户端 (打卡机)\n\n```\n最低配置:\n├─ CPU: Intel i5-8400 或同级 (4核)\n├─ 内存: 8GB RAM\n├─ 显卡: NVIDIA GTX 1050 或以上 (推荐)\n├─ 存储: 256GB SSD\n├─ 网络: 10Mbps 局域网 / 4G 网络\n└─ 摄像头: 1080p USB 摄像头 / 内置摄像头\n\n推荐配置 (生产环境):\n├─ CPU: Intel i7-9700 或同级 (8核+)\n├─ 内存: 16GB RAM\n├─ 显卡: NVIDIA RTX 3060 (12GB 显存)\n├─ 存储: 512GB NVMe SSD\n├─ 网络: 千兆以太网\n└─ 摄像头: 工业级人脸识别摄像头 (130° 广角)\n```\n\n#### 服务器\n\n```\n最低配置:\n├─ CPU: 4 核虚拟处理器\n├─ 内存: 8GB RAM\n├─ 存储: 100GB 数据盘 + 50GB 系统盘\n├─ 网络: 100Mbps 专线\n├─ 数据库: MySQL 5.7+\n└─ 容错: 单机部署\n\n推荐配置 (生产环境):\n├─ CPU: 16 核物理处理器 (双 CPU)\n├─ 内存: 32GB 高速 ECC 内存\n├─ 存储: SSD 磁盘阵列 (RAID 1)\n├─ 网络: 千兆网络 + 专线备链\n├─ 数据库: MySQL 8.0 主从集群 (3 节点)\n└─ 容错: 高可用架构 (Keepalived)\n```\n\n### 软件要求\n\n#### Windows 客户端\n\n```\n操作系统:\n├─ Windows 10 Pro (21H2) 或更新\n├─ Windows 11 (任何版本)\n└─ Windows Server 2019/2022 (可选)\n\n开发工具:\n├─ Visual Studio 2019/2022 Community 或 Professional\n│ └─ C++ 工作负载\n├─ Qt Creator 5.12 或更新\n└─ CMake 3.16+\n\n依赖库:\n├─ Qt 5.12.1+ (编译好的二进制)\n├─ OpenCV 4.5+ (CUDA 支持)\n├─ ONNX Runtime 1.12+\n├─ CUDA Toolkit 11.x (GPU 加速用)\n└─ cuDNN 8.x (深度学习库)\n\n模型文件:\n├─ retinaface-resnet50.onnx (人脸检测)\n└─ w600k_r50.onnx (特征提取)\n```\n\n#### Linux 服务器\n\n```\n操作系统:\n├─ Ubuntu 20.04 LTS / 22.04 LTS (推荐)\n├─ CentOS 7/8\n└─ Debian 10+\n\n开发环境:\n├─ GCC 9.0+ / Clang 10+\n├─ CMake 3.16+\n├─ Make / Ninja\n└─ Git\n\n依赖库:\n├─ Qt 5.12.1+ (开发库)\n├─ MySQL Client 8.0\n├─ ODBC Driver 17 for SQL Server (可选)\n└─ OpenSSL 1.1+\n\n系统库:\n└─ build-essential, libssl-dev 等标准开发库\n```\n\n---\n\n## 🔧 编译与构建\n\n### Windows 客户端编译\n\n#### 步骤 1: 安装依赖\n\n```bash\n# 1. 安装 Visual Studio 2022\n# - 选择 C++ 工作负载\n# - 包含 CMake 和 MSVC 编译器\n\n# 2. 安装 Qt 5.12.1\n# 下载: https://www.qt.io/download\n# 选择 MSVC 2019/2022 64-bit 版本\n# 安装路径: C:\\Qt\\5.12.1\\msvc2022_64\n\n# 3. 安装 OpenCV (CUDA 支持)\n# 方式 A: 预编译版本 (推荐)\n# 下载: https://github.com/opencv/opencv/releases\n# 选择: opencv-4.5.5-vc14_vc15.exe\n# 安装路径: C:\\OpenCV\n\n# 方式 B: 从源码编译 (如需 CUDA)\ngit clone https://github.com/opencv/opencv.git\ncd opencv\nmkdir build && cd build\ncmake -G \"Visual Studio 17 2022\" ^\n -DWITH_CUDA=ON ^\n -DCUDA_FAST_MATH=ON ^\n -DWITH_CUBLAS=ON ^\n -DCMAKE_INSTALL_PREFIX=C:\\OpenCV_CUDA ..\ncmake --build . --config Release -j 8\ncmake --install . --config Release\n\n# 4. 安装 CUDA Toolkit 11.8\n# 下载: https://developer.nvidia.com/cuda-11-8-0-download-archive\n# 选择 Windows x86_64\n# 安装到: C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\n\n# 5. 安装 cuDNN 8.6\n# 下载: https://developer.nvidia.com/cudnn (需注册)\n# 解压到 CUDA 安装目录\nxcopy C:\\cudnn\\bin\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\bin\" /Y\nxcopy C:\\cudnn\\include\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\include\" /Y\nxcopy C:\\cudnn\\lib\\x64\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\lib\\x64\" /Y\n\n# 6. 安装 ONNX Runtime\n# 下载: https://github.com/microsoft/onnxruntime/releases\n# 选择: onnxruntime-win-x64-gpu-1.14.1.zip\n# 解压路径: C:\\onnxruntime\n\n# 7. 下载模型文件\n# retinaface-resnet50.onnx (80MB)\n# https://github.com/deepinsight/insightface/releases\n# w600k_r50.onnx (200MB)\n# https://github.com/deepinsight/insightface/releases\n# 放置路径: D:\\models\\\n```\n\n#### 步骤 2: 配置 CMakeLists.txt\n\n```cmake\n# FaceAttendanceSystem/CMakeLists.txt (示例)\n\ncmake_minimum_required(VERSION 3.16)\nproject(FaceAttendanceSystem)\n\nset(CMAKE_CXX_STANDARD 17)\nset(CMAKE_AUTOMOC ON)\nset(CMAKE_AUTORCC ON)\nset(CMAKE_AUTOUIC ON)\n\n# 1. 查找 Qt\nfind_package(Qt5 COMPONENTS \n Core Gui Widgets Network Sql \n REQUIRED \n)\n\n# 2. 查找 OpenCV (CUDA 版本)\nfind_package(OpenCV 4.5 REQUIRED)\n\n# 3. 查找 ONNX Runtime\nset(ONNXRUNTIME_ROOT \"C:/onnxruntime\")\nfind_library(ONNXRUNTIME_LIB \n NAMES onnxruntime \n PATHS ${ONNXRUNTIME_ROOT}/lib\n)\nset(ONNXRUNTIME_INCLUDE_DIR \"${ONNXRUNTIME_ROOT}/include\")\n\n# 4. CUDA 配置\nenable_language(CUDA)\nset(CUDA_NVCC_FLAGS \"${CUDA_NVCC_FLAGS} -arch=sm_75\")\n\n# 5. 客户端可执行文件\nadd_executable(AttendanceClient\n AttendanceClient/main.cpp\n AttendanceClient/AttendanceClient.cpp\n AttendanceClient/MainWidget.cpp\n AttendanceClient/FaceProcessThread.cpp\n AttendanceClient/NetworkHelper.cpp\n AttendanceClient/PunchModule.cpp\n AttendanceClient/RegisterModule.cpp\n AttendanceClient/ChatModule.cpp\n AttendanceClient/AIAssistantModule.cpp\n AttendanceClient/RecordModule.cpp\n AttendanceClient/UserModule.cpp\n AttendanceClient/ProfileModule.cpp\n AttendanceClient/HomeModule.cpp\n)\n\ntarget_link_libraries(AttendanceClient\n Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::Sql\n ${OpenCV_LIBS}\n ${ONNXRUNTIME_LIB}\n cuda_runtime cudart\n)\n\ntarget_include_directories(AttendanceClient PUBLIC\n ${ONNXRUNTIME_INCLUDE_DIR}\n ${CUDA_INCLUDE_DIRS}\n)\n\n# 6. 服务端可执行文件\nadd_executable(AttendanceServer\n AttendanceServer/main.cpp\n AttendanceServer/AttendanceServer.cpp\n AttendanceServer/DatabaseManager.cpp\n AttendanceServer/RequestHandler.cpp\n AttendanceServer/Requesthandler_part1.cpp\n AttendanceServer/Requesthandler_part2.cpp\n AttendanceServer/Requesthandler_part3.cpp\n AttendanceServer/Requesthandler_part4.cpp\n AttendanceServer/ServerLogin.cpp\n AttendanceServer/ConfigEncryptor.cpp\n)\n\ntarget_link_libraries(AttendanceServer\n Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::Sql\n)\n```\n\n#### 步骤 3: 编译客户端\n\n```bash\n# 在项目根目录\n\n# 创建 build 目录\nmkdir build\ncd build\n\n# 配置 (CMake)\ncmake -G \"Visual Studio 17 2022\" ^\n -DCMAKE_PREFIX_PATH=\"C:/Qt/5.12.1/msvc2022_64\" ^\n -DOpenCV_DIR=\"C:/OpenCV/opencv-build\" ^\n -DONNXRUNTIME_ROOT=\"C:/onnxruntime\" ..\n\n# 编译 (Release 模式，8 并行线程)\ncmake --build . --config Release -j 8\n\n# 输出目录\n# .\\Release\\AttendanceClient.exe (可执行文件)\n# .\\Release\\*.dll (所有 Qt/OpenCV DLL 文件)\n```\n\n#### 步骤 4: 打包应用\n\n```bash\n# 使用 Qt 部署工具\ncd Release\n\n# 复制依赖库\nwindeployqt.exe AttendanceClient.exe\n\n# 结果:\n# AttendanceClient.exe (主程序)\n# platforms/qwindows.dll\n# imageformats/*.dll\n# sqldrivers/*.dll\n# (以及 OpenCV/ONNX 库)\n\n# 创建安装包 (可选)\n# 使用 NSIS 或 WiX 工具包\n```\n\n### Linux 服务器编译\n\n#### 步骤 1: 安装依赖\n\n```bash\n# Ubuntu 22.04 为例\n\n# 系统库\nsudo apt update\nsudo apt install -y \\\n build-essential \\\n cmake \\\n git \\\n libqt5core5a libqt5gui5 libqt5widgets5 \\\n qt5-qmake qtbase5-dev \\\n libmysqlclient-dev \\\n libssl-dev \\\n libodbc1 odbcinst unixodbc-dev\n\n# MySQL 客户端\nsudo apt install -y mysql-client mysql-server\n\n# 可选: ODBC Driver 17\ncurl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -\nsudo add-apt-repository \"$(curl https://packages.microsoft.com/config/ubuntu/22.04/mssql-server-2019.list)\"\nsudo apt install -y msodbcsql17\n\n# 编译工具\nsudo apt install -y ninja-build pkg-config\n```\n\n#### 步骤 2: 编译服务端\n\n```bash\n# 创建 build 目录\nmkdir build && cd build\n\n# 配置 (CMake)\ncmake -DCMAKE_BUILD_TYPE=Release \\\n -G Ninja \\\n -DCMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt5 ..\n\n# 编译\nninja -j $(nproc)\n\n# 输出\n./AttendanceServer (可执行文件)\n```\n\n---\n\n## 🗄️ 数据库初始化\n\n### 步骤 1: 创建数据库\n\n```sql\n-- 连接 MySQL 服务器 (root 用户)\nmysql -u root -p\n\n-- 创建数据库\nCREATE DATABASE attendance_db \nCHARACTER SET utf8mb4 \nCOLLATE utf8mb4_unicode_ci;\n\n-- 创建用户 (建议不用 root)\nCREATE USER 'attendance'@'localhost' IDENTIFIED BY 'your_secure_password';\nGRANT ALL PRIVILEGES ON attendance_db.* TO 'attendance'@'localhost';\nFLUSH PRIVILEGES;\n\n-- 验证\nUSE attendance_db;\nSHOW TABLES; -- 首次为空，由程序自动创建表\n```\n\n### 步骤 2: 配置连接字符串\n\n#### Windows 客户端\n\n```ini\n# AttendanceClient/server.ini (需手动创建)\n\n[Server]\nip=127.0.0.1 # 服务端 IP 地址\nport=9999 # 服务端监听端口\n```\n\n#### Linux 服务器\n\n```ini\n# AttendanceServer/server.ini\n\n[Database]\nhost=127.0.0.1\nport=3305\nuser=attendance\npassword=your_secure_password\ndatabase=attendance_db\n\n[Server]\nlisten_port=9999\nmax_connections=100\n\n[Security]\nssl_enabled=0 # 可选: 1 开启 SSL\nsession_timeout=480 # Session 超时 (分钟)\n\n[AI]\ndeepseek_key=sk-xxx...\ndoubao_key=xxx...\n```\n\n### 步骤 3: 初始化表结构\n\n```bash\n# 首次运行服务端自动创建表\n./AttendanceServer\n\n# 或手动导入 SQL 脚本\nmysql -u attendance -p attendance_db < schema.sql\n```\n\n---\n\n## 🚀 部署上线\n\n### 单机部署 (小规模)\n\n```bash\n# 步骤 1: 准备目录结构\n/opt/attendance/\n├── server/\n│ ├── AttendanceServer (可执行文件)\n│ ├── server.ini (配置文件)\n│ ├── server_config.enc (加密配置)\n│ └── models/ (可选: AI 模型)\n├── client/\n│ └── AttendanceClient (可执行文件)\n└── data/\n └── mysql_data/ (数据库文件)\n\n# 步骤 2: 启动 MySQL\nsudo systemctl start mysql\n# 或\nsudo service mysql start\n\n# 步骤 3: 启动服务器\ncd /opt/attendance/server\n./AttendanceServer &\n\n# 步骤 4: 在客户端配置 server.ini\n[Server]\nip=192.168.1.10 # 服务器 IP\nport=9999\n\n# 步骤 5: 启动客户端\n./AttendanceClient\n```\n\n### 集群部署 (大规模)\n\n```\n┌─────────────────────────────────────────────┐\n│ 负载均衡器 (Nginx/HAProxy) │\n│ 监听 0.0.0.0:9999 │\n└──────────────┬──────────────────────────────┘\n ↓\n ┌──────────┴──────────┬───────────┐\n ↓ ↓ ↓\n┌─────────┐ ┌─────────┐ ┌─────────┐\n│ Server1 │ │ Server2 │ │ Server3 │\n│:9999 │ │:9999 │ │:9999 │\n└────┬────┘ └────┬────┘ └────┬────┘\n │ │ │\n └───────────────────┼────────────┘\n ↓\n ┌──────────────────────────┐\n │ MySQL Master (主库) │\n │ 192.168.1.20:3306 │\n └────────────┬─────────────┘\n ↓\n ┌──────────────────────────┐\n │ MySQL Slaves (从库) │\n │ (可选, 用于读取) │\n └──────────────────────────┘\n\n配置步骤:\n1. 在 3 台服务器上部署 AttendanceServer\n2. 配置 Nginx 负载均衡\n3. 配置 MySQL 主从复制\n4. 客户端连接到负载均衡器 IP\n5. 使用 Keepalived 实现高可用 (可选)\n```\n\n### Docker 容器化 (推荐)\n\n```dockerfile\n# Dockerfile (服务端)\n\nFROM ubuntu:22.04\n\n# 安装依赖\nRUN apt update && apt install -y \\\n qt5-qmake qtbase5-dev libmysqlclient-dev \\\n libssl-dev unixodbc-dev && \\\n rm -rf /var/lib/apt/lists/*\n\n# 复制编译好的文件\nCOPY AttendanceServer /app/AttendanceServer\nCOPY server.ini /app/server.ini\nCOPY server_config.enc /app/server_config.enc\n\nWORKDIR /app\nEXPOSE 9999\nENTRYPOINT [\"./AttendanceServer\"]\n```\n\n```bash\n# 构建镜像\ndocker build -t attendance-server:latest .\n\n# 运行容器\ndocker run -d \\\n --name attendance-server \\\n -p 9999:9999 \\\n -e ATTENDANCE_CONFIG_KEY=\"your-env-key\" \\\n -v /path/to/config:/app/config \\\n -v mysql_data:/var/lib/mysql \\\n --link mysql-container:mysql \\\n attendance-server:latest\n\n# Docker Compose (整个栈)\n# 见 docker-compose.yml 文件\n```\n\n---\n\n## 📋 验证部署\n\n### 客户端验证\n\n```bash\n# 1. 检查依赖库\nldd ./AttendanceClient | grep \"not found\"\n# 应该没有输出 (表示所有库都找到了)\n\n# 2. 启动客户端\n./AttendanceClient\n\n# 3. 手动测试\n- 连接到服务器 ✓\n- 打卡页面显示摄像头 ✓\n- 人脸检测框出现 ✓\n- 打卡成功后更新状态 ✓\n- 查询考勤记录 ✓\n- 发送聊天消息 ✓\n```\n\n### 服务器验证\n\n```bash\n# 1. 检查服务状态\nnetstat -tlnp | grep 9999\n# 应该显示: LISTEN 0.0.0.0:9999\n\n# 2. 检查数据库连接\nmysql -h 127.0.0.1 -u attendance -p attendance_db -e \"SHOW TABLES;\"\n# 应该显示 9 张表\n\n# 3. 性能测试\nab -n 1000 -c 100 http://127.0.0.1:9999/\n\n# 4. 查看日志\ntail -f AttendanceServer.log\n```\n\n---\n\n## 🔧 常见问题排查\n\n### 问题 1: 无法连接数据库\n\n```\n错误信息: \"Database connection failed\"\n\n排查步骤:\n1. 检查 MySQL 服务状态\n sudo systemctl status mysql\n\n2. 验证连接字符串\n mysql -h 127.0.0.1 -u attendance -p\n\n3. 检查防火墙规则\n sudo ufw allow 3306/tcp\n\n4. 查看 MySQL 日志\n tail -f /var/log/mysql/error.log\n\n5. 重新配置环境变量\n export ATTENDANCE_CONFIG_KEY=\"your-key\"\n```\n\n### 问题 2: 人脸检测不工作\n\n```\n错误信息: \"Face detection failed\" / \"模型加载失败\"\n\n排查步骤:\n1. 检查模型文件是否存在\n ls -la D:\\models\\\n - retinaface-resnet50.onnx\n - w600k_r50.onnx\n\n2. 检查 ONNX Runtime 是否正确安装\n python -c \"import onnxruntime; print(onnxruntime.__version__)\"\n\n3. 检查 CUDA/GPU 是否可用\n nvidia-smi\n \n4. 查看客户端日志\n tail -f AttendanceClient.log\n\n5. 尝试 CPU 模式 (禁用 CUDA)\n 在 FaceProcessThread 中注释 CUDA 配置\n```\n\n### 问题 3: 高延迟/卡顿\n\n```\n症状: 打卡延迟 >1 秒 / UI 卡死\n\n排查步骤:\n1. 检查网络延迟\n ping -c 10 server_ip\n // 应该 <10ms\n\n2. 检查 CPU/GPU 使用率\n htop (客户端)\n nvidia-smi (GPU)\n\n3. 检查数据库查询性能\n SHOW PROCESSLIST;\n EXPLAIN SELECT * FROM attendance_records;\n\n4. 增加 MySQL 连接池\n 在 server.ini 中修改 max_connections\n\n5. 启用 GPU 加速\n 确保 CUDA 和 cuDNN 正确安装\n```\n\n### 问题 4: 活体检测误拒\n\n```\n症状: 真人无法通过活体检测\n\n排查步骤:\n1. 检查光线是否充足\n - 目标: 500+ Lux 照度\n\n2. 调整活体检测参数\n FaceProcessThread.cpp 中:\n - m_livenessThreshold (默认 0.05)\n - m_livenessFrameCount (默认 30)\n\n3. 尝试不同姿态\n - 眨眼 / 看向不同方向\n\n4. 检查摄像头画质\n - 清晰度 / 帧率\n\n5. 调试活体检测日志\n 在 onLiveness() 中添加:\n qDebug() << \"stddev:\" << stddev;\n```\n\n---\n\n## 📊 性能优化建议\n\n| 优化项 | 操作 | 收益 |\n|------|------|------|\n| GPU 加速 | 启用 CUDA | 2-5x 检测速度 |\n| 连接池 | 增加 pool size | 吞吐量 +30% |\n| 数据库索引 | 创建复合索引 | 查询 10-100x 快速 |\n| 缓存层 | Redis 缓存 | 响应 50ms → 5ms |\n| 分页查询 | 避免 SELECT * | 内存 -80% |\n| 异步处理 | ThreadPool | UI 不卡顿 |\n\n---\n\n## 🔒 生产环境清单\n\n- [ ] 启用 SSL/TLS 加密传输\n- [ ] 配置 WAF (Web 应用防火墙)\n- [ ] 启用数据库加密\n- [ ] 配置备份策略 (每日/每周)\n- [ ] 配置监控告警 (Prometheus + Grafana)\n- [ ] 启用审计日志\n- [ ] 配置负载均衡和故障转移\n- [ ] 进行压力测试和容量规划\n- [ ] 编写运维文档和应急预案\n- [ ] 定期进行安全审计\n\n"}, "3712e250ee09e01f97a7b6731b79dcba575f88a4": {"t": 1785766379.1223922, "n": 12481, "h": "507d900b2c999035", "c": "# FaceAttendanceSystem 部署指南\n\n## 📋 系统需求\n\n### 硬件要求\n\n#### 客户端 (打卡机)\n\n```\n最低配置:\n├─ CPU: Intel i5-8400 或同级 (4核)\n├─ 内存: 8GB RAM\n├─ 显卡: NVIDIA GTX 1050 或以上 (推荐)\n├─ 存储: 256GB SSD\n├─ 网络: 10Mbps 局域网 / 4G 网络\n└─ 摄像头: 1080p USB 摄像头 / 内置摄像头\n\n推荐配置 (生产环境):\n├─ CPU: Intel i7-9700 或同级 (8核+)\n├─ 内存: 16GB RAM\n├─ 显卡: NVIDIA RTX 3060 (12GB 显存)\n├─ 存储: 512GB NVMe SSD\n├─ 网络: 千兆以太网\n└─ 摄像头: 工业级人脸识别摄像头 (130° 广角)\n```\n\n#### 服务器\n\n```\n最低配置:\n├─ CPU: 4 核虚拟处理器\n├─ 内存: 8GB RAM\n├─ 存储: 100GB 数据盘 + 50GB 系统盘\n├─ 网络: 100Mbps 专线\n├─ 数据库: MySQL 5.7+\n└─ 容错: 单机部署\n\n推荐配置 (生产环境):\n├─ CPU: 16 核物理处理器 (双 CPU)\n├─ 内存: 32GB 高速 ECC 内存\n├─ 存储: SSD 磁盘阵列 (RAID 1)\n├─ 网络: 千兆网络 + 专线备链\n├─ 数据库: MySQL 8.0 主从集群 (3 节点)\n└─ 容错: 高可用架构 (Keepalived)\n```\n\n### 软件要求\n\n#### Windows 客户端\n\n```\n操作系统:\n├─ Windows 10 Pro (21H2) 或更新\n├─ Windows 11 (任何版本)\n└─ Windows Server 2019/2022 (可选)\n\n开发工具:\n├─ Visual Studio 2019/2022 Community 或 Professional\n│ └─ C++ 工作负载\n├─ Qt Creator 5.12 或更新\n└─ CMake 3.16+\n\n依赖库:\n├─ Qt 5.12.1+ (编译好的二进制)\n├─ OpenCV 4.5+ (CUDA 支持)\n├─ ONNX Runtime 1.12+\n├─ CUDA Toolkit 11.x (GPU 加速用)\n└─ cuDNN 8.x (深度学习库)\n\n模型文件:\n├─ retinaface-resnet50.onnx (人脸检测)\n└─ w600k_r50.onnx (特征提取)\n```\n\n#### Linux 服务器\n\n```\n操作系统:\n├─ Ubuntu 20.04 LTS / 22.04 LTS (推荐)\n├─ CentOS 7/8\n└─ Debian 10+\n\n开发环境:\n├─ GCC 9.0+ / Clang 10+\n├─ CMake 3.16+\n├─ Make / Ninja\n└─ Git\n\n依赖库:\n├─ Qt 5.12.1+ (开发库)\n├─ MySQL Client 8.0\n├─ ODBC Driver 17 for SQL Server (可选)\n└─ OpenSSL 1.1+\n\n系统库:\n└─ build-essential, libssl-dev 等标准开发库\n```\n\n---\n\n## 🔧 编译与构建\n\n### Windows 客户端编译\n\n#### 步骤 1: 安装依赖\n\n```bash\n# 1. 安装 Visual Studio 2022\n# - 选择 C++ 工作负载\n# - 包含 CMake 和 MSVC 编译器\n\n# 2. 安装 Qt 5.12.1\n# 下载: https://www.qt.io/download\n# 选择 MSVC 2019/2022 64-bit 版本\n# 安装路径: C:\\Qt\\5.12.1\\msvc2022_64\n\n# 3. 安装 OpenCV (CUDA 支持)\n# 方式 A: 预编译版本 (推荐)\n# 下载: https://github.com/opencv/opencv/releases\n# 选择: opencv-4.5.5-vc14_vc15.exe\n# 安装路径: C:\\OpenCV\n\n# 方式 B: 从源码编译 (如需 CUDA)\ngit clone https://github.com/opencv/opencv.git\ncd opencv\nmkdir build && cd build\ncmake -G \"Visual Studio 17 2022\" ^\n -DWITH_CUDA=ON ^\n -DCUDA_FAST_MATH=ON ^\n -DWITH_CUBLAS=ON ^\n -DCMAKE_INSTALL_PREFIX=C:\\OpenCV_CUDA ..\ncmake --build . --config Release -j 8\ncmake --install . --config Release\n\n# 4. 安装 CUDA Toolkit 11.8\n# 下载: https://developer.nvidia.com/cuda-11-8-0-download-archive\n# 选择 Windows x86_64\n# 安装到: C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\n\n# 5. 安装 cuDNN 8.6\n# 下载: https://developer.nvidia.com/cudnn (需注册)\n# 解压到 CUDA 安装目录\nxcopy C:\\cudnn\\bin\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\bin\" /Y\nxcopy C:\\cudnn\\include\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\include\" /Y\nxcopy C:\\cudnn\\lib\\x64\\* \"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\lib\\x64\" /Y\n\n# 6. 安装 ONNX Runtime\n# 下载: https://github.com/microsoft/onnxruntime/releases\n# 选择: onnxruntime-win-x64-gpu-1.14.1.zip\n# 解压路径: C:\\onnxruntime\n\n# 7. 下载模型文件\n# retinaface-resnet50.onnx (80MB)\n# https://github.com/deepinsight/insightface/releases\n# w600k_r50.onnx (200MB)\n# https://github.com/deepinsight/insightface/releases\n# 放置路径: D:\\models\\\n```\n\n#### 步骤 2: 配置 CMakeLists.txt\n\n```cmake\n# FaceAttendanceSystem/CMakeLists.txt (示例)\n\ncmake_minimum_required(VERSION 3.16)\nproject(FaceAttendanceSystem)\n\nset(CMAKE_CXX_STANDARD 17)\nset(CMAKE_AUTOMOC ON)\nset(CMAKE_AUTORCC ON)\nset(CMAKE_AUTOUIC ON)\n\n# 1. 查找 Qt\nfind_package(Qt5 COMPONENTS \n Core Gui Widgets Network Sql \n REQUIRED \n)\n\n# 2. 查找 OpenCV (CUDA 版本)\nfind_package(OpenCV 4.5 REQUIRED)\n\n# 3. 查找 ONNX Runtime\nset(ONNXRUNTIME_ROOT \"C:/onnxruntime\")\nfind_library(ONNXRUNTIME_LIB \n NAMES onnxruntime \n PATHS ${ONNXRUNTIME_ROOT}/lib\n)\nset(ONNXRUNTIME_INCLUDE_DIR \"${ONNXRUNTIME_ROOT}/include\")\n\n# 4. CUDA 配置\nenable_language(CUDA)\nset(CUDA_NVCC_FLAGS \"${CUDA_NVCC_FLAGS} -arch=sm_75\")\n\n# 5. 客户端可执行文件\nadd_executable(AttendanceClient\n AttendanceClient/main.cpp\n AttendanceClient/AttendanceClient.cpp\n AttendanceClient/MainWidget.cpp\n AttendanceClient/FaceProcessThread.cpp\n AttendanceClient/NetworkHelper.cpp\n AttendanceClient/PunchModule.cpp\n AttendanceClient/RegisterModule.cpp\n AttendanceClient/ChatModule.cpp\n AttendanceClient/AIAssistantModule.cpp\n AttendanceClient/RecordModule.cpp\n AttendanceClient/UserModule.cpp\n AttendanceClient/ProfileModule.cpp\n AttendanceClient/HomeModule.cpp\n)\n\ntarget_link_libraries(AttendanceClient\n Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::Sql\n ${OpenCV_LIBS}\n ${ONNXRUNTIME_LIB}\n cuda_runtime cudart\n)\n\ntarget_include_directories(AttendanceClient PUBLIC\n ${ONNXRUNTIME_INCLUDE_DIR}\n ${CUDA_INCLUDE_DIRS}\n)\n\n# 6. 服务端可执行文件\nadd_executable(AttendanceServer\n AttendanceServer/main.cpp\n AttendanceServer/AttendanceServer.cpp\n AttendanceServer/DatabaseManager.cpp\n AttendanceServer/RequestHandler.cpp\n AttendanceServer/Requesthandler_part1.cpp\n AttendanceServer/Requesthandler_part2.cpp\n AttendanceServer/Requesthandler_part3.cpp\n AttendanceServer/Requesthandler_part4.cpp\n AttendanceServer/ServerLogin.cpp\n AttendanceServer/ConfigEncryptor.cpp\n)\n\ntarget_link_libraries(AttendanceServer\n Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::Sql\n)\n```\n\n#### 步骤 3: 编译客户端\n\n```bash\n# 在项目根目录\n\n# 创建 build 目录\nmkdir build\ncd build\n\n# 配置 (CMake)\ncmake -G \"Visual Studio 17 2022\" ^\n -DCMAKE_PREFIX_PATH=\"C:/Qt/5.12.1/msvc2022_64\" ^\n -DOpenCV_DIR=\"C:/OpenCV/opencv-build\" ^\n -DONNXRUNTIME_ROOT=\"C:/onnxruntime\" ..\n\n# 编译 (Release 模式，8 并行线程)\ncmake --build . --config Release -j 8\n\n# 输出目录\n# .\\Release\\AttendanceClient.exe (可执行文件)\n# .\\Release\\*.dll (所有 Qt/OpenCV DLL 文件)\n```\n\n#### 步骤 4: 打包应用\n\n```bash\n# 使用 Qt 部署工具\ncd Release\n\n# 复制依赖库\nwindeployqt.exe AttendanceClient.exe\n\n# 结果:\n# AttendanceClient.exe (主程序)\n# platforms/qwindows.dll\n# imageformats/*.dll\n# sqldrivers/*.dll\n# (以及 OpenCV/ONNX 库)\n\n# 创建安装包 (可选)\n# 使用 NSIS 或 WiX 工具包\n```\n\n### Linux 服务器编译\n\n#### 步骤 1: 安装依赖\n\n```bash\n# Ubuntu 22.04 为例\n\n# 系统库\nsudo apt update\nsudo apt install -y \\\n build-essential \\\n cmake \\\n git \\\n libqt5core5a libqt5gui5 libqt5widgets5 \\\n qt5-qmake qtbase5-dev \\\n libmysqlclient-dev \\\n libssl-dev \\\n libodbc1 odbcinst unixodbc-dev\n\n# MySQL 客户端\nsudo apt install -y mysql-client mysql-server\n\n# 可选: ODBC Driver 17\ncurl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -\nsudo add-apt-repository \"$(curl https://packages.microsoft.com/config/ubuntu/22.04/mssql-server-2019.list)\"\nsudo apt install -y msodbcsql17\n\n# 编译工具\nsudo apt install -y ninja-build pkg-config\n```\n\n#### 步骤 2: 编译服务端\n\n```bash\n# 创建 build 目录\nmkdir build && cd build\n\n# 配置 (CMake)\ncmake -DCMAKE_BUILD_TYPE=Release \\\n -G Ninja \\\n -DCMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt5 ..\n\n# 编译\nninja -j $(nproc)\n\n# 输出\n./AttendanceServer (可执行文件)\n```\n\n---\n\n## 🗄️ 数据库初始化\n\n### 步骤 1: 创建数据库\n\n```sql\n-- 连接 MySQL 服务器 (root 用户)\nmysql -u root -p\n\n-- 创建数据库\nCREATE DATABASE attendance_db \nCHARACTER SET utf8mb4 \nCOLLATE utf8mb4_unicode_ci;\n\n-- 创建用户 (建议不用 root)\nCREATE USER 'attendance'@'localhost' IDENTIFIED BY 'your_secure_password';\nGRANT ALL PRIVILEGES ON attendance_db.* TO 'attendance'@'localhost';\nFLUSH PRIVILEGES;\n\n-- 验证\nUSE attendance_db;\nSHOW TABLES; -- 首次为空，由程序自动创建表\n```\n\n### 步骤 2: 配置连接字符串\n\n#### Windows 客户端\n\n```ini\n# AttendanceClient/server.ini (需手动创建)\n\n[Server]\nip=127.0.0.1 # 服务端 IP 地址\nport=9999 # 服务端监听端口\n```\n\n#### Linux 服务器\n\n```ini\n# AttendanceServer/server.ini\n\n[Database]\nhost=127.0.0.1\nport=3305\nuser=attendance\npassword=your_secure_password\ndatabase=attendance_db\n\n[Server]\nlisten_port=9999\nmax_connections=100\n\n[Security]\nssl_enabled=0 # 可选: 1 开启 SSL\nsession_timeout=480 # Session 超时 (分钟)\n\n[AI]\ndeepseek_key=sk-xxx...\ndoubao_key=xxx...\n```\n\n### 步骤 3: 初始化表结构\n\n```bash\n# 首次运行服务端自动创建表\n./AttendanceServer\n\n# 或手动导入 SQL 脚本\nmysql -u attendance -p attendance_db < schema.sql\n```\n\n---\n\n## 🚀 部署上线\n\n### 单机部署 (小规模)\n\n```bash\n# 步骤 1: 准备目录结构\n/opt/attendance/\n├── server/\n│ ├── AttendanceServer (可执行文件)\n│ ├── server.ini (配置文件)\n│ ├── server_config.enc (加密配置)\n│ └── models/ (可选: AI 模型)\n├── client/\n│ └── AttendanceClient (可执行文件)\n└── data/\n └── mysql_data/ (数据库文件)\n\n# 步骤 2: 启动 MySQL\nsudo systemctl start mysql\n# 或\nsudo service mysql start\n\n# 步骤 3: 启动服务器\ncd /opt/attendance/server\n./AttendanceServer &\n\n# 步骤 4: 在客户端配置 server.ini\n[Server]\nip=192.168.1.10 # 服务器 IP\nport=9999\n\n# 步骤 5: 启动客户端\n./AttendanceClient\n```\n\n### 集群部署 (大规模)\n\n```\n┌─────────────────────────────────────────────┐\n│ 负载均衡器 (Nginx/HAProxy) │\n│ 监听 0.0.0.0:9999 │\n└──────────────┬──────────────────────────────┘\n ↓\n ┌──────────┴──────────┬───────────┐\n ↓ ↓ ↓\n┌─────────┐ ┌─────────┐ ┌─────────┐\n│ Server1 │ │ Server2 │ │ Server3 │\n│:9999 │ │:9999 │ │:9999 │\n└────┬────┘ └────┬────┘ └────┬────┘\n │ │ │\n └───────────────────┼────────────┘\n ↓\n ┌──────────────────────────┐\n │ MySQL Master (主库) │\n │ 192.168.1.20:3306 │\n └────────────┬─────────────┘\n ↓\n ┌──────────────────────────┐\n │ MySQL Slaves (从库) │\n │ (可选, 用于读取) │\n └──────────────────────────┘\n\n配置步骤:\n1. 在 3 台服务器上部署 AttendanceServer\n2. 配置 Nginx 负载均衡\n3. 配置 MySQL 主从复制\n4. 客户端连接到负载均衡器 IP\n5. 使用 Keepalived 实现高可用 (可选)\n```\n\n### Docker 容器化 (推荐)\n\n```dockerfile\n# Dockerfile (服务端)\n\nFROM ubuntu:22.04\n\n# 安装依赖\nRUN apt update && apt install -y \\\n qt5-qmake qtbase5-dev libmysqlclient-dev \\\n libssl-dev unixodbc-dev && \\\n rm -rf /var/lib/apt/lists/*\n\n# 复制编译好的文件\nCOPY AttendanceServer /app/AttendanceServer\nCOPY server.ini /app/server.ini\nCOPY server_config.enc /app/server_config.enc\n\nWORKDIR /app\nEXPOSE 9999\nENTRYPOINT [\"./AttendanceServer\"]\n```\n\n```bash\n# 构建镜像\ndocker build -t attendance-server:latest .\n\n# 运行容器\ndocker run -d \\\n --name attendance-server \\\n -p 9999:9999 \\\n -e ATTENDANCE_CONFIG_KEY=\"your-env-key\" \\\n -v /path/to/config:/app/config \\\n -v mysql_data:/var/lib/mysql \\\n --link mysql-container:mysql \\\n attendance-server:latest\n\n# Docker Compose (整个栈)\n# 见 docker-compose.yml 文件\n```\n\n---\n\n## 📋 验证部署\n\n### 客户端验证\n\n```bash\n# 1. 检查依赖库\nldd ./AttendanceClient | grep \"not found\"\n# 应该没有输出 (表示所有库都找到了)\n\n# 2. 启动客户端\n./AttendanceClient\n\n# 3. 手动测试\n- 连接到服务器 ✓\n- 打卡页面显示摄像头 ✓\n- 人脸检测框出现 ✓\n- 打卡成功后更新状态 ✓\n- 查询考勤记录 ✓\n- 发送聊天消息 ✓\n```\n\n### 服务器验证\n\n```bash\n# 1. 检查服务状态\nnetstat -tlnp | grep 9999\n# 应该显示: LISTEN 0.0.0.0:9999\n\n# 2. 检查数据库连接\nmysql -h 127.0.0.1 -u attendance -p attendance_db -e \"SHOW TABLES;\"\n# 应该显示 9 张表\n\n# 3. 性能测试\nab -n 1000 -c 100 http://127.0.0.1:9999/\n\n# 4. 查看日志\ntail -f AttendanceServer.log\n```\n\n---\n\n## 🔧 常见问题排查\n\n### 问题 1: 无法连接数据库\n\n```\n错误信息: \"Database connection failed\"\n\n排查步骤:\n1. 检查 MySQL 服务状态\n sudo systemctl status mysql\n\n2. 验证连接字符串\n mysql -h 127.0.0.1 -u attendance -p\n\n3. 检查防火墙规则\n sudo ufw allow 3306/tcp\n\n4. 查看 MySQL 日志\n tail -f /var/log/mysql/error.log\n\n5. 重新配置环境变量\n export ATTENDANCE_CONFIG_KEY=\"your-key\"\n```\n\n### 问题 2: 人脸检测不工作\n\n```\n错误信息: \"Face detection failed\" / \"模型加载失败\"\n\n排查步骤:\n1. 检查模型文件是否存在\n ls -la D:\\models\\\n - retinaface-resnet50.onnx\n - w600k_r50.onnx\n\n2. 检查 ONNX Runtime 是否正确安装\n python -c \"import onnxruntime; print(onnxruntime.__version__)\"\n\n3. 检查 CUDA/GPU 是否可用\n nvidia-smi\n \n4. 查看客户端日志\n tail -f AttendanceClient.log\n\n5. 尝试 CPU 模式 (禁用 CUDA)\n 在 FaceProcessThread 中注释 CUDA 配置\n```\n\n### 问题 3: 高延迟/卡顿\n\n```\n症状: 打卡延迟 >1 秒 / UI 卡死\n\n排查步骤:\n1. 检查网络延迟\n ping -c 10 server_ip\n // 应该 <10ms\n\n2. 检查 CPU/GPU 使用率\n htop (客户端)\n nvidia-smi (GPU)\n\n3. 检查数据库查询性能\n SHOW PROCESSLIST;\n EXPLAIN SELECT * FROM attendance_records;\n\n4. 增加 MySQL 连接池\n 在 server.ini 中修改 max_connections\n\n5. 启用 GPU 加速\n 确保 CUDA 和 cuDNN 正确安装\n```\n\n### 问题 4: 活体检测误拒\n\n```\n症状: 真人无法通过活体检测\n\n排查步骤:\n1. 检查光线是否充足\n - 目标: 500+ Lux 照度\n\n2. 调整活体检测参数\n FaceProcessThread.cpp 中:\n - m_livenessThreshold (默认 0.05)\n - m_livenessFrameCount (默认 30)\n\n3. 尝试不同姿态\n - 眨眼 / 看向不同方向\n\n4. 检查摄像头画质\n - 清晰度 / 帧率\n\n5. 调试活体检测日志\n 在 onLiveness() 中添加:\n qDebug() << \"stddev:\" << stddev;\n```\n\n---\n\n## 📊 性能优化建议\n\n| 优化项 | 操作 | 收益 |\n|------|------|------|\n| GPU 加速 | 启用 CUDA | 2-5x 检测速度 |\n| 连接池 | 增加 pool size | 吞吐量 +30% |\n| 数据库索引 | 创建复合索引 | 查询 10-100x 快速 |\n| 缓存层 | Redis 缓存 | 响应 50ms → 5ms |\n| 分页查询 | 避免 SELECT * | 内存 -80% |\n| 异步处理 | ThreadPool | UI 不卡顿 |\n\n---\n\n## 🔒 生产环境清单\n\n- [ ] 启用 SSL/TLS 加密传输\n- [ ] 配置 WAF (Web 应用防火墙)\n- [ ] 启用数据库加密\n- [ ] 配置备份策略 (每日/每周)\n- [ ] 配置监控告警 (Prometheus + Grafana)\n- [ ] 启用审计日志\n- [ ] 配置负载均衡和故障转移\n- [ ] 进行压力测试和容量规划\n- [ ] 编写运维文档和应急预案\n- [ ] 定期进行安全审计\n\n"}}}} |