# 端口管控系统

**Repository Path**: webicc/portctrl

## Basic Information

- **Project Name**: 端口管控系统
- **Description**: No description available
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# USB Guard - 企业级外设管控系统

**版本**: 1.0.542 | **平台**: Windows 7/8/10/11, Linux | **许可证**: MIT

USB Guard 是一个跨平台的企业级外设管控系统，提供 USB 存储设备、无线网卡、蓝牙设备、光驱、红外设备、手机等外设的集中管理与控制。系统采用 C99 标准开发，支持 **Windows 和 Linux 跨平台互通**、P2P 自动升级、Web 管理界面、实时日志推送等企业级功能。

---

## 系统概述

USB Guard 是一个跨平台的设备管控系统，主要面向企业办公环境，提供以下核心功能：

- **USB 存储设备管控**：自动检测并阻止未授权的 U 盘、移动硬盘
- **外设管控**：无线网卡、蓝牙设备、光驱、红外设备、手机的检测与控制
- **Web 管理界面**：通过浏览器即可管理所有设备和配置
- **白名单机制**：支持基于 VID/PID/序列号的设备白名单
- **状态持久化**：设备状态自动保存，重启后恢复
- **看门狗保护**：确保服务持续运行，防止意外退出
- **程序自动迁移**：首次运行自动迁移到 `%ProgramData%\USBGuard` 目录
- **配置文件加密**：XOR 加密存储，路径 `C:\ProgramData\USBGuard\usb_guard.conf`
- **自动版本号递增**：每次编译自动递增 PATCH 版本
- **防火墙规则自动配置**：自动添加 ICMP 和端口访问规则（幂等性优化）
- **进程互斥锁保护**：防止多实例运行
- **在线终端发现**：局域网 P2P 终端互相发现（UDP 广播心跳，优化版 10 秒间隔）
- **健康检查接口**：`GET /api/health` 提供系统运行状态监控
- **跨平台互通**：Windows 和 Linux 终端可在同一局域网内互相发现和管理

---

## 核心功能

### 🔒 USB 存储设备管控
- ✅ 实时检测 USB 存储设备插入/拔出事件
- ✅ 自动阻止未授权设备（插入即禁用）
- ✅ 基于 VID/PID/序列号的白名单机制
- ✅ 设备状态持久化，重启后自动恢复
- ✅ 智能降频扫描（稳定时延长至 5 秒，活跃时保持 1 秒，降低 CPU 占用峰值）

### 📡 外设管控（5 大类）
| 设备类型 | 检测方法 | 覆盖范围 |
|---------|---------|----------|
| **无线网卡** | 关键词匹配 + PCI/USB 总线验证 | 中英文设备名称 |
| **蓝牙设备** | VID 白名单 + 复合设备过滤 | 30+ 主流品牌（罗技、微软、雷柏等） |
| **光驱** | CDROM 类 GUID 扫描 | 内置光驱（USB 外接由 USB 列表管理） |
| **红外设备** | 红外类 GUID 扫描 | 物理红外端口 |
| **手机设备** | MTP/PTP GUID + 关键词匹配 | Android/iOS 移动设备 |

**外设监控频率**：每 30 秒扫描一次，降低 CPU 占用

**外设管控特性**：
- ✅ 单个外设独立控制（启用/禁用）
- ✅ 外设白名单管理（基于设备 ID）
- ✅ 状态持久化（重启后自动恢复）
- ✅ 外设列表实时查看（`GET /api/peripherals`）
- ✅ 外设状态切换（`POST /api/peripheral/toggle`）

###  P2P 自动升级 ⭐ 核心特性
- ✅ **局域网自动发现**：UDP 广播心跳包（优化版 10 秒间隔，子网 + 全局双播）
- ✅ **跨平台互通**：Windows 和 Linux 终端使用相同的 P2P 协议，可互相发现
- ✅ **时间戳优化**：使用本地接收时间而非对方时间戳，消除系统时间不同步导致的误判
- ✅ **最优源选择**：自动选择版本号最高的对等节点作为下载源
- ✅ **双进程架构**：主进程 + 升级子进程，确保升级可靠性
- ✅ **智能文件替换**：重命名优先策略，解决顽固文件锁定问题
- ✅ **版本一致性验证**：基于 PE 文件版本号的完整性检查
- ✅ **自动清理机制**：启动时自动删除旧版本 ZIP 包，节省磁盘空间
- ✅ **HTTP API 通知**：通过 `POST /api/upgrade-exit` 优雅关闭旧程序
- ✅ **强制终止保护**：超时后强制终止进程，确保升级流程继续
- ✅ **看门狗守护**：独立进程监控主程序，异常退出时自动重启
- ✅ **预打包升级包**：程序启动时自动打包当前版本 ZIP，无需手动准备
- ✅ **升级包下载接口**：`GET /api/upgrade-download` 提供 ZIP 文件下载

