@wq-hook/anti-cheating-monitor

v1.0.10

Published

23 days ago

基于阿里云视觉智能平台的实时反作弊监控系统，提供人脸检测、异常行为分析和完整的在线监考解决方案

Downloads

230

0High
0Medium
0Low

wangqiang_000001

anti-cheating online-proctoring face-detection alibaba-cloud viapi react typescript monitoring education exam proctoring behavior-detection violation-detection

🛡️ Anti-Cheating Monitor

基于阿里云视觉智能平台的实时反作弊监控系统，提供人脸检测、异常行为分析和完整的在线监考解决方案。

✨ 特性

🎯 实时监控 - 基于摄像头的持续行为分析
🧠 智能检测 - 多维度异常行为识别
☁️ 云端处理 - 阿里云 VIAPI 高精度分析
📊 数据统计 - 完整的监控数据和性能指标
🔒 安全可靠 - 完善的错误处理和资源管理
🚀 高性能 - 节流控制和优化策略
📱 响应式 - 适配各种设备和屏幕尺寸
⚙️ 可配置 - 灵活的阈值配置和热更新
📝 审计日志 - 完整的配置变更追踪
🎣 Hook集成 - 现代React Hook API

🚀 快速开始

安装

# 使用 npm
npm install @wq-hook/anti-cheating-monitor

# 使用 yarn
yarn add @wq-hook/anti-cheating-monitor

# 使用 pnpm
pnpm add @wq-hook/anti-cheating-monitor

基础用法

import React from 'react';
import { useAntiCheatingMonitor } from '@wq-hook/anti-cheating-monitor';

const ExamMonitor = () => {
 const {
   videoRef,
   canvasRef,
   startMonitoring,
   stopMonitoring,
   isMonitoring,
   latestResult,
   stats,
   config,
   updateConfig
 } = useAntiCheatingMonitor({
   credentials: {
     accessKeyId: process.env.VITE_ACCESS_KEY_ID!,
     accessKeySecret: process.env.VITE_ACCESS_KEY_SECRET!,
     securityToken: process.env.VITE_SECURITY_TOKEN,
   },
   config: {
     checkInterval: 3000,           // 检测间隔（毫秒）
     detectMultiplePeople: true,     // 检测多人
     detectDeviceUsage: true,        // 检测设备使用
     detectAbsence: true,            // 检测离席
     resolution: { width: 640, height: 480 },
   },
   onViolation: (violation) => {
     console.log('检测到违规:', violation);
     // 处理违规行为，如记录日志、发送通知等
   },
   onDetectionResult: (result) => {
     console.log('检测结果:', result);
     if (result.violations.length > 0) {
       // 处理异常行为
       // 使用更友好的通知方式替代 alert
       console.warn(`检测到异常: ${result.violations.map(v => v.description).join(', ')}`);
       // 这里可以集成通知组件库，如 antd 的 message 或 notification
       // message.error(`检测到异常: ${result.violations.map(v => v.description).join(', ')}`);
     }
   },
   onError: (error) => {
     console.error('监控错误:', error);
   },
 });

 return (
   <div className="monitor-container">
     <video
       ref={videoRef}
       autoPlay
       muted
       playsInline
       className="monitor-video"
     />
     <canvas ref={canvasRef} style={{ display: 'none' }} />
     
     <div className="control-panel">
       <button
         onClick={startMonitoring}
         disabled={isMonitoring}
         className="btn btn-primary"
       >
         {isMonitoring ? '监控中...' : '开始监控'}
       </button>
       
       <button
         onClick={stopMonitoring}
         disabled={!isMonitoring}
         className="btn btn-secondary"
       >
         停止监控
       </button>
     </div>
     
     {isMonitoring && (
       <div className="stats-panel">
         <div>检测次数: {stats.checkCount}</div>
         <div>异常次数: {stats.abnormalCount}</div>
         <div>网络延迟: {stats.latency}ms</div>
         <div>网络质量: {stats.networkQuality}</div>
       </div>
     )}
   </div>
 );
};

export default ExamMonitor;

📖 API 文档

useAntiCheatingMonitor

核心 Hook，提供完整的反作弊监控功能。

参数

interface UseAntiCheatingMonitorProps {
  credentials: AntiCheatingCredentials;  // 阿里云凭证
  config?: Partial<DetectionConfig>;     // 配置选项
  onViolation?: (violation: CheatingViolation) => void;  // 违规回调
  onDetectionResult?: (result: DetectionResult) => void;  // 检测结果回调
  onError?: (error: Error) => void;     // 错误回调
  onConfigChange?: (config: DetectionConfig) => void;  // 配置变更回调
}

返回值

