连接 Dolt 服务器

Beadbox 可以连接运行中的 Dolt SQL 服务器，在你通过 CLI 使用的 beads 数据库之上实现多用户写入和团队协作。

需要 Beadbox 0.9.12+ 在 Settings > About 中或前往以下地址检查版本 /api/version.

前提条件

开始之前，你需要以下三个组件正在运行：

组件最低版本检查方式
beads CLI (bd)0.56.x+bd --version
Dolt 服务器运行中并接受连接dolt sql-server 在你的项目中
Beadbox0.9.12+Settings > About

你的 Dolt 服务器必须至少有一个遵循 beads_ 命名规范的数据库。这是 beads 在 Dolt 模式下运行 bd init 时创建的。Beadbox 使用这个前缀来发现 beads 数据库并忽略无关数据库。

快速开始（本地，无认证）

最快路径：在本机运行 Dolt 服务器，不配置认证。

1. 启动 Dolt 服务器

cd ~/Projects/myproject
dolt sql-server

Dolt 默认监听端口 3307。

2. 打开 Beadbox

在工作区选择器中，点击 通过服务器添加（如果是首次启动，在欢迎页面找到 Advanced 卡片）。

3. 输入连接信息

Host127.0.0.1 （已预填）
Port3307 （已预填）
Userroot （已预填）
Password留空
TLS未勾选

4. 点击 "Discover Databases"

Beadbox 连接服务器并运行 SHOW DATABASES，查找所有匹配 beads_* 模式的数据库。

5. 选择数据库

发现界面列出服务器上找到的所有 beads 数据库。勾选你要添加为工作区的数据库，每个数据库会分配一个本地目录路径。

6. 点击 "Add Workspaces"

Beadbox 创建本地 .beads/ 目录，其中的 metadata.json 指向你的服务器，注册工作区并打开它。

连接成功。通过 bd 在 CLI 中做的更改，或其他团队成员写入同一 Dolt 服务器的更改，将在几秒内出现在 Beadbox 中（服务器模式以 1 秒间隔轮询变更）。

使用认证连接

如果你的 Dolt 服务器需要用户名和密码：

  1. 按快速开始的步骤操作，但在 User 和 Password 字段中填入你的 Dolt 服务器凭据。
  2. 如果需要 TLS（远程服务器常见），勾选 Use TLS 复选框。
  3. 点击 Discover Databases 并继续发现流程。

密码处理方式

  • 密码仅保存在内存中。Beadbox 不会将密码写入磁盘。
  • Beadbox 重启后密码会丢失。为避免每次启动都重新输入，请在 shell 配置文件中设置 BEADS_DOLT_PASSWORD（参见 持久化密码）。
  • 在底层，Beadbox 每次调用子进程时通过 BEADS_DOLT_PASSWORD 环境变量将密码传递给 bd CLI。

Hosted Dolt 和远程服务器

对于运行在远程机器、云虚拟机或 Hosted Dolt 上的 Dolt 服务器：

  1. Host：输入服务器的主机名或 IP 地址。
  2. Port：使用提供商指定的端口。Hosted Dolt 通常使用 3306。
  3. User/Password：输入提供商给你的凭据。
  4. TLS：勾选 "Use TLS"（Hosted Dolt 必须，任何远程连接都建议勾选）。
  5. 点击 Discover Databases，按正常流程操作。

持久化密码

Beadbox 仅在内存中保存密码，重启后会丢失。对于需要认证的服务器（本地或远程），你可以在 shell 配置文件中设置密码来跳过每次输入：

export BEADS_DOLT_PASSWORD="your-password-here"

Beadbox 会自动为所有服务器模式的工作区读取此变量。如果同时设置了 UI 密码字段和环境变量，UI 字段优先。

工作原理

添加服务器工作区时，Beadbox 执行三个操作：

1. 写入连接元数据

在本地项目目录中创建 .beads/metadata.json，包含服务器连接信息：

{
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 3307,
  "dolt_database": "beads_myproject",
  "dolt_server_user": "root",
  "database": "dolt"
}

启用 TLS 时，会添加 "dolt_server_tls": true 键。这个文件告诉 bd 连接远程服务器而非使用本地嵌入数据库。密码不会出现在此文件中。

2. 注册工作区

将本地目录添加到 ~/.beads/registry.json，以便 Beadbox 和 bd 在后续启动时能找到它。

3. 在运行时传递凭据

每次 Beadbox 为此工作区调用 bd 命令时，都会在子进程环境中设置 BEADS_DOLT_PASSWORD。密码仅存在于进程内存中。

故障排查

连接被拒绝

Error: connect ECONNREFUSED 127.0.0.1:3307
  • Dolt 是否在运行？ 用 ps aux | grep dolt 检查，或在项目目录中尝试 dolt sql-server。
  • 端口是否正确？ Dolt 默认端口为 3307，但你可能配置了不同的端口。
  • 防火墙？ 在远程服务器上，确保端口对入站连接开放。

访问被拒绝

Error: Access denied for user 'root'
  • 需要密码？ 你的 Dolt 服务器可能启用了认证。在连接表单中输入密码。
  • 用户名错误？ 验证用户名是否匹配具有读取权限的 Dolt 用户。
  • 密码错误？ 密码不会在会话之间保存。重启 Beadbox 后需要重新输入。

TLS 握手失败

Error: TLS handshake failed
  • TLS 复选框不匹配。 如果服务器要求 TLS，勾选 "Use TLS"。如果不支持 TLS，取消勾选。任一方向的错误都会导致握手失败。
  • 自签名证书。 如果你的 Dolt 服务器使用自签名证书，可能需要将 CA 添加到系统信任存储。bd CLI 使用系统根 CA 池，会拒绝不受信任的证书。

未找到数据库

No beads databases found on 127.0.0.1:3307.
Databases must follow the beads_* naming pattern.
  • 命名规范。 Beadbox 只发现名称以 beads_ 开头的数据库。如果你的数据库使用了其他名称，请重命名或在 Dolt 模式下用 bd init 创建新的。
  • 数据库存在但不可见？ 该用户账号可能没有查看所有数据库的权限。
  • 全新的服务器？ 如果你刚启动 Dolt 但还没有初始化 beads，则不存在 beads 数据库。在配置了 Dolt 模式的项目目录中运行 bd init，然后重试发现。