**升级流程**：
```
1. 检测对等节点 → 2. 比较版本号 → 3. HTTP 下载 ZIP → 4. 解压到临时目录
→ 5. 创建升级子进程 → 6. 通知旧程序退出 → 7. 等待进程完全退出
→ 8. 强制终止（如需要）→ 9. 文件替换（重命名优先）→ 10. 启动新版本
```

### 🌐 Web 管理界面
- **访问地址**：`http://localhost:9527`（可配置端口）
- **Session 认证**：支持 Cookie 和 X-Session-ID 双重认证方式
- **SSE 实时日志推送**：Server-Sent Events 技术，延迟 <100ms，支持分类过滤（INFO/DEBUG/WARN/ERROR/[PEER]）
- **多线程并发**：一连接一线程模型，支持多用户同时操作
- **日志级别优化**：高频心跳日志降级为 DEBUG，减少磁盘 I/O 压力
- **功能模块**：
  - USB 设备列表与管控（允许/阻止/白名单管理）
  - 外设状态查看与控制（WiFi/蓝牙/光驱/红外/手机）
  - 白名单管理（USB + 外设独立管理）
  - 系统信息查看（CPU、内存、硬盘、网络适配器、BIOS、计算机信息）
  - 计算机信息自定义（编号、位置、责任人、启用日期、用途、密级）
  - 计算机名称修改（支持远程修改主机名）
  - 配置管理（密码修改、自动阻止、开机自启、日志级别）
  - 实时日志面板（ERROR/WARN/INFO 颜色区分）
  - 在线终端发现（局域网 P2P 终端列表，含 MAC 地址和序列号）

### 🛡️ 安全保护机制
**核心设备保护**：绝对禁止禁用以下系统核心设备，防止系统瘫痪：
- USB Hub / Root Hub
- USB Controller / Host Controller
- xHCI / EHCI / OHCI / UHCI 控制器
- Enhanced Host Controller

任何尝试禁用这些设备的操作都会被拒绝，并记录安全日志：
```
[SECURITY] Blocked attempt to disable protected device: USB\VID_xxxx&PID_xxxx\...
```

**其他安全措施**：
- SHA256 密码哈希存储（不可逆推）
- 防火墙规则幂等性优化（先删除再添加，避免累积重复）
- 任务计划程序开机自启（自动提权，兼容 Win7~Win11）
- 进程互斥锁保护（防止多实例运行）
- 局域网 IP 限制（`/api/shutdown` 仅允许局域网地址调用）
- 核心设备安全保护（绝对禁止禁用 USB Hub/Controller）
- 网络适配器 MAC 地址去重（每个物理网卡只显示一次）

---

## 技术架构

### 系统架构图

```
┌──────────────────────────────────────────────────────┐
│                  USB Guard System                     │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ HTTP     │  │ 设备     │  │ P2P      │          │
│  │ Server   │  │ 监控     │  │ 升级     │          │
│  │ (9527)   │  │ Loop     │  │ Client   │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │             │             │                 │
│  ┌────┴─────────────┴─────────────┴────┐            │
│  │        核心逻辑层                   │            │
│  │  sys_info.c, usb_guard.c           │            │
│  │  config.c, auth.c, logger.c        │            │
│  └────────────────┬───────────────────┘            │
│                   │                                │
│  ┌────────────────┴───────────────────┐            │
│  │        平台适配层                  │            │
│  │  Windows: usb_win.c               │            │
│  │  Linux:   usb_linux.c             │            │
│  └────────────────┬───────────────────┘            │
│                   │                                │
│  ┌────────────────┴───────────────────┐            │
│  │        工具模块                    │            │
│  │  disk_utils.c (硬盘探测)           │            │
│  │  network_utils.c (网卡检测)        │            │
│  │  device_control.c (外设管控)       │            │
│  │  zip_utils.c (ZIP 解压)            │            │
│  └────────────────────────────────────┘            │
│                                                    │
└────────────────────────────────────────────────────┘
```

