rqlite 完全指南 / 第 2 章：安装与集群搭建
第 2 章：安装与集群搭建
从零开始安装 rqlite，搭建单节点和多节点集群。
2.1 安装方式总览
| 安装方式 | 适用场景 | 复杂度 | 推荐度 |
|---|---|---|---|
| 二进制下载 | 生产部署、快速体验 | ⭐ | ⭐⭐⭐ |
| Docker 容器 | 开发测试、容器化部署 | ⭐ | ⭐⭐⭐ |
| 源码编译 | 需要自定义修改 | ⭐⭐⭐ | ⭐⭐ |
| Go Install | Go 开发者 | ⭐⭐ | ⭐⭐ |
2.2 二进制安装
2.2.1 下载预编译二进制
rqlite 在 GitHub Releases 页面提供各平台预编译二进制包：
# 设置版本变量
RQLITE_VERSION=8.36.5
# Linux AMD64
curl -LO https://github.com/rqlite/rqlite/releases/download/v${RQLITE_VERSION}/rqlite-v${RQLITE_VERSION}-linux-amd64.tar.gz
# 解压
tar xzf rqlite-v${RQLITE_VERSION}-linux-amd64.tar.gz
# 移动到 PATH
sudo mv rqlite-v${RQLITE_VERSION}-linux-amd64/rqlited /usr/local/bin/
sudo mv rqlite-v${RQLITE_VERSION}-linux-amd64/rqlite /usr/local/bin/
# 验证安装
rqlited -version
注意:
rqlited是服务端程序，rqlite是官方 CLI 客户端。两者都需要安装。
2.2.2 支持的平台
| 平台 | 架构 | 二进制名 |
|---|---|---|
| Linux | AMD64 | rqlite-*-linux-amd64.tar.gz |
| Linux | ARM64 | rqlite-*-linux-arm64.tar.gz |
| macOS | AMD64 | rqlite-*-darwin-amd64.tar.gz |
| macOS | ARM64 (M1/M2) | rqlite-*-darwin-arm64.tar.gz |
| Windows | AMD64 | rqlite-*-windows-amd64.zip |
2.2.3 创建系统用户和目录
# 创建专用用户
sudo useradd -r -s /bin/false rqlite
# 创建数据目录
sudo mkdir -p /var/lib/rqlite
sudo chown rqlite:rqlite /var/lib/rqlite
2.2.4 创建 systemd 服务
# /etc/systemd/system/rqlited.service
[Unit]
Description=rqlite distributed SQLite database
After=network.target
[Service]
Type=simple
User=rqlite
Group=rqlite
ExecStart=/usr/local/bin/rqlited \
-node-id node1 \
-http-addr 0.0.0.0:4001 \
-raft-addr 0.0.0.0:4002 \
/var/lib/rqlite/data
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable rqlited
sudo systemctl start rqlited
sudo systemctl status rqlited
2.3 Docker 安装
2.3.1 快速启动单节点
# 最简启动
docker run -d --name rqlite \
-p 4001:4001 \
-p 4002:4002 \
rqlite/rqlite
# 查看日志
docker logs -f rqlite
# 验证服务
curl http://localhost:4001/status
2.3.2 持久化数据启动
# 创建数据目录
mkdir -p /data/rqlite
# 持久化启动
docker run -d --name rqlite \
-p 4001:4001 \
-p 4002:4002 \
-v /data/rqlite:/rqlite/file \
rqlite/rqlite \
-disco-mode=off \
-node-id=node1
2.3.3 Docker 启动参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
-node-id | 节点唯一标识符 | 自动生成 |
-http-addr | HTTP API 监听地址 | 0.0.0.0:4001 |
-raft-addr | Raft 通信地址 | 0.0.0.0:4002 |
-disco-mode | 发现模式（off/id/dns/srv） | 自动 |
-join | 加入已有集群的地址 | 空 |
-auth | 认证配置文件路径 | 空 |
2.4 源码编译
# 前提：已安装 Go 1.21+ 和 GCC（CGO 依赖）
git clone https://github.com/rqlite/rqlite.git
cd rqlite
# 编译
go build -o rqlited ./cmd/rqlited
go build -o rqlite ./cmd/rqlite
# 安装
sudo mv rqlited rqlite /usr/local/bin/
注意: rqlite 使用
mattn/go-sqlite3，该库依赖 CGO，因此编译时需要 GCC。
2.5 单节点启动
2.5.1 最简启动
# 创建数据目录
mkdir -p /tmp/rqlite/data
# 启动单节点（关闭发现）
rqlited -node-id=node1 -disco-mode=off /tmp/rqlite/data
启动后会看到类似输出：
[rqlited] 2026/05/10 10:00:00 rqlited starting, version 8.36.5, SQLite 3.45.0
[rqlited] 2026/05/10 10:00:00 Raft TCP Listener starting on 127.0.0.1:4002
[rqlited] 2026/05/10 10:00:00 HTTP server starting on 127.0.0.1:4001
[rqlited] 2026/05/10 10:00:00 Node is ready
2.5.2 验证单节点
# 检查状态
curl -s localhost:4001/status | python3 -m json.tool
# 检查 Leader 信息
curl -s localhost:4001/status?pretty
# 执行简单查询
curl -s -G 'localhost:4001/db/query' \
--data-urlencode 'q=SELECT sqlite_version()' | python3 -m json.tool
2.5.3 完整启动参数列表
rqlited [flags] <data-directory>
| 参数 | 说明 | 默认值 |
|---|---|---|
-node-id | 节点 ID（集群内唯一） | 自动生成 UUID |
-http-addr | HTTP API 地址 | localhost:4001 |
-http-adv-addr | HTTP 广告地址（对外暴露） | 同 -http-addr |
-raft-addr | Raft 通信地址 | localhost:4002 |
-raft-adv-addr | Raft 广告地址 | 同 -raft-addr |
-join | 加入集群的目标地址 | 空 |
-disco-mode | 发现模式 | "" |
-disco-id | 发现服务 ID | 空 |
-auth | 认证文件路径 | 空 |
-tls-cert | TLS 证书路径 | 空 |
-tls-key | TLS 私钥路径 | 空 |
-on-disk | 强制使用磁盘存储（默认自动） | false |
-fk | 启用外键约束 | false |
2.6 集群搭建
2.6.1 三节点集群架构
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Node 1 │ │ Node 2 │ │ Node 3 │
│ (Leader) │ │ (Follower) │ │ (Follower) │
│ │ │ │ │ │
│ HTTP :4001 │ │ HTTP :4011 │ │ HTTP :4021 │
│ Raft :4002 │ │ Raft :4012 │ │ Raft :4022 │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────────────────┼────────────────────┘
Raft 网络通信
2.6.2 方式一：使用发现服务
# 节点 1 — 首先启动，会自动创建发现 URL
rqlited -node-id=node1 \
-http-addr=0.0.0.0:4001 \
-raft-addr=0.0.0.0:4002 \
/tmp/rqlite/node1
# 查看日志中的 Discovery URL，类似：
# Discovery URL: https://discovery.rqlite.io/6fbd9cb1...
# 节点 2 — 使用相同的 Discovery URL 加入
rqlited -node-id=node2 \
-http-addr=0.0.0.0:4011 \
-raft-addr=0.0.0.0:4012 \
-disco-id=<discovery-id> \
/tmp/rqlite/node2
# 节点 3 — 同样加入
rqlited -node-id=node3 \
-http-addr=0.0.0.0:4021 \
-raft-addr=0.0.0.0:4022 \
-disco-id=<discovery-id> \
/tmp/rqlite/node3
2.6.3 方式二：使用 -join 参数（推荐）
# 第一个节点（无需 -join）
rqlited -node-id=node1 \
-http-addr=0.0.0.0:4001 \
-raft-addr=0.0.0.0:4002 \
-disco-mode=off \
/tmp/rqlite/node1
# 第二个节点加入 node1
rqlited -node-id=node2 \
-http-addr=0.0.0.0:4011 \
-raft-addr=0.0.0.0:4012 \
-disco-mode=off \
-join=http://127.0.0.1:4001 \
/tmp/rqlite/node2
# 第三个节点加入 node1
rqlited -node-id=node3 \
-http-addr=0.0.0.0:4021 \
-raft-addr=0.0.0.0:4022 \
-disco-mode=off \
-join=http://127.0.0.1:4001 \
/tmp/rqlite/node3
2.6.4 方式三：使用 /join API
先以单节点模式启动所有节点，然后通过 HTTP API 加入集群：
# 以独立模式启动所有节点
rqlited -node-id=node1 -disco-mode=off /tmp/rqlite/node1 &
rqlited -node-id=node2 -disco-mode=off -http-addr=:4011 -raft-addr=:4012 /tmp/rqlite/node2 &
rqlited -node-id=node3 -disco-mode=off -http-addr=:4021 -raft-addr=:4022 /tmp/rqlite/node3 &
# 将 node2 和 node3 加入 node1 的集群
curl -XPOST 'localhost:4011/join' \
-H 'Content-Type: application/json' \
-d '{"id": "node2", "address": "127.0.0.1:4012"}'
curl -XPOST 'localhost:4021/join' \
-H 'Content-Type: application/json' \
-d '{"id": "node3", "address": "127.0.0.1:4022"}'
注意:
join请求中的address是 Raft 地址而非 HTTP 地址。
2.6.5 验证集群状态
# 查看集群状态
curl -s 'localhost:4001/status?pretty' | grep -A 20 '"store"'
# 查看节点列表
curl -s 'localhost:4001/nodes?pretty'
# 测试数据复制
curl -XPOST 'localhost:4001/db/execute' \
-H 'Content-Type: application/json' \
-d '[["CREATE TABLE test (id INTEGER PRIMARY KEY, msg TEXT)"]]'
curl -XPOST 'localhost:4001/db/execute' \
-H 'Content-Type: application/json' \
-d '[["INSERT INTO test VALUES (1, \"hello cluster\")"]]'
# 从 Follower 读取数据
curl -G 'localhost:4011/db/query' \
--data-urlencode 'q=SELECT * FROM test'
预期输出：
{
"results": [
{
"columns": ["id", "msg"],
"types": ["integer", "text"],
"values": [[1, "hello cluster"]]
}
],
"time": 0.000123
}
2.7 集群拓扑建议
| 节点数 | 可容忍故障 | 适用场景 | 建议 |
|---|---|---|---|
| 1 | 0 | 开发测试 | ❌ 不推荐生产 |
| 3 | 1 | 小型生产环境 | ✅ 推荐起步 |
| 5 | 2 | 中型生产环境 | ✅ 推荐 |
| 7 | 3 | 大型环境 | ⚠️ 性能开始下降 |
重要: 节点数必须为奇数，避免脑裂（Split-Brain）。偶数节点没有额外的容错优势，反而增加了 Raft 共识的开销。
2.8 本章小结
| 要点 | 内容 |
|---|---|
| 安装方式 | 二进制下载最简单，Docker 适合开发测试 |
| 服务端程序 | rqlited（服务端）+ rqlite（CLI 客户端） |
| 数据目录 | 启动时指定，包含 SQLite 数据库和 Raft 日志 |
| 集群搭建 | 推荐 -join 参数方式，无需外部依赖 |
| 推荐节点数 | 3 或 5 节点（奇数） |
上一章：第 1 章：rqlite 概念与适用场景 下一章：第 3 章：架构深度解析