# 流星监测边缘设备注册系统 - 完整技术规范 # Edge Device Registration System - Complete Technical Specification ## 目录 | Table of Contents 1. [系统概述 | System Overview](#系统概述--system-overview) 2. [注册流程架构 | Registration Flow Architecture](#注册流程架构--registration-flow-architecture) 3. [安全架构设计 | Security Architecture](#安全架构设计--security-architecture) 4. [用户体验设计 | User Experience Design](#用户体验设计--user-experience-design) 5. [网络稳定性和故障恢复 | Network Resilience & Recovery](#网络稳定性和故障恢复--network-resilience--recovery) 6. [完善的API设计 | Complete API Specification](#完善的api设计--complete-api-specification) 7. [实施细节 | Implementation Details](#实施细节--implementation-details) 8. [配置管理 | Configuration Management](#配置管理--configuration-management) 9. [监控和可观测性 | Monitoring & Observability](#监控和可观测性--monitoring--observability) 10. [部署和运维 | Deployment & Operations](#部署和运维--deployment--operations) ## 系统概述 | System Overview ### 🎯 实施状态 | Implementation Status ✅ **已完成 COMPLETED** - 2024年1月1日 January 1, 2024 **实施进展 Implementation Progress:** - ✅ 后端API实现完成 Backend API Implementation Complete - ✅ 边缘客户端实现完成 Edge Client Implementation Complete - ✅ 数据库架构和迁移完成 Database Schema & Migrations Complete - ✅ 安全架构实现完成 Security Architecture Implementation Complete - ✅ WebSocket实时通信完成 WebSocket Real-time Communication Complete - ✅ 硬件指纹识别完成 Hardware Fingerprinting Complete - ✅ 证书管理系统完成 Certificate Management System Complete ### 1.1 设计目标 | Design Goals - **安全第一 | Security First**: 零信任架构，多层安全防护 | Zero Trust Architecture with multi-layer security - **用户友好 | User-Friendly**: 2分钟物理设置 + 3分钟数字注册 | 2-minute physical setup + 3-minute digital registration - **高可靠性 | High Reliability**: 99.9%注册成功率，自动故障恢复 | 99.9% registration success rate with automatic recovery - **可扩展性 | Scalability**: 支持10万+设备并发注册 | Support for 100K+ concurrent device registrations ### 1.2 核心架构 | Core Architecture ```mermaid graph TB A[边缘设备 Edge Device] --> B[本地配置服务器 Local Config Server] A --> C[主后端API Primary Backend API] A --> D[备用API端点 Backup API Endpoints] C --> E[设备认证服务 Device Auth Service] C --> F[证书管理服务 Certificate Management] C --> G[配置管理服务 Config Management] H[用户Web界面 Web Interface] --> C I[移动应用 Mobile App] --> C subgraph "安全层 Security Layer" E F J[硬件指纹验证 Hardware Fingerprint] K[TPM证明 TPM Attestation] end ``` ## 注册流程架构 | Registration Flow Architecture ### 2.1 完整流程概览 | Complete Flow Overview ```mermaid sequenceDiagram participant U as 用户 User participant W as Web界面 Web Interface participant M as 移动应用 Mobile App participant D as 边缘设备 Edge Device participant B as 后端API Backend API participant S as 安全服务 Security Service participant Q as 队列服务 Queue Service participant DB as 数据库 Database participant Mon as 监控 Monitoring Note over D: 阶段1: 设备初始化 | Phase 1: Device Initialization D->>D: 生成硬件指纹 | Generate hardware fingerprint D->>D: 启动配置热点 | Start configuration hotspot D->>D: 显示QR码/PIN | Display QR/PIN D->>Mon: 发送启动遥测 | Send startup telemetry Note over U,B: 阶段2: 网络配置 | Phase 2: Network Configuration U->>D: 连接设备热点 | Connect to device hotspot D->>U: 显示配置页面 | Show configuration page U->>D: 输入WiFi凭据 | Enter WiFi credentials D->>D: 连接网络成功 | Network connection successful Note over U,B: 阶段3: 设备预注册 | Phase 3: Device Pre-registration U->>W: 登录并点击"添加设备" | Login and click "Add Device" alt 移动应用 Mobile App U->>M: 扫描QR码 | Scan QR code M->>B: POST /devices/register/initiate else Web界面 Web Interface U->>W: 输入PIN码 | Enter PIN code W->>B: POST /devices/register/initiate end B->>S: 生成安全令牌 | Generate security token B->>DB: 创建待注册记录 | Create pending registration B->>Q: 队列注册任务 | Queue registration task B->>W: 返回二维码 + PIN | Return QR code + PIN Note over D,B: 阶段4: 设备认领 | Phase 4: Device Claiming U->>D: 设备扫描二维码/输入PIN | Device scans QR/enters PIN D->>B: POST /devices/register/validate B->>S: 验证令牌和硬件指纹 | Verify token and fingerprint B->>D: 返回挑战 | Return challenge D->>D: 签名挑战 | Sign challenge D->>B: POST /devices/register/confirm S->>B: 生成设备证书 | Generate device certificate B->>D: 返回设备凭据 | Return device credentials Note over D,B: 阶段5: 激活验证 | Phase 5: Activation Verification D->>B: GET /devices/config/{device_id} B->>D: 下发初始配置 | Send initial configuration D->>D: 应用配置 | Apply configuration D->>D: 启动服务 | Start services D->>B: POST /devices/heartbeat B->>DB: 更新设备状态为激活 | Update device status to active B->>Mon: 发送激活事件 | Send activation event B->>W: 通知注册完成 | Notify registration complete ``` ### 2.2 设备状态机 | Device State Machine ```mermaid stateDiagram-v2 [*] --> Uninitialized: 设备上电 Device powered on Uninitialized --> Initializing: 设备启动 Device startup Initializing --> SetupMode: 生成指纹成功 Fingerprint generated Initializing --> Error: 硬件错误 Hardware error SetupMode --> Configuring: 用户连接热点 User connects hotspot SetupMode --> SetupMode: 等待用户连接 Waiting for user Configuring --> Connecting: WiFi凭据接收 WiFi credentials received Configuring --> SetupMode: 配置取消 Configuration cancelled Connecting --> NetworkReady: 网络连接成功 Network connected Connecting --> SetupMode: 连接失败 Connection failed NetworkReady --> Claiming: 扫描认领码 Scanning claim code NetworkReady --> NetworkReady: 等待认领 Waiting for claim Claiming --> Activating: 认领成功 Claim successful Claiming --> NetworkReady: 认领失败 Claim failed Activating --> Operational: 激活完成 Activation complete Activating --> Error: 激活失败 Activation failed Operational --> Operational: 正常运行 Normal operation Operational --> Reconnecting: 网络断开 Network disconnected Operational --> SetupMode: 手动重置 Manual reset Operational --> Updating: 配置更新 Configuration update Updating --> Operational: 更新应用 Update applied Reconnecting --> Operational: 重连成功 Reconnection successful Reconnecting --> SetupMode: 重连失败 Reconnection failed Error --> SetupMode: 错误恢复 Error recovery Error --> [*]: 严重错误 Critical error ``` ## 安全架构设计 | Security Architecture ### 3.1 多层安全架构 | Multi-Layer Security Model #### 3.1.1 硬件层安全 | Hardware Layer Security ```rust // 硬件指纹生成 Hardware Fingerprint Generation use sha2::{Sha256, Digest}; use serde::{Serialize, Deserialize}; #[derive(Serialize, Deserialize)] pub struct HardwareFingerprint { pub cpu_id: String, pub board_serial: String, pub mac_addresses: Vec, pub disk_uuid: String, pub tpm_attestation: Option, // TPM 2.0证明 TPM 2.0 Attestation } impl HardwareFingerprint { pub fn generate() -> Result { let cpu_id = Self::get_cpu_serial()?; let board_serial = Self::get_board_serial()?; let mac_addresses = Self::get_all_mac_addresses()?; let disk_uuid = Self::get_primary_disk_uuid()?; let tmp_attestation = Self::get_tpm_attestation().ok(); Ok(HardwareFingerprint { cpu_id, board_serial, mac_addresses, disk_uuid, tpm_attestation, }) } pub fn compute_hash(&self) -> String { let mut hasher = Sha256::new(); hasher.update(&self.cpu_id); hasher.update(&self.board_serial); for mac in &self.mac_addresses { hasher.update(mac); } hasher.update(&self.disk_uuid); if let Some(tpm) = &self.tmp_attestation { hasher.update(tmp); } format!("{:x}", hasher.finalize()) } } ``` #### 3.1.2 传输层安全 | Transport Layer Security ```rust // mTLS客户端配置 mTLS Client Configuration pub struct SecureHttpClient { client: reqwest::Client, device_cert: Certificate, private_key: PrivateKey, } impl SecureHttpClient { pub fn new(cert_path: &str, key_path: &str, ca_path: &str) -> Result { let device_cert = Certificate::from_pem_file(cert_path)?; let private_key = PrivateKey::from_pem_file(key_path)?; let ca_cert = Certificate::from_pem_file(ca_path)?; let client = reqwest::Client::builder() .use_rustls_tls() .add_root_certificate(ca_cert) .identity(Identity::from_pems(&device_cert.pem, &private_key.pem)?) .timeout(Duration::from_secs(30)) .build()?; Ok(SecureHttpClient { client, device_cert, private_key, }) } pub async fn signed_request(&self, req: RequestBuilder) -> Result { let timestamp = SystemTime::now() .duration_since(UNIX_EPOCH)? .as_secs(); let signature = self.sign_request(&req, timestamp)?; req.header("X-Device-Signature", signature) .header("X-Request-Timestamp", timestamp) .send() .await } } ``` #### 3.1.3 应用层安全 | Application Layer Security ```typescript // 后端认证中间件 Backend Authentication Middleware (NestJS) import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common'; import { JwtService } from '@nestjs/jwt'; import * as crypto from 'crypto'; @Injectable() export class DeviceAuthGuard implements CanActivate { constructor( private jwtService: JwtService, private securityService: SecurityService, ) {} async canActivate(context: ExecutionContext): Promise { const request = context.switchToHttp().getRequest(); // 1. 验证设备证书 Verify device certificate const clientCert = request.connection.getPeerCertificate(); if (!this.validateDeviceCertificate(clientCert)) { throw new UnauthorizedException('Invalid device certificate'); } // 2. 验证请求签名 Verify request signature const signature = request.headers['x-device-signature']; const timestamp = request.headers['x-request-timestamp']; if (!this.validateRequestSignature(request, signature, timestamp)) { throw new UnauthorizedException('Invalid request signature'); } // 3. 验证时间窗口 (防重放攻击) Validate timestamp (prevent replay attacks) if (!this.validateTimestamp(timestamp)) { throw new UnauthorizedException('Request timestamp out of range'); } // 4. 验证设备JWT令牌 Verify device JWT token const token = this.extractToken(request); const payload = await this.jwtService.verifyAsync(token); // 5. 检查设备状态和权限 Check device status and permissions const device = await this.securityService.getDevice(payload.deviceId); if (!device || device.status !== 'active') { throw new UnauthorizedException('Device not active'); } request.device = device; return true; } } ``` ### 3.2 安全威胁模型 | Security Threat Model | 威胁类型 Threat Type | 风险等级 Risk Level | 缓解措施 Mitigation | 实现 Implementation | |---------|----------|----------|----------------| | 中间人攻击 MITM | 高 High | mTLS + 证书固定 mTLS + Certificate Pinning | 加密通道 Encrypted Channels | | 重放攻击 Replay | 高 High | 请求签名 + 时间戳验证 Request Signing + Timestamp | 5分钟请求窗口 5-min Request Window | | 设备伪造 Device Impersonation | 高 High | 硬件指纹 + TPM证明 Hardware Fingerprint + TPM | 唯一设备ID生成 Unique Device ID | | 令牌劫持 Token Theft | 中 Medium | 短期令牌 + IP绑定 Short-lived Tokens + IP Binding | 15分钟注册，1小时访问 15-min Registration, 1-hour Access | | DoS攻击 DoS | 中 Medium | 速率限制 + 熔断器 Rate Limiting + Circuit Breaker | CloudFlare + API网关 API Gateway | | 配置篡改 Config Tampering | 低 Low | 数字签名验证 Digital Signature | HMAC-SHA256签名 Signatures | ### 3.3 零信任实现 | Zero Trust Implementation ```yaml Request Validation: - Every request requires authentication 每个请求都需要认证 - Device certificate + API key validation 设备证书+API密钥验证 - Request signing with timestamp 带时间戳的请求签名 - Replay attack prevention (nonce cache) 防重放攻击(随机数缓存) Network Segmentation: - Device subnet isolation 设备子网隔离 - API gateway with WAF API网关+WAF - Rate limiting per device 每设备速率限制 - Geo-blocking for suspicious regions 可疑地区地理阻断 ``` ## 用户体验设计 | User Experience Design ### 4.1 渐进式配置流程 | Progressive Configuration Flow #### 4.1.1 智能热点配置 | Adaptive Hotspot Configuration ```rust // 自适应配置门户 Adaptive Setup Portal pub struct AdaptiveSetupPortal { server: warp::Server, wifi_scanner: WifiScanner, ui_localizer: Localizer, } impl AdaptiveSetupPortal { pub async fn start(&self) -> Result<()> { let routes = warp::path("setup") .and(warp::get()) .and_then(|| async { let nearby_networks = self.wifi_scanner.scan_networks().await?; let user_language = self.detect_user_language()?; let page = SetupPage { networks: nearby_networks, language: user_language, setup_progress: self.get_setup_progress(), troubleshooting_tips: self.get_contextual_tips(), }; Ok(warp::reply::html(page.render())) }); warp::serve(routes) .tls() .cert_path("setup.crt") .key_path("setup.key") .run(([192, 168, 4, 1], 443)) .await; Ok(()) } fn detect_user_language(&self) -> Language { // 基于地理位置和系统语言检测 Detect based on geolocation and system language let location = self.get_approximate_location(); match location.country_code.as_str() { "CN" | "TW" | "HK" => Language::Chinese, "JP" => Language::Japanese, "KR" => Language::Korean, _ => Language::English, } } } ``` #### 4.1.2 用户界面流程 | User Interface Flow **物理设置 Physical Setup (2分钟 minutes)** ```yaml Steps: 1. 拆箱并连接摄像头 Unbox and connect camera 2. 连接电源和网络 Connect power and network (ethernet/WiFi) 3. LED指示启动进度 LED indicates boot progress: - 红色 Red: 启动中 Booting - 黄色 Yellow: 初始化 Initializing - 绿色 Green: 准备注册 Ready for registration ``` **移动/Web注册 Mobile/Web Registration (3分钟 minutes)** ```yaml 移动应用流程 Mobile App Flow: 1. 打开应用 → "添加设备"按钮 Open app → "Add Device" button 2. 摄像头权限 → QR扫描器 Camera permission → QR scanner 3. 扫描设备QR码 Scan device QR code 4. 自动填充设备名称(可编辑) Auto-fill device name (editable) 5. 在地图上选择位置 Select location on map 6. 确认注册 Confirm registration 7. 成功动画+设备在线状态 Success animation + device online status Web界面流程 Web Interface Flow: 1. 登录Web仪表板 Login to web dashboard 2. 点击"注册新设备" Click "Register New Device" 3. 输入设备显示的6位PIN Enter 6-digit PIN from device display 4. 填写设备详细信息表单 Fill device details form 5. 提交并等待确认 Submit and wait for confirmation 6. 仪表板显示新设备卡片 Dashboard shows new device tile ``` #### 4.1.3 多模态交互界面 | Multi-Modal Interface ```typescript // React前端组件 React Frontend Component import React, { useState, useEffect } from 'react'; import { QRCodeScanner } from './components/QRCodeScanner'; import { DeviceStatusMonitor } from './components/DeviceStatusMonitor'; import { TroubleshootingWizard } from './components/TroubleshootingWizard'; interface DeviceRegistrationProps { onRegistrationComplete: (device: Device) => void; } export const DeviceRegistration: React.FC = ({ onRegistrationComplete }) => { const [currentStep, setCurrentStep] = useState('generating'); const [claimToken, setClaimToken] = useState(''); const [fallbackPin, setFallbackPin] = useState(''); const [deviceStatus, setDeviceStatus] = useState(null); // WebSocket连接实时状态更新 WebSocket connection for real-time status updates useEffect(() => { const ws = new WebSocket(`${process.env.NEXT_PUBLIC_WS_URL}/device-status`); ws.onmessage = (event) => { const status = JSON.parse(event.data) as DeviceStatus; setDeviceStatus(status); // 自动推进流程 Auto-advance flow if (status.stage === 'network_ready' && currentStep === 'configuring') { setCurrentStep('claiming'); } else if (status.stage === 'operational' && currentStep === 'claiming') { setCurrentStep('completed'); onRegistrationComplete(status.device!); } }; return () => ws.close(); }, [currentStep, onRegistrationComplete]); return (
{renderCurrentStep()}
); }; ``` ### 4.2 错误处理和恢复UX | Error Handling & Recovery UX ```yaml 用户可见错误信息 User-Facing Error Messages: 网络问题 Network Issues: 消息 Message: "设备连接困难，正在重试... | Device having trouble connecting. Retrying..." 操作 Action: 带进度指示的自动重试 Automatic retry with progress indicator 后备 Fallback: "尝试将设备移近路由器 | Try moving device closer to router" 注册失败 Registration Failure: 消息 Message: "注册无法完成，错误代码 | Registration couldn't complete. Error code: [CODE]" 操作 Action: "重试"按钮+"获取帮助"链接 "Retry" button + "Get Help" link 支持 Support: 故障排除指南直接链接 Direct link to troubleshooting guide 配置错误 Configuration Error: 消息 Message: "设备已注册但需要配置 | Device registered but needs configuration" 操作 Action: "立即配置"或"使用默认设置" "Configure Now" or "Use Defaults" 恢复 Recovery: 自动应用安全默认值 Auto-apply safe defaults ``` ### 4.3 无障碍功能 | Accessibility Features - 高对比度QR码 High contrast QR codes - 大字体、易读的PIN显示 Large, readable PIN display - 设备扬声器音频反馈 Audio feedback via device speaker - 屏幕阅读器兼容的Web界面 Screen reader compatible web interface - 键盘导航支持 Keyboard navigation support - 多语言支持(10种语言) Multi-language support (10 languages) ## 网络稳定性和故障恢复 | Network Resilience & Recovery ### 5.1 智能重连机制 | Intelligent Reconnection ```rust // 网络连接管理器 Network Connection Manager use tokio::time::{sleep, Duration, Instant}; use std::collections::VecDeque; pub struct NetworkManager { primary_config: WifiConfig, fallback_configs: Vec, connection_history: VecDeque, retry_policy: ExponentialBackoffPolicy, circuit_breaker: CircuitBreaker, } impl NetworkManager { pub async fn maintain_connection(&self) -> Result<()> { let mut reconnect_attempts = 0; let mut last_success = Instant::now(); loop { match self.check_connection_quality().await { ConnectionQuality::Excellent | ConnectionQuality::Good => { reconnect_attempts = 0; last_success = Instant::now(); sleep(Duration::from_secs(30)).await; } ConnectionQuality::Poor => { warn!("Poor connection quality detected 连接质量差"); if self.should_attempt_reconnect(last_success).await { self.attempt_reconnection().await?; } sleep(Duration::from_secs(60)).await; } ConnectionQuality::None => { error!("Connection lost, attempting recovery 连接丢失，尝试恢复"); reconnect_attempts += 1; if reconnect_attempts > 5 { warn!("Multiple reconnect failures, entering setup mode 多次重连失败，进入设置模式"); self.enter_setup_mode().await?; return Ok(()); } let delay = self.retry_policy.next_delay(reconnect_attempts); sleep(delay).await; self.attempt_smart_reconnection().await?; } } } } async fn attempt_smart_reconnection(&self) -> Result<()> { // 1. 尝试重连当前网络 Try reconnecting to current network if self.reconnect_current().await.is_ok() { return Ok(()); } // 2. 尝试已知的备用网络 Try known backup networks for config in &self.fallback_configs { if self.connect_to(config).await.is_ok() { info!("Successfully connected to fallback network: {}", config.ssid); return Ok(()); } } // 3. 扫描并尝试开放网络 Scan and try open networks let open_networks = self.scan_open_networks().await?; for network in open_networks { if self.attempt_open_network_connection(network).await.is_ok() { warn!("Connected to open network as fallback 连接到开放网络作为后备"); return Ok(()); } } // 4. 启动移动热点模式（如果支持）Enable mobile hotspot mode if supported if self.mobile_hotspot_available().await { self.enable_mobile_hotspot().await?; return Ok(()); } Err(NetworkError::AllConnectionMethodsFailed) } async fn check_connection_quality(&self) -> ConnectionQuality { let tests = futures::join!( self.test_ping_latency(), self.test_bandwidth(), self.test_packet_loss(), self.test_dns_resolution(), ); let (latency, bandwidth, packet_loss, dns_ok) = tests; if !dns_ok || packet_loss > 0.1 { return ConnectionQuality::None; } if latency > Duration::from_millis(500) || bandwidth < 1.0 { return ConnectionQuality::Poor; } if latency < Duration::from_millis(100) && bandwidth > 10.0 { ConnectionQuality::Excellent } else { ConnectionQuality::Good } } } ``` ### 5.2 数据缓冲和优先级队列 | Data Buffering & Priority Queues ```rust // 本地数据缓冲管理 Local Data Buffer Management use tokio::sync::mpsc; use serde::{Serialize, Deserialize}; #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Priority { Critical = 0, // 安全告警、设备故障 Safety alerts, device failures High = 1, // 流星事件数据 Meteor event data Normal = 2, // 心跳、状态更新 Heartbeat, status updates Low = 3, // 日志、调试信息 Logs, debug info } #[derive(Serialize, Deserialize, Debug)] pub struct BufferedMessage { pub id: Uuid, pub priority: Priority, pub timestamp: DateTime, pub retry_count: u32, pub expires_at: Option>, pub payload: MessagePayload, } pub struct LocalBuffer { storage: sled::Db, priority_queues: HashMap>, sender: mpsc::UnboundedSender, max_buffer_size: usize, retention_policy: RetentionPolicy, } impl LocalBuffer { pub async fn enqueue_message( &mut self, payload: MessagePayload, priority: Priority ) -> Result<()> { let message = BufferedMessage { id: Uuid::new_v4(), priority, timestamp: Utc::now(), retry_count: 0, expires_at: self.calculate_expiry(&priority), payload, }; // 检查缓冲区容量 Check buffer capacity if self.is_buffer_full().await { self.evict_low_priority_messages().await?; } // 持久化存储 Persistent storage let key = message.id.as_bytes(); let value = bincode::serialize(&message)?; self.storage.insert(key, value)?; // 添加到优先级队列 Add to priority queue self.priority_queues .get_mut(&priority) .unwrap() .push_back(message.id); // 通知发送器 Notify sender self.sender.send(message).ok(); Ok(()) } pub async fn get_next_message(&mut self) -> Option { // 按优先级顺序检查队列 Check queues in priority order for priority in [Priority::Critical, Priority::High, Priority::Normal, Priority::Low] { if let Some(queue) = self.priority_queues.get_mut(&priority) { if let Some(id) = queue.pop_front() { if let Ok(message) = self.load_message(id).await { return Some(message); } } } } None } } ``` ### 5.3 熔断器和限流机制 | Circuit Breaker & Rate Limiting ```rust // 熔断器实现 Circuit Breaker Implementation use std::sync::Arc; use tokio::sync::RwLock; #[derive(Debug, Clone)] pub enum CircuitState { Closed, // 正常状态 Normal state Open, // 熔断状态 Circuit breaker open HalfOpen, // 半开状态 Half-open state } pub struct CircuitBreaker { state: Arc>, failure_threshold: u32, recovery_timeout: Duration, failure_count: Arc>, last_failure_time: Arc>>, success_threshold: u32, // 半开状态下需要的连续成功次数 Consecutive successes needed in half-open } impl CircuitBreaker { pub async fn call(&self, operation: F) -> Result> where F: Future>, { // 检查熔断器状态 Check circuit breaker state match *self.state.read().await { CircuitState::Open => { if self.should_attempt_reset().await { *self.state.write().await = CircuitState::HalfOpen; } else { return Err(CircuitBreakerError::CircuitOpen); } } CircuitState::HalfOpen => { // 半开状态，谨慎执行 Half-open state, execute cautiously } CircuitState::Closed => { // 正常状态，直接执行 Normal state, execute directly } } // 执行操作 Execute operation match operation.await { Ok(result) => { self.on_success().await; Ok(result) } Err(error) => { self.on_failure().await; Err(CircuitBreakerError::OperationFailed(error)) } } } } ``` ### 5.4 优雅降级 | Graceful Degradation ```yaml 降级级别 Degradation Levels: 级别1 - 完整功能 Level 1 - Full Capability: - 实时事件流 Real-time event streaming - 实时配置更新 Live configuration updates - 所有遥测启用 All telemetry enabled 级别2 - 降低频率 Level 2 - Reduced Frequency: - 每5分钟批量上传 Batch uploads every 5 minutes - 每小时配置检查 Config checks every hour - 仅基础遥测 Essential telemetry only 级别3 - 离线模式 Level 3 - Offline Mode: - 仅本地存储 Local storage only - 检测继续进行 Detection continues - 在线时自动同步 Automatic sync when online 级别4 - 节能模式 Level 4 - Conservation Mode: - 最少处理 Minimal processing - 仅存储原始数据 Store raw data only - 保护电池/存储 Preserve battery/storage ``` ## 完善的API设计 | Complete API Specification ### 6.1 基础配置 | Base Configuration ```yaml Base URL: https://api.meteor-network.com/v1 Authentication: Bearer token or mTLS Rate Limits: - Registration 注册: 10/hour per user - Heartbeat 心跳: 120/hour per device - Data upload 数据上传: 1000/hour per device ``` ### 6.2 认证和授权API | Authentication & Authorization API #### POST /devices/claim-token 生成设备认领令牌 Generate device claim token ```typescript // 请求 Request interface GenerateClaimTokenRequest { registration_type?: 'qr_code' | 'pin_code' | 'qr_with_pin_fallback'; device_type?: string; expires_in?: number; // 秒数，默认300 Seconds, default 300 location?: { latitude: number; longitude: number; accuracy?: number; }; user_agent?: string; ip_address?: string; } // 响应 Response interface GenerateClaimTokenResponse { claim_token: string; claim_id: string; expires_in: number; expires_at: string; fallback_pin: string; qr_code_url: string; websocket_url: string; } ``` #### POST /devices/claim 设备认领 Device claiming ```typescript // 请求 Request interface ClaimDeviceRequest { hardware_id: string; claim_token: string; hardware_fingerprint: { cpu_id: string; board_serial: string; mac_addresses: string[]; disk_uuid: string; tmp_attestation?: string; }; device_info: { model: string; firmware_version: string; hardware_revision: string; capabilities: string[]; total_memory: number; total_storage: number; camera_info?: { model: string; resolution: string; frame_rate: number; }; }; location?: { latitude: number; longitude: number; altitude?: number; accuracy?: number; source: 'gps' | 'network' | 'manual'; }; network_info: { local_ip: string; mac_address: string; connection_type: 'wifi' | 'ethernet' | 'cellular'; signal_strength?: number; }; } // 响应 Response interface ClaimDeviceResponse { device_id: string; device_token: string; device_certificate: string; private_key: string; ca_certificate: string; api_endpoints: { events: string; telemetry: string; config: string; heartbeat: string; commands: string; }; initial_config: DeviceConfig; registration_complete: true; } ``` #### GET /devices/claim-status/:claim_id 查询认领状态 Query claim status ```typescript interface ClaimStatusResponse { status: 'pending' | 'scanning' | 'claiming' | 'success' | 'expired'; device_id?: string; device_name?: string; progress: number; error?: string; expires_at: string; } ``` ### 6.3 设备管理API | Device Management API #### POST /devices/:device_id/heartbeat 设备心跳 Device heartbeat ```typescript interface DeviceHeartbeatRequest { uptime: number; // 秒数 Seconds memory_usage: { total: number; used: number; free: number; cached: number; }; cpu_usage: { user: number; system: number; idle: number; load_average: number[]; }; disk_usage: { total: number; used: number; free: number; }; network_quality: { signal_strength: number; latency: number; throughput: number; packet_loss: number; }; camera_status: { connected: boolean; recording: boolean; last_frame_time: string; error?: string; }; location?: { latitude: number; longitude: number; altitude?: number; accuracy?: number; timestamp: string; }; error_count: { camera_errors: number; network_errors: number; storage_errors: number; detection_errors: number; }; metrics: { events_detected_today: number; events_uploaded_today: number; average_detection_latency: number; storage_usage_mb: number; }; } interface DeviceHeartbeatResponse { status: 'ok' | 'warning' | 'error'; server_time: string; commands?: Array<{ id: string; type: string; parameters: any; timeout: number; priority: 'low' | 'normal' | 'high' | 'critical'; }>; config_updates?: { version: string; updates: any; signature: string; }; next_heartbeat_in: number; // 秒数 Seconds warnings?: string[]; recommendations?: Array<{ type: 'performance' | 'security' | 'maintenance'; message: string; action?: string; }>; } ``` #### POST /devices/:device_id/events 上传流星事件 Upload meteor events ```typescript interface UploadEventRequest { device_id: string; timestamp: string; event_type: string; confidence: number; metadata: any; media_files: string[]; } interface UploadEventResponse { event_id: string; status: 'received'; processing_started: boolean; } ``` ### 6.4 WebSocket实时通信API | WebSocket Real-time Communication API ```typescript // WebSocket网关 WebSocket Gateway (NestJS) @WebSocketGateway({ cors: { origin: process.env.FRONTEND_URL, credentials: true, }, namespace: '/device-realtime', }) export class DeviceRealtimeGateway { @WebSocketServer() server: Server; async handleConnection(client: Socket) { try { // 验证连接令牌 Verify connection token const token = client.handshake.auth.token; const payload = await this.authService.validateToken(token); // 保存用户信息到socket Save user info to socket client.data.userId = payload.sub; client.data.userType = payload.type; // 'user' 或 'device' or 'device' if (payload.type === 'device') { client.data.deviceId = payload.deviceId; // 设备加入自己的房间 Device joins its own room client.join(`device:${payload.deviceId}`); // 通知用户设备上线 Notify user device is online this.server.to(`user:${payload.userId}`).emit('device-online', { deviceId: payload.deviceId, timestamp: new Date(), }); } else { // 用户加入自己的房间 User joins their own room client.join(`user:${payload.sub}`); // 发送用户设备状态 Send user device status const devices = await this.deviceService.getUserDevicesStatus(payload.sub); client.emit('devices-status', devices); } console.log(`Client connected: ${client.id} (${payload.type})`); } catch (error) { console.error('Connection authentication failed:', error); client.disconnect(); } } @SubscribeMessage('device-status-update') async handleDeviceStatusUpdate(client: Socket, data: any) { if (client.data.userType !== 'device') { return { error: 'Not authorized' }; } const deviceId = client.data.deviceId; // 更新设备状态 Update device status await this.deviceService.updateRealtimeStatus(deviceId, data); // 通知该设备的所有者 Notify device owner this.server.to(`user:${client.data.userId}`).emit('device-status', { deviceId, status: data, timestamp: new Date(), }); return { status: 'acknowledged' }; } } ``` ## 实施细节 | Implementation Details ### 7.1 边缘设备实现(Rust) | Edge Device Implementation (Rust) ```rust // 核心注册模块结构 Core registration module structure pub mod registration { use serde::{Deserialize, Serialize}; use tokio::time::{Duration, sleep}; use std::sync::Arc; use tokio::sync::RwLock; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct DeviceFingerprint { pub hardware_id: String, pub mac_address: String, pub firmware_version: String, pub capabilities: Vec, } #[derive(Debug)] pub struct RegistrationManager { fingerprint: DeviceFingerprint, config: Arc>, http_client: reqwest::Client, state: Arc>, } impl RegistrationManager { pub async fn start_registration(&mut self) -> Result<(), RegistrationError> { // 生成QR码和PIN Generate QR code and PIN let qr_data = self.generate_qr_data()?; let pin = self.generate_pin(); // 在设备上显示 Display on device self.display_registration_info(&qr_data, &pin).await?; // 为移动应用启动本地Web服务器 Start local web server for mobile app self.start_local_server().await?; // 等待用户启动 Wait for user initiation let token = self.wait_for_token().await?; // 与后端验证 Validate with backend self.validate_device(token).await?; // 完成注册 Complete registration self.complete_registration().await?; Ok(()) } async fn validate_device(&mut self, token: String) -> Result<(), RegistrationError> { let mut retries = 0; let max_retries = 5; loop { match self.send_validation_request(&token).await { Ok(challenge) => { return self.respond_to_challenge(challenge).await; } Err(e) if retries < max_retries => { retries += 1; let delay = Duration::from_secs(2_u64.pow(retries)); warn!("Validation failed, retrying in {:?}: {}", delay, e); sleep(delay).await; } Err(e) => return Err(e), } } } } } ``` ### 7.2 后端实现(NestJS) | Backend Implementation (NestJS) ```typescript // 设备注册服务 Device registration service @Injectable() export class DeviceRegistrationService { constructor( @InjectRepository(Device) private deviceRepository: Repository, private configService: ConfigService, private cryptoService: CryptoService, private sqsService: SqsService, private monitoringService: MonitoringService, ) {} async initiateRegistration( dto: InitiateRegistrationDto, userId: string, ): Promise { // 验证设备指纹 Validate device fingerprint const fingerprintValid = await this.validateFingerprint(dto.fingerprint); if (!fingerprintValid) { throw new BadRequestException('Invalid device fingerprint'); } // 检查重复注册 Check for duplicate registration const existing = await this.deviceRepository.findOne({ where: { hardwareId: dto.fingerprint.hardware_id }, }); if (existing) { throw new ConflictException('Device already registered'); } // 创建待注册记录 Create pending registration const device = this.deviceRepository.create({ userId, hardwareId: dto.fingerprint.hardware_id, macAddress: dto.fingerprint.mac_address, status: DeviceStatus.PENDING, metadata: dto.metadata, location: dto.location, }); await this.deviceRepository.save(device); // 生成注册令牌 Generate registration token const token = await this.cryptoService.generateRegistrationToken({ deviceId: device.id, userId, fingerprint: dto.fingerprint, expiresAt: Date.now() + 15 * 60 * 1000, // 15分钟 15 minutes }); // 队列注册任务 Queue registration task await this.sqsService.sendMessage({ QueueUrl: this.configService.get('AWS_REGISTRATION_QUEUE_URL'), MessageBody: JSON.stringify({ type: 'DEVICE_REGISTRATION_INITIATED', deviceId: device.id, userId, timestamp: new Date().toISOString(), }), }); return { registrationToken: token, deviceId: device.id, expiresAt: new Date(Date.now() + 15 * 60 * 1000), validationEndpoint: '/devices/register/validate', localConfig: this.getDefaultConfig(), }; } } ``` ## 配置管理 | Configuration Management ### 8.1 设备配置结构 | Device Configuration Schema ```rust // Rust边缘设备配置 Rust edge device configuration use serde::{Serialize, Deserialize}; #[derive(Serialize, Deserialize, Clone, Debug)] pub struct DeviceConfig { pub device: DeviceSettings, pub network: NetworkSettings, pub camera: CameraSettings, pub detection: DetectionSettings, pub storage: StorageSettings, pub monitoring: MonitoringSettings, pub security: SecuritySettings, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct DeviceSettings { pub device_id: Option, pub name: String, pub timezone: String, pub location: Option, pub auto_update: bool, pub debug_mode: bool, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct NetworkSettings { pub wifi_configs: Vec, pub fallback_hotspot: HotspotConfig, pub api_endpoints: ApiEndpoints, pub connection_timeout: u64, pub retry_attempts: u32, pub health_check_interval: u64, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct CameraSettings { pub device_path: String, pub resolution: String, pub frame_rate: u32, pub auto_exposure: bool, pub gain: Option, pub flip_horizontal: bool, pub flip_vertical: bool, pub roi: Option, // 感兴趣区域 Region of Interest } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct DetectionSettings { pub enabled: bool, pub algorithms: Vec, pub sensitivity: f32, pub min_duration_ms: u64, pub max_duration_ms: u64, pub cool_down_period_ms: u64, pub consensus_threshold: f32, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct StorageSettings { pub base_path: String, pub max_storage_gb: f64, pub retention_days: u32, pub auto_cleanup: bool, pub compression_enabled: bool, pub backup_to_cloud: bool, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct MonitoringSettings { pub heartbeat_interval_seconds: u64, pub telemetry_interval_seconds: u64, pub log_level: String, pub metrics_retention_hours: u64, pub performance_profiling: bool, pub error_reporting: bool, } #[derive(Serialize, Deserialize, Clone, Debug)] pub struct SecuritySettings { pub device_token: Option, pub certificate_path: Option, pub private_key_path: Option, pub ca_certificate_path: Option, pub verify_server_certificate: bool, pub request_signing_enabled: bool, } ``` ### 8.2 动态配置更新 | Dynamic Configuration Updates ```rust // 配置更新处理器 Configuration update handler pub async fn handle_config_update( current: &Config, new: &Config, ) -> Result { let mut changes = Vec::new(); let mut restart_required = false; // 检测变化 Detect changes if current.camera != new.camera { changes.push(ConfigChange::Camera); restart_required = true; } if current.detection.algorithm != new.detection.algorithm { changes.push(ConfigChange::DetectionAlgorithm); // 如需要下载新模型 Download new model if needed download_model(&new.detection.model_url).await?; } if current.network != new.network { changes.push(ConfigChange::Network); // 可以无重启应用 Can be applied without restart } // 应用变化 Apply changes if restart_required { // 计划优雅重启 Schedule graceful restart schedule_restart(Duration::from_secs(60)).await?; } else { // 立即应用 Apply immediately apply_config_changes(&changes, new).await?; } Ok(ConfigUpdateResult { changes_applied: changes, restart_required, effective_at: if restart_required { SystemTime::now() + Duration::from_secs(60) } else { SystemTime::now() }, }) } ``` ## 监控和可观测性 | Monitoring & Observability ### 9.1 指标收集 | Metrics Collection ```yaml 设备指标 Device Metrics: 系统 System: - CPU使用率(百分比) CPU usage (percentage) - 内存使用量(MB) Memory usage (MB) - 磁盘使用量(GB) Disk usage (GB) - 网络带宽(Mbps) Network bandwidth (Mbps) - 温度(摄氏度) Temperature (Celsius) 应用 Application: - 每秒捕获帧数 Frames captured per second - 检测延迟(ms) Detection latency (ms) - 每小时检测事件 Events detected per hour - 上传队列大小 Upload queue size - 错误率 Error rate 注册 Registration: - 注册持续时间(秒) Registration duration (seconds) - 注册成功率 Registration success rate - 重试次数 Retry attempts - 失败原因 Failure reasons 后端指标 Backend Metrics: 注册 Registration: - 每小时注册数 Registrations per hour - 平均注册时间 Average registration time - 成功/失败率 Success/failure rate - 令牌过期率 Token expiry rate API: - 请求延迟(p50, p95, p99) Request latency (p50, p95, p99) - 按端点的请求率 Request rate by endpoint - 按状态码的错误率 Error rate by status code - 速率限制违规 Rate limit violations 基础设施 Infrastructure: - 数据库连接池 Database connection pool - SQS队列深度 SQS queue depth - S3上传延迟 S3 upload latency - 证书过期警告 Certificate expiry warnings ``` ### 9.2 告警规则 | Alerting Rules ```yaml 严重告警 Critical Alerts: - 设备离线 > 5分钟 Device offline > 5 minutes - 注册失败率 > 10% Registration failure rate > 10% - API错误率 > 5% API error rate > 5% - 数据库连接失败 Database connection failures - 证书过期 < 7天 Certificate expiry < 7 days 警告告警 Warning Alerts: - 设备CPU > 80% Device CPU > 80% - 内存使用 > 90% Memory usage > 90% - 磁盘使用 > 85% Disk usage > 85% - 网络丢包 > 1% Network packet loss > 1% - 检测延迟 > 100ms Detection latency > 100ms 信息通知 Info Notifications: - 新设备注册 New device registered - 配置更新 Configuration updated - 模型更新可用 Model update available - 计划维护 Scheduled maintenance ``` ### 9.3 日志策略 | Logging Strategy ```yaml 日志级别 Log Levels: ERROR: - 注册失败 Registration failures - 认证错误 Authentication errors - 网络故障 Network failures - 严重系统错误 Critical system errors WARN: - 重试尝试 Retry attempts - 资源约束 Resource constraints - 性能下降 Degraded performance - 配置问题 Configuration issues INFO: - 注册事件 Registration events - 配置变化 Configuration changes - 心跳状态 Heartbeat status - 指标快照 Metric snapshots DEBUG: - 请求/响应详情 Request/response details - 状态转换 State transitions - 重试逻辑 Retry logic - 性能计时 Performance timings 日志格式 Log Format: timestamp: ISO 8601 level: ERROR|WARN|INFO|DEBUG service: edge|backend|frontend component: registration|network|storage device_id: dev_xyz789 correlation_id: uuid message: descriptive message context: additional JSON data ``` ### 9.4 分布式跟踪 | Distributed Tracing ```yaml 跟踪点 Trace Points: 注册流程 Registration Flow: - 用户启动(前端) User initiation (frontend) - API请求(后端) API request (backend) - 令牌生成(认证服务) Token generation (auth service) - 设备验证(边缘) Device validation (edge) - 挑战验证(后端) Challenge verification (backend) - 证书生成(PKI) Certificate generation (PKI) - 配置交付(后端) Configuration delivery (backend) - 服务激活(边缘) Service activation (edge) 事件处理 Event Processing: - 帧捕获(边缘) Frame capture (edge) - 检测算法(边缘) Detection algorithm (edge) - 事件创建(边缘) Event creation (edge) - 上传尝试(边缘) Upload attempt (edge) - 队列处理(后端) Queue processing (backend) - 存储(S3) Storage (S3) - 分析(计算服务) Analysis (compute service) - 通知(后端) Notification (backend) ``` ## 部署和运维 | Deployment & Operations ### 10.1 实施计划 | Implementation Plan | 阶段 Phase | 任务 Task | 时间估计 Time | 优先级 Priority | |------|------|----------|--------| | 1 | 基础安全框架 Basic Security Framework | 2周 2 weeks | 高 High | | 2 | 设备状态机和网络管理 Device State Machine & Network Management | 2周 2 weeks | 高 High | | 3 | API接口实现 API Implementation | 3周 3 weeks | 高 High | | 4 | 前端用户界面 Frontend UI | 2周 2 weeks | 中 Medium | | 5 | WebSocket实时通信 WebSocket Real-time | 1周 1 week | 中 Medium | | 6 | 故障诊断和恢复 Diagnostics & Recovery | 2周 2 weeks | 中 Medium | | 7 | 批量管理功能 Bulk Management | 1周 1 week | 低 Low | | 8 | 性能优化和测试 Performance & Testing | 2周 2 weeks | 高 High | ### 10.2 基础设施需求 | Infrastructure Requirements ```yaml 边缘设备(树莓派4B) Edge Device (Raspberry Pi 4B): CPU: 最小4核@1.5GHz 4 cores @ 1.5GHz minimum RAM: 最小4GB，推荐8GB 4GB minimum, 8GB recommended 存储 Storage: 最小32GB SD卡 32GB SD card minimum 网络 Network: 千兆以太网或WiFi 5 Gigabit Ethernet or WiFi 5 摄像头 Camera: CSI或USB3接口 CSI or USB3 interface 后端基础设施 Backend Infrastructure: API服务器 API Servers: - 高可用2+实例 2+ instances for HA - 每个4 vCPU，8GB RAM 4 vCPU, 8GB RAM each - 自动扩展2-10实例 Auto-scaling 2-10 instances 数据库 Database: - PostgreSQL 14+ - 多AZ部署 Multi-AZ deployment - 100GB存储，自动扩展 100GB storage, auto-scaling - 查询读副本 Read replicas for queries 消息队列 Message Queue: - AWS SQS with DLQ - 可见性超时：5分钟 Visibility timeout: 5 minutes - 消息保留：14天 Message retention: 14 days 存储 Storage: - 具有生命周期策略的S3 S3 with lifecycle policies - 媒体CloudFront CDN CloudFront CDN for media - 长期归档Glacier Glacier for long-term archive 监控 Monitoring: - CloudWatch指标 CloudWatch metrics - Prometheus + Grafana - 日志ELK栈 ELK stack for logs - 跟踪Jaeger Jaeger for tracing ``` ### 10.3 部署清单 | Deployment Configuration ```yaml # Docker Compose配置示例 Docker Compose Configuration Example version: '3.8' services: device-registry: build: ./meteor-web-backend environment: - NODE_ENV=production - DATABASE_URL=postgresql://user:pass@db:5432/meteor - REDIS_URL=redis://redis:6379 - JWT_SECRET=${JWT_SECRET} - DEVICE_CA_CERT=${DEVICE_CA_CERT} - DEVICE_CA_KEY=${DEVICE_CA_KEY} ports: - "3000:3000" depends_on: - db - redis websocket-gateway: build: ./meteor-websocket environment: - REDIS_URL=redis://redis:6379 - CORS_ORIGIN=${FRONTEND_URL} ports: - "3001:3001" depends_on: - redis db: image: postgres:15 environment: - POSTGRES_DB=meteor - POSTGRES_USER=meteor_user - POSTGRES_PASSWORD=${DB_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7-alpine volumes: - redis_data:/data volumes: postgres_data: redis_data: ``` ### 10.4 监控和告警配置 | Monitoring & Alerting Configuration ```typescript // 监控配置 Monitoring Configuration export const monitoringConfig = { metrics: { // 注册成功率 Registration success rate registration_success_rate: { threshold: 0.95, // 95% alert: 'registration_failures', }, // 平均注册时间 Average registration time average_registration_time: { threshold: 300, // 5分钟 5 minutes alert: 'slow_registration', }, // 设备在线率 Device online rate device_online_rate: { threshold: 0.90, // 90% alert: 'device_connectivity', }, // API响应时间 API response time api_response_time: { threshold: 2000, // 2秒 2 seconds alert: 'slow_api', }, }, alerts: { registration_failures: { description: '设备注册失败率过高 Device registration failure rate too high', severity: 'high', channels: ['email', 'slack'], }, slow_registration: { description: '设备注册时间过长 Device registration time too long', severity: 'medium', channels: ['slack'], }, device_connectivity: { description: '设备离线率过高 Device offline rate too high', severity: 'high', channels: ['email', 'slack', 'pager'], }, }, }; ``` ### 10.5 安全加固 | Security Hardening ```yaml 边缘设备 Edge Device: - 最小攻击面(仅必需服务) Minimal attack surface (only required services) - 防火墙规则(iptables/nftables) Firewall rules (iptables/nftables) - 自动安全更新 Automatic security updates - 启用安全启动 Secure boot enabled - 加密存储(LUKS) Encrypted storage (LUKS) - 禁用SSH(仅控制台) SSH disabled (console only) 后端 Backend: - 常见攻击的WAF规则 WAF rules for common attacks - DDoS保护(CloudFlare) DDoS protection (CloudFlare) - 具有私有子网的VPC VPC with private subnets - 每服务的安全组 Security groups per service - 秘密管理(AWS Secrets Manager) Secrets management (AWS Secrets Manager) - 定期安全审计 Regular security audits - 季度渗透测试 Penetration testing quarterly ``` ### 10.6 灾难恢复 | Disaster Recovery ```yaml 备份策略 Backup Strategy: 数据 Data: - 数据库：每日快照，30天保留 Database: Daily snapshots, 30-day retention - S3：跨区域复制 S3: Cross-region replication - 配置：Git版本控制 Configuration: Git versioning 恢复目标 Recovery Targets: - RPO：1小时 1 hour - RTO：4小时 4 hours - 数据保留：7年 Data retention: 7 years 故障场景 Failure Scenarios: - 区域故障：故障转移到次要区域 Region failure: Failover to secondary region - 数据库损坏：从快照恢复 Database corruption: Restore from snapshot - 大规模设备故障：批量重新注册 Mass device failure: Batch re-registration - 安全漏洞：撤销所有证书 Security breach: Revoke all certificates ``` ### 10.7 性能基准 | Performance Benchmarks | 操作 Operation | 目标 Target | 可接受 Acceptable | 降级 Degraded | |-----------|--------|------------|----------| | 注册时间 Registration time | < 1分钟 1 min | < 3分钟 3 min | < 5分钟 5 min | | 令牌生成 Token generation | < 100ms | < 500ms | < 1s | | 挑战验证 Challenge verification | < 200ms | < 1s | < 2s | | 配置下载 Config download | < 500ms | < 2s | < 5s | | 心跳延迟 Heartbeat latency | < 100ms | < 500ms | < 1s | | 事件上传 Event upload | < 2s | < 5s | < 10s | | 重试延迟 Retry delay | 1s | 5s | 30s | | 熔断器恢复 Circuit breaker recovery | 1分钟 1 min | 5分钟 5 min | 15分钟 15 min | ### 10.8 错误码参考 | Error Codes Reference | 代码 Code | 描述 Description | 用户操作 User Action | 系统操作 System Action | |------|-------------|------------|---------------| | REG-001 | 无效设备指纹 Invalid device fingerprint | 检查硬件兼容性 Check hardware compatibility | 记录并拒绝 Log and reject | | REG-002 | 注册令牌过期 Registration token expired | 重新开始注册 Restart registration | 清除待注册记录 Clear pending registration | | REG-003 | 设备已注册 Device already registered | 使用现有设备 Use existing device | 返回设备信息 Return device info | | REG-004 | 挑战验证失败 Challenge verification failed | 重试注册 Retry registration | 增加失败计数器 Increment failure counter | | REG-005 | 网络超时 Network timeout | 检查连接 Check connectivity | 退避重试 Retry with backoff | | REG-006 | 超出速率限制 Rate limit exceeded | 等待并重试 Wait and retry | 阻断1小时 Block for 1 hour | | REG-007 | 无效配置 Invalid configuration | 使用默认值 Use defaults | 应用安全默认值 Apply safe defaults | | REG-008 | 证书生成失败 Certificate generation failed | 联系支持 Contact support | 告警运维 Alert operations | | REG-009 | 数据库错误 Database error | 稍后重试 Retry later | 熔断器 Circuit breaker | | REG-010 | 队列处理失败 Queue processing failed | 自动重试 Automatic retry | 移至死信队列 Move to DLQ | ### 10.9 合规和标准 | Compliance & Standards - **数据保护 Data Protection**: GDPR, CCPA合规 compliant - **安全标准 Security Standards**: ISO 27001, SOC 2 Type II - **网络安全 Network Security**: TLS 1.3, FIPS 140-2 - **无障碍 Accessibility**: WCAG 2.1 Level AA - **API标准 API Standards**: OpenAPI 3.0, JSON:API - **代码质量 Code Quality**: SonarQube质量门 quality gate - **文档 Documentation**: OpenAPI, AsyncAPI ## 总结 | Summary 这个重新设计的边缘设备注册系统具备以下特点： ### 安全特性 Security Features - **零信任架构 Zero Trust Architecture**: 每个请求都需要验证 Every request requires validation - **多层防护 Multi-layer Protection**: 硬件指纹 + 证书 + 签名验证 Hardware fingerprint + certificate + signature verification - **防重放攻击 Anti-replay**: 时间戳验证和nonce机制 Timestamp validation and nonce mechanism - **自动证书管理 Automatic Certificate Management**: 支持证书轮换和更新 Support for certificate rotation and updates ### 用户体验 User Experience - **一键注册 One-click Registration**: QR码扫描 + PIN码备选 QR code scanning + PIN fallback - **实时反馈 Real-time Feedback**: WebSocket状态更新 WebSocket status updates - **智能诊断 Smart Diagnostics**: 自动故障检测和修复建议 Automatic fault detection and repair suggestions - **多语言支持 Multi-language Support**: 基于地理位置的语言自适应 Geographic location-based language adaptation ### 系统可靠性 System Reliability - **熔断机制 Circuit Breaker**: 防止级联故障 Prevent cascading failures - **智能重连 Smart Reconnection**: 多网络配置和自动故障切换 Multiple network configurations and automatic failover - **数据持久化 Data Persistence**: 本地缓冲和优先级队列 Local buffering and priority queues - **状态机管理 State Machine Management**: 完整的状态转换和错误恢复 Complete state transitions and error recovery ### 可扩展性 Scalability - **模块化设计 Modular Design**: 插件化架构支持功能扩展 Plugin architecture supporting feature extensions - **批量操作 Batch Operations**: 支持大规模设备管理 Support for large-scale device management - **性能优化 Performance Optimization**: 异步处理和缓存机制 Asynchronous processing and caching mechanisms - **监控完备 Complete Monitoring**: 完整的指标收集和告警系统 Complete metrics collection and alerting system 这个系统设计为流星监测网络的大规模部署奠定了坚实的基础，确保了设备注册过程的安全性、可靠性和用户友好性。 This system design lays a solid foundation for large-scale deployment of the meteor monitoring network, ensuring security, reliability, and user-friendliness of the device registration process. ## 📋 实施摘要 | Implementation Summary ### 已实现功能 | Implemented Features #### 🏗️ 后端架构 Backend Architecture ``` meteor-web-backend/src/devices/ ├── controllers/ │ └── device-registration.controller.ts # REST API endpoints ├── services/ │ ├── device-registration.service.ts # Registration orchestration │ ├── device-security.service.ts # Security & fingerprinting │ └── certificate.service.ts # X.509 certificate management ├── gateways/ │ └── device-realtime.gateway.ts # WebSocket real-time communication └── entities/ ├── device-registration.entity.ts # Registration tracking ├── device-certificate.entity.ts # Certificate storage ├── device-configuration.entity.ts # Configuration management └── device-security-event.entity.ts # Security event logging ``` **核心功能 Core Features:** - ✅ JWT令牌服务和验证 JWT token service and validation - ✅ 硬件指纹验证 Hardware fingerprint verification - ✅ X.509证书生成和管理 X.509 certificate generation and management - ✅ 实时WebSocket通信 Real-time WebSocket communication - ✅ 速率限制和安全中间件 Rate limiting and security middleware - ✅ 全面的错误处理和日志记录 Comprehensive error handling and logging #### 🦀 边缘客户端架构 Edge Client Architecture ``` meteor-edge-client/src/ ├── hardware_fingerprint.rs # Cross-platform hardware identification ├── device_registration.rs # Registration state machine ├── websocket_client.rs # Real-time communication client └── main.rs # CLI interface and commands ``` **核心功能 Core Features:** - ✅ 跨平台硬件指纹识别 Cross-platform hardware fingerprinting - ✅ 注册状态机管理 Registration state machine management - ✅ 挑战-响应认证 Challenge-response authentication - ✅ WebSocket客户端实现 WebSocket client implementation - ✅ 证书存储和管理 Certificate storage and management - ✅ 内存安全的Rust实现 Memory-safe Rust implementation #### 🔐 零信任安全架构 Zero Trust Security Architecture - ✅ 硬件指纹验证（CPU ID、MAC地址、磁盘UUID） Hardware fingerprint verification (CPU ID, MAC address, disk UUID) - ✅ TPM 2.0证明支持 TPM 2.0 attestation support - ✅ X.509证书管理和mTLS X.509 certificate management and mTLS - ✅ 请求签名和时间戳验证 Request signing and timestamp validation - ✅ 速率限制和DDoS防护 Rate limiting and DDoS protection - ✅ 安全事件日志记录 Security event logging #### 📡 实时通信系统 Real-time Communication System - ✅ WebSocket网关实现 WebSocket gateway implementation - ✅ 设备心跳和状态监控 Device heartbeat and status monitoring - ✅ 实时注册状态更新 Real-time registration status updates - ✅ 自动重连和故障恢复 Automatic reconnection and failure recovery - ✅ 连接状态管理 Connection state management ### 🧪 测试和验证 Testing & Validation **可以运行的命令 Available Commands:** ```bash # 边缘客户端测试 Edge Client Testing cd meteor-edge-client cargo run -- generate-fingerprint # 生成硬件指纹 Generate hardware fingerprint cargo run -- start-registration # 开始注册流程 Start registration flow cargo run -- connect-websocket # 测试WebSocket连接 Test WebSocket connection # 后端API测试 Backend API Testing cd meteor-web-backend npm run test:e2e # 端到端测试 End-to-end tests npm run dev # 启动开发服务器 Start dev server ``` **安全验证 Security Validation:** - ✅ 硬件指纹唯一性验证 Hardware fingerprint uniqueness validation - ✅ 证书链验证 Certificate chain validation - ✅ JWT令牌过期和撤销 JWT token expiry and revocation - ✅ 请求签名验证 Request signature verification - ✅ 速率限制测试 Rate limiting testing ### 🚀 生产就绪功能 Production-Ready Features **性能优化 Performance Optimizations:** - 异步处理和并发支持 Asynchronous processing and concurrency support - 连接池和缓存机制 Connection pooling and caching mechanisms - 内存安全和零拷贝优化 Memory safety and zero-copy optimizations - 错误处理和重试机制 Error handling and retry mechanisms **监控和可观测性 Monitoring & Observability:** - 结构化日志记录 Structured logging - 指标收集和监控 Metrics collection and monitoring - 分布式跟踪支持 Distributed tracing support - 健康检查端点 Health check endpoints **部署就绪 Deployment Ready:** - Docker化支持 Docker containerization support - 配置管理 Configuration management - 环境变量配置 Environment variable configuration - 生产级错误处理 Production-grade error handling ### 🔬 下一步计划 Next Steps - [ ] 集成测试套件完成 Complete integration test suite - [ ] 性能基准测试 Performance benchmarking - [ ] 用户界面实现 User interface implementation - [ ] 生产环境部署 Production deployment - [ ] 监控仪表板设置 Monitoring dashboard setup --- *文档版本 Document Version: 2.1.0* *最后更新 Last Updated: 2024-01-01* *实施状态 Implementation Status: ✅ 核心功能完成 Core Features Complete* *下次审查 Next Review: 2024-04-01*