### 编译架构

- **构建系统**：CMake 3.15+
- **语言标准**：C99
- **编译器**：MinGW-w64 / MSVC / GCC
- **目标架构**：x86_64（强制 64 位）
- **兼容性**：Windows 7 (WINVER 0x0601) ~ Windows 11, Ubuntu 18.04+, CentOS 7+
- **自动签名**：编译时生成自签名证书并签名可执行文件（Windows）
- **版本号管理**：每次编译自动递增版本号（version_increment.cmake）
- **日志开关**：生产模式默认关闭调试日志（零开销），开发时可开启
- **Windows 服务支持**：`--service` 参数可作为系统服务运行
- **Linux systemd 支持**：提供 systemd 服务文件，支持开机自启和看门狗
- **跨平台设计**：统一的平台适配层，支持 Windows 和 Linux
- **设备缓存机制**：避免重复枚举，提升性能
- **UTF-8 编码支持**：所有系统信息统一 UTF-8 编码，日志文件带 BOM 标记
- **JSON 转义处理**：防止设备描述中的反斜杠导致 JSON 解析失败
- **日志 UTF-8 BOM**：新建日志文件时写入 BOM，确保 Windows 记事本正确显示中文

---

## 快速开始

### 环境要求

**Windows 平台**：
- 操作系统：Windows 7 SP1 及以上（推荐 Win10/Win11）
- 编译器：MinGW-w64（推荐）或 Visual Studio 2019+
- 构建工具：CMake 3.15+
- 权限：**必须以管理员身份运行**

**Linux 平台**：
- 操作系统：Ubuntu 18.04+ / CentOS 7+
- 编译器：GCC 7+
- 构建工具：CMake 3.15+
- 依赖库：libudev-dev

### 编译步骤

#### Windows（MinGW-w64，推荐）

```bash
# 1. 创建构建目录
mkdir build && cd build

# 2. 配置项目
cmake .. -G "MinGW Makefiles"

# 3. 编译（自动签名 + 版本号递增）
cmake --build . --config Release

# 4. 运行（右键以管理员身份运行）
.\usb-guard.exe
```

#### Windows（Visual Studio）

```bash
# 1. 创建构建目录
mkdir build && cd build

# 2. 配置项目
cmake .. -G "Visual Studio 16 2019" -A x64

# 3. 编译
cmake --build . --config Release

# 4. 运行（右键以管理员身份运行）
.\Release\usb-guard.exe
```

#### Linux

```bash
# 1. 安装依赖
sudo apt-get install cmake libudev-dev build-essential  # Debian/Ubuntu
# 或
sudo yum install cmake libudev-devel gcc  # CentOS/RHEL

# 2. 创建构建目录
mkdir build && cd build

# 3. 配置并编译
cmake .. -DCMAKE_BUILD_TYPE=Release
make

# 4. 运行（需要 root 权限）
sudo ./usb-guard
```

### Linux systemd 服务部署（推荐）

```bash
# 1. 编译完成后，复制可执行文件
sudo cp build/usb-guard /opt/usb-guard/
sudo cp build/usb-guard-watchdog /opt/usb-guard/

# 2. 创建 systemd 服务文件
sudo tee /etc/systemd/system/usb-guard.service > /dev/null <<EOF
[Unit]
Description=USB Guard - 企业级外设管控系统
After=network.target

[Service]
Type=simple
ExecStart=/opt/usb-guard/usb-guard --service
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=usb-guard

# 安全加固
NoNewPrivileges=no
ProtectSystem=full
ReadWritePaths=/etc/usb-guard /var/log/usb-guard

[Install]
WantedBy=multi-user.target
EOF

# 3. 启用服务
sudo systemctl daemon-reload
sudo systemctl enable usb-guard.service
sudo systemctl start usb-guard.service

# 4. 查看状态
sudo systemctl status usb-guard.service
journalctl -u usb-guard.service -f  # 实时日志
```