interface UseAntiCheatingMonitorReturn {
  videoRef: React.RefObject<HTMLVideoElement | null>;  // 视频元素引用
  canvasRef: React.RefObject<HTMLCanvasElement | null>; // 画布元素引用
  startMonitoring: () => Promise<void>;                // 开始监控
  stopMonitoring: () => void;                          // 停止监控
  forceCheck: () => Promise<void>;                     // 强制检测
  isMonitoring: boolean;                               // 监控状态
  latestResult: DetectionResult | null;                // 最新检测结果
  stats: MonitorStats;                                 // 统计信息
  config: DetectionConfig;                              // 当前配置
  updateConfig: (config: Partial<DetectionConfig>) => Promise<{success: boolean, errors?: string[]}>; // 更新配置
  getConfigManager: () => ConfigManager;                // 获取配置管理器
}

检测配置

interface DetectionConfig {
  checkInterval: number;                    // 检测间隔（毫秒）
  detectMultiplePeople: boolean;            // 是否检测多人
  detectDeviceUsage: boolean;               // 是否检测设备使用
  detectAbsence: boolean;                  // 是否检测离席
  resolution: { width: number; height: number }; // 视频分辨率
  type: number;                           // 检测类型
  earphoneThreshold: number;               // 耳机检测阈值
  cellphoneThreshold: number;              // 手机检测阈值
  headPoseThreshold: {                    // 头部姿态阈值
    pitch: number;  // 俯仰角
    roll: number;   // 翻滚角
    yaw: number;    // 偏航角
  };
  faceCompletenessThreshold: number;       // 人脸完整度阈值
  centeringThreshold: number;             // 人脸居中阈值
  movementThreshold: number;              // 可疑移动阈值
}

违规类型

enum CheatingType {
  PERSON_COUNT_ANOMALY = "PERSON_COUNT_ANOMALY",    // 人数异常
  EARPHONE_DETECTED = "EARPHONE_DETECTED",            // 检测到耳机
  CELLPHONE_DETECTED = "CELLPHONE_DETECTED",          // 检测到手机
  HEAD_POSTURE_ABNORMAL = "HEAD_POSTURE_ABNORMAL",    // 头部姿态异常
  FACE_MISSING = "FACE_MISSING",                      // 人脸缺失
  FACE_OCCLUDED = "FACE_OCCLUDED",                    // 人脸被遮挡
  NO_FACE_DETECTED = "NO_FACE_DETECTED",              // 未检测到人脸
  MULTIPLE_FACES_DETECTED = "MULTIPLE_FACES_DETECTED", // 检测到多张人脸
  NOT_CENTERED = "NOT_CENTERED",                     // 未居中
  SUSPICIOUS_MOVEMENT = "SUSPICIOUS_MOVEMENT"        // 可疑移动
}

🔧 高级配置

配置管理

import { ConfigManager } from 'anti-cheating-monitor';

// 获取配置管理器实例
const configManager = new ConfigManager();

// 更新配置
const result = configManager.updateConfig({
  checkInterval: 5000,
  detectMultiplePeople: true
}, {
  source: 'local',
  operator: 'admin'
});

if (result.success) {
  console.log('配置更新成功');
} else {
  console.error('配置更新失败:', result.errors);
}

// 获取审计日志
const auditLogs = configManager.getAuditLogs();
console.log('配置变更历史:', auditLogs);

检测引擎

import { DetectionEngine } from 'anti-cheating-monitor';

const engine = new DetectionEngine(config, credentials);

// 执行检测
const result = await engine.detect(imageData);
console.log('检测结果:', result);

// 获取统计信息
const stats = engine.getDetectionStats();
console.log('检测统计:', stats);

🔒 安全最佳实践

1. 凭证管理

// ❌ 不推荐：硬编码凭证
const credentials = {
  accessKeyId: "LTAI5t...",
  accessKeySecret: "secretpassword"
};

// ✅ 推荐：使用环境变量
const credentials = {
  accessKeyId: process.env.VITE_ACCESS_KEY_ID!,
  accessKeySecret: process.env.VITE_ACCESS_KEY_SECRET!,
  securityToken: process.env.VITE_SECURITY_TOKEN, // STS 临时凭证
};

2. STS 临时凭证

// 获取 STS 临时凭证
const getTemporaryCredentials = async () => {
  const response = await fetch('/api/sts-token');
  return await response.json();
};

// 在组件中使用
const [credentials, setCredentials] = useState();

useEffect(() => {
  getTemporaryCredentials().then(setCredentials);
}, []);

🌍 浏览器支持

Chrome >= 88
Firefox >= 85
Safari >= 14
Edge >= 88

📦 依赖

Peer Dependencies

React >= 18.0.0
React-DOM >= 18.0.0

Dependencies

ali-oss: 阿里云对象存储SDK

🤝 贡献

欢迎贡献代码！请查看贡献指南了解详细信息。

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

阿里云视觉智能开放平台 - 提供强大的人脸识别和行为分析能力
React - 用户界面构建
Vite - 现代化构建工具
TypeScript - 类型安全的 JavaScript

📞 支持

📧 邮箱: [email protected]
🐛 问题反馈: GitHub Issues
💬 讨论: GitHub Discussions
📖 文档: 在线文档

⭐ 如果这个项目对您有帮助，请给我们一个 Star！