在嵌入式设备的联调、测试、产线和售后阶段上位机几乎是一个绕不开的工程角色。很多嵌入式项目并不需要复杂的云端平台而是需要一台运行在 Windows 或 Linux 上的 PC 软件通过串口、USB、TCP/UDP 与下位机通信完成参数下发、状态显示、数据记录和本地存储。C Qt 是这个领域里很常用的一套跨平台框架而 SQLite 则承担了本地数据持久化的工作。下面围绕一个由 Qt 编写的嵌入式上位机项目重点说明为什么把 SQLite 作为必备技术以及如何把 Qt 界面、通信线程、数据库写入和查询组成一条完整可运行的链路。1. 先理解上位机、下位机和 SQLite 的各自分工1.1 上位机到底解决什么问题下位机通常是单片机、PLC、嵌入式板卡负责采集传感器、控制执行器。它的特点是资源受限屏幕小、内存小、算力有限不适合做复杂的人机交互。但嵌入式项目又离不开现场调试、参数标定、数据记录和离线分析这时候就需要一台 PC 程序来承担这些任务这就是上位机。上位机并不是一个万能平台它的核心价值是把下位机回传的原始数据转换成可视化信息并把配置参数可靠地下发给下位机。一个典型场景是设备联调下位机通过串口或网络持续上报温度、压力、转速等数据上位机实时显示曲线并保存到本地数据库方便后续追溯和统计分析。另一个典型场景是产线标定上位机通过界面输入 PID 参数打包成协议帧下发给下位机写入 EEPROM 或 Flash。这两个场景都依赖稳定的通信、清晰的数据结构和可靠的数据存储。1.2 为什么 Qt 适合做上位机开发在 C 技术栈里Qt 是跨平台 GUI 开发的高频选择。它不只是一套控件库还提供了网络、串口、SQL、多线程、JSON/XML 解析、图表、OpenGL 等模块基本能把上位机的常见需求覆盖掉。Qt 的几个特性在嵌入式上位机场景中非常关键信号槽机制让 UI 事件、通信数据到达、定时器、数据库操作之间的联动更清晰。跨平台能力让同一套代码可以在 Windows、Linux、部分国产操作系统上运行适合工控机和产线设备。Qt SQL 模块内置 SQLite 驱动不需要额外安装数据库服务部署成本低。QThread、QtConcurrent 等并发工具可以处理采集线程和 UI 线程之间的协作。配套的 Qt Creator、qmake/CMake、windeployqt 等工具让开发和发布流程完整。有人会对比 C# 上位机。C# 在 Windows 生态下开发效率很高但离开 Windows 之后会遇到运行时和 UI 框架的移植问题。Qt 的优势在于跨平台和 C 性能劣势是 UI 快速开发不如 C# 在某些场景下高效。实际选型时只要项目有跨平台、长时间稳定运行、协议栈和底层硬件交互较多的要求Qt 就是合理的候选方案。1.3 SQLite 在上位机中的定位SQLite 是一个内嵌式关系数据库不需要独立的数据库服务进程直接把数据写入一个普通文件。它非常适合单机软件因为它安装简单、数据文件方便备份、SQL 查询能力完整。Qt 里通过QSqlDatabase加QSQLITE驱动即可访问属于默认支持范围。上位机数据存储场景通常包括设备参数、实时采集数据、告警事件、操作日志。如果用文本日志保存查询某一天的曲线数据会非常麻烦如果用 Excel 或 CSV 文件并发写入和格式管理都不可控。SQLite 的价值在于用标准的 SQL 语法完成插入、查询、聚合、去重和删除同时把数据收敛在一个文件里。选择 SQLite 而不是 MySQL、PostgreSQL主要原因是上位机通常运行在单机或者少数几台电脑上不需要网络数据库服务。数据库服务会引入安装、账号、端口、防火墙等额外维护成本对产线和售后场景不友好。SQLite 虽然也有并发写入上限但通过 WAL 模式和合理的业务隔离完全能应对常见的采集频率和操作量。存储方案是否需要服务并发能力查询能力部署复杂度典型场景SQLite不需要文件型中低多个读单写较稳定支持标准 SQL聚合、索引、事务低直接随应用部署单机上位机、本地历史数据、配置存储CSV/文本不需要低无事务保证基本不支持复杂查询极低简单导出、临时记录MySQL/PostgreSQL需要独立服务高强高需要安装维护多机数据汇总、服务端应用这里要注意不要把 SQLite 当成高并发数据库。如果多个上位机同时写同一个数据库文件或者采集频率非常高且每次都单独执行事务就会出现锁冲突。后续章节会专门讲如何用 WAL、busy_timeout和批量写入来缓解。2. 环境准备把 Qt、编译器和 SQLite 驱动的链路先确认好2.1 选择 Qt 版本和编译器Qt 的版本选择会直接影响后面的代码写法和插件目录结构。Qt 5.15 是目前很多存量项目还在使用的版本因为它对老编译器兼容好、资料多。Qt 6.5 LTS 则是新项目更推荐的选择它移除了部分旧模块对 C17 要求更明确Charts 模块改由单独维护的模块提供。可以先按场景做一个简化判断场景推荐版本编译器说明学习、新项目、跨平台Qt 6.5 LTS 或更高MSVC 2019/2022Linux 下用 GCC 9长期维护官方文档更聚焦 Qt 6维护老项目Qt 5.15根据原项目编译链保持避免升级引发大量接口变更Windows 下的快速验证Qt 6.x MinGWMinGW 11.2安装简单但发布时要注意运行时库安装 Qt 时需要注意在线安装器里先选择对应版本的 Widgets、Sql、Charts、Network、SerialPort 等模块。如果勾选时漏掉 Sql 模块后面会出现 SQLite 驱动加载失败。实践中宁可多选几个常用模块也不要等编译时报错再回头重装。2.2 创建 Qt Widgets 工程这里推荐使用 CMake 作为构建方式因为 CMake 对跨平台、命令行构建和 CI 集成更友好。Qt Creator 也可以直接生成工程但 CMake 文件更容易在团队中统一。一个最小工程的 CMakeLists.txt 如下cmake_minimum_required(VERSION 3.16) project(EmbeddedHostApp VERSION 0.1 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) find_package(Qt6 REQUIRED COMPONENTS Widgets Sql Charts) qt_add_executable(EmbeddedHostApp main.cpp MainWindow.cpp MainWindow.h DatabaseManager.cpp DatabaseManager.h ) target_link_libraries(EmbeddedHostApp PRIVATE Qt6::Widgets Qt6::Sql Qt6::Charts )代码里的关键点是find_package中的Sql和Charts组件。Qt6::Sql是数据库操作模块Qt6::Charts用于曲线显示。如果当前工程不需要曲线可以暂时去掉 Charts避免多引入依赖。使用 Qt 5 时组件名和库名类似但要确保编译器和 Qt 版本一致。2.3 验证 SQLite 驱动是否可用Qt 操作 SQLite 并不需要单独安装 SQLite 开发包因为 Qt 官方已经把 SQLite 驱动编译成插件。但在某些 Linux 发行版或自定义 Qt 安装中插件可能缺失。启动程序后如果在控制台看到类似下面这样的一行说明驱动加载可能有问题QSqlDatabase: QSQLITE driver not loaded出现这个报错时第一步是先打印当前可用的驱动列表#include QSqlDatabase #include QDebug void printAvailableDrivers() { const QStringList drivers QSqlDatabase::drivers(); qDebug() Available SQL drivers: drivers; }正常输出里应该包含QSQLITE。如果没有需要检查 Qt 安装时是否勾选了 Sql 模块以及程序运行时能否找到 Qt 的sqldrivers插件目录。Windows 下发布时常见的错误是只拷贝了Qt6Sql.dll却没有把plugins/sqldrivers/qsqlite.dll拷贝到程序同级的sqldrivers目录。Linux 下则要留意 Qt 插件的安装路径是否在QT_PLUGIN_PATH中。注意不要只验证程序能够启动还要用QSqlDatabase::drivers()确认 SQLite 驱动真实存在否则数据库操作会一直停留在“打不开数据库”的阶段。3. 用一个最小上位机项目跑通“采集-存储-查询”闭环3.1 项目结构和模块划分这个最小项目不需要写真实的串口解析先用“手动填写传感器数据点击保存列表查询显示”来跑通 Qt 和 SQLite 的完整链路。等这条链路没有问题后再把采集来源替换成串口或网络即可。推荐的项目结构如下EmbeddedHostApp/ ├── CMakeLists.txt ├── main.cpp ├── MainWindow.h ├── MainWindow.cpp ├── DatabaseManager.h ├── DatabaseManager.cpp └── resources/DatabaseManager专门负责数据库初始化、连接管理和建表MainWindow负责 UI 交互和展示。这样把数据库访问和界面代码分开后续换数据库或加业务逻辑时不至于把 main.cpp 写得很长。3.2 数据库初始化和建表先定义DatabaseManager的头文件// DatabaseManager.h #pragma once #include QSqlDatabase #include QString class DatabaseManager { public: static bool init(const QString dbPath); static QSqlDatabase connection(); };实现文件里先打开数据库再执行建表语句// DatabaseManager.cpp #include DatabaseManager.h #include QSqlQuery #include QSqlError #include QDir #include QDebug static QString s_dbPath; bool DatabaseManager::init(const QString dbPath) { s_dbPath dbPath; // 如果目标目录不存在先创建目录 QDir dir QFileInfo(dbPath).absoluteDir(); if (!dir.exists()) { dir.mkpath(.); } // Qt 6 中默认连接名可以直接使用 QSqlDatabase db QSqlDatabase::contains(host_conn) ? QSqlDatabase::database(host_conn) : QSqlDatabase::addDatabase(QSQLITE, host_conn); db.setDatabaseName(dbPath); if (!db.open()) { qCritical() Open database failed: db.lastError().text(); return false; } QSqlQuery query(db); bool ok query.exec( CREATE TABLE IF NOT EXISTS sensor_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_id TEXT NOT NULL, sensor_name TEXT NOT NULL, value REAL NOT NULL, unit TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ); if (!ok) { qCritical() Create table failed: query.lastError().text(); return false; } return true; } QSqlDatabase DatabaseManager::connection() { return QSqlDatabase::database(host_conn); }这里用QSqlDatabase::contains(host_conn)避免重复创建同名的数据库连接。实际项目中如果多线程访问数据库建议按线程创建独立连接而不是所有线程共享同一个连接后面会说明原因。3.3 主界面布局和手动插入一条记录在MainWindow构造函数里布局 UI至少需要这几个控件设备 ID 输入框类型QLineEdit传感器名称下拉框类型QComboBox数值输入框类型QDoubleSpinBox单位输入框类型QLineEdit保存按钮类型QPushButton表格视图类型QTableView界面代码可以直接用 Qt Creator 生成也可以手写。这里以手动添加核心控件的方式展示// MainWindow.cpp 片段 MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , m_deviceIdEdit(new QLineEdit(device_001, this)) , m_sensorNameCombo(new QComboBox(this)) , m_valueSpin(new QDoubleSpinBox(this)) , m_unitEdit(new QLineEdit(℃, this)) , m_saveButton(new QPushButton(写入数据库, this)) , m_tableView(new QTableView(this)) { m_sensorNameCombo-addItems({温度, 压力, 转速, 电压}); // 布局演示时使用两个水平布局拼接 auto *controlLayout new QHBoxLayout; controlLayout-addWidget(new QLabel(设备ID:, this)); controlLayout-addWidget(m_deviceIdEdit); controlLayout-addWidget(new QLabel(传感器:, this)); controlLayout-addWidget(m_sensorNameCombo); controlLayout-addWidget(new QLabel(数值:, this)); controlLayout-addWidget(m_valueSpin); controlLayout-addWidget(new QLabel(单位:, this)); controlLayout-addWidget(m_unitEdit); controlLayout-addWidget(m_saveButton); auto *central new QWidget(this); auto *mainLayout new QVBoxLayout(central); mainLayout-addLayout(controlLayout); mainLayout-addWidget(m_tableView); setCentralWidget(central); connect(m_saveButton, QPushButton::clicked, this, MainWindow::onSaveRecord); refreshTable(); }保存按钮对应的槽函数如下void MainWindow::onSaveRecord() { QSqlDatabase db DatabaseManager::connection(); QSqlQuery query(db); query.prepare( INSERT INTO sensor_history(device_id, sensor_name, value, unit) VALUES (?, ?, ?, ?) ); query.addBindValue(m_deviceIdEdit-text().trimmed()); query.addBindValue(m_sensorNameCombo-currentText()); query.addBindValue(m_valueSpin-value()); query.addBindValue(m_unitEdit-text().trimmed()); if (!query.exec()) { qWarning() Insert failed: query.lastError().text(); return; } refreshTable(); }这里使用prepare加addBindValue而不是直接拼接 SQL 字符串。原因是传感器名称、设备 ID 都可能是外部输入直接拼接可能会出现 SQL 转义问题和安全风险。Qt 的预处理参数绑定可以避免这个问题。3.4 查询和刷新逻辑用QSqlQueryModel把查询结果直接显示到表格里。刷新函数如下void MainWindow::refreshTable() { m_model new QSqlQueryModel(this); m_model-setQuery( SELECT device_id AS 设备ID, sensor_name AS 传感器, value AS 数值, unit AS 单位, created_at AS 记录时间 FROM sensor_history ORDER BY id DESC LIMIT 200, DatabaseManager::connection() ); m_tableView-setModel(m_model); m_tableView-resizeColumnsToContents(); }QSqlQueryModel适合只读展示不需要自己实现QAbstractTableModel代码量小。如果后续需要编辑、排序、自定义单元格颜色再替换成QSqlTableModel或自定义模型。这里还要注意每次刷新都创建一个新模型并setModel旧模型会被 Qt 的父子对象机制释放不需要手动 delete但频繁刷新时最好不要在槽函数里用局部模型指针。3.5 运行验证运行程序后按照下面的步骤验证最小闭环填写设备 ID、选择传感器名称、输入数值和单位。点击“写入数据库”按钮。表格区域立即出现一条新记录。关闭程序再次打开表格中依然有刚才插入的记录。用 DB Browser for SQLite 打开数据库文件查看sensor_history表的数据。如果第 3 步查询不到记录常见原因是refreshTable()使用的连接和插入使用的连接不是同一个或者QSqlQueryModel::setQuery没有传入连接。这里建议整个项目都用DatabaseManager::connection()返回同一个连接名下的连接对象。4. 把项目推到真实场景线程写入、WAL、事务与可视化4.1 数据表结构设计要贴合上位机业务最小项目里只有一张sensor_history表真实上位机还需要更多表。按业务可以分成三类采集数据表设备 ID、时间戳、通道号、数值、状态位。配置表设备参数、通信参数、界面配置。事件日志表上电、断电、告警、升级、用户操作。配置表可以用通用的键值对结构CREATE TABLE IF NOT EXISTS device_config ( key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP );采集表则需要在时间和设备维度上建立索引CREATE INDEX IF NOT EXISTS idx_sensor_history_device_time ON sensor_history(device_id, created_at);索引不是越多越好。采集表如果高频写入过多索引会拖慢插入速度。一般建议只给查询最频繁的组合建索引比如device_id created_at。如果数据量很大可以考虑按月分表例如sensor_history_202504通过程序动态拼接表名避免单表数据膨胀。4.2 批量写入一定要用事务上位机接收串口或网络数据时往往不是每秒一条而是一帧数据里有多个通道的数值。如果每一条都执行一次单独的INSERT数据库每次都要做事务提交和磁盘同步写入性能会明显下降。更合理的做法是把一个批次的数据放到一个事务里批量提交。示例思路如下void DataWriter::appendRecords(const QListQVariantMap records) { QSqlDatabase db DatabaseManager::connection(); db.transaction(); QSqlQuery query(db); query.prepare( INSERT INTO sensor_history(device_id, sensor_name, value, unit) VALUES (?, ?, ?, ?) ); for (const auto record : records) { query.addBindValue(record.value(device_id).toString()); query.addBindValue(record.value(sensor_name).toString()); query.addBindValue(record.value(value).toDouble()); query.addBindValue(record.value(unit).toString()); if (!query.exec()) { qWarning() Batch insert failed: query.lastError().text(); db.rollback(); return; } } if (!db.commit()) { qWarning() Commit failed: db.lastError().text(); } }事务能显著减少磁盘写入次数但也要控制批次大小。批次太小比如只有 2 条就提交性能提升不明显批次太大比如几千条一次提交事务执行期间可能长时间占用写锁导致其他查询阻塞。常见做法是每 100 到 500 条提交一次或者每 1 秒提交一次具体要结合实际采集频率测试。4.3 WAL 模式和 busy_timeoutSQLite 默认的日志模式是DELETE读写会互相阻塞。上位机界面显示和历史数据写入往往同时发生长时间阻塞会让界面表格卡住。开启 WALWrite-Ahead Logging模式后读操作和写操作可以并发执行写操作之间仍然串行但整体体验会好很多。在数据库初始化之后可以执行以下 PRAGMAQSqlQuery pragma(db); pragma.exec(PRAGMA journal_modeWAL); pragma.exec(PRAGMA synchronousNORMAL); pragma.exec(PRAGMA busy_timeout5000);这些参数的含义和推荐值如下参数默认值推荐值影响journal_modeDELETEWALWAL 提升读写并发能力但会产生 -wal 文件synchronousFULL某些平台不同NORMALNORMAL 减小 fsync 频率性能更好FULL 更安全但写慢busy_timeout05000单位毫秒写锁冲突时等待 5 秒而不是立即报 lockedcache_size2000 页视数据量调整越大能缓存越多页但占用内存更多配置完 WAL 后数据库目录下会出现.db-wal和.db-shm文件这是正常的。程序正常关闭后WAL 文件会被合并回主数据库文件。如果程序异常退出下次打开 SQLite 会自动恢复。发布软件时不要只拷贝.db文件而忽略-wal文件否则可能损失最近写入的数据。4.4 采集线程和 UI 线程如何协作上位机界面必须保持响应所以重的 I/O 操作不能放在 UI 线程。常见做法是串口或网络读取线程负责数据采集信号槽将解析后的数据发给数据库写入线程同时 UI 线程只负责接收刷新信号。这里需要特别强调不要跨线程共享同一个QSqlDatabase连接。SQLite 连接默认与创建线程绑定在另一个线程使用同一个连接是危险的轻则报错重则导致崩溃。推荐的做法是为每个线程创建独立的数据库连接或者把所有数据库写入操作集中到同一个工作线程对象里其他线程通过信号槽发数据给这个线程处理。Qt 的信号槽跨线程传递时如果使用Qt::QueuedConnection槽函数会在线程的事件循环中执行数据库访问只发生在固定线程内。一个简单的写入线程类可以这样设计class DataWriter : public QObject { Q_OBJECT public: explicit DataWriter(QObject *parent nullptr); public slots: void onFrameReady(const QVariantMap data); signals: void writeFinished(bool ok); };在实现里onFrameReady收到的数据统一写入数据库。主线程只需要调用connect(worker, SerialWorker::frameParsed, dataWriter, DataWriter::onFrameReady, Qt::QueuedConnection);注意如果worker和dataWriter都依附于同一个线程信号槽会自动选择直接连接或队列连接如果它们在两个不同线程Qt::QueuedConnection能保证槽函数不影响发送方线程。4.5 用曲线和表格展示历史数据采集到的数据除了写入 SQLite还需要在界面上实时展示。Qt Charts 模块可以很方便地绘制折线图。下面是一个从数据库读取最近 1000 个点并显示到QLineSeries的示例#include QtCharts/QChart #include QtCharts/QChartView #include QtCharts/QLineSeries void MainWindow::updateChart(const QString deviceId) { QLineSeries *series new QLineSeries(); QSqlDatabase db DatabaseManager::connection(); QSqlQuery query(db); query.prepare( SELECT strftime(%s, created_at) * 1000 AS ts, value FROM sensor_history WHERE device_id ? ORDER BY id DESC LIMIT 1000 ); query.addBindValue(deviceId); if (!query.exec()) { qWarning() Query chart data failed: query.lastError().text(); return; } while (query.next()) { qint64 ts query.value(0).toLongLong(); double value query.value(1).toDouble(); series-append(ts, value); } // 注意查询用 ORDER BY id DESC曲线点会逆序需要反转后再显示 // 更稳妥的方式是先取出按时间正序的数据 }这里有个很容易踩的坑为了显示“最近 1000 条”如果直接ORDER BY id DESC LIMIT 1000查出来的点是倒序的。绘制曲线之前要么把series里的点反转要么先按id DESC取出临时列表再反转要么使用子查询SELECT ts, value FROM ( SELECT strftime(%s, created_at) * 1000 AS ts, value FROM sensor_history WHERE device_id ? ORDER BY id DESC LIMIT 1000 ) ORDER BY ts ASC;时间戳建议存成自增 ID 之外的时间字段如果created_at是字符串格式绘制曲线时需要用strftime转成 epoch 毫秒或者在建表时额外存一个timestamp_ms INTEGER字段避免每次查询都做转换。5. 常见问题排查驱动、锁库、卡顿和数据丢失5.1 QSQLITE driver not loaded这是一个非常高频的问题尤其在程序从开发机拷贝到另一台电脑时更容易出现。问题现象常见原因检查方式处理建议控制台或日志出现QSQLITE driver not loadedQt 安装时未包含 SQL 模块或发布时缺少sqldrivers/qsqlite.dll用QSqlDatabase::drivers()查看驱动列表重新安装 Qt 勾选 Sql 模块发布时用windeployqt并确保插件目录完整同一份代码在开发机正常发布到新电脑报错目标机器缺少 Qt 运行时 DLL 或插件路径错误检查程序目录下是否有Qt6Sql.dll、qsqlite.dll把Qt6Sql.dll、Qt6Core.dll和sqldrivers插件目录一起拷贝Linux 下报错系统缺少 Qt SQLite 插件包执行ldd查看动态库依赖安装对应的 Qt SQL 插件包或调整QT_PLUGIN_PATH排查时不要先怀疑代码先确认插件目录。在 Qt 安装目录里找到plugins/sqldrivers/qsqlite.dll把它复制到可执行文件同级目录下的sqldrivers目录中。如果程序是 Qt 6 编译的不要混入 Qt 5 的插件。5.2 database is lockeddatabase is locked是 SQLite 最常让人困惑的错误。它并不一定是数据库文件只读也可能是并发写入冲突。一个典型错误日志QSqlQuery::exec: database is locked Unable to execute statement: database is locked可能原因和解决方式多个数据库连接同时写同一个文件确保写入线程只有一个或者启用 WAL 并设置busy_timeout。事务没有正常结束transaction()后commit()或rollback()必须成对出现如果程序在事务中异常返回连接可能一直持有锁。查询对象在事务中间还持有结果集让QSqlQuery的生命周期在commit()前结束尤其是QSqlQueryModel还在绑定查询结果时。外部程序如 DB Browser for SQLite占用数据库文件使用外部工具查看数据库时它可能处于写入状态关闭后重试。排查顺序建议检查日志中是否出现未提交事务的提示。在代码里全局搜索beginTransaction或transaction(确认是否存在没有commit的分支。给数据库连接设置PRAGMA busy_timeout5000观察是否从报错变成延迟等待。开启 WAL 模式降低读写互斥概率。注意SQLite 的锁是文件级锁不是行级锁。多个写者同时提交时后提交的会等待或报错。用 WAL 只能让读和写并发不能让多个写者同时写同一个文件。5.3 界面卡顿或采集数据丢失界面卡顿最常见的原因是 UI 线程做了耗时操作。比如在串口接收槽里直接执行数据库插入或者把大量的曲线刷新和数据库查询放在同一个事件循环里。解决方法是把采集、写入、查询移动到独立线程UI 线程只通过信号槽接收刷新通知。数据丢失的原因通常集中在三个地方程序退出前没有把缓存队列中的数据写入数据库。写入线程失败后只打印日志没有重试或落盘到错误文件。数据库文件路径使用临时目录系统清理后数据消失。检查退出逻辑时至少要在关闭事件里保证写入线程执行一次 flushvoid MainWindow::closeEvent(QCloseEvent *event) { // 通知写入线程停止接收新数据并处理剩余队列 emit shutdownWriter(); // 根据情况等待线程结束或超时 QThread::msleep(200); event-accept(); }5.4 数据插入后查询不到新记录如果插入成功但表格查询不到先确认以下几点查询使用的数据库连接和插入使用的是否同一个连接名。QSqlQueryModel::setQuery是否传入了连接对象如果没有会使用默认连接而默认连接可能没有打开。事务是否已经提交如果插入代码没有调用commit()数据只存在于事务中。数据库文件路径是否一致有的程序插入和查询用了两个不同路径的数据库文件。建议把数据库路径在启动时打印一次qInfo() Database file: dbPath;这样排查路径问题会很快。6. 工程化建议路径、备份、日志、打包6.1 数据库文件路径别写死开发时很多人习惯把数据库文件放在exe同级目录例如C:/MyApp/data.db。这个路径在开发机上没问题但部署到生产环境时程序目录可能没有写权限或者 Windows 会进行虚拟化重定向导致数据写入看不见的位置。推荐使用 Qt 提供的标准路径#include QStandardPaths #include QDir QString getDefaultDbPath() { QString baseDir QStandardPaths::writableLocation(QStandardPaths::AppDataLocation); QDir().mkpath(baseDir); return baseDir /device_data.db; }AppDataLocation在不同平台会映射到不同的用户数据目录比如 Windows 下的C:/Users/user/AppData/Roaming/appLinux 下的~/.local/share/app。如果管理员希望数据跟随程序安装目录也可以把路径做成配置项允许通过配置文件或启动参数覆盖。6.2 定期备份和归档SQLite 的数据文件如果长期不清理会越来越大查询速度也会下降。生产环境建议做两件事定期备份和定期归档。备份可以使用 SQLite 的在线备份接口也可以在程序空闲时执行VACUUM INTO 备份文件路径把当前数据库的一致性快照写到另一个文件。如果不写代码可以借助sqlite3命令行工具在系统计划任务里执行备份。备份频率取决于数据重要程度一般每天备份一次足够。历史数据清理可以用定时 SQL 完成DELETE FROM sensor_history WHERE created_at datetime(now, -90 days);执行后如果文件仍然占用很大空间可以在维护时段执行VACUUM;VACUUM会重建数据库文件压缩空闲空间但执行期间会锁定数据库不能在生产采集时频繁执行。6.3 日志和异常处理上位机长期运行在工控机上无法时刻盯着界面。数据库异常、通信异常都应该写日志而不是只弹出一个QMessageBox。可以安装一个全局消息处理函数#include QLoggingCategory #include QMutex #include QFile #include QTextStream void messageHandler(QtMsgType type, const QMessageLogContext context, const QString msg) { QMutexLocker locker(logMutex); QFile outFile(logFilePath); if (outFile.open(QIODevice::WriteOnly | QIODevice::Append)) { QTextStream ts(outFile); ts QDateTime::currentDateTime().toString(Qt::ISODate) [ type ] msg \n; } }生产环境还要考虑日志文件轮换避免单个日志文件无限增长。最简单的方式是启动时检查日志文件大小超过 10MB 就重命名为带时间的旧日志再新建一个日志文件。6.4 打包和发布Qt 程序发布时需要把依赖的动态库和插件一起带上。Windows 下可以使用官方工具windeployqtwindeployqt EmbeddedHostApp.exe这条命令会自动复制 Qt 相关的 DLL 和插件但有时候不会完整复制 SQLite 插件需要手动确认sqldrivers/qsqlite.dll存在。更稳妥的方式是使用 CMake 的安装规则install(TARGETS EmbeddedHostApp BUNDLE DESTINATION . RUNTIME DESTINATION bin ) install(DIRECTORY ${Qt6_DIR}/../../../plugins/sqldrivers DESTINATION bin FILES_MATCHING PATTERN *.dll )发布前检查清单如下检查项说明可执行文件是否编译为 Release 模式Qt 运行时库是否包含Qt6Core.dll、Qt6Gui.dll、Qt6Widgets.dll、Qt6Sql.dll等SQLite 插件sqldrivers/qsqlite.dll是否在程序目录下网络/串口模块如果用到Qt6SerialPort.dll、Qt6Network.dll也要复制数据库文件目录目标机器是否有写权限日志目录是否可写是否需要自动创建杀毒软件或白名单产线电脑可能限制写入路径需要提前沟通Linux 下发布可以使用linuxdeployqt或 AppImage 打包工具但要注意目标机器上的 libc 版本和依赖库。嵌入式 Linux 工控机如果系统镜像精简还需要额外确认libEGL、libGLES等图形依赖是否存在。7. 从最小闭环到可维护项目开发顺序和扩展方向如果第一次接触 C Qt 上位机建议不要一上来就同时做串口协议解析、多线程、数据库、曲线和打包。比较合理的顺序是先完成 Qt Widgets 工程跑通 SQLite 驱动和数据库建表。用按钮模拟一条数据写入再用QSqlQueryModel显示出来。增加定时器模拟周期性采集数据验证批量写入和事务。接入真实串口或网络的帧解析用信号槽把数据送到写入线程和 UI。加入图表显示、配置表、事件日志和生产环境的备份、打包。每一步的验证重点不同。第 1 步重点确认环境第 2 步确认 SQL 语句和连接第 3 步确认事务和性能第 4 步确认线程模型第 5 步才进入完整项目形态。这样遇到问题时定位范围会小很多。扩展方向上这个项目可以继续加入 Modbus RTU/TCP、CAN、日志导出 CSV、Excel 报表、远程升级 bootloader 等功能。SQLite 在其中仍然是基础因为不管是设备台账、配置项还是上报记录都需要一个能查询、能备份、能长期保存的本地数据库。建议后续学习中重点研究 Qt SerialPort、QModbus、QThread、QSqlTableModel 和 Qt Charts 这几个模块的组合使用方式它们是嵌入式上位机项目里最常见的拼图。 
长河君 · 2026/9/1 7:02:03 · 阅读 1.2k Qt上位机开发：嵌入式数据存储与SQLite应用实践
在嵌入式设备的联调、测试、产线和售后阶段上位机几乎是一个绕不开的工程角色。很多嵌入式项目并不需要复杂的云端平台而是需要一台运行在 Windows 或 Linux 上的 PC 软件通过串口、USB、TCP/UDP 与下位机通信完成参数下发、状态显示、数据记录和本地存储。C Qt 是这个领域里很常用的一套跨平台框架而 SQLite 则承担了本地数据持久化的工作。下面围绕一个由 Qt 编写的嵌入式上位机项目重点说明为什么把 SQLite 作为必备技术以及如何把 Qt 界面、通信线程、数据库写入和查询组成一条完整可运行的链路。1. 先理解上位机、下位机和 SQLite 的各自分工1.1 上位机到底解决什么问题下位机通常是单片机、PLC、嵌入式板卡负责采集传感器、控制执行器。它的特点是资源受限屏幕小、内存小、算力有限不适合做复杂的人机交互。但嵌入式项目又离不开现场调试、参数标定、数据记录和离线分析这时候就需要一台 PC 程序来承担这些任务这就是上位机。上位机并不是一个万能平台它的核心价值是把下位机回传的原始数据转换成可视化信息并把配置参数可靠地下发给下位机。一个典型场景是设备联调下位机通过串口或网络持续上报温度、压力、转速等数据上位机实时显示曲线并保存到本地数据库方便后续追溯和统计分析。另一个典型场景是产线标定上位机通过界面输入 PID 参数打包成协议帧下发给下位机写入 EEPROM 或 Flash。这两个场景都依赖稳定的通信、清晰的数据结构和可靠的数据存储。1.2 为什么 Qt 适合做上位机开发在 C 技术栈里Qt 是跨平台 GUI 开发的高频选择。它不只是一套控件库还提供了网络、串口、SQL、多线程、JSON/XML 解析、图表、OpenGL 等模块基本能把上位机的常见需求覆盖掉。Qt 的几个特性在嵌入式上位机场景中非常关键信号槽机制让 UI 事件、通信数据到达、定时器、数据库操作之间的联动更清晰。跨平台能力让同一套代码可以在 Windows、Linux、部分国产操作系统上运行适合工控机和产线设备。Qt SQL 模块内置 SQLite 驱动不需要额外安装数据库服务部署成本低。QThread、QtConcurrent 等并发工具可以处理采集线程和 UI 线程之间的协作。配套的 Qt Creator、qmake/CMake、windeployqt 等工具让开发和发布流程完整。有人会对比 C# 上位机。C# 在 Windows 生态下开发效率很高但离开 Windows 之后会遇到运行时和 UI 框架的移植问题。Qt 的优势在于跨平台和 C 性能劣势是 UI 快速开发不如 C# 在某些场景下高效。实际选型时只要项目有跨平台、长时间稳定运行、协议栈和底层硬件交互较多的要求Qt 就是合理的候选方案。1.3 SQLite 在上位机中的定位SQLite 是一个内嵌式关系数据库不需要独立的数据库服务进程直接把数据写入一个普通文件。它非常适合单机软件因为它安装简单、数据文件方便备份、SQL 查询能力完整。Qt 里通过QSqlDatabase加QSQLITE驱动即可访问属于默认支持范围。上位机数据存储场景通常包括设备参数、实时采集数据、告警事件、操作日志。如果用文本日志保存查询某一天的曲线数据会非常麻烦如果用 Excel 或 CSV 文件并发写入和格式管理都不可控。SQLite 的价值在于用标准的 SQL 语法完成插入、查询、聚合、去重和删除同时把数据收敛在一个文件里。选择 SQLite 而不是 MySQL、PostgreSQL主要原因是上位机通常运行在单机或者少数几台电脑上不需要网络数据库服务。数据库服务会引入安装、账号、端口、防火墙等额外维护成本对产线和售后场景不友好。SQLite 虽然也有并发写入上限但通过 WAL 模式和合理的业务隔离完全能应对常见的采集频率和操作量。存储方案是否需要服务并发能力查询能力部署复杂度典型场景SQLite不需要文件型中低多个读单写较稳定支持标准 SQL聚合、索引、事务低直接随应用部署单机上位机、本地历史数据、配置存储CSV/文本不需要低无事务保证基本不支持复杂查询极低简单导出、临时记录MySQL/PostgreSQL需要独立服务高强高需要安装维护多机数据汇总、服务端应用这里要注意不要把 SQLite 当成高并发数据库。如果多个上位机同时写同一个数据库文件或者采集频率非常高且每次都单独执行事务就会出现锁冲突。后续章节会专门讲如何用 WAL、busy_timeout和批量写入来缓解。2. 环境准备把 Qt、编译器和 SQLite 驱动的链路先确认好2.1 选择 Qt 版本和编译器Qt 的版本选择会直接影响后面的代码写法和插件目录结构。Qt 5.15 是目前很多存量项目还在使用的版本因为它对老编译器兼容好、资料多。Qt 6.5 LTS 则是新项目更推荐的选择它移除了部分旧模块对 C17 要求更明确Charts 模块改由单独维护的模块提供。可以先按场景做一个简化判断场景推荐版本编译器说明学习、新项目、跨平台Qt 6.5 LTS 或更高MSVC 2019/2022Linux 下用 GCC 9长期维护官方文档更聚焦 Qt 6维护老项目Qt 5.15根据原项目编译链保持避免升级引发大量接口变更Windows 下的快速验证Qt 6.x MinGWMinGW 11.2安装简单但发布时要注意运行时库安装 Qt 时需要注意在线安装器里先选择对应版本的 Widgets、Sql、Charts、Network、SerialPort 等模块。如果勾选时漏掉 Sql 模块后面会出现 SQLite 驱动加载失败。实践中宁可多选几个常用模块也不要等编译时报错再回头重装。2.2 创建 Qt Widgets 工程这里推荐使用 CMake 作为构建方式因为 CMake 对跨平台、命令行构建和 CI 集成更友好。Qt Creator 也可以直接生成工程但 CMake 文件更容易在团队中统一。一个最小工程的 CMakeLists.txt 如下cmake_minimum_required(VERSION 3.16) project(EmbeddedHostApp VERSION 0.1 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) find_package(Qt6 REQUIRED COMPONENTS Widgets Sql Charts) qt_add_executable(EmbeddedHostApp main.cpp MainWindow.cpp MainWindow.h DatabaseManager.cpp DatabaseManager.h ) target_link_libraries(EmbeddedHostApp PRIVATE Qt6::Widgets Qt6::Sql Qt6::Charts )代码里的关键点是find_package中的Sql和Charts组件。Qt6::Sql是数据库操作模块Qt6::Charts用于曲线显示。如果当前工程不需要曲线可以暂时去掉 Charts避免多引入依赖。使用 Qt 5 时组件名和库名类似但要确保编译器和 Qt 版本一致。2.3 验证 SQLite 驱动是否可用Qt 操作 SQLite 并不需要单独安装 SQLite 开发包因为 Qt 官方已经把 SQLite 驱动编译成插件。但在某些 Linux 发行版或自定义 Qt 安装中插件可能缺失。启动程序后如果在控制台看到类似下面这样的一行说明驱动加载可能有问题QSqlDatabase: QSQLITE driver not loaded出现这个报错时第一步是先打印当前可用的驱动列表#include QSqlDatabase #include QDebug void printAvailableDrivers() { const QStringList drivers QSqlDatabase::drivers(); qDebug() Available SQL drivers: drivers; }正常输出里应该包含QSQLITE。如果没有需要检查 Qt 安装时是否勾选了 Sql 模块以及程序运行时能否找到 Qt 的sqldrivers插件目录。Windows 下发布时常见的错误是只拷贝了Qt6Sql.dll却没有把plugins/sqldrivers/qsqlite.dll拷贝到程序同级的sqldrivers目录。Linux 下则要留意 Qt 插件的安装路径是否在QT_PLUGIN_PATH中。注意不要只验证程序能够启动还要用QSqlDatabase::drivers()确认 SQLite 驱动真实存在否则数据库操作会一直停留在“打不开数据库”的阶段。3. 用一个最小上位机项目跑通“采集-存储-查询”闭环3.1 项目结构和模块划分这个最小项目不需要写真实的串口解析先用“手动填写传感器数据点击保存列表查询显示”来跑通 Qt 和 SQLite 的完整链路。等这条链路没有问题后再把采集来源替换成串口或网络即可。推荐的项目结构如下EmbeddedHostApp/ ├── CMakeLists.txt ├── main.cpp ├── MainWindow.h ├── MainWindow.cpp ├── DatabaseManager.h ├── DatabaseManager.cpp └── resources/DatabaseManager专门负责数据库初始化、连接管理和建表MainWindow负责 UI 交互和展示。这样把数据库访问和界面代码分开后续换数据库或加业务逻辑时不至于把 main.cpp 写得很长。3.2 数据库初始化和建表先定义DatabaseManager的头文件// DatabaseManager.h #pragma once #include QSqlDatabase #include QString class DatabaseManager { public: static bool init(const QString dbPath); static QSqlDatabase connection(); };实现文件里先打开数据库再执行建表语句// DatabaseManager.cpp #include DatabaseManager.h #include QSqlQuery #include QSqlError #include QDir #include QDebug static QString s_dbPath; bool DatabaseManager::init(const QString dbPath) { s_dbPath dbPath; // 如果目标目录不存在先创建目录 QDir dir QFileInfo(dbPath).absoluteDir(); if (!dir.exists()) { dir.mkpath(.); } // Qt 6 中默认连接名可以直接使用 QSqlDatabase db QSqlDatabase::contains(host_conn) ? QSqlDatabase::database(host_conn) : QSqlDatabase::addDatabase(QSQLITE, host_conn); db.setDatabaseName(dbPath); if (!db.open()) { qCritical() Open database failed: db.lastError().text(); return false; } QSqlQuery query(db); bool ok query.exec( CREATE TABLE IF NOT EXISTS sensor_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_id TEXT NOT NULL, sensor_name TEXT NOT NULL, value REAL NOT NULL, unit TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ); if (!ok) { qCritical() Create table failed: query.lastError().text(); return false; } return true; } QSqlDatabase DatabaseManager::connection() { return QSqlDatabase::database(host_conn); }这里用QSqlDatabase::contains(host_conn)避免重复创建同名的数据库连接。实际项目中如果多线程访问数据库建议按线程创建独立连接而不是所有线程共享同一个连接后面会说明原因。3.3 主界面布局和手动插入一条记录在MainWindow构造函数里布局 UI至少需要这几个控件设备 ID 输入框类型QLineEdit传感器名称下拉框类型QComboBox数值输入框类型QDoubleSpinBox单位输入框类型QLineEdit保存按钮类型QPushButton表格视图类型QTableView界面代码可以直接用 Qt Creator 生成也可以手写。这里以手动添加核心控件的方式展示// MainWindow.cpp 片段 MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , m_deviceIdEdit(new QLineEdit(device_001, this)) , m_sensorNameCombo(new QComboBox(this)) , m_valueSpin(new QDoubleSpinBox(this)) , m_unitEdit(new QLineEdit(℃, this)) , m_saveButton(new QPushButton(写入数据库, this)) , m_tableView(new QTableView(this)) { m_sensorNameCombo-addItems({温度, 压力, 转速, 电压}); // 布局演示时使用两个水平布局拼接 auto *controlLayout new QHBoxLayout; controlLayout-addWidget(new QLabel(设备ID:, this)); controlLayout-addWidget(m_deviceIdEdit); controlLayout-addWidget(new QLabel(传感器:, this)); controlLayout-addWidget(m_sensorNameCombo); controlLayout-addWidget(new QLabel(数值:, this)); controlLayout-addWidget(m_valueSpin); controlLayout-addWidget(new QLabel(单位:, this)); controlLayout-addWidget(m_unitEdit); controlLayout-addWidget(m_saveButton); auto *central new QWidget(this); auto *mainLayout new QVBoxLayout(central); mainLayout-addLayout(controlLayout); mainLayout-addWidget(m_tableView); setCentralWidget(central); connect(m_saveButton, QPushButton::clicked, this, MainWindow::onSaveRecord); refreshTable(); }保存按钮对应的槽函数如下void MainWindow::onSaveRecord() { QSqlDatabase db DatabaseManager::connection(); QSqlQuery query(db); query.prepare( INSERT INTO sensor_history(device_id, sensor_name, value, unit) VALUES (?, ?, ?, ?) ); query.addBindValue(m_deviceIdEdit-text().trimmed()); query.addBindValue(m_sensorNameCombo-currentText()); query.addBindValue(m_valueSpin-value()); query.addBindValue(m_unitEdit-text().trimmed()); if (!query.exec()) { qWarning() Insert failed: query.lastError().text(); return; } refreshTable(); }这里使用prepare加addBindValue而不是直接拼接 SQL 字符串。原因是传感器名称、设备 ID 都可能是外部输入直接拼接可能会出现 SQL 转义问题和安全风险。Qt 的预处理参数绑定可以避免这个问题。3.4 查询和刷新逻辑用QSqlQueryModel把查询结果直接显示到表格里。刷新函数如下void MainWindow::refreshTable() { m_model new QSqlQueryModel(this); m_model-setQuery( SELECT device_id AS 设备ID, sensor_name AS 传感器, value AS 数值, unit AS 单位, created_at AS 记录时间 FROM sensor_history ORDER BY id DESC LIMIT 200, DatabaseManager::connection() ); m_tableView-setModel(m_model); m_tableView-resizeColumnsToContents(); }QSqlQueryModel适合只读展示不需要自己实现QAbstractTableModel代码量小。如果后续需要编辑、排序、自定义单元格颜色再替换成QSqlTableModel或自定义模型。这里还要注意每次刷新都创建一个新模型并setModel旧模型会被 Qt 的父子对象机制释放不需要手动 delete但频繁刷新时最好不要在槽函数里用局部模型指针。3.5 运行验证运行程序后按照下面的步骤验证最小闭环填写设备 ID、选择传感器名称、输入数值和单位。点击“写入数据库”按钮。表格区域立即出现一条新记录。关闭程序再次打开表格中依然有刚才插入的记录。用 DB Browser for SQLite 打开数据库文件查看sensor_history表的数据。如果第 3 步查询不到记录常见原因是refreshTable()使用的连接和插入使用的连接不是同一个或者QSqlQueryModel::setQuery没有传入连接。这里建议整个项目都用DatabaseManager::connection()返回同一个连接名下的连接对象。4. 把项目推到真实场景线程写入、WAL、事务与可视化4.1 数据表结构设计要贴合上位机业务最小项目里只有一张sensor_history表真实上位机还需要更多表。按业务可以分成三类采集数据表设备 ID、时间戳、通道号、数值、状态位。配置表设备参数、通信参数、界面配置。事件日志表上电、断电、告警、升级、用户操作。配置表可以用通用的键值对结构CREATE TABLE IF NOT EXISTS device_config ( key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP );采集表则需要在时间和设备维度上建立索引CREATE INDEX IF NOT EXISTS idx_sensor_history_device_time ON sensor_history(device_id, created_at);索引不是越多越好。采集表如果高频写入过多索引会拖慢插入速度。一般建议只给查询最频繁的组合建索引比如device_id created_at。如果数据量很大可以考虑按月分表例如sensor_history_202504通过程序动态拼接表名避免单表数据膨胀。4.2 批量写入一定要用事务上位机接收串口或网络数据时往往不是每秒一条而是一帧数据里有多个通道的数值。如果每一条都执行一次单独的INSERT数据库每次都要做事务提交和磁盘同步写入性能会明显下降。更合理的做法是把一个批次的数据放到一个事务里批量提交。示例思路如下void DataWriter::appendRecords(const QListQVariantMap records) { QSqlDatabase db DatabaseManager::connection(); db.transaction(); QSqlQuery query(db); query.prepare( INSERT INTO sensor_history(device_id, sensor_name, value, unit) VALUES (?, ?, ?, ?) ); for (const auto record : records) { query.addBindValue(record.value(device_id).toString()); query.addBindValue(record.value(sensor_name).toString()); query.addBindValue(record.value(value).toDouble()); query.addBindValue(record.value(unit).toString()); if (!query.exec()) { qWarning() Batch insert failed: query.lastError().text(); db.rollback(); return; } } if (!db.commit()) { qWarning() Commit failed: db.lastError().text(); } }事务能显著减少磁盘写入次数但也要控制批次大小。批次太小比如只有 2 条就提交性能提升不明显批次太大比如几千条一次提交事务执行期间可能长时间占用写锁导致其他查询阻塞。常见做法是每 100 到 500 条提交一次或者每 1 秒提交一次具体要结合实际采集频率测试。4.3 WAL 模式和 busy_timeoutSQLite 默认的日志模式是DELETE读写会互相阻塞。上位机界面显示和历史数据写入往往同时发生长时间阻塞会让界面表格卡住。开启 WALWrite-Ahead Logging模式后读操作和写操作可以并发执行写操作之间仍然串行但整体体验会好很多。在数据库初始化之后可以执行以下 PRAGMAQSqlQuery pragma(db); pragma.exec(PRAGMA journal_modeWAL); pragma.exec(PRAGMA synchronousNORMAL); pragma.exec(PRAGMA busy_timeout5000);这些参数的含义和推荐值如下参数默认值推荐值影响journal_modeDELETEWALWAL 提升读写并发能力但会产生 -wal 文件synchronousFULL某些平台不同NORMALNORMAL 减小 fsync 频率性能更好FULL 更安全但写慢busy_timeout05000单位毫秒写锁冲突时等待 5 秒而不是立即报 lockedcache_size2000 页视数据量调整越大能缓存越多页但占用内存更多配置完 WAL 后数据库目录下会出现.db-wal和.db-shm文件这是正常的。程序正常关闭后WAL 文件会被合并回主数据库文件。如果程序异常退出下次打开 SQLite 会自动恢复。发布软件时不要只拷贝.db文件而忽略-wal文件否则可能损失最近写入的数据。4.4 采集线程和 UI 线程如何协作上位机界面必须保持响应所以重的 I/O 操作不能放在 UI 线程。常见做法是串口或网络读取线程负责数据采集信号槽将解析后的数据发给数据库写入线程同时 UI 线程只负责接收刷新信号。这里需要特别强调不要跨线程共享同一个QSqlDatabase连接。SQLite 连接默认与创建线程绑定在另一个线程使用同一个连接是危险的轻则报错重则导致崩溃。推荐的做法是为每个线程创建独立的数据库连接或者把所有数据库写入操作集中到同一个工作线程对象里其他线程通过信号槽发数据给这个线程处理。Qt 的信号槽跨线程传递时如果使用Qt::QueuedConnection槽函数会在线程的事件循环中执行数据库访问只发生在固定线程内。一个简单的写入线程类可以这样设计class DataWriter : public QObject { Q_OBJECT public: explicit DataWriter(QObject *parent nullptr); public slots: void onFrameReady(const QVariantMap data); signals: void writeFinished(bool ok); };在实现里onFrameReady收到的数据统一写入数据库。主线程只需要调用connect(worker, SerialWorker::frameParsed, dataWriter, DataWriter::onFrameReady, Qt::QueuedConnection);注意如果worker和dataWriter都依附于同一个线程信号槽会自动选择直接连接或队列连接如果它们在两个不同线程Qt::QueuedConnection能保证槽函数不影响发送方线程。4.5 用曲线和表格展示历史数据采集到的数据除了写入 SQLite还需要在界面上实时展示。Qt Charts 模块可以很方便地绘制折线图。下面是一个从数据库读取最近 1000 个点并显示到QLineSeries的示例#include QtCharts/QChart #include QtCharts/QChartView #include QtCharts/QLineSeries void MainWindow::updateChart(const QString deviceId) { QLineSeries *series new QLineSeries(); QSqlDatabase db DatabaseManager::connection(); QSqlQuery query(db); query.prepare( SELECT strftime(%s, created_at) * 1000 AS ts, value FROM sensor_history WHERE device_id ? ORDER BY id DESC LIMIT 1000 ); query.addBindValue(deviceId); if (!query.exec()) { qWarning() Query chart data failed: query.lastError().text(); return; } while (query.next()) { qint64 ts query.value(0).toLongLong(); double value query.value(1).toDouble(); series-append(ts, value); } // 注意查询用 ORDER BY id DESC曲线点会逆序需要反转后再显示 // 更稳妥的方式是先取出按时间正序的数据 }这里有个很容易踩的坑为了显示“最近 1000 条”如果直接ORDER BY id DESC LIMIT 1000查出来的点是倒序的。绘制曲线之前要么把series里的点反转要么先按id DESC取出临时列表再反转要么使用子查询SELECT ts, value FROM ( SELECT strftime(%s, created_at) * 1000 AS ts, value FROM sensor_history WHERE device_id ? ORDER BY id DESC LIMIT 1000 ) ORDER BY ts ASC;时间戳建议存成自增 ID 之外的时间字段如果created_at是字符串格式绘制曲线时需要用strftime转成 epoch 毫秒或者在建表时额外存一个timestamp_ms INTEGER字段避免每次查询都做转换。5. 常见问题排查驱动、锁库、卡顿和数据丢失5.1 QSQLITE driver not loaded这是一个非常高频的问题尤其在程序从开发机拷贝到另一台电脑时更容易出现。问题现象常见原因检查方式处理建议控制台或日志出现QSQLITE driver not loadedQt 安装时未包含 SQL 模块或发布时缺少sqldrivers/qsqlite.dll用QSqlDatabase::drivers()查看驱动列表重新安装 Qt 勾选 Sql 模块发布时用windeployqt并确保插件目录完整同一份代码在开发机正常发布到新电脑报错目标机器缺少 Qt 运行时 DLL 或插件路径错误检查程序目录下是否有Qt6Sql.dll、qsqlite.dll把Qt6Sql.dll、Qt6Core.dll和sqldrivers插件目录一起拷贝Linux 下报错系统缺少 Qt SQLite 插件包执行ldd查看动态库依赖安装对应的 Qt SQL 插件包或调整QT_PLUGIN_PATH排查时不要先怀疑代码先确认插件目录。在 Qt 安装目录里找到plugins/sqldrivers/qsqlite.dll把它复制到可执行文件同级目录下的sqldrivers目录中。如果程序是 Qt 6 编译的不要混入 Qt 5 的插件。5.2 database is lockeddatabase is locked是 SQLite 最常让人困惑的错误。它并不一定是数据库文件只读也可能是并发写入冲突。一个典型错误日志QSqlQuery::exec: database is locked Unable to execute statement: database is locked可能原因和解决方式多个数据库连接同时写同一个文件确保写入线程只有一个或者启用 WAL 并设置busy_timeout。事务没有正常结束transaction()后commit()或rollback()必须成对出现如果程序在事务中异常返回连接可能一直持有锁。查询对象在事务中间还持有结果集让QSqlQuery的生命周期在commit()前结束尤其是QSqlQueryModel还在绑定查询结果时。外部程序如 DB Browser for SQLite占用数据库文件使用外部工具查看数据库时它可能处于写入状态关闭后重试。排查顺序建议检查日志中是否出现未提交事务的提示。在代码里全局搜索beginTransaction或transaction(确认是否存在没有commit的分支。给数据库连接设置PRAGMA busy_timeout5000观察是否从报错变成延迟等待。开启 WAL 模式降低读写互斥概率。注意SQLite 的锁是文件级锁不是行级锁。多个写者同时提交时后提交的会等待或报错。用 WAL 只能让读和写并发不能让多个写者同时写同一个文件。5.3 界面卡顿或采集数据丢失界面卡顿最常见的原因是 UI 线程做了耗时操作。比如在串口接收槽里直接执行数据库插入或者把大量的曲线刷新和数据库查询放在同一个事件循环里。解决方法是把采集、写入、查询移动到独立线程UI 线程只通过信号槽接收刷新通知。数据丢失的原因通常集中在三个地方程序退出前没有把缓存队列中的数据写入数据库。写入线程失败后只打印日志没有重试或落盘到错误文件。数据库文件路径使用临时目录系统清理后数据消失。检查退出逻辑时至少要在关闭事件里保证写入线程执行一次 flushvoid MainWindow::closeEvent(QCloseEvent *event) { // 通知写入线程停止接收新数据并处理剩余队列 emit shutdownWriter(); // 根据情况等待线程结束或超时 QThread::msleep(200); event-accept(); }5.4 数据插入后查询不到新记录如果插入成功但表格查询不到先确认以下几点查询使用的数据库连接和插入使用的是否同一个连接名。QSqlQueryModel::setQuery是否传入了连接对象如果没有会使用默认连接而默认连接可能没有打开。事务是否已经提交如果插入代码没有调用commit()数据只存在于事务中。数据库文件路径是否一致有的程序插入和查询用了两个不同路径的数据库文件。建议把数据库路径在启动时打印一次qInfo() Database file: dbPath;这样排查路径问题会很快。6. 工程化建议路径、备份、日志、打包6.1 数据库文件路径别写死开发时很多人习惯把数据库文件放在exe同级目录例如C:/MyApp/data.db。这个路径在开发机上没问题但部署到生产环境时程序目录可能没有写权限或者 Windows 会进行虚拟化重定向导致数据写入看不见的位置。推荐使用 Qt 提供的标准路径#include QStandardPaths #include QDir QString getDefaultDbPath() { QString baseDir QStandardPaths::writableLocation(QStandardPaths::AppDataLocation); QDir().mkpath(baseDir); return baseDir /device_data.db; }AppDataLocation在不同平台会映射到不同的用户数据目录比如 Windows 下的C:/Users/user/AppData/Roaming/appLinux 下的~/.local/share/app。如果管理员希望数据跟随程序安装目录也可以把路径做成配置项允许通过配置文件或启动参数覆盖。6.2 定期备份和归档SQLite 的数据文件如果长期不清理会越来越大查询速度也会下降。生产环境建议做两件事定期备份和定期归档。备份可以使用 SQLite 的在线备份接口也可以在程序空闲时执行VACUUM INTO 备份文件路径把当前数据库的一致性快照写到另一个文件。如果不写代码可以借助sqlite3命令行工具在系统计划任务里执行备份。备份频率取决于数据重要程度一般每天备份一次足够。历史数据清理可以用定时 SQL 完成DELETE FROM sensor_history WHERE created_at datetime(now, -90 days);执行后如果文件仍然占用很大空间可以在维护时段执行VACUUM;VACUUM会重建数据库文件压缩空闲空间但执行期间会锁定数据库不能在生产采集时频繁执行。6.3 日志和异常处理上位机长期运行在工控机上无法时刻盯着界面。数据库异常、通信异常都应该写日志而不是只弹出一个QMessageBox。可以安装一个全局消息处理函数#include QLoggingCategory #include QMutex #include QFile #include QTextStream void messageHandler(QtMsgType type, const QMessageLogContext context, const QString msg) { QMutexLocker locker(logMutex); QFile outFile(logFilePath); if (outFile.open(QIODevice::WriteOnly | QIODevice::Append)) { QTextStream ts(outFile); ts QDateTime::currentDateTime().toString(Qt::ISODate) [ type ] msg \n; } }生产环境还要考虑日志文件轮换避免单个日志文件无限增长。最简单的方式是启动时检查日志文件大小超过 10MB 就重命名为带时间的旧日志再新建一个日志文件。6.4 打包和发布Qt 程序发布时需要把依赖的动态库和插件一起带上。Windows 下可以使用官方工具windeployqtwindeployqt EmbeddedHostApp.exe这条命令会自动复制 Qt 相关的 DLL 和插件但有时候不会完整复制 SQLite 插件需要手动确认sqldrivers/qsqlite.dll存在。更稳妥的方式是使用 CMake 的安装规则install(TARGETS EmbeddedHostApp BUNDLE DESTINATION . RUNTIME DESTINATION bin ) install(DIRECTORY ${Qt6_DIR}/../../../plugins/sqldrivers DESTINATION bin FILES_MATCHING PATTERN *.dll )发布前检查清单如下检查项说明可执行文件是否编译为 Release 模式Qt 运行时库是否包含Qt6Core.dll、Qt6Gui.dll、Qt6Widgets.dll、Qt6Sql.dll等SQLite 插件sqldrivers/qsqlite.dll是否在程序目录下网络/串口模块如果用到Qt6SerialPort.dll、Qt6Network.dll也要复制数据库文件目录目标机器是否有写权限日志目录是否可写是否需要自动创建杀毒软件或白名单产线电脑可能限制写入路径需要提前沟通Linux 下发布可以使用linuxdeployqt或 AppImage 打包工具但要注意目标机器上的 libc 版本和依赖库。嵌入式 Linux 工控机如果系统镜像精简还需要额外确认libEGL、libGLES等图形依赖是否存在。7. 从最小闭环到可维护项目开发顺序和扩展方向如果第一次接触 C Qt 上位机建议不要一上来就同时做串口协议解析、多线程、数据库、曲线和打包。比较合理的顺序是先完成 Qt Widgets 工程跑通 SQLite 驱动和数据库建表。用按钮模拟一条数据写入再用QSqlQueryModel显示出来。增加定时器模拟周期性采集数据验证批量写入和事务。接入真实串口或网络的帧解析用信号槽把数据送到写入线程和 UI。加入图表显示、配置表、事件日志和生产环境的备份、打包。每一步的验证重点不同。第 1 步重点确认环境第 2 步确认 SQL 语句和连接第 3 步确认事务和性能第 4 步确认线程模型第 5 步才进入完整项目形态。这样遇到问题时定位范围会小很多。扩展方向上这个项目可以继续加入 Modbus RTU/TCP、CAN、日志导出 CSV、Excel 报表、远程升级 bootloader 等功能。SQLite 在其中仍然是基础因为不管是设备台账、配置项还是上报记录都需要一个能查询、能备份、能长期保存的本地数据库。建议后续学习中重点研究 Qt SerialPort、QModbus、QThread、QSqlTableModel 和 Qt Charts 这几个模块的组合使用方式它们是嵌入式上位机项目里最常见的拼图。