### 首次运行配置

1. **管理员权限**：程序需要管理员/root 权限才能控制系统设备
2. **Web 界面访问**：打开浏览器访问 `http://localhost:9527`
3. **登录**：使用初始密码登录系统（首次登录后请立即修改，密码请在部署文档中查看）
4. **配置白名单**：添加允许使用的 USB 设备到白名单
5. **启用自动阻止**：在设置中开启"自动阻止未授权设备"
6. **开机自启**：勾选"启用后台服务（开机自启）"，系统将自动配置任务计划程序

**重要提示**：
- 程序会自动迁移到 `%ProgramData%\USBGuard` 目录运行
- 首次运行时会自动预打包升级 ZIP 包（用于 P2P 升级）
- 防火墙规则会自动配置（允许 ICMP 和端口访问）

---

## Web API 接口

系统提供完整的 RESTful API 接口，支持程序化管理和第三方集成。

### 认证与基础接口

### 健康检查与监控

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/health` | GET | 无需 | 健康检查（返回运行状态、在线终端数、运行时长） |
| `/api/login` | POST | 无需 | 登录验证，返回 session_id 和 Cookie |
| `/api/version` | GET | 无需 | 获取程序版本号（公开接口） |
| `/api/events` | GET | 需要 | SSE 实时日志推送（长连接） |

### USB 设备管理

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/devices` | GET | 需要 | 获取 USB 存储设备列表 |
| `/api/block` | POST | 需要 | 禁用设备（同时从白名单移除） |
| `/api/allow` | POST | 需要 | 允许设备（临时允许，不加入白名单） |
| `/api/whitelist` | GET | 需要 | 获取 USB 白名单 |
| `/api/whitelist/add` | POST | 需要 | 添加到 USB 白名单 |
| `/api/whitelist/remove` | POST | 需要 | 从 USB 白名单移除 |

### 外设管控

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/peripherals` | GET | 需要 | 获取所有外设列表（WiFi/蓝牙/光驱/红外/手机） |
| `/api/peripheral/toggle` | POST | 需要 | 切换单个外设状态 |
| `/api/peripheral-whitelist` | GET | 需要 | 获取外设白名单 |
| `/api/peripheral-whitelist/remove` | POST | 需要 | 从外设白名单移除并禁用 |
| `/api/wifi` | GET/POST | 需要 | 无线网卡状态查询/控制 |
| `/api/bluetooth` | GET/POST | 需要 | 蓝牙设备状态查询/控制 |
| `/api/cdrom` | GET/POST | 需要 | 光驱状态查询/控制 |
| `/api/ir` | GET/POST | 需要 | 红外设备状态查询/控制 |

### 系统信息与管理

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/sysinfo` | POST | 需要 | 获取系统信息（CPU、内存、硬盘、网络等） |
| `/api/sysinfo/save` | POST | 需要 | 保存系统信息自定义字段 |
| `/api/computer-name` | POST | 需要 | 修改计算机名称（需重启生效） |
| `/api/settings` | GET | 需要 | 获取当前设置（自动阻止、开机自启、日志级别） |
| `/api/settings` | POST | 需要 | 修改系统设置 |
| `/api/peers` | GET | 需要 | 获取在线终端列表（P2P 发现） |
| `/api/shutdown` | POST | 无需 | 关机/升级退出（仅限局域网 IP） |
| `/api/exit` | POST | 需要 | 退出程序（优雅关闭） |

