ghcr.io/ladybugdb/explorer:0.12.2

Ladybug Explorer

基于浏览器的Ladybug图数据库用户界面。

快速开始

Ladybug Explorer是一个从已部署的Docker镜像启动的Web应用。有关如何安装和使用Docker的详细信息，请参考Docker文档。

下面展示两种不同的Ladybug Explorer启动方式。这两种方式都可通过 http://localhost:8000 访问Ladybug Explorer。如果启动成功，您应该会在终端中看到类似以下的日志：

Access mode: READ_WRITE
Version of Ladybug: v0.12.2
Deployed server started on port: 8000

选项1：使用现有数据库

要访问现有的Ladybug数据库，可按以下方式将其路径挂载到 /database 目录：

docker run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
--rm lbugdb/explorer:latest

通过 -v {包含数据库文件的目录路径} 和 -e LBUG_FILE={数据库文件名} 将本地数据库文件挂载到Docker后，在UI中所做的更改会在UI关闭后持久化到本地数据库文件中。如果挂载了目录但未设置LBUG_FILE环境变量，Ladybug Explorer会在挂载目录中查找名为 database.kz 的文件；如果不存在，则会在挂载目录中创建一个新的 database.kz 数据库文件。

--rm 标志告诉Docker在关闭容器后自动删除该容器。

选项2：使用带示例数据的空数据库启动

您也可以不指定现有数据库而启动Ladybug Explorer。Ladybug Explorer捆绑了数据集，可用于探索Ladybug的基本功能。只需移除上述示例中的 -v 标志即可实现。如果未通过 -v 指定数据库路径，服务器将以空数据库启动。

docker run -p 8000:8000 --rm lbugdb/explorer:latest

点击右上角的 Datasets 选项卡，然后：(i) 从下拉菜单中选择一个捆绑的数据集；(ii) 点击 "Load Dataset" 按钮将其加载到Ladybug中；(iii) 最后使用Ladybug Explorer进行探索。

其他启动配置

访问模式

默认情况下，Ladybug Explorer以读写模式启动，这意味着您可以修改数据库。如果要以只读模式启动Ladybug Explorer，可通过将MODE环境变量设置为 READ_ONLY 实现，如下所示：

docker run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
-e MODE=READ_ONLY \
--rm lbugdb/explorer:latest

在只读模式下，您仍可以执行读查询并可视化结果，但无法运行写查询或修改模式。

缓冲池大小

默认情况下，Ladybug Explorer启动时的最大缓冲池大小为可用内存的80%。如果要使用不同的缓冲池大小启动Ladybug Explorer，可通过将LBUG_BUFFER_POOL_SIZE环境变量设置为所需的字节数实现，如下所示：

例如，要以1GB的缓冲池大小启动Ladybug Explorer，可运行以下命令：

docker run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
-e LBUG_BUFFER_POOL_SIZE=1073741824 \
--rm lbugdb/explorer:latest

内存模式

默认情况下，Ladybug Explorer以磁盘模式启动。如果要以内存模式启动Ladybug Explorer，可通过将LBUG_IN_MEMORY环境变量设置为 true 实现，如下所示：

docker run -p 8000:8000 \
-e LBUG_IN_MEMORY=true \
--rm lbugdb/explorer:latest

在内存模式下，数据库存储在内存中，即使挂载了数据库目录，服务器关闭后所有更改也会丢失。此外，内存模式不支持只读访问模式。

WebAssembly模式

在WebAssembly模式下，Ladybug Explorer使用 @ladybugdb/wasm-core 启动，该核心直接在浏览器中运行所有查询。如果要以WebAssembly模式启动Ladybug Explorer，可通过将LBUG_WASM环境变量设置为 true 实现，如下所示：

docker run -p 8000:8000 \
-e LBUG_WASM=true \
--rm lbugdb/explorer:latest

在WebAssembly模式下，数据库存储在当前浏览器会话中，关闭浏览器标签页或刷新标签页后所有更改都会丢失。WebAssembly模式下会忽略所有其他配置参数。

开发构建版本

如果要使用Ladybug的最新开发构建版本启动Ladybug Explorer，可使用 dev 标签代替 latest：

docker run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
--rm lbugdb/explorer:dev

dev 标签每日更新，大约在Ladybug最新开发构建版本发布后两小时更新。

更新Ladybug Explorer

初始启动后，如果Ladybug Explorer发布了新版本，重新启动容器不会自动将本地镜像更新到最新版本。要将本地镜像更新到最新版本，可运行以下命令：

docker pull lbugdb/explorer:latest

拉取最新镜像后，可使用与之前相同的命令重新启动容器。

使用Podman启动

如果您使用Podman而非Docker，可将上述命令中的 docker 替换为 podman 来启动Ladybug Explorer。但请注意，Podman默认会将默认用户账户映射到容器中的root用户。这在将本地数据库文件挂载到容器时可能导致权限问题。要避免此问题，可使用 --userns=keep-id 标志在容器内保留当前用户的用户ID，或为每个卷启用 :U 选项以将源卷的所有者和组更改为当前用户。

例如：

podman run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database:U \
-e LBUG_FILE={数据库文件名} \
--rm lbugdb/explorer:latest

podman run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
--userns=keep-id \
--rm lbugdb/explorer:latest

有关挂载外部卷和用户命名空间模式的更多信息，请参考官方Podman文档。

文档

有关启动和使用Ladybug Explorer的更多信息，请参考文档。

开发（使用从源代码编译的Ladybug）

技术栈

• 服务端
  • Node.js
  • Express.js
  • Ladybug
• 客户端
  • Vue 3
  • Bootstrap 5
  • Monaco Editor
  • G6

前提条件

• Node.js v20
• JDK 11+
• 用于构建Ladybug的工具链
• Git

环境设置

安装Node.js依赖

npm i

下载并编译Ladybug

git submodule update --init --recursive
npm run build-lbug

生成语法文件

npm run generate-grammar

获取数据集

npm run fetch-datasets

运行开发服务器（带热重载）

env LBUG_DIR={包含Ladybug数据库的目录} LBUG_FILE={数据库文件名} npm run serve

使用ESLint检查代码风格

npm run eslint

添加 -fix 可自动修复可修复的风格问题：

npm run eslint-fix

构建并服务生产版本

本地运行生产服务器

npm run build
env LBUG_DIR={包含Ladybug数据库的目录} LBUG_FILE={数据库文件名} npm run serve-prod

使用Docker运行生产服务器

docker build -t lbugdb/explorer:latest .
docker run -p 8000:8000 \
-v {包含数据库文件的目录路径}:/database \
-e LBUG_FILE={数据库文件名} \
--rm lbugdb/explorer:latest

部署

已配置GitHub Actions流水线，在推送到master分支时自动构建Docker镜像并部署到Docker Hub。流水线将为amd64和arm64平台构建镜像。

贡献

我们欢迎对Ladybug Explorer的贡献。通过贡献到Ladybug Explorer，您同意您的贡献将根据MIT许可证进行许可。