ghcr.io/ladybugdb/explorer:0.17.0

Ladybug Explorer

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

Get started

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

远程（SSH）模式

SSH模式使用sshfs将远程目录挂载到运行Ladybug Explorer的机器上，并直接从挂载点打开数据库。更改会实时写入远程机器。

运行Ladybug Explorer的机器上的sshfs要求：

Linux

sshfs sudo apt install sshfs sudo dnf install fuse-sshfs /dev/fuse sshpass sudo apt install sshpass sudo dnf install sshpass

macOS

macOS默认不包含FUSE支持。请先安装macFUSE，然后在系统设置→隐私与安全性中允许其内核扩展（可能需要重启）。在Apple Silicon上，可能还需要禁用SIP——请参阅macFUSE常见问题。

brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac # sshfs
brew install hudochenkov/sshpass/sshpass # only needed for password auth

私钥认证在任何平台上都不需要sshpass。

远程机器上的要求：

只需SSH守护进程（sshd）。不需要其他软件。

通过Docker运行时，授予容器对FUSE的访问权限：

docker run -p 8000:8000 \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--rm lbugdb/explorer:latest

容器镜像中还必须包含sshfs以及（如果使用密码认证）sshpass。

您也可以在不指定现有数据库的情况下启动Ladybug Explorer。Ladybug Explorer附带了捆绑数据集，您可以使用这些数据集探索Ladybug的基本功能。只需删除上述示例中的-v标志即可实现。如果未使用-v指定数据库路径，服务器将使用空数据库启动。

docker run -p 8000:8000 --rm ghcr.io/ladybugdb/explorer:latest

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

其他启动配置

访问模式

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

docker run -p 8000:8000 \
-v {path to the directory containing the database file}:/database \
-e LBUG_FILE={database file name} \
-e MODE=READ_ONLY \
--rm ghcr.io/ladybugdb/explorer:latest

在只读模式下，您仍然可以执行读查询并可视化结果，但不能运行写查询或修改架构。

缓冲池大小

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

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

docker run -p 8000:8000 \
-v {path to the directory containing the database file}:/database \
-e LBUG_FILE={database file name} \
-e LBUG_BUFFER_POOL_SIZE=1073741824 \
--rm ghcr.io/ladybugdb/explorer:latest

内存模式

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

docker run -p 8000:8000 \
-e LBUG_IN_MEMORY=true \
--rm ghcr.io/ladybugdb/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 ghcr.io/ladybugdb/explorer:latest

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

开发构建版

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

docker run -p 8000:8000 \
-v {path to the directory containing the database file}:/database \
-e LBUG_FILE={database file name} \
--rm ghcr.io/ladybugdb/explorer:dev

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

更新Ladybug Explorer

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

docker pull ghcr.io/ladybugdb/explorer:latest

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

使用Podman启动

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

例如：

podman run -p 8000:8000 \
-v {path to the directory containing the database file}:/database:U \
-e LBUG_FILE={database file name} \
--rm ghcr.io/ladybugdb/explorer:latest

或者，

podman run -p 8000:8000 \
-v {path to the directory containing the database file}:/database \
-e LBUG_FILE={database file name} \
--userns=keep-id \
--rm ghcr.io/ladybugdb/explorer:latest

运行时切换数据库

侧边栏中的DB菜单允许您在不重启服务器的情况下切换活动数据库。支持三种模式：

• 文件型 — 打开本地文件系统上的数据库文件
• 内存型 — 临时数据库；重启时所有数据丢失
• 远程（SSH） — 通过SSH从远程机器挂载数据库

远程（SSH）模式

SSH模式使用sshfs将远程目录挂载到运行Ladybug Explorer的机器上，并直接从挂载点打开数据库。更改会实时写入远程机器。

运行Ladybug Explorer的机器要求：

Linux

macOS

macOS默认不包含FUSE支持。请先安装https://osxfuse.github.io/%EF%BC%8C%E7%84%B6%E5%90%8E%E5%9C%A8**%E7%B3%BB%E7%BB%9F%E8%AE%BE%E7%BD%AE → 隐私与安全性**中允许其内核扩展（可能需要重启）。在Apple Silicon上，可能还需要禁用SIP — 请参阅https://github.com/osxfuse/osxfuse/wiki/FAQ%E3%80%82

brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac # sshfs
brew install hudochenkov/sshpass/sshpass # 仅密码认证时需要

私钥认证在任何平台上都不需要sshpass。

远程机器要求：

只需SSH守护进程（sshd）。不需要其他软件。

通过Docker运行时，授予容器对FUSE的访问权限：

docker run -p 8000:8000 \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--rm lbugdb/explorer:latest

容器镜像中还必须包含 sshfs 以及（如果使用密码认证）sshpass。

文档

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

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

技术栈

• 服务端
• Node.js
• Express.js
• Ladybug
• 客户端
• Vue 3
• Bootstrap 5
• https://microsoft.github.io/monaco-editor/
• https://github.com/antvis/G6

前提条件

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

环境设置

安装 Node.js 依赖

npm i

安装 Ladybug 原生绑定

@ladybugdb/core 依赖项通过其 npm 安装脚本和可选平台包为您的平台安装原生模块。

生成语法文件

生成的 TypeScript 解析器已签入 src/utils/CypherParser，因此正常开发时无需重新生成。仅当 Ladybug 的 Cypher 语法发生变化时才需要重新生成。

更新语法的步骤：

1. 检出与您要匹配的版本对应的 Ladybug 源代码树。对于版本更新，请使用与 package.json 中 @ladybugdb/core 版本对应的提交或标签。
2. 将 Ladybug 检出内容放在 ./ladybug 目录下。生成器当前会读取 ladybug/scripts/antlr4/keywordhandler.py、ladybug/src/antlr4/Cypher.g4 和 ladybug/src/antlr4/keywords.txt。
3. 运行生成器：

npm run generate-grammar

4. 检查并提交 src/utils/CypherParser 下重新生成的文件。临时的 ladybug 检出目录仅作为生成输入，不应提交。

获取数据集

npm run fetch-datasets

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

env LBUG_DIR={directory containing ladybug database} LBUG_FILE={database file name} npm run serve

使用 ESLint 检查代码风格

npm run eslint

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

npm run eslint-fix

构建并部署生产环境

本地运行生产服务器

npm run build
env LBUG_DIR={directory containing ladybug database} LBUG_FILE={database file name} npm run serve-prod

使用 Docker 运行生产服务器

docker build -t ghcr.io/ladybugdb/explorer:latest .
docker run -p 8000:8000 \
-v {path to the directory containing the database file}:/database \
-e LBUG_FILE={database file name} \
--rm ghcr.io/ladybugdb/explorer:latest

部署

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

贡献

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