### P2P 升级

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/upgrade-download` | GET | 无需 | 下载升级包（提供预打包 ZIP 文件） |
| `/api/upgrade-exit` | POST | 无需 | 升级专用退出（快速退出，无需 Session） |

### Session 认证方式

- **Cookie 方式**：登录成功后自动设置 `session_id` Cookie
- **Header 方式**：在请求头中添加 `X-Session-ID: <session_id>`
- **有效期**：Session 有效期 3600 秒（1 小时）

---

## 配置说明

### 配置文件位置

- **Windows**: `%ProgramData%\USBGuard\config.json`
- **Linux**: `/etc/usb-guard/config.json`

### 配置项详解

```json
{
  "password_hash": "SHA256哈希值（不可逆推）",
  "auto_block": 1,          // 自动阻止未授权设备（0=关闭，1=开启）
  "enable_service": 1,      // 开机自启（0=关闭，1=开启）
  "web_port": 9527,         // Web 管理界面端口（默认 9527）
  "log_level": 3,           // 日志级别（0=无，1=错误，2=警告，3=信息，4=调试）
  
  // USB 设备白名单
  "whitelist": [
    {
      "vid": "0781",        // 厂商 ID（十六进制字符串）
      "pid": "5567",        // 产品 ID（十六进制字符串）
      "serial": "",         // 设备序列号（可选，空表示匹配所有序列号）
      "description": "SanDisk USB"  // 设备描述（便于识别）
    }
  ],
  
  // 外设白名单（WiFi/蓝牙/光驱/红外/手机）
  "peripheral_whitelist": [
    {
      "device_id": "USB\\VID_046D&PID_C534\\...",
      "name": "Logitech USB Receiver",
      "device_type": "bluetooth"  // wifi/bluetooth/cdrom/ir/mobile
    }
  ],
  
  // 外设状态持久化（1=启用，0=禁用，-1=未设置/使用当前状态）
  "wifi_enabled": -1,       // 无线网卡状态
  "bluetooth_enabled": -1,  // 蓝牙状态
  "ir_enabled": -1,         // 红外状态
  "cdrom_enabled": -1       // 光驱状态
}
```

### 配置修改方式

1. **Web 界面**（推荐）：系统设置 → 修改配置 → 保存
2. **手动编辑**：直接修改 `config.json` 文件，重启程序生效
3. **API 接口**：通过 HTTP API 动态修改（需要 Session 认证）

---

## Web 管理界面

### 访问方式

- **地址**：`http://localhost:9527`（或配置的端口）
- **认证**：Session-based 认证，支持 Cookie 和 X-Session-ID
- **并发**：多线程模型，支持多用户同时在线操作

### 功能模块

#### 📋 USB 设备管理
- **设备列表**：实时显示所有 USB 存储设备
- **详细信息**：VID、PID、序列号、描述、状态（允许/阻止）
- **操作功能**：
  - 允许/阻止设备（立即生效）
  - 添加到白名单（永久允许）
  - 从白名单移除

#### 📡 外设管控
- **无线网卡**：检测并控制无线网络适配器
- **蓝牙设备**：检测并控制蓝牙接收器（支持 30+ 品牌 VID 白名单）
- **光驱**：检测并控制内置光驱（USB 外接光驱由 USB 列表管理）
- **红外设备**：检测并控制红外端口
- **手机设备**：检测并控制连接的手机（Android/iOS，MTP/PTP 协议）

**注意**：外设每 30 秒扫描一次，不在白名单中的设备会自动禁用

#### ✅ 白名单管理
- **USB 白名单**：基于 VID/PID/序列号的精确匹配
- **外设白名单**：基于设备 ID 的外设匹配
- 支持添加/删除/查看白名单条目

#### 💻 系统信息
- **硬件信息**：CPU、内存、主板、BIOS
- **硬盘信息**：品牌、型号、序列号、容量（百分比列宽布局）
- **网络信息**：网卡列表、IPv4 地址、子网掩码、网关、MAC 地址（自动去重）
- **系统信息**：操作系统版本、安装日期
- **计算机信息**：编号、位置、责任人、启用日期、用途、密级（自定义字段）
- **在线终端**：局域网 P2P 终端列表（编号、设备序列号、位置、责任人、主机名、操作系统、IP、MAC、程序版本）

#### ⚙️ 系统设置
- **修改密码**：更改管理员密码（SHA256 哈希存储）
- **自动阻止**：开启/关闭自动阻止未授权设备
- **开机自启**：配置任务计划程序开机自动启动（自动提权）
- **日志级别**：调整日志输出级别（ERROR/WARN/INFO/DEBUG）
- **退出程序**：优雅关闭程序（包括看门狗）
- **计算机名称**：修改计算机主机名（需重启生效）

#### 📊 实时日志面板
- **SSE 推送**：Server-Sent Events 技术，延迟 <100ms
- **颜色区分**：ERROR（红色）、WARN（黄色）、INFO（绿色）
- **自动滚动**：最新日志自动显示在底部
- **条数限制**：最多保留 100 条日志，防止浏览器卡顿
- **心跳机制**：15 秒发送一次心跳，保持连接活跃

