集群安装

部署 Coordinator 和 Worker,验证分布式查询,再扩展到跨主机和故障接管。

本页目录

1. 准备主机

Coordinator 提供控制台、发布模型,并把符合条件的 HTTP 查询、预览和导出任务派发给 Worker。Bolt 和 Gremlin 驱动会话在 Coordinator 执行。Worker 获取已发布模型并读取来源,因此这两类进程都需要访问对应的数据和凭据。

首次部署可用一台运行 systemd 的 Debian 12 主机,准备监听 127.0.0.1:2379 的 etcd v3 HTTP/JSON 网关。每台主机完成Linux 安装的下载校验和安装服务两节,解包并安装 systemd 单元,再按下文启动集群。所有节点使用相同的 GraphLake 构建。

2. 配置单主机集群

将下方配置保存为 cluster.yaml。示例使用两个回环 Worker 和一个私有的本地存储目录。Coordinator 的工作台端口为 7337,进程状态端口为 7338。

YAML
name: finance-lab
metadata: http://127.0.0.1:2379
storage: /var/lib/graphlake/cluster-data
token_env: GRAPHLAKE_CLUSTER_TOKEN
distributed_partitions: 4
memory_mib: 256
workers:
  - http://127.0.0.1:7441
  - http://127.0.0.1:7442

安装配置,在环境文件中设置 GRAPHLAKE_CLUSTER_TOKEN,值可用 openssl rand -hex 32 生成。Coordinator 与 Worker 使用相同令牌,并从该文件载入模型引用的源凭据变量。

Shell
curl -fsS http://127.0.0.1:2379/health
sudo install -d -m 0750 -o root -g graphlake /etc/graphlake
sudo install -d -m 0700 -o graphlake -g graphlake /var/lib/graphlake/cluster-data
sudo install -m 0640 -o root -g graphlake cluster.yaml /etc/graphlake/cluster.yaml
sudo touch /etc/graphlake/graphlake.env
sudo chown root:root /etc/graphlake/graphlake.env
sudo chmod 0600 /etc/graphlake/graphlake.env
sudoedit /etc/graphlake/graphlake.env

3. 启动 Worker 和 Coordinator

将 Worker 模板保存为 /etc/systemd/system/graphlake-worker@.service。实例名决定回环端口。把来源文件放在示例的 catalog 路径下,或将 --source-dir 改为实际挂载目录。

systemd
[Unit]
Description=GraphLake Worker on port %i
After=network-online.target
Wants=network-online.target

[Service]
User=graphlake
Group=graphlake
EnvironmentFile=/etc/graphlake/graphlake.env
ExecStart=/opt/graphlake/current/bin/graphlake-admin --cluster-config /etc/graphlake/cluster.yaml --port %i worker --source-dir /var/lib/graphlake/catalog
Restart=on-failure
UMask=0077
NoNewPrivileges=yes

[Install]
WantedBy=multi-user.target

执行 systemctl edit graphlake 时填入下方配置。空的 ExecStart= 清除随安装包提供的单机启动命令。

systemd
[Service]
EnvironmentFile=/etc/graphlake/graphlake.env
ExecStart=
ExecStart=/opt/graphlake/current/bin/graphlake-admin --catalog-dir /var/lib/graphlake/catalog --assets-dir /opt/graphlake/current/web --cluster-config /etc/graphlake/cluster.yaml --status-port 7338 --query-slots 3

首次使用的 catalog 需初始化一次管理员密码。若已有管理员,从第二条命令开始。

Shell
sudo -u graphlake /opt/graphlake/current/bin/graphlake-admin \
  --catalog-dir /var/lib/graphlake/catalog auth init
sudo systemctl edit graphlake
sudo systemctl daemon-reload
sudo systemctl enable --now graphlake-worker@7441 graphlake-worker@7442
sudo systemctl enable --now graphlake
curl -fsS http://127.0.0.1:7337/readyz
curl -fsS http://127.0.0.1:7338/status

打开 http://127.0.0.1:7337/,远程访问可用 SSH 隧道。发布模型后,在运行配置 → 健康检查中检查模型,再运行一条结果已知的查询。实际采用分布式阶段的查询会在原始响应的 distributed 字段显示参与 Worker 和阶段数量。小规模探测查询可能只在一个 Worker 上执行。

4. 扩展到多台主机

同步各主机时钟,准备具备多数派的 etcd 集群,以及使用独立前缀的 S3 兼容存储。各节点使用同一份集群配置。为运行账号授予该前缀所需权限,并为来源数据使用只读凭据。Parquet 可放到共享对象存储,也可在所有读取节点挂载同一份文件。

YAML
name: finance
metadata:
  - https://etcd-a.example:2379
  - https://etcd-b.example:2379
  - https://etcd-c.example:2379
storage: s3://graphlake-state/finance
token_env: GRAPHLAKE_CLUSTER_TOKEN
ca_file: /etc/graphlake/tls/cluster-ca.pem
identity_file: /etc/graphlake/tls/client-identity.pem
distributed_partitions: 4
memory_mib: 256
workers:
  - https://worker-a.example:7443
  - https://worker-b.example:7443

替换示例中的地址和存储前缀。metadata 最多配置同一个 etcd 集群的三个成员入口。集群 CA 必须信任私有 TLS 端点。每台主机在 identity_file 对应路径部署包含证书和私钥的 PEM 文件,确保服务账号可读。

每台 Worker 主机启动一个实例,Worker 仍仅监听 IPv4 回环地址。通过 mTLS 反向代理校验客户端证书,仅转发 /internal/v1/jobs、/internal/v1/stages、/internal/v1/csr、/internal/v1/identity 和 /internal/v1/readiness/{model}/{revision}。把代理的私有 HTTPS 地址写入 workers,逐节点检查 etcd、共享存储和来源访问。

将 distributed_partitions 设为 2 至 8,可让符合条件的查询使用分布式阶段。设为 0 时,每条查询派给一个 Worker。调优参数及内存语义见分布式执行参考。

5. 启用 Coordinator 故障接管

两台 Coordinator 使用相同构建、集群命名空间和启动用的 catalog,管理员密码哈希也保持一致。在两台 Coordinator 的服务命令中加入下方参数,并将公开地址设为浏览器访问的正式 HTTPS 源地址。

Shell flags
--coordinator-failover --public-url https://graphlake.example

先启动一台 Coordinator 并等待首次导入完成,再启动备用实例。TLS 入口通过私有转发访问 Coordinator,只将 HTTP 请求路由至通过 /coordinator/active 检查的实例。随包的 HAProxy 配置包含 HTTPS、Gremlin WebSocket、Bolt 握手和恢复路由。仅在客户端需要 Bolt 时启用并验证 Bolt 监听。

通过真实入口检查 HTTPS 就绪并运行结果已知的查询。故障接管演练中停止当前活动 Coordinator,确认备用节点接管并重新执行同一查询,再验证各启用的驱动能重连。使用独立状态端口观察两个节点。升级时先升级 Worker,再升级 Coordinator,并保留升级前的恢复点。使用 HAProxy 与 Keepalived 双入口时,参见冗余入口参考。