Lovefield 性能监控 Dashboard：本地运行与 Cordova Android 打包部署指南

• 关系型数据库
• 数据库
• 前端

导读

Lovefield 是一个用 JavaScript 编写、可跨浏览器运行的 Web 关系型数据库，提供快速、安全、易用的 SQL 风格 API。本文面向希望运行并部署 Lovefield 官方性能监控面板（dashboard）的开发者：它既是一个观察 Lovefield 各基准测试（benchmark）执行耗时与趋势的可视化面板，也是一个展示"Angular 前端 + Lovefield 本地存储 + D3 图表 + 远程数据同步"完整架构的实战样例。读完本文，你将掌握从零搭建本地调试环境、理解其数据模型与同步机制，以及使用 Cordova 将面板打包为 Android 原生应用的完整流程。

该 dashboard 位于仓库的 tools/dashboard 目录，其核心使命是：定期从远程服务器拉取 Lovefield 各基准测试（如全表扫描 SCUD、基于主键的 SCUD、Select 基准、场景模拟、外键基准等）的执行耗时数据，写入本地 Lovefield 数据库，并通过 D3 绘制"每日几何平均耗时"和各测试套件的趋势曲线，用于长期追踪 Lovefield 的性能回归。

一、环境准备与本地运行（完整步骤）

README（tools/dashboard/README.md）给出的本地运行流程共 6 步，下面逐条展开并补充每一步的作用说明：

1. 安装 gulp（若尚未安装）

   npm install -g gulp

   gulp 是项目的构建与本地服务器工具。当前仓库使用的 gulp 为 3.x（见 tools/dashboard/package.json 中"gulp": "^3.9.0"），全局安装后即可在任意目录调用gulp命令。

2. 安装 bower（若尚未安装）

   npm install -g bower

   bower 用于拉取浏览器端依赖。dashboard 的 bower 依赖声明在 tools/dashboard/bower.json 中，包括：

   • angular（^1.4.7）：前端 MVVM 框架，用于控制器与视图绑定；
   • bootstrap（^3.3.5）：页面样式；
   • lovefield（lovefield#master）：本仓库核心，即 Lovefield 数据库本体；
   • promise-polyfill（^2.1.0）：为不支持原生 Promise 的旧浏览器提供补丁。

3. 拉取 npm 依赖

   npm install .

   这会安装 tools/dashboard/package.json 中声明的构建与运行时工具依赖，包括：

   • cordova（^5.3.3）：用于后续 Android 打包；
   • d3（^3.5.5）：负责图表绘制；
   • gulp-gjslint：JS 风格检查；
   • gulp-webserver：本地 Web 服务器；
   • fs-extra、nopt：文件拷贝与命令行参数解析。

4. 拉取 bower 依赖

   bower install

   将上表所列浏览器端库安装到bower_components目录。

5. 启动本地 Web 服务器

   gulp debug

   默认端口为 8000。如需更换端口，可显式指定，例如：

   gulp debug --port=9000

6. 浏览器访问面板

   http://localhost:8000/www/src/dashboard.html

   若在第 5 步更换了端口，请同步修改 URL 中的端口号。

1.1gulp debug背后发生了什么

从 tools/dashboard/gulpfile.js 的源码可以看到，debug任务并非单纯起一个静态服务器，它先依赖copy_dependencies任务，把bower_components与node_modules中的运行库拷贝到www/lib目录：