---

## 日志系统

### 日志级别

| 级别 | 值 | 说明 | 适用场景 |
|-----|---|------|----------|
| NONE | 0 | 不输出任何日志 | 生产环境（极致性能） |
| ERROR | 1 | 仅错误信息 | 生产环境（排查问题） |
| WARN | 2 | 警告 + 错误 | 生产环境（推荐） |
| INFO | 3 | 信息 + 警告 + 错误 | 生产环境（默认） |
| DEBUG | 4 | 所有日志 + 调试信息 | 开发调试 |

### 日志配置

- **配置文件**：修改 `config.json` 中的 `log_level` 字段
- **Web 界面**：系统设置 → 日志级别下拉框
- **运行时生效**：修改后立即生效，无需重启
- **编译时开关**：通过 `-DENABLE_DEBUG_LOG=ON` 开启详细调试日志（生产模式默认关闭，零开销）

### 日志输出方式

1. **控制台输出**：实时输出到命令行窗口（INFO 及以上级别）
2. **SSE 推送**：实时推送到 Web 界面的日志面板（INFO 及以上级别）
3. **文件输出**：可选输出到日志文件（需编译时开启 `ENABLE_DEBUG_LOG`）

### 日志标签说明

- `[UPGRADE]` - 升级流程相关日志
- `[UPGRADE-PROC]` - 升级子进程日志
- `[PEER]` - P2P 发现与心跳日志
- `[NETWORK]` - 网络适配器检测日志
- `[AUTOSTART]` - 开机自启状态检测日志
- `[SECURITY]` - 安全保护相关日志（核心设备保护）
- `[FILE]` - 文件操作日志
- `[BACKUP]` - 备份操作日志
- `[COPY]` - 文件复制日志
- `[MIGRATE]` - 程序迁移日志

---

## 安全机制

### 核心设备保护

系统内置安全机制，**绝对禁止**禁用以下核心设备：

- USB Hub / Root Hub
- USB Controller / Host Controller
- xHCI / EHCI / OHCI / UHCI 控制器

任何尝试禁用这些设备的操作都会被拒绝，并记录安全日志：
```
[SECURITY] Blocked attempt to disable protected device: USB\VID_xxxx&PID_xxxx\...
```

### 密码安全

- 密码使用 SHA256 哈希存储，不以明文形式保存
- 配置文件中的 `password_hash` 字段为哈希值，不可逆推

### 进程保护

- **看门狗机制**：监控主程序运行状态，异常退出时自动重启
- **文件锁定**：运行时锁定配置文件和程序文件，防止被删除
- **权限保护**：需要管理员权限才能运行

---

## 常见问题

### Q1：程序需要管理员权限吗？

**A**：是的，程序需要管理员/root 权限才能控制系统设备。没有管理员权限，设备管控功能将无法正常工作。

### Q2：如何允许某个 USB 设备？

**A**：有两种方式：
1. **Web 界面**：USB 设备列表 → 找到设备 → 点击"允许"
2. **白名单**：USB 白名单 → 添加设备（输入 VID、PID、序列号）

### Q3：开机自启如何配置？

**A**：在 Web 界面的"系统设置"中，勾选"启用后台服务（开机自启）"并保存配置。系统会自动配置 Windows 任务计划程序，以最高权限启动。

### Q4：所有 USB 设备都无法使用了怎么办？

**A**：系统内置了核心设备保护机制，不会禁用 USB Hub 和 Controller。如果出现问题：
1. 进入 PE 系统恢复注册表
2. 检查配置文件中是否错误禁用了关键设备
3. 查看日志文件排查原因

### Q5：如何在另一台计算机上编译？

**A**：
1. 安装 CMake 和编译器（MinGW/MSVC/GCC）
2. 克隆代码库
3. 执行编译步骤（见"快速开始"章节）
4. 编译时会自动生成签名证书，无需手动配置

### Q6：Web 界面无法访问？

**A**：
1. 检查程序是否正在运行
2. 检查端口是否被占用（默认 9527）
3. 检查防火墙是否阻止了端口访问（程序会自动配置防火墙规则）
4. 尝试访问 `http://127.0.0.1:9527`

