RavenDB 7.2 多节点集群部署指南

目标：在三台服务器上部署 RavenDB 7.2 组成一个 3 节点集群，覆盖集群架构、节点配置（ServerUrl/PublicServerUrl/TCP 端口）、集群引导、节点加入、license 授权要求与集群验证。

1. 集群架构

RavenDB 集群基于 Raft 一致性算法，节点间通过 8080 HTTP 端口与专用 TCP 端口通信。集群中一个节点被选为 Leader，负责共识决策；数据库在多个节点上各存一个副本（Replication Factor）。

本文部署拓扑：

节点	主机名	IP（示例）	HTTP 端口	TCP 端口
node1	node1.ravendb.local	192.168.100.11	8080	3888
node2	node2.ravendb.local	192.168.100.12	8080	3888
node3	node3.ravendb.local	192.168.100.13	8080	3888

节点间必须能按主机名互相解析（/etc/hosts 或 DNS），且 8080 与 TCP 端口互通。

2. 前置准备

2.1 三台服务器安装 RavenDB

三台服务器均按《Ubuntu 22.04 安装 RavenDB 7.2 指南》或《CentOS 8 安装 RavenDB 7.2 指南》完成安装与启动。

2.2 配置主机名解析

每台服务器编辑 /etc/hosts：

sudo tee -a /etc/hosts > /dev/null <<'EOF'
192.168.100.11 node1.ravendb.local
192.168.100.12 node2.ravendb.local
192.168.100.13 node3.ravendb.local
EOF

2.3 集群 license 要求

RavenDB 集群（超过 1 个节点）需要 license。社区版免费，可到 https://ravendb.net/license/request 申请免费的 Community 版 license；在 Studio 的「Manage Server → License」页面粘贴申请到的 license 即可激活。

⚠️ 未激活 license（显示为 None）时，向集群添加节点会报错：Your current license (None) does not allow adding nodes to the cluster。社区版免费 license 支持最多 3 节点集群。

3. 各节点集群化配置

集群节点的 settings.json 需要配置公网地址（PublicServerUrl）与 TCP 端口，使 Leader 能通过主机名回连各节点。

以 node1 为例，/opt/ravendb/Server/settings.json：

{
    "ServerUrl": "http://node1.ravendb.local:8080",
    "PublicServerUrl": "http://node1.ravendb.local:8080",
    "Server.TcpPort": 3888,
    "Cluster.TcpPort": 3888,
    "PublicTcpServerUrl": "tcp://node1.ravendb.local:3888",
    "DataDir": "/opt/ravendb/RavenData",
    "Security.UnsecuredAccessAllowed": "PublicNetwork",
    "Setup.Mode": "None"
}

node2、node3 的 settings.json 结构相同，仅把主机名与地址改为各自节点：

{
    "ServerUrl": "http://node2.ravendb.local:8080",
    "PublicServerUrl": "http://node2.ravendb.local:8080",
    "Server.TcpPort": 3888,
    "Cluster.TcpPort": 3888,
    "PublicTcpServerUrl": "tcp://node2.ravendb.local:3888",
    "DataDir": "/opt/ravendb/RavenData",
    "Security.UnsecuredAccessAllowed": "PublicNetwork",
    "Setup.Mode": "None"
}

{
    "ServerUrl": "http://node3.ravendb.local:8080",
    "PublicServerUrl": "http://node3.ravendb.local:8080",
    "Server.TcpPort": 3888,
    "Cluster.TcpPort": 3888,
    "PublicTcpServerUrl": "tcp://node3.ravendb.local:3888",
    "DataDir": "/opt/ravendb/RavenData",
    "Security.UnsecuredAccessAllowed": "PublicNetwork",
    "Setup.Mode": "None"
}

配置项说明：

配置项	说明
`ServerUrl`	节点自身 HTTP 监听地址
`PublicServerUrl`	集群其他节点访问本节点的 HTTP 公网地址
`Server.TcpPort`	数据库间复制的 TCP 端口
`Cluster.TcpPort`	集群共识（Raft）的 TCP 端口
`PublicTcpServerUrl`	集群其他节点访问本节点的 TCP 公网地址

修改配置后重启各节点服务：

sudo systemctl restart ravendb

4. 组建集群

4.1 引导集群（node1 上执行）

在 node1 上执行集群引导，并预先声明 3 个静态节点：

curl -s -X POST "http://127.0.0.1:8080/admin/cluster/bootstrap" \
  -H "Content-Type: application/json" \
  -d '{"NodeUrl":"http://node1.ravendb.local:8080","StaticNodes":["http://node1.ravendb.local:8080","http://node2.ravendb.local:8080","http://node3.ravendb.local:8080"]}'

引导完成后 node1 成为单节点集群并当选 Leader：

curl -s "http://127.0.0.1:8080/cluster/topology"

{"@metadata":{"DateTime":"2026-10-03T01:32:15Z","WebUrl":"http://node1.ravendb.local:8080","NodeTag":"A"},"Topology":{"TopologyId":"c1e92126-8639-40b1-bb8b-fae98c73a2bc","AllNodes":{"A":"http://node1.ravendb.local:8080"},"Members":{"A":"http://node1.ravendb.local:8080"},"Promotables":{},"Watchers":{},"LastNodeId":"A","Etag":1},"Etag":1,"Leader":"A","LeaderShipDuration":32926,"CurrentState":"Leader","NodeTag":"A","ServerRole":"Member","CurrentTerm":1}

4.2 加入节点 node2

在 node1（Leader）上执行，将 node2 加入集群：