gulp.task('copy_dependencies', function() { var filesToCopy = [ 'bower_components/angular/angular.min.js', 'bower_components/lovefield/dist/lovefield.min.js', 'bower_components/promise-polyfill/Promise.min.js', 'node_modules/d3/d3.min.js', 'bower_components/bootstrap/dist/css/bootstrap.min.css' ]; // ... 逐个拷贝到 www/lib });

随后再以gulp-webserver启动服务（开启directoryListing、默认端口 8000，端口号通过nopt解析--port参数）。也就是说，页面入口 tools/dashboard/www/src/dashboard.html 中引用的../lib/angular.min.js、../lib/lovefield.min.js、../lib/d3.min.js、../lib/Promise.min.js等脚本，正是由这一步准备好的。

1.2 其他可用的 gulp 任务

在 dashboard 目录下运行gulp（不带参数）会打印任务帮助信息，共四个任务：

二、面板目录结构与技术架构

2.1 前端模块一览

面板前端全部位于tools/dashboard/www/src/，各文件的职责在源码注释中都有明确说明：

2.2 依赖关系（三份配置文件）

• npm 依赖（构建期）：gulp、gulp-webserver、cordova、d3、nopt、fs-extra、gulp-gjslint，见 tools/dashboard/package.json；
• bower 依赖（运行期）：angular、bootstrap、lovefield、promise-polyfill，见 tools/dashboard/bower.json；
• Cordova 配置：com.google.lovefield（应用名LfPerf），见 tools/dashboard/config.xml。

三、数据模型与同步机制（源码级剖析）

3.1 两张核心表：TestCase 与 PerfData

面板的数据库模式定义在 tools/dashboard/www/src/lovefield_service.js 的buildSchema_方法中，数据库名为dashboard，当前 schema 版本为 2：

• TestCase 表：id（INTEGER，主键）、testSuiteName（STRING）、testCaseName（STRING），并对(testSuiteName, testCaseName)建了唯一索引uq_suitCase，用于保证"套件 + 用例"组合唯一；
• PerfData 表：testCaseId（INTEGER，外键引用TestCase.id）、date（DATE_TIME）、execTime（NUMBER），对(testCaseId, date)建唯一索引uq_caseIdDate，外键fk_testCaseId使用RESTRICT动作与IMMEDIATE时序——即不允许删除仍被 PerfData 引用的 TestCase 记录。

连接数据库时（getDbConnection）还做了一次环境适配：在 Safari 下（UA 含 "Safari" 且不含 "Chrome"）使用lf.schema.DataStoreType.MEMORY（内存存储），其余浏览器使用INDEXED_DB（IndexedDB 持久化），并开启了enableInspector: true以便调试。若 schema 版本变化，onUpgradeDb_会通过底层 raw transaction 清空两张表，避免旧数据与新结构不兼容。

3.2 同步流程：从服务器到本地 Lovefield

SyncService（sync_service.js）的init_是完整的数据管道：

1. 通过getLastSyncDate()查询本地 PerfData 中date列的最大值（使用lf.fn.max聚合函数）；
2. 将上次同步日期交给NetworkDataFetcher（data_fetcher.js）：
   • 若从未同步过（lastSyncDate == null），请求参数为{'name': [testSuite], 'days': 14}，拉取最近 14 天数据；
   • 否则请求参数为{'name': [testSuite], 'since': 'YYYYMMDD'}，只拉增量；
3. 抓取到的数据是"每个测试套件一张表、首行是测试用例名"的表格结构，parsePerfDataForTestSuite_将其展开为{testCaseId, date, execTime}行；
4. processRawData_为每个测试用例分配/复用整数 ID：已存在的用例查询TestCase.id，新出现的用例从当前最大 ID 递增分配；
5. 最后通过LovefieldService.insertData将新用例与性能数据写入数据库。写库时使用db.createTransaction()创建事务，一次性exec([q1, q2])保证 TestCase 与 PerfData 两个插入操作原子完成（lovefield_service.js）。

3.3 数据读取与图表绘制

• 每日几何平均：getGeoMeanData()对PerfData按date分组，用lf.fn.geomean(execTime)计算当日所有用例执行耗时的几何平均，按日期倒序返回；
• 单条用例趋势：getTestCaseDataByName(testSuite, testCase)先按套件名 + 用例名查到 ID，再执行预编译的查询（testCaseId.eq(lf.bind(0))、按日期倒序、limit(14)，即最多最近 14 条记录）；
• 套件列表：getTestSuiteList()用lf.fn.distinct(testSuiteName)去重后按名升序返回；
• 增量刷新：whenLastSyncDateChanged()用db.observe(query, callback)注册观察器，当MAX(date)查询结果变化时自动触发重绘——这也是控制器中"新数据到达即重画"机制的来源（dashboard_controller.js）。

图表的曲线清单是硬编码的（服务器暂不提供动态获取接口），见 views.js。例如Full_table_SCUD套件包含"Select/Insert/Update/Delete × 10000~50000"共 16 条曲线；SelectBenchmark则覆盖带谓词的单行/多行查询、投影、排序、连接与聚合等场景；ForeignKeysBenchmark对比"无外键 / IMMEDIATE / DEFERRABLE"三种约束模式下的插入、更新、删除耗时。每个图可含多条曲线，绘制由 graph_plotter.js 的Curve与GraphPlotter完成，数据点按 X 轴（日期）升序排序以便鼠标悬停时二分查找。

四、使用 Cordova 打包为 Android 应用

README 同时提供了将面板打包为 Android 应用（基于 Cordova 5.3.3）的完整流程，共 3 步。

1. 添加 Android 平台

   ./node_modules/cordova/bin/cordova platform add android

   使用项目本地安装的 cordova 命令（npm install .已将其装进node_modules）。此步要求本机已安装 Android SDK 并正确配置环境变量。

2. 构建应用

   ./node_modules/cordova/bin/cordova build android

   编译产物默认输出到platforms/android/build/outputs/apk/android-debug.apk。

3. 安装到 Android 设备先连接 Android 设备（或启动模拟器），确认 adb 能识别设备：

   adb devices

   再安装 APK：

   adb install -r platforms/android/build/outputs/apk/android-debug.apk

   其中-r表示允许覆盖已存在的同名应用。

4.1 Cordova 配置解读

config.xml 中与打包直接相关的配置项：

4.2 Android 端运行要点

从 main.js 的源码注释可以看出一个已知注意点：作者原本设计在 Cordova 的deviceready事件触发后再初始化 Angular 应用，但实际该事件并未如期触发，因此当前代码直接显式调用app.onDeviceReady()，以保证在 Web 与 Android 两种环境下都能完成初始化。若在真机调试时遇到页面空白，可优先检查这一点，并配合enableInspector: true的数据库连接选项进行排查。

此外，Android WebView 基于 Chromium，不会命中代码中的 Safari 分支，因此将使用INDEXED_DB存储类型，性能数据会持久化在应用本地，后续打开应用会基于本地数据先渲染、再增量同步。

五、常见问题与调试建议

• 页面 404 或脚本加载失败：确认已先执行gulp debug（它内部会执行copy_dependencies填充www/lib）；若手动清理过www/lib，重新执行gulp debug即可恢复。
• 首次打开没有任何数据：属正常现象。dashboard_controller.js的drawGeoMean_对空结果直接返回，控制器会在数据库连接就绪后通过SyncService.init()触发首次服务器同步，之后面板自动重绘。同步依赖网络，需保证设备可访问数据服务地址（见data_fetcher.js中的请求模板）。
• 想看不同端口的调试服务：使用gulp debug --port=<number>，端口号由 gulpfile.js 中的nopt解析，默认 8000。
• 部署为静态站点：执行gulp export会得到包含全部运行期依赖的dist/目录，可直接交由任意静态服务器托管。

六、小结

Lovefield 性能监控 dashboard 是一个麻雀虽小五脏俱全的示例工程：它以 Lovefield 自身为存储引擎，演示了建库建表、索引与外键约束、参数化查询、聚合函数（geomean/max/distinct）、事务写入、观察器自动刷新等核心 API 的真实用法；同时又展示了gulp构建链路与 Cordova Android 打包的完整落地流程。无论是想快速验证 Lovefield 的性能表现，还是把该面板当作"Web 数据库应用 + 移动端打包"的参考实现，都可以按本文步骤在本仓库中直接复现。

如需深入研究其数据流与查询实现，建议对照阅读 tools/dashboard/www/src/lovefield_service.js（数据层）、tools/dashboard/www/src/sync_service.js（同步编排）与 tools/dashboard/www/src/views.js（图表配置），再结合仓库中 testing/perf 下的各基准测试代码理解数据来源。

• 关系型数据库
• 数据库
• 前端