1. QT+C++ 开发智能访客系统:从零搭建可运行的跨平台桌面应用
你有没有遇到过这样的场景:客户临时要一个带界面的嵌入式设备管理工具,要求三天内交付原型;或者实验室需要一套轻量级访客登记系统,能跑在国产化 ARM 工控机上,还要支持串口读卡、本地 SQLite 存储、多级权限和打印导出——但团队里没人专职做桌面 GUI?这时候,QT+C++ 不是“备选方案”,而是唯一能同时扛住开发效率、跨平台兼容性、硬件对接能力和长期维护成本这四重压力的技术组合。它不像 Electron 那样吃内存,也不像纯 Win32 API 那样锁死平台,更不像 LabVIEW 那样依赖昂贵授权和封闭生态。本文不讲“QT 是什么”或“信号槽原理”,而是直接带你用一套真实可运行的智能平台访客系统源码(已开源验证),完成从环境准备、UI 编译、串口集成到调试上线的完整闭环。所有步骤均基于 Qt 5.15.2 + C++17 + MinGW/MSVC 双编译链实测,覆盖 Windows 10/11 和 Ubuntu 22.04 LTS 环境。如果你手头有一台能装 Qt 的电脑,现在就可以打开终端或命令行,跟着往下走——15 分钟后,你会看到一个带主界面、系统设置、警情查询、调试帮助和用户退出功能的完整访客系统真正跑起来。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境搭建与项目结构初始化:避开 Qt 版本与构建链的三大深坑
2.1 选择 Qt 版本与编译器组合:为什么必须是 5.15.2 而不是 6.x?
Qt 6.x 虽然引入了更现代的 QML 渲染架构和 Vulkan 支持,但它彻底移除了对传统 Widgets 模块中部分关键类(如 QAxWidget、QWindowsStyle 的深度定制接口)的向后兼容,而访客系统中“调试帮助”模块依赖的串口日志实时滚动控件、以及“系统设置”中对 Windows 注册表的写入逻辑,都强耦合于 Qt 5.15.x 的 Widgets 行为。更重要的是,Qt 6 默认启用 CMake 构建系统,而本项目原始源码基于 qmake 构建,迁移成本远超预期。我们实测发现:在 Ubuntu 22.04 上使用 Qt 6.5.2 + qmake 兼容层编译时,QSerialPort 在非主线程中打开端口会触发 QThread: Destroyed while thread is still running 崩溃,该问题在 Qt 5.15.2 中已被稳定修复。因此,必须锁定 Qt 5.15.2。安装方式如下:
-
Windows(推荐 MSVC 2019):
下载 Qt Online Installer for Windows → 安装时勾选Qt 5.15.2→MSVC 2019 64-bit→Qt Serial Port→Qt SQL (SQLite)→Qt Tools (Qt Creator)。注意:不要勾选任何 Qt 6.x 组件,避免环境变量污染。 -
Ubuntu 22.04(推荐 GCC 11.4):
bash复制sudo apt update && sudo apt install build-essential libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0-dev libxcb-xrender0-dev libxcb-xtest0-dev libxcb-xv0-dev libxcb-xvmc0-dev libxcb-xkb-dev libxcb-xinerama0-dev libxcb-xinput0-dev libxcb-xfixes0-dev libxcb-xrender0-dev libxcb-xtest0-dev libxcb-xv0-dev libxcb-xvmc0-dev libxcb-xkb-dev libxcb-xinerama0-dev libxcb-xinput0-dev libxcb-xfixes0-dev libxcb-xrender0-dev libxcb-xtest0-dev libxcb-xv0-dev libxcb-xvmc0-dev libxcb-xkb-dev wget https://download.qt.io/official_releases/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.tar.xz tar -xf qt-everywhere-src-5.15.2.tar.xz cd qt-everywhere-src-5.15.2 ./configure -prefix $HOME/Qt5.15.2 -opensource -confirm-license -release -no-opengl -sql-sqlite -qt-zlib -qt-pcre -qt-libpng -qt-libjpeg -qt-freetype -no-compile-examples -skip qtwebengine -skip qtwebview -nomake tests -nomake examples make -j$(nproc) && make install echo 'export PATH=$HOME/Qt5.15.2/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
提示:
-no-opengl是关键。本项目 UI 未启用 OpenGL 渲染,强制开启会导致在某些 Intel 集成显卡工控机上出现窗口闪烁或黑屏,这是 Qt 5.15.2 已知的驱动适配问题。
2.2 解压并识别项目结构:五个核心目录与三个不可删文件
从 CSDN 博客链接下载的源码包解压后,得到标准 Qt qmake 项目结构:
code复制visitor_system/
├── visitor_system.pro ← 项目主配置文件(不可删!)
├── main.cpp ← 程序入口,含 QApplication 初始化与主窗口创建
├── mainwindow.h/.cpp ← 主界面类,继承自 QMainWindow,含菜单栏、状态栏、中心控件
├── systemsetting.h/.cpp ← “系统设置”功能模块,负责串口参数配置、数据库路径设定、用户权限管理
├── alarmquery.h/.cpp ← “警情查询”模块,实现 SQLite 查询、时间范围筛选、结果导出为 CSV
├── debughelp.h/.cpp ← “调试帮助”模块,含串口数据收发日志、内存占用监控、错误码速查表
├── resources/ ← 图标、字体、SQL 初始化脚本存放目录
│ ├── icons/ ← .png 格式图标(main_icon.png, exit_icon.png 等)
│ └── init_db.sql ← 创建 users、visitors、alarms 三张表的 SQL 脚本
└── build/ ← 编译输出目录(首次需手动创建)
其中,visitor_system.pro 是整个项目的“宪法”,它定义了编译目标、依赖模块、头文件路径和资源文件引用。切勿用 Qt Creator 自动重生成该文件——原版已精确配置了 QT += serialport sql widgets 和 CONFIG += c++17,若被覆盖,QSerialPort 将无法链接,编译报错 undefined reference to 'QSerialPort::QSerialPort(QObject*)'。
2.3 初始化 SQLite 数据库:执行 init_db.sql 的两种可靠方式
访客系统所有业务数据(访客信息、报警记录、用户账号)均存于本地 visitor.db 文件,首次运行前必须初始化表结构。resources/init_db.sql 内容如下:
sql复制CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL,
role TEXT CHECK(role IN ('admin', 'operator')) DEFAULT 'operator'
);
CREATE TABLE IF NOT EXISTS visitors (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
id_card TEXT UNIQUE,
phone TEXT,
visit_time DATETIME DEFAULT CURRENT_TIMESTAMP,
status TEXT CHECK(status IN ('in', 'out')) DEFAULT 'in'
);
CREATE TABLE IF NOT EXISTS alarms (
id INTEGER PRIMARY KEY AUTOINCREMENT,
visitor_id INTEGER,
type TEXT NOT NULL,
description TEXT,
trigger_time DATETIME DEFAULT CURRENT_TIMESTAMP,
handled BOOLEAN DEFAULT 0,
FOREIGN KEY(visitor_id) REFERENCES visitors(id)
);
方式一(推荐,代码内自动执行):
在 systemsetting.cpp 的构造函数中,已内置数据库初始化逻辑:
cpp复制// systemsetting.cpp 第 42 行起
QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
db.setDatabaseName(QApplication::applicationDirPath() + "/visitor.db");
if (!db.open()) {
qCritical() << "Failed to open database:" << db.lastError().text();
return;
}
QSqlQuery query(db);
// 读取并执行 init_db.sql
QFile file(QApplication::applicationDirPath() + "/resources/init_db.sql");
if (file.open(QIODevice::ReadOnly | QIODevice::Text)) {
QString sql = file.readAll();
file.close();
QStringList statements = sql.split(";", Qt::SkipEmptyParts);
for (const QString &stmt : statements) {
if (!stmt.trimmed().isEmpty() && !stmt.trimmed().startsWith("--")) {
if (!query.exec(stmt.trimmed())) {
qWarning() << "SQL exec failed:" << stmt.trimmed() << query.lastError().text();
}
}
}
}
只要确保 resources/init_db.sql 与可执行文件同级目录下的 resources/ 文件夹存在,程序启动时会自动建库建表。
方式二(手动验证):
若需独立验证 SQL 正确性,使用 sqlite3 命令行工具:
bash复制cd visitor_system
mkdir -p build && cd build
sqlite3 ../visitor.db < ../resources/init_db.sql
sqlite3 ../visitor.db ".tables" # 应输出:alarms users visitors
注意:
QApplication::applicationDirPath()返回的是可执行文件所在目录,不是源码目录。因此resources/必须复制到最终生成的visitor_system.exe或visitor_system二进制文件同级目录下,否则init_db.sql加载失败,导致后续所有数据库操作返回空结果。
3. 主界面与核心功能模块集成:从 UI 设计到信号槽绑定
3.1 使用 Qt Designer 构建主窗口:四个关键控件与布局约束
mainwindow.ui 是通过 Qt Designer 拖拽生成的标准 .ui 文件,其核心控件结构如下(可在 Qt Creator 中双击打开编辑):
| 控件类型 | 对象名 | 功能说明 | 关键属性设置 |
|---|---|---|---|
QTabWidget |
tabWidget |
主功能区容器,含“主界面”、“系统设置”、“警情查询”、“调试帮助”四个 Tab | currentIndex=0(默认显示主界面) |
QTableWidget |
visitorTable |
主界面访客列表,实时显示当前在场人员 | columnCount=4, horizontalHeaderLabels=["姓名","身份证号","电话","进入时间"], selectionBehavior=SelectRows |
QPushButton |
btnAddVisitor |
主界面“新增访客”按钮 | icon=QIcon(":/icons/add.png"), shortcut=Ctrl+N |
QStatusBar |
statusBar |
底部状态栏,显示串口连接状态、数据库路径、当前用户 | showMessage("Ready") 初始化 |
布局采用 QVBoxLayout(主窗口)→ QHBoxLayout(顶部按钮区)→ QTabWidget(功能区)三级嵌套。必须注意的约束:visitorTable 的 sizePolicy 应设为 Expanding(水平/垂直均为 Expanding),否则在高分屏 Windows 10 上会出现表格高度固定、无法随窗口拉伸的问题。此设置在 Designer 的 Property Editor 中修改,不可仅靠代码 setSizePolicy() 覆盖。
3.2 信号槽绑定实战:三个最易出错的连接点
Qt 的信号槽机制是访客系统各模块解耦的核心,但新手常因线程、对象生命周期或连接类型错误导致功能失效。以下是三个真实踩坑点及修复方案:
坑点一:QSerialPort::readyRead() 信号在子线程中未触发
现象:在 debughelp.cpp 中创建了 QSerialPort 对象并 moveToThread,但 connect(serial, &QSerialPort::readyRead, this, &DebugHelp::onSerialDataReceived) 无响应。
原因:QSerialPort 的事件循环必须在其所属线程中运行,而 moveToThread 后未启动该线程的 QEventLoop。
解决:在 DebugHelp 构造函数中添加:
cpp复制// debughelp.cpp 第 35 行
serialThread = new QThread(this);
serial = new QSerialPort();
serial->moveToThread(serialThread);
connect(serialThread, &QThread::started, serial, &QSerialPort::open); // 启动线程即打开串口
connect(serial, &QSerialPort::readyRead, this, &DebugHelp::onSerialDataReceived, Qt::QueuedConnection); // 强制队列连接
serialThread->start(); // 必须在 connect 之后调用!
坑点二:“系统设置”中串口参数修改后未实时生效
现象:在 systemsetting.ui 中修改波特率下拉框,点击“应用”按钮,但 QSerialPort 实际波特率未改变。
原因:QComboBox 的 currentTextChanged 信号未绑定到更新逻辑,且 QSerialPort::setBaudRate() 必须在串口关闭状态下调用。
解决:在 systemsetting.cpp 中:
cpp复制// systemsetting.cpp 第 88 行
connect(ui->baudRateCombo, &QComboBox::currentTextChanged, this, [this](const QString &text){
bool ok;
int baud = text.toInt(&ok);
if (ok && serial->isOpen()) {
serial->close(); // 先关闭
serial->setBaudRate(baud);
serial->open(QIODevice::ReadWrite); // 再打开
}
});
坑点三:“警情查询”的日期范围筛选器返回空结果
现象:选择开始/结束时间后点击“查询”,QSqlQueryModel 显示 0 条记录。
原因:SQLite 的 DATETIME 字段存储格式为 YYYY-MM-DD HH:MM:SS,而 QDateTimeEdit 的 dateTime().toString("yyyy-MM-dd hh:mm:ss") 生成的字符串中 hh 是 12 小时制,导致 WHERE visit_time BETWEEN ? AND ? 匹配失败。
解决:统一使用 24 小时制格式:
cpp复制// alarmquery.cpp 第 124 行
QString startStr = ui->startTimeEdit->dateTime().toString("yyyy-MM-dd HH:mm:ss");
QString endStr = ui->endTimeEdit->dateTime().toString("yyyy-MM-dd HH:mm:ss");
query.prepare("SELECT * FROM visitors WHERE visit_time BETWEEN ? AND ?");
query.addBindValue(startStr);
query.addBindValue(endStr);
3.3 多线程安全的串口通信:QSerialPort 与 QThread 的黄金搭档
访客系统的串口通信(用于读取 IC 卡 ID、门禁控制器状态)必须脱离主线程,否则 UI 会卡死。debughelp.h 中定义了专用通信类:
cpp复制class SerialWorker : public QObject {
Q_OBJECT
public slots:
void doWork(const QString &portName, int baudRate); // 执行串口打开与数据接收
signals:
void resultReady(const QByteArray &data); // 接收到的数据
void errorOccured(const QString &msg); // 错误信息
};
DebugHelp 类中启动工作线程:
cpp复制// debughelp.cpp 第 62 行
worker = new SerialWorker();
workerThread = new QThread();
worker->moveToThread(workerThread);
connect(workerThread, &QThread::finished, worker, &QObject::deleteLater);
connect(this, &DebugHelp::startSerial, worker, &SerialWorker::doWork);
connect(worker, &SerialWorker::resultReady, this, &DebugHelp::handleSerialData);
connect(worker, &SerialWorker::errorOccured, this, &DebugHelp::showSerialError);
workerThread->start();
SerialWorker::doWork 实现(关键节选):
cpp复制void SerialWorker::doWork(const QString &portName, int baudRate) {
QSerialPort serial;
serial.setPortName(portName);
serial.setBaudRate(baudRate);
if (!serial.open(QIODevice::ReadOnly)) {
emit errorOccured("Open port failed: " + serial.errorString());
return;
}
// 设置串口参数
serial.setDataBits(QSerialPort::Data8);
serial.setParity(QSerialPort::NoParity);
serial.setStopBits(QSerialPort::OneStop);
serial.setFlowControl(QSerialPort::NoFlowControl);
while (serial.isOpen()) {
if (serial.waitForReadyRead(100)) { // 100ms 超时
QByteArray data = serial.readAll();
if (!data.isEmpty()) {
emit resultReady(data);
}
}
QThread::msleep(10); // 避免 CPU 占用过高
}
}
避坑 / 常见问题 / 排查
- 现象:
QSerialPort::waitForReadyRead()在 Linux 上永远返回false,即使串口有数据。
原因:Linux 内核串口驱动默认启用ICRNL(回车换行转换),导致QSerialPort读取到的\r\n被转换为\n,而waitForReadyRead()的内部缓冲区未及时刷新。
解决:在open()前显式禁用输入处理:cpp复制#ifdef Q_OS_LINUX struct termios tty; if (tcgetattr(serial.handle(), &tty) == 0) { cfmakeraw(&tty); // 清除所有输入处理标志 tcsetattr(serial.handle(), TCSANOW, &tty); } #endif
- 现象:Windows 上串口打开后立即触发
readyRead,但读取到的数据为空或乱码。
原因:串口设备(如 USB 转 TTL 模块)上电时会发送初始化字符串,QSerialPort在open()后立即读取该垃圾数据。
解决:在open()后立即清空输入缓冲区:cpp复制serial.open(QIODevice::ReadWrite); serial.clear(); // 清除启动时的垃圾数据
- 现象:多设备同时访问同一串口(如调试助手与访客系统),系统报错
Resource busy。
原因:Linux 下串口设备文件(如/dev/ttyUSB0)被其他进程独占。
解决:检查并杀掉占用进程:bash复制lsof /dev/ttyUSB0 # 查看占用进程 sudo kill -9 <PID> # 强制终止 # 或永久加入 dialout 用户组避免权限问题 sudo usermod -a -G dialout $USER
4. 跨平台编译与部署:生成可独立运行的二进制包
4.1 Windows 平台:MSVC 编译 + windeployqt 打包
在 Qt Creator 中,选择 Projects → Build & Run → Kits,确认已配置 Desktop Qt 5.15.2 MSVC2019 64bit。构建步骤:
Build → Rebuild Project "visitor_system"- 编译成功后,进入
build-visitor_system-Desktop_Qt_5_15_2_MSVC2019_64bit-Release/目录 - 执行
windeployqt命令(路径需替换为你的 Qt 安装路径):cmd复制D:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe --no-angle --no-opengl-sw --no-compiler-runtime --no-system-d3d-compiler --verbose=2 visitor_system.exe关键参数说明:
--no-angle:禁用 ANGLE OpenGL ES 转译层,避免在无 GPU 工控机上崩溃;
--no-opengl-sw:禁用软件 OpenGL 渲染,防止qwindows.dll依赖冲突;
--no-compiler-runtime:不打包 MSVC 运行时(假设目标机器已安装 VC++ 2019 Redistributable);
--verbose=2:输出详细日志,便于排查缺失的 DLL。
执行后,visitor_system.exe 同级目录将生成 platforms/qwindows.dll、imageformats/qsvg.dll、sqldrivers/qsqlite.dll 等必要插件。必须验证:将整个目录拷贝到一台干净的 Windows 10 虚拟机(未安装 Qt),双击 visitor_system.exe,确认主界面正常弹出、串口可识别、数据库可读写。
4.2 Ubuntu 22.04 平台:GCC 编译 + linuxdeployqt 打包
先安装 linuxdeployqt:
bash复制wget https://github.com/probonopd/linuxdeployqt/releases/download/continuous/linuxdeployqt-continuous-x86_64.AppImage
chmod a+x linuxdeployqt-continuous-x86_64.AppImage
sudo mv linuxdeployqt-continuous-x86_64.AppImage /usr/local/bin/linuxdeployqt
构建步骤:
- 在 Qt Creator 中切换 Kit 为
Desktop Qt 5.15.2 GCC 64bit Build → Rebuild Project- 进入
build-visitor_system-Desktop_Qt_5_15_2_GCC_64bit-Release/ - 执行打包:
bash复制
其中linuxdeployqt visitor_system.desktop -appimage -executable visitor_system -bundle-non-qt-libs -no-strip -verbose=2visitor_system.desktop需手动创建(内容如下):ini复制[Desktop Entry] Name=Visitor System Exec=visitor_system Icon=visitor_system Type=Application Categories=Utility;
打包生成的 visitor_system-x86_64.AppImage 是单文件可执行包。验证方法:在 Ubuntu 22.04 Live USB 环境中挂载该 AppImage,直接运行,确认:
QSerialPort能枚举/dev/ttyUSB*设备(需提前sudo usermod -a -G dialout $USER);- SQLite 数据库存储在
$HOME/.local/share/visitor_system/visitor.db(符合 XDG Base Directory 规范); - 界面字体清晰,无模糊或缩放异常。
4.3 通用部署检查清单:九项必验项
| 检查项 | 验证方法 | 不通过表现 | 修复动作 |
|---|---|---|---|
| 1. 串口设备权限 | ls -l /dev/ttyUSB0 |
crw-rw---- 1 root dialout → 当前用户不在 dialout 组 |
sudo usermod -a -G dialout $USER && reboot |
| 2. SQLite 插件加载 | 运行时设置 export QT_DEBUG_PLUGINS=1 |
控制台输出 Cannot load library .../sqldrivers/libqsqlite.so |
确认 sqldrivers/ 目录存在且 libqsqlite.so 权限为 755 |
| 3. 图标资源路径 | 检查 resources/icons/ 是否与二进制同级 |
界面按钮显示“X”而非图标 | 将 resources/ 文件夹整体复制到二进制所在目录 |
| 4. 中文字符显示 | 在“新增访客”输入中文姓名并保存 | 数据库中显示为 ???? |
在 main.cpp 中 QApplication 创建后添加 QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8")); |
| 5. 系统托盘图标 | Ubuntu 上右下角无托盘图标 | QSystemTrayIcon 构造失败 |
安装 libappindicator1:sudo apt install libappindicator1 |
| 6. 高分屏缩放 | Windows 10 设置缩放为 150% | 界面元素挤压变形 | 在 main.cpp 中 QApplication 创建前添加 qputenv("QT_SCALE_FACTOR", "1.5"); |
| 7. 打印功能可用性 | 点击“导出为 PDF” → 选择打印机 | 报错 QPrinter: No such file or directory |
Ubuntu 需安装 libcups2-dev 并重新编译 Qt(生产环境建议改用 QTextDocument::print() + QPrinter::OutputFormat::PdfFormat) |
| 8. 数据库路径可写 | ls -ld $(dirname $(realpath visitor_system.db)) |
权限为 drwxr-xr-x(无写权限) |
chmod 755 $(dirname $(realpath visitor_system.db)) |
| 9. 调试日志输出 | 启动时加参数 ./visitor_system --log-level debug |
无日志输出 | 在 main.cpp 中 QApplication 创建后添加 qInstallMessageHandler(customMessageHandler); |
5. 调试帮助模块深度用法:从日志分析到硬件故障定位
5.1 串口日志的四级过滤与关键词高亮
debughelp.ui 中的 QTextEdit 日志窗口支持实时过滤,其核心逻辑在 DebugHelp::appendLog():
cpp复制void DebugHelp::appendLog(const QString &msg, LogLevel level) {
QString prefix;
QTextCharFormat format;
switch (level) {
case LOG_INFO:
prefix = "[INFO] ";
format.setForeground(Qt::black);
break;
case LOG_WARN:
prefix = "[WARN] ";
format.setForeground(Qt::darkYellow);
break;
case LOG_ERROR:
prefix = "[ERROR] ";
format.setForeground(Qt::red);
break;
case LOG_DEBUG:
prefix = "[DEBUG] ";
format.setForeground(Qt::gray);
break;
}
// 四级过滤:仅显示选中的日志级别
if (level >= currentLogLevel) {
QTextCursor cursor = ui->logTextEdit->textCursor();
cursor.movePosition(QTextCursor::End);
cursor.insertText(prefix + msg + "\n", format);
ui->logTextEdit->verticalScrollBar()->setValue(ui->logTextEdit->verticalScrollBar()->maximum());
}
}
实战技巧:在“调试帮助”页签中,点击 Filter Level 下拉框,可动态切换日志级别。当系统出现“访客信息无法保存”时,将级别设为 DEBUG,观察日志中是否出现:
code复制[DEBUG] Executing SQL: INSERT INTO visitors (name, id_card, phone) VALUES (?, ?, ?)
[ERROR] SQL error: UNIQUE constraint failed: visitors.id_card
这直接指向身份证号重复的业务逻辑错误,而非数据库连接失败。
5.2 内存与 CPU 占用监控:嵌入式设备的健康度仪表盘
debughelp.ui 右下角的 QProgressBar 和 QLabel 实时显示系统资源,其数据来源为 QProcess 调用系统命令:
cpp复制// debughelp.cpp 第 215 行
void DebugHelp::updateSystemStats() {
#ifdef Q_OS_WIN
// Windows 获取内存使用率
MEMORYSTATUSEX memInfo;
memInfo.dwLength = sizeof(MEMORYSTATUSEX);
GlobalMemoryStatusEx(&memInfo);
int memUsage = static_cast<int>(100.0 * (memInfo.ullTotalPhys - memInfo.ullAvailPhys) / memInfo.ullTotalPhys);
ui->memProgressBar->setValue(memUsage);
ui->memLabel->setText(QString("Mem: %1%").arg(memUsage));
// CPU 使用率(需 WMI 查询,此处简化为固定值)
ui->cpuProgressBar->setValue(15);
ui->cpuLabel->setText("CPU: 15%");
#else
// Linux 获取内存使用率
QFile file("/proc/meminfo");
if (file.open(QIODevice::ReadOnly | QIODevice::Text)) {
QTextStream in(&file);
QString line;
ulong total = 0, free = 0;
while (!in.atEnd()) {
line = in.readLine();
if (line.startsWith("MemTotal:")) {
total = line.split(' ', Qt::SkipEmptyParts)[1].toULong();
} else if (line.startsWith("MemAvailable:")) {
free = line.split(' ', Qt::SkipEmptyParts)[1].toULong();
}
}
file.close();
if (total > 0) {
int memUsage = static_cast<int>(100.0 * (total - free) / total);
ui->memProgressBar->setValue(memUsage);
ui->memLabel->setText(QString("Mem: %1%").arg(memUsage));
}
}
// Linux CPU 使用率(采样 /proc/stat)
QFile cpuFile("/proc/stat");
if (cpuFile.open(QIODevice::ReadOnly | QIODevice::Text)) {
QString cpuLine = cpuFile.readLine();
cpuFile.close();
QStringList cpuVals = cpuLine.split(' ', Qt::SkipEmptyParts);
if (cpuVals.size() >= 5) {
ulong user = cpuVals[1].toULong();
ulong nice = cpuVals[2].toULong();
ulong system = cpuVals[3].toULong();
ulong idle = cpuVals[4].toULong();
static ulong lastUser = 0, lastNice = 0, lastSystem = 0, lastIdle = 0;
ulong totalDelta = (user + nice + system + idle) - (lastUser + lastNice + lastSystem + lastIdle);
ulong idleDelta = idle - lastIdle;
if (totalDelta > 0) {
int cpuUsage = static_cast<int>(100.0 * (totalDelta - idleDelta) / totalDelta);
ui->cpuProgressBar->setValue(cpuUsage);
ui->cpuLabel->setText(QString("CPU: %1%").arg(cpuUsage));
}
lastUser = user; lastNice = nice; lastSystem = system; lastIdle = idle;
}
}
#endif
}
玄学经验:在 ARM 工控机上部署时,若 cpuProgressBar 长期显示 95%+,但 top 命令显示 visitor_system 进程 CPU 占用仅 5%,大概率是 QTimer::singleShot(100, this, &DebugHelp::updateSystemStats) 的 100ms 间隔太短,导致定时器频繁抢占。此时应将间隔改为 500,并增加防抖逻辑:
cpp复制// debughelp.h 中添加
QElapsedTimer lastUpdateTimer;
// debughelp.cpp 中 updateSystemStats() 开头
if (lastUpdateTimer.isValid() && lastUpdateTimer.elapsed() < 400) {
return; // 防抖,至少间隔 400ms
}
lastUpdateTimer.start();
5.3 错误码速查表:访客系统专属的 12 个核心错误码
debughelp.ui 中的 QTableWidget errorTable 内置了访客系统所有可能错误的速查表,其数据来自 debughelp.cpp 的静态映射:
cpp复制const QMap<int, QString> DebugHelp::errorMap = {
{1001, "串口未打开:请检查设备连接及端口号"},
{1002, "串口参数错误:波特率/数据位/校验位不匹配"},
{1003, "数据库打开失败:visitor.db 被其他程序占用"},
{1004, "SQL 执行失败:语法错误或字段不存在"},
{1005, "身份证号重复:系统已存在相同 ID 的访客"},
{1006, "用户权限不足:当前账号无权执行此操作"},
{1007, "图片加载失败:resources/icons/ 路径错误"},
{1008, "打印服务未就绪:请检查 CUPS 服务状态"},
{1009, "网络请求超时:与后端服务器通信失败"},
{1010, "证书验证失败:HTTPS 连接证书无效"},
{1011, "内存分配失败:系统剩余内存低于 50MB"},
{1012, "硬件看门狗触发:系统检测到长时间无响应"}
};
血泪经验:某次现场交付时,客户反馈“点击‘新增访客’无反应”,日志中只显示 [ERROR] Error code: 1004。按速查表应为 SQL 错误,但检查 init_db.sql 无误。最终发现是客户自行修改了 visitor_system.pro,删除了 QT += sql,导致 QSqlQuery 类未链接。教训:每次修改 .pro 文件后,必须执行 qmake 重新生成 Makefile,并确认 make clean && make 无警告。
6. 生产环境加固与长期维护策略:让访客系统真正“活”三年
6.1 数据库自动备份与版本迁移
访客系统默认将 visitor.db 存于可执行文件同级目录,但生产环境需定期备份并支持 schema 升级。我们在 systemsetting.cpp 中实现了自动备份策略:
cpp复制// systemsetting.cpp 第 312 行
void SystemSetting::autoBackupDatabase() {
QString dbPath = QApplication::applicationDirPath() + "/visitor.db";
QString backupDir = QApplication::applicationDirPath() + "/backup";
QDir().mkpath(backupDir);
QString timestamp = QDateTime::currentDateTime().toString("yyyyMMdd_hhmmss");
QString backupPath = backupDir + "/visitor_" + timestamp + ".db";
if (QFile::copy(dbPath, backupPath)) {
// 保留最近 7 天的备份
QDir backupDirObj(backupDir);
QFileInfoList backups = backupDirObj.entryInfoList({"visitor_*.db"}, QDir::Files, QDir::Time);
for (int i = 7; i < backups
