journeyapps/powersync-diagnostics-app

Sync Diagnostics Client

镜像概述和主要用途

Sync Diagnostics Client是一个从特定用户视角展示数据的工具（无服务器端统计），主要用于：查看用户本地数据库统计信息、检查设备上的表和同步桶、无需创建应用即可快速使用SQLite数据库，以及在遇到问题时作为基准比较自有应用。该应用目前可通过[***]访问，也可作为本地独立Web应用运行，主要基于web SDK构建。

核心功能和特性

• 数据库统计：展示用户本地数据库的详细信息。
• 检测到的表：仅包含有同步数据的表（同步行数为0的表不会显示）。
• 同步桶：仅包含有同步数据的桶；同步大量数据时，总操作数从检查点计算，会快速填充，其他统计信息会在数据下载时填充，可能需要一段时间。
• SQL控制台：与其他演示应用功能相同，支持SQL查询操作。
• 动态模式[内部]：某些功能需要模式，模式会从下载的数据中动态生成并自动更新，使用的模式会在单独页面显示；若表同步行数为0，则不会出现在模式中，引用该表的查询将失败；表和列仅会添加到模式中，从同步规则中移除时不会自动删除，需通过主页面的“清除并重新下载”按钮刷新模式。

使用场景和适用范围

• 开发调试：快速查看本地数据库状态和同步情况。
• 本地数据库检查：无需开发应用即可查看SQLite数据库内容。
• 应用问题排查：作为基准工具，对比自有应用与标准情况的差异。
• 同步数据验证：检查同步桶和表的同步状态及数据量。

使用方法和配置说明

使用Docker运行应用

sh
docker run --pull always -p 8082:80 journeyapps/powersync-diagnostics-app

应用将在 http://localhost:8082 可用。

本地运行应用

在仓库根目录运行：

sh
pnpm install
pnpm build:packages

然后在当前目录运行：

sh
pnpm dev

应用将在 http://localhost:5173/ 可用。

登录

以用户身份登录需要PowerSync Token（JWT）和Endpoint。

PowerSync Token

为用户生成开发令牌。

PowerSync Endpoint

• 对于PowerSync开发令牌，Endpoint会自动填充。
• 对于其他JWT（如Supabase令牌），需手动输入。
• 对于PowerSync Cloud，Endpoint是实例URL。
• 对于自托管设置（在Docker中运行PowerSync服务），返回的实例URL是Docker网络内部的，外部无法访问；由于诊断应用在Docker外部运行，可连接到docker-proxy暴露的Endpoint，例如 http://localhost:8080。

已知问题

现阶段，建议打开开发控制台运行应用，因为部分错误当前未在UI中显示。其他已知问题：

• 在多个标签页中打开应用可能导致问题。
• 同步大量数据时，主仪表板可能会变慢。