### Q7：P2P 自动升级不工作？

**A**：检查以下几点：
1. 确保两台计算机在同一局域网内
2. 检查防火墙是否允许 UDP 广播和 HTTP 访问
3. 查看日志中的 `[PEER]` 标签，确认心跳包是否正常发送
4. 确认对等节点的版本号确实高于当前版本
5. 检查 ZIP 包是否存在于程序目录（`usb-guard-{version}.zip`）

### Q8：升级后主程序未更新？

**A**：这是已知问题，已在 v1.0.372+ 修复。请升级到最新版本。新版本采用了"重命名优先"策略，解决了顽固文件锁定问题。

### Q9：蓝牙设备检测不准确？

**A**：程序使用 VID 白名单 + 复合设备过滤策略：
- 只匹配 `Service=usbccgp` 的复合设备（无线接收器特征）
- 跳过 `Service=HidUsb` 单功能设备（内置设备）
- 覆盖 30+ 主流品牌 VID
- 如果误判，请将设备添加到外设白名单

### Q10：网卡 IP 地址显示为 N/A？

**A**：已在 v1.0.246+ 修复。新版本的网卡检测逻辑会遍历整个 unicast 地址链表，找到第一个 IPv4 地址，兼容 Win7/Win10/Win11 的 IPv6/IPv4 双栈环境。

### Q11：P2P 终端发现显示不全？

**A**：已在 v1.0.542 深度优化：
- 心跳间隔优化为 10 秒，减少网络负载
- 使用本地接收时间而非对方时间戳，消除系统时间不同步导致的误判
- 接收缓冲区增加到 256KB，减少 UDP 丢包
- 日志级别优化，高频心跳日志降级为 DEBUG，减少 I/O 阻塞
- 如仍有问题，请检查防火墙是否允许 UDP 19527 端口

### Q12：Windows 和 Linux 终端如何互通？

**A**：P2P 协议完全兼容：
- 使用相同的 UDP 广播端口 19527
- 心跳包 JSON 格式完全一致
- PeerInfo 结构体字段对齐
- 只需确保在同一局域网子网内，Windows 和 Linux 终端可互相发现和管理

### Q13：日志文件中文乱码？

**A**：已在 v1.0.542 修复：
- 新建日志文件时自动写入 UTF-8 BOM (0xEF, 0xBB, 0xBF)
- 确保 Windows 记事本、Notepad++ 等工具能正确识别 UTF-8 编码
- 所有系统信息统一 UTF-8 编码输出

---

## 开发指南

### 项目结构

```
portctrl/
├── src/                    # 源代码
│   ├── main.c             # 主程序入口（版本检测、迁移、升级）
│   ├── sys_info.c         # 系统信息与设备检测代理
│   ├── http_server.c      # HTTP 服务器（多线程模型）
│   ├── http_session.c     # Session 管理模块
│   ├── http_api.c         # HTTP API 处理
│   ├── usb_guard.c        # USB 设备管控核心逻辑
│   ├── config.c           # 配置管理
│   ├── auth.c             # 认证模块（SHA256 哈希）
│   ├── crypto.c           # 加密工具
│   ├── logger.c           # 日志系统
│   ├── peer_discovery.c   # P2P 发现与心跳
│   ├── upgrade_client.c   # P2P 升级客户端
│   ├── zip_utils.c        # ZIP 解压工具
│   ├── disk_utils.c       # 硬盘探测模块
│   ├── network_utils.c    # 网络信息采集模块
│   ├── device_control.c   # 外设控制模块（WiFi/蓝牙/光驱/红外/手机）
│   ├── platform/          # 平台适配层
│   │   ├── windows/       # Windows 平台实现
│   │   │   └── usb_win.c  # USB 管控 + 防火墙 + 任务计划程序
│   │   └── linux/         # Linux 平台实现
│   │       └── usb_linux.c
│   └── watchdog/          # 看门狗程序
│       └── watchdog.c
├── include/               # 头文件
│   ├── usb_guard.h        # 主头文件（版本号、常量、结构体）
│   ├── sys_info.h         # 系统信息头文件
│   ├── http_server.h      # HTTP 服务器头文件
│   ├── http_session.h     # Session 管理头文件
│   ├── config.h           # 配置管理头文件
│   ├── auth.h             # 认证模块头文件
│   ├── peer_discovery.h   # P2P 发现头文件
│   ├── upgrade_client.h   # 升级客户端头文件
│   ├── zip_utils.h        # ZIP 工具头文件
│   ├── disk_utils.h       # 硬盘探测头文件
│   ├── network_utils.h    # 网络信息采集头文件
│   └── device_control.h   # 外设控制头文件
├── web/                   # Web 管理界面
│   ├── index.html         # 主页面（双页签布局）
│   ├── login.html         # 登录页面
│   ├── app.js             # 前端逻辑（SSE 连接、API 调用）
│   └── style.css          # 样式文件（百分比列宽布局）
├── build/                 # 构建目录（自动生成）
├── CMakeLists.txt         # CMake 构建配置
├── version_increment.cmake # 版本号递增脚本
├── sign.ps1               # 签名脚本（自签名证书）
└── CHANGES.md             # 变更历史记录
```

