# 端口管控系统 **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-04-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # USB Guard 系统 企业级外设管控系统，支持 USB 存储设备、无线网卡、蓝牙设备、光驱、红外设备、手机等外设的集中管理与控制。 --- ## 系统概述 USB Guard 是一个跨平台的设备管控系统，主要面向企业办公环境，提供以下核心功能： - **USB 存储设备管控**：自动检测并阻止未授权的 U 盘、移动硬盘 - **外设管控**：无线网卡、蓝牙设备、光驱、红外设备、手机的检测与控制 - **Web 管理界面**：通过浏览器即可管理所有设备和配置 - **白名单机制**：支持基于 VID/PID/序列号的设备白名单 - **状态持久化**：设备状态自动保存，重启后恢复 - **看门狗保护**：确保服务持续运行，防止意外退出 --- ## 功能特性 ### USB 存储设备管控 - 实时检测 USB 存储设备插入/拔出 - 自动阻止未授权设备（插入即禁用） - 支持白名单机制（VID + PID + 序列号） - 设备状态持久化，重启后自动恢复 ### 外设管控 支持以下类型外设的检测与控制： | 设备类型 | 检测方法 | 说明 | |---------|---------|------| | 无线网卡 | 关键词匹配 + PCI/USB 总线验证 | 支持中英文设备名称 | | 蓝牙设备 | VID 白名单 + 复合设备检测 | 覆盖 30+ 主流品牌 | | 光驱 | CDROM 类 GUID 扫描 | 过滤 USB 外接光驱 | | 红外设备 | 红外类 GUID 扫描 | 物理红外端口 | | 手机 | MTP/PTP GUID + 关键词匹配 | 支持 Android/iOS | ### 安全保护 **核心设备保护**：程序内置安全机制，禁止禁用以下系统核心设备： - USB Hub / Root Hub - USB Controller / Host Controller - xHCI / EHCI / OHCI / UHCI 控制器 - Enhanced Host Controller 任何尝试禁用这些设备的操作都会被拒绝，防止系统瘫痪。 ### Web 管理界面 - 端口：8080（可配置） - 访问地址：`http://localhost:8080` - 功能： - USB 设备列表与管控 - 外设状态查看与控制 - 白名单管理（USB + 外设） - 系统信息查看（CPU、内存、网络等） - 配置管理（密码修改、自动阻止、开机自启等） - 日志级别调整（ERROR / WARN / INFO / DEBUG） --- ## 技术架构 ### 系统架构 ``` ┌─────────────────────────────────────────────┐ │ USB Guard System │ ├─────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌────────── │ │ │ HTTP │ │ 设备 │ │ 配置 │ │ │ │ Server │ │ 监控 │ │ 管理 │ │ │ │ (8080) │ │ Loop │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ┌────┴─────────────┴─────────────┴────┐ │ │ │ 核心逻辑层 │ │ │ │ (sys_info.c, usb_guard.c) │ │ │ └────────────────────┬────────────────┘ │ │ │ │ │ ┌────────────────────┴────────────────┐ │ │ │ 平台适配层 │ │ │ │ Windows: usb_win.c │ │ │ │ Linux: usb_linux.c │ │ │ └─────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────┘ ``` ### 编译架构 - **构建系统**：CMake 3.15+ - **语言**：C99 标准 - **编译器**：MinGW / MSVC / GCC - **自动签名**：编译时自动生成自签名证书并签名可执行文件 - **版本号管理**：每次编译自动递增版本号 --- ## 快速开始 ### 环境要求 **Windows 平台**： - 操作系统：Windows 7 及以上 - 编译器：MinGW-w64 或 Visual Studio 2019+ - 构建工具：CMake 3.15+ **Linux 平台**： - 操作系统：Ubuntu 18.04+ / CentOS 7+ - 编译器：GCC 7+ - 构建工具：CMake 3.15+ - 依赖：libudev-dev ### 编译步骤 #### Windows（MinGW） ```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" # 3. 编译 cmake --build . --config Release # 4. 运行（右键以管理员身份运行） .\Release\usb-guard.exe ``` #### Linux ```bash # 1. 安装依赖 sudo apt-get install cmake libudev-dev build-essential # 2. 创建构建目录 mkdir build cd build # 3. 配置并编译 cmake .. -DCMAKE_BUILD_TYPE=Release make # 4. 运行（需要 root 权限） sudo ./usb-guard ``` ### 首次运行 1. **管理员权限**：程序需要管理员/root 权限才能控制系统设备 2. **Web 界面访问**：打开浏览器访问 `http://localhost:8080` 3. **登录**：使用管理员配置的密码登录系统 4. **配置白名单**：添加允许使用的 USB 设备到白名单 5. **启用自动阻止**：在设置中开启"自动阻止未授权设备" --- ## 配置说明 ### 配置文件 配置文件位于：`%ProgramData%\USBGuard\config.json`（Windows） ### 配置项说明 ```json { "password_hash": "已加密的密码哈希值", "auto_block": 1, // 自动阻止未授权设备（0=关闭，1=开启） "enable_service": 1, // 开机自启（0=关闭，1=开启） "web_port": 8080, // Web 管理界面端口 "log_level": 3, // 日志级别（0=无，1=错误，2=警告，3=信息，4=调试） "whitelist": [ // USB 设备白名单 { "vid": "0781", // 厂商 ID "pid": "5567", // 产品 ID "serial": "", // 设备序列号（可选） "description": "SanDisk USB" // 设备描述 } ], "peripheral_whitelist": [ // 外设白名单 { "device_id": "USB\\VID_046D&PID_C534\\...", "name": "Logitech USB Receiver", "device_type": "bluetooth" } ], "wifi_enabled": -1, // 无线网卡状态（1=启用，0=禁用，-1=未设置） "bluetooth_enabled": -1, // 蓝牙状态 "ir_enabled": -1, // 红外状态 "cdrom_enabled": -1 // 光驱状态 } ``` --- ## Web 管理界面 ### 功能模块 #### USB 设备管理 - **设备列表**：显示所有 USB 存储设备 - **设备信息**：VID、PID、序列号、描述、状态 - **操作**：允许/阻止设备、添加到白名单 #### 外设管控 - **无线网卡**：检测并控制无线网络适配器 - **蓝牙设备**：检测并控制蓝牙接收器（支持 30+ 品牌） - **光驱**：检测并控制内置光驱（USB 外接光驱由 USB 列表管理） - **红外设备**：检测并控制红外端口 - **手机设备**：检测并控制连接的手机（Android/iOS） #### 白名单管理 - **USB 白名单**：基于 VID/PID/序列号的设备白名单 - **外设白名单**：基于设备 ID 的外设白名单 - 支持添加/删除白名单条目 #### 系统信息 - **硬件信息**：CPU、内存、主板、BIOS - **网络信息**：网卡列表、IP 地址、子网掩码、网关、MAC 地址 - **系统信息**：操作系统版本、安装日期 #### 系统设置 - **修改密码**：更改管理员密码 - **自动阻止**：开启/关闭自动阻止未授权设备 - **开机自启**：配置服务开机自动启动 - **日志级别**：调整日志输出级别 --- ## 日志系统 ### 日志级别 | 级别 | 值 | 说明 | 适用场景 | |-----|---|------|---------| | NONE | 0 | 不输出任何日志 | 生产环境（极致性能） | | ERROR | 1 | 仅错误信息 | 生产环境（排查问题） | | WARN | 2 | 警告 + 错误 | 生产环境（推荐） | | INFO | 3 | 信息 + 警告 + 错误 | 生产环境（默认） | | DEBUG | 4 | 所有日志 + 调试信息 | 开发调试 | ### 日志配置 - **配置文件**：修改 `config.json` 中的 `log_level` 字段 - **Web 界面**：系统设置 → 日志级别下拉框 - **运行时生效**：修改后立即生效，无需重启 ### 日志输出 - **控制台**：实时输出到命令行窗口 - **文件**：可选输出到日志文件（需编译时开启 `ENABLE_DEBUG_LOG`） --- ## 安全机制 ### 核心设备保护 系统内置安全机制，**绝对禁止**禁用以下核心设备： - 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 界面的"系统设置"中，勾选"启用后台服务（开机自启）"并保存配置。 ### 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. 检查端口是否被占用（默认 8080） 3. 检查防火墙是否阻止了端口访问 4. 尝试访问 `http://127.0.0.1:8080` --- ## 开发指南 ### 项目结构 ``` portctrl/ ├── src/ # 源代码 │ ├── main.c # 主程序入口 │ ├── sys_info.c # 系统信息与设备检测 │ ├── http_server.c # HTTP 服务器 │ ├── usb_guard.c # USB 设备管控 │ ├── config.c # 配置管理 │ ├── auth.c # 认证模块 │ ├── platform/ # 平台适配层 │ │ ├── windows/ # Windows 平台实现 │ │ │ └── usb_win.c │ │ └── linux/ # Linux 平台实现 │ │ └── usb_linux.c │ └── watchdog/ # 看门狗程序 │ └── watchdog.c ├── include/ # 头文件 │ ├── usb_guard.h # 主头文件 │ ├── sys_info.h # 系统信息头文件 │ └── http_server.h # HTTP 服务器头文件 ├── web/ # Web 管理界面 │ ├── index.html # 主页面 │ ├── login.html # 登录页面 │ ├── app.js # 前端逻辑 │ └── style.css # 样式文件 ├── build/ # 构建目录（自动生成） ├── CMakeLists.txt # CMake 构建配置 ├── version_increment.cmake # 版本号递增脚本 └── sign.ps1 # 签名脚本 ``` ### 添加新设备类型 1. 在 `sys_info.c` 中添加设备检测函数（参考 `wifi_list_devices()`） 2. 在 `sys_info.h` 中声明函数 3. 在 `main.c` 的 `monitor_loop()` 中调用检测函数 4. 在 `config.c` 中添加状态持久化支持 ### 修改 Web 界面 1. 编辑 `web/` 目录下的 HTML/CSS/JS 文件 2. 使用浏览器开发者工具调试 3. 修改后直接刷新页面即可生效（无需重新编译） ### 编译选项 ```bash # 开启调试日志（默认关闭） cmake .. -DENABLE_DEBUG_LOG=ON # 指定安装路径 cmake .. -DCMAKE_INSTALL_PREFIX=/opt/usb-guard # 交叉编译（Linux） cmake .. -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake ``` --- ## 版本历史 详见 [CHANGES.md](CHANGES.md) --- ## 许可证 本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。 --- ## 联系方式 - 项目仓库：https://gitee.com/webicc/portctrl - 问题反馈：请在 Gitee 上提交 Issue --- **注意**：本系统面向企业办公环境设计，请确保在合法授权范围内使用。使用前请咨询相关 IT 管理部门。