Grafana作为一款流行的可视化工具，默认支持MySQL、PostgreSQL、InfluxDB等主流数据库，但SQLite这种轻量级的嵌入式数据库却不在官方数据源列表里。很多团队的本机日志、传感器采集数据、爬虫结果都存放在SQLite文件中，想要直接接入Grafana做看板时就会卡在第一步。实际上，借助第三方插件完全可以打通这条链路，而且配置过程并不复杂。本文将以实战的方式，把SQLite接入Grafana的每个环节讲透，包括插件安装、数据源配置、SQL编写和图表联动。
一、为什么Grafana不能直接连接SQLite
要理解配置方案，先得明白问题的根源。Grafana的数据源架构是插件化的，官方维护的数据源插件主要面向网络型数据库，它们通过网络协议（TCP连接、HTTP接口）与后端服务通信。而SQLite是嵌入式数据库，整个数据库就是一个本地文件，没有独立的服务进程，也没有监听端口。Grafana服务需要通过网络访问数据源，这种架构上的差异导致官方一直没有提供原生支持。
不过社区给出了很成熟的解决思路：让Grafana以插件的形式直接读取服务器本地的SQLite文件。目前使用最广泛的是frser-sqlite-datasource插件，它本质上是一个带后端的数据源插件，通过Grafana的插件机制直接调用SQLite驱动去查询文件，绕过了网络访问的限制。
需要注意一个前提：插件读取的是Grafana服务器所在机器上的文件路径。如果你的SQLite文件在其他机器上，要么把文件同步过来，要么考虑用定时任务导出数据。这一点在架构设计阶段就要想清楚。
二、安装frser-sqlite-datasource插件
插件安装推荐使用grafana-cli命令行工具。登录到Grafana所在服务器，执行以下命令：
# 使用grafana-cli安装插件 grafana-cli plugins install frser-sqlite-datasource # 安装完成后重启Grafana服务 systemctl restart grafana-server # 如果是Docker部署，在启动参数中加入 docker run -d -p 3000:3000 \ -v /var/lib/grafana/plugins:/var/lib/grafana/plugins \ -e GF_INSTALL_PLUGINS=frser-sqlite-datasource \ grafana/grafana
安装完成后，打开Grafana的Web界面，进入Configuration中的Data Sources页面，点击Add data source按钮。如果列表里出现了SQLite选项，说明插件安装成功。如果看不到这个选项，大概率是插件目录权限问题，可以检查/var/lib/grafana/plugins目录下是否存在frser-sqlite-datasource文件夹，并确保grafana用户对该目录有读取权限。
有些企业内网环境无法访问外网插件仓库，这时可以采用离线安装方式。先在有网的机器上从插件的代码仓库下载发布包，解压后直接放到插件目录，再重启服务即可。离线安装时要特别注意插件版本与Grafana版本的兼容性，版本差异过大可能导致插件加载失败。
三、配置数据源并编写查询
在数据源配置页面，核心要填写的只有两项：Name是数据源显示名称，Database Paths填写SQLite数据库文件的绝对路径，例如/data/sensor/records.db。建议使用绝对路径避免歧义。配置完成后点击Save and Test，出现连接成功提示就可以开始建图表了。
Grafana的时间序列图表对时间字段有格式要求，最理想的情况是表中有一个Unix时间戳字段。假设有一张温度采集表，建表语句如下：
CREATE TABLE temperature (
id INTEGER PRIMARY KEY AUTOINCREMENT,
ts INTEGER NOT NULL, -- Unix时间戳，单位秒
device_name TEXT NOT NULL,
temperature REAL NOT NULL
);
CREATE INDEX idx_ts ON temperature(ts);
编写查询时，Grafana提供了宏来简化时间范围过滤。$__timeFrom()和$__timeTo()会自动替换成当前选择的时间范围，$__time(ts)则把字段标记为时间列。一条典型的查询写法：
SELECT
$__time(ts),
device_name AS metric,
temperature AS value
FROM temperature
WHERE $__timeFilter(ts)
ORDER BY ts ASC;
如果表里的时间是文本格式（比如2024-01-15 08:30:00这样的字符串），可以用strftime函数转换：strftime('%s', time_str)会把文本时间转成Unix时间戳。转换函数会让查询变慢，数据量大时最好提前把时间列改成整数时间戳并建立索引，这是SQLite性能优化中非常实用的一招。
做仪表盘联动时，可以把多个Panel都指向同一个SQLite数据源，配合Grafana的变量功能实现下拉筛选。例如定义一个类型为Query的变量，查询语句写SELECT DISTINCT device_name FROM temperature，然后在Panel的SQL里用WHERE device_name IN ($device)引用变量，就能实现按设备名动态过滤图表数据。
四、常见问题排查与优化建议
配置过程中最容易遇到的几个问题，这里集中说明一下。
第一个是查询没有返回数据。先在Grafana的Query Inspector里查看实际执行的SQL和返回结果，确认时间范围是否覆盖了数据的时间区间。SQLite的$__timeFilter基于Unix秒级时间戳，如果你的时间戳是毫秒级的，需要除以1000，否则时间范围会完全对不上。
第二个是文件锁冲突。SQLite在写入时会对文件加锁，如果采集程序正在高频写入，Grafana的读取可能遇到database is locked错误。解决办法有两种：写入方开启WAL模式（PRAGMA journal_mode=WAL;），让读写可以并发进行；或者开启busy_timeout，让读操作短暂等待而不是立刻失败。
-- 开启WAL模式，允许读写并发 PRAGMA journal_mode=WAL; -- 设置等待超时为5秒 PRAGMA busy_timeout=5000;
第三个是性能问题。SQLite的单机能力虽然不及大型数据库，但配合索引处理千万级数据的聚合查询完全够用。务必给时间字段建索引，聚合查询尽量在SQL里用GROUP BY完成，只把聚合结果返回给Grafana渲染，而不是把原始明细全查出来。对于按小时聚合的场景，可以按ts/3600分组再换算回时间。
最后提醒一点，如果数据更新频率很高，可以在仪表盘的Query options里设置合理的刷新间隔，例如每5分钟自动刷新一次，既能保证数据时效性，又不会给服务器带来过大压力。配置完成后，你就可以像使用MySQL一样，在Grafana里灵活地对SQLite数据做各类可视化分析了。