连接 Dolt 服务器

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

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

前提条件

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

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

你的 Dolt 服务器必须至少有一个由 bd init 创建的数据库。Beadbox 会发现服务器上的所有用户数据库（information_schema 等系统数据库会被排除）。

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

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

1. 启动 Dolt 服务器

cd ~/Projects/myproject
bd dolt start

bd 会使用操作系统分配的端口启动 Dolt，并将端口存储在 .beads/dolt-server.port 中。该端口会打印在终端输出中。如果你直接运行 dolt sql-server，默认端口为 3307。

2. 打开 Beadbox

在工作区选择器中，点击使用现有工作区（如果是首次启动，在欢迎页面找到 Advanced 卡片）。

Tip: 或者，点击 <strong>扫描服务器</strong> 自动检测本地运行的 Dolt 服务器。如果检测到你的服务器，Beadbox 会自动填入主机和端口。

3. 输入连接信息

Host	`127.0.0.1` （已预填）
Port	查看 bd dolt start 的终端输出，或查看 .beads/dolt-server.port 文件
User	`root` （已预填）
Password	留空
TLS	未勾选

4. 点击 "Discover Databases"

Beadbox 连接服务器并运行 SHOW DATABASES，查找所有用户数据库。

5. 选择数据库

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

6. 点击 "Add Workspaces"

如果你有包含 .beads/ 的本地项目目录，Beadbox 会更新其 metadata.json 写入服务器连接信息。如果你连接的是没有本地项目的远程服务器，Beadbox 会在 ~/.beadbox/servers/ 创建一个存根工作区及其 metadata.json。无论哪种情况，工作区都会被注册并立即打开。

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

使用认证连接

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

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

密码处理方式

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

Hosted Dolt 和远程服务器

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

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

持久化密码

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

export BEADS_DOLT_PASSWORD="your-password-here"

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

工作原理

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

1. 写入连接元数据

写入 .beads/metadata.json 包含服务器连接信息。对于本地项目，此文件位于项目目录中。对于仅服务器连接（无本地项目），此文件位于 ~/.beadbox/servers/。

{
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 13842,
  "dolt_database": "myproject",
  "dolt_server_user": "root",
  "database": "dolt"
}

启用 TLS 时，会添加 "dolt_server_tls": true 键。这个文件告诉 bd 连接指定的远程服务器，而不是自动启动本地服务器。密码不会出现在此文件中。

2. 注册工作区

将工作区添加到 ~/.beadbox/registry.json，以便 Beadbox 和 bd 在后续启动时能找到它。

3. 在运行时传递凭据

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

故障排查

连接被拒绝

Error: connect ECONNREFUSED 127.0.0.1:<port>

Dolt 是否在运行？用 ps aux | grep dolt 检查，或在项目目录中尝试 dolt sql-server。
端口是否正确？如果你通过 bd dolt start 启动 Dolt，端口会存储在 .beads/dolt-server.port 中。查看该文件获取当前值。直接运行 dolt sql-server 默认端口为 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 databases found on 127.0.0.1:<port>.
Verify the Dolt server has at least one database created with bd init.

命名规范。请确认至少在一个项目目录中运行过 bd init。数据库应该出现在 Dolt 服务器的 SHOW DATABASES 中。
数据库存在但不可见？该用户账号可能没有查看所有数据库的权限。
全新的服务器？如果你刚启动 Dolt 但还没有初始化 beads，则不存在 beads 数据库。在项目目录中运行 bd init，然后重试发现。