curl -s -X PUT "http://127.0.0.1:8080/admin/cluster/node?url=http://node2.ravendb.local:8080" \
  -H "Content-Type: application/json" -d '{}'

⚠️ 若未激活 license，返回：Raven.Client.Exceptions.Commercial.LicenseLimitException: Your current license (None) does not allow adding nodes to the cluster。请先在 Studio 中激活免费 Community license 后重试。

4.3 加入节点 node3

在 node1 上执行，将 node3 加入集群：

curl -s -X PUT "http://127.0.0.1:8080/admin/cluster/node?url=http://node3.ravendb.local:8080" \
  -H "Content-Type: application/json" -d '{}'

4.4 查看集群拓扑

curl -s "http://127.0.0.1:8080/cluster/topology"

{"@metadata":{"DateTime":"2026-10-03T01:33:09Z","WebUrl":"http://node1.ravendb.local:8080","NodeTag":"A"},"Topology":{"TopologyId":"...","AllNodes":{"A":"http://node1.ravendb.local:8080","B":"http://node2.ravendb.local:8080","C":"http://node3.ravendb.local:8080"},"Members":{"A":"http://node1.ravendb.local:8080","B":"http://node2.ravendb.local:8080","C":"http://node3.ravendb.local:8080"},"Promotables":{},"Watchers":{},"LastNodeId":"C","Etag":...},"Etag":...,"Leader":"A","CurrentState":"Leader","ServerRole":"Member"}

3 个节点均为 Member，且都出现在 AllNodes 与 Members 中，即集群组建成功。

5. 建库并验证数据复制

5.1 创建 3 副本数据库

在任意节点上创建数据库，ReplicationFactor 设为 3：

curl -s -X PUT "http://127.0.0.1:8080/admin/databases?name=appdb" \
  -H "Content-Type: application/json" \
  -d '{"DatabaseName":"appdb","Settings":{"DataDir":"Databases/appdb"},"ReplicationFactor":3,"Disabled":false}'

5.2 写入文档并验证三节点均有副本

向 node1 写入文档：

curl -s -X PUT "http://127.0.0.1:8080/databases/appdb/docs?id=orders/1" \
  -H "Content-Type: application/json" \
  -d '{"Customer":"Alice","Amount":99.5,"Status":"New"}'

{"Id":"orders/1","ChangeVector":"A:1-xxxx"}

从 node2、node3 分别读取，均应能返回同一文档：

curl -s "http://192.168.100.12:8080/databases/appdb/docs?id=orders/1"
curl -s "http://192.168.100.13:8080/databases/appdb/docs?id=orders/1"

{"Results":[{"Customer":"Alice","Amount":99.5,"Status":"New","@metadata":{"@id":"orders/1","@change-vector":"..."}}],"Includes":{}}

5.3 查看数据库拓扑

curl -s "http://127.0.0.1:8080/databases/appdb/topology"

输出中 Members 应包含 node1/node2/node3 三个节点标签，ReplicationFactor 为 3。

6. 集群运维

6.1 查看节点状态

curl -s "http://127.0.0.1:8080/cluster/topology" | jq '.Topology.Members'

6.2 节点摘除

curl -s -X DELETE "http://127.0.0.1:8080/admin/cluster/node?url=http://node3.ravendb.local:8080"

6.3 从 Studio 管理集群

浏览器访问 http://node1.ravendb.local:8080，进入 Studio 的「Cluster」页面，可查看集群拓扑、节点健康状态、进行节点添加/移除操作。

7. 故障场景说明

Leader 故障：集群自动选举新 Leader（Raft），数据仍可读写。
节点失联：数据库副本由剩余节点继续服务；节点恢复后自动同步。
副本数不足：可调整数据库 Replication Factor 增加副本数：

curl -s -X POST "http://127.0.0.1:8080/admin/databases/topology/modify" \
  -H "Content-Type: application/json" \
  -d '{"DatabaseName":"appdb","ReplicationFactor":3}'

8. 参考链接

RavenDB 集群文档：https://docs.ravendb.net/7.2/server/clustering/overview
集群设置（Setup Wizard）：https://docs.ravendb.net/7.2/start/installation/setup-wizard/overview
免费 Community license：https://ravendb.net/license/request

9. 常见问题

Q1：Leader 节点故障后集群还能读写吗？

RavenDB 基于 Raft 一致性算法，Leader 故障后集群会自动选举新 Leader；只要多数节点存活（3 节点集群需 ≥2 个），集群仍可正常读写。可通过 /cluster/topology 查看当前 Leader 节点。

Q2：节点失联后数据会丢失吗？

不会。数据库副本由剩余节点继续服务，失联节点恢复后会通过 Raft 日志自动同步补齐数据。若节点长期失联，可先按「6.2 节点摘除」移除，恢复后再重新加入集群。

Q3：加入节点报 license 错误？

报错 Your current license (None) does not allow adding nodes to the cluster 表示 license 未激活。到 https://ravendb.net/license/request 申请免费 Community license（支持最多 3 节点），在 Studio 的「Manage Server → License」页面粘贴激活后重试。

Q4：节点加入后拓扑中看不到该节点？

检查该节点 settings.json 的 PublicServerUrl/PublicTcpServerUrl 是否填写了其他节点可解析的主机名（而非 127.0.0.1），并确认 8080 与 TCP 端口互通；修改配置后重启 ravendb 服务再重新加入。

Q5：数据库副本数不足如何调整？

使用 /admin/databases/topology/modify 接口调整 ReplicationFactor（见「7. 故障场景说明」中的命令），调整后副本会自动在集群节点间补齐。