### 添加新设备类型

1. 在 `device_control.c` 中添加设备检测函数（参考 `wifi_list_devices()`）
2. 在 `device_control.h` 中声明函数
3. 在 `main.c` 的 `monitor_loop()` 中调用检测函数
4. 在 `config.c` 中添加状态持久化支持
5. 在 Web 界面添加对应的控制面板

### 修改 Web 界面

1. 编辑 `web/` 目录下的 HTML/CSS/JS 文件
2. 使用浏览器开发者工具调试
3. 修改后直接刷新页面即可生效（无需重新编译）
4. **注意**：修改后需要重新打包 ZIP 包（或删除旧 ZIP，程序启动时会自动重新打包）

### 编译选项

```bash
# 开启调试日志（默认关闭，生产模式零开销）
cmake .. -DENABLE_DEBUG_LOG=ON

# 指定安装路径
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/usb-guard

# 交叉编译（Linux）
cmake .. -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake
```

### 关键设计决策

#### 1. 为什么使用任务计划程序而不是注册表 Run 键？
- **自动提权**：任务计划程序可以配置以最高权限运行，无需 UAC 弹窗
- **兼容性**：兼容 Win7~Win11/Server，注册表 Run 键在某些系统上无法自动提权
- **可靠性**：避免因权限不足导致的防火墙配置失败、端口监听失败等问题

#### 2. 为什么 P2P 升级采用双进程架构？
- **原子性**：升级子进程独立于主进程，确保文件替换的可靠性
- **容错性**：即使主进程异常退出，升级子进程仍可完成升级流程
- **安全性**：通过 TerminateProcess 只终止自己，不影响子进程

#### 3. 为什么使用重命名优先策略？
- **解决锁定**：Windows 资源管理器或安全软件可能缓存文件句柄
- **提高成功率**：MoveFileExA 在同一分区内的重命名操作比覆盖更容易成功
- **立即腾出路径**：重命名后立即释放原路径，供新文件写入

#### 4. 为什么网卡检测要遍历 unicast 链表？
- **IPv6/IPv4 双栈**：Windows 系统中第一个 unicast 地址可能是 IPv6
- **兼容性**：确保在任何网络配置下都能正确提取 IPv4 地址
- **完整性**：同时遍历网关链表，确保获取正确的 IPv4 网关

#### 5. 为什么使用 XOR 加密存储配置文件？
- **防篡改**：配置文件不可直接编辑，防止恶意修改
- **轻量级**：XOR 加密性能开销极小，不影响启动速度
- **安全性**：配合文件权限控制，提供基础安全保障

#### 6. 为什么外设监控频率从 10 秒延长到 30 秒？
- **降低 CPU 占用**：减少不必要的系统调用和枚举操作
- **外设变化不频繁**：WiFi/蓝牙/光驱等外设通常不会频繁插拔
- **平衡性能与响应**：30 秒间隔在保证响应性的同时显著降低 CPU 峰值

---

## 版本历史

详见 [CHANGES.md](CHANGES.md)

---

## 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

---

## 联系方式

- 项目仓库：https://gitee.com/webicc/portctrl
- 问题反馈：请在 Gitee 上提交 Issue

---

**注意**：本系统面向企业办公环境设计，请确保在合法授权范围内使用。使用前请咨询相关 IT 管理部门。