第 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 章：架构深度解析

强曰为道

第 2 章：安装与集群搭建

第 2 章：安装与集群搭建

2.1 安装方式总览

2.2 二进制安装

2.2.1 下载预编译二进制

2.2.2 支持的平台

2.2.3 创建系统用户和目录

2.2.4 创建 systemd 服务

2.3 Docker 安装

2.3.1 快速启动单节点

2.3.2 持久化数据启动

2.3.3 Docker 启动参数说明

2.4 源码编译

2.5 单节点启动

2.5.1 最简启动

2.5.2 验证单节点

2.5.3 完整启动参数列表

2.6 集群搭建

2.6.1 三节点集群架构

2.6.2 方式一：使用发现服务

2.6.3 方式二：使用 -join 参数（推荐）

2.6.4 方式三：使用 /join API

2.6.5 验证集群状态

2.7 集群拓扑建议

2.8 本章小结