别再单机跑 Consul 了!三节点集群从零部署全记录,照着敲命令就行
凌晨三点,线上的服务注册中心挂了。我盯着报错日志看了半小时,最后发现是当初图省事,Consul 只起了单机模式,一个节点崩了,整个服务发现全停。那晚之后我给自己立了条规矩:凡是跟"服务发现"沾边的基础组件,起步就是三节点集群,不然就等于把命交到一台机器手上。
今天这篇,我把 Consul 从头讲一遍。它是什么、靠什么原理保证不丢数据、能用在哪些地方、三节点集群怎么一步步搭起来,最后配上验证命令和踩坑清单。你照着敲,一台到三台机器就能跑起来,不用再去网上拼那些零散版本。
Consul 到底是个啥
项目地址:https://github.com/hashicorp/consul
一句话:它是一个分布式服务发现和配置中心,HashiCorp 公司写的,Go 语言,单个二进制文件,跑起来没别的依赖。
它干的活,说白了就三件:
第一,服务注册和发现。微服务启动的时候把自己登记进来,别的服务要用的时候,通过 Consul 查到它的地址和端口,不用在配置文件里写死 IP。这是它最核心的能力,也是它和纯 KV 存储最大的区别。
第二,健康检查。Consul 会定期去探活每个服务,HTTP、TCP、gRPC、Docker、脚本都行,探到挂了就把它从可用列表里摘掉,流量不会再打到尸体上。这个"摘除"的动作是自动的,不用你写额外逻辑。
第三,KV 存储。存一些非敏感的动态配置,比如功能开关、灰度比例、黑白名单,各服务拉下来就能用。注意我说"非敏感",密码、密钥这类东西别放 Consul,那是 Vault 的活,别混了。
这三个能力凑在一起,才让 Consul 和 etcd、ZooKeeper 拉开区别。etcd 是纯 KV,服务发现你得自己在它上面搭一套;ZooKeeper 强在分布式协调,但客户端重、Java 生态绑定深、运维门槛高,还要自己搞定 watcher 和临时节点。Consul 是把发现、健康检查、KV 一股脑打包好,还自带一个 Web UI 和一个 DNS 接口,开箱即用,这是它当年能火起来的原因。
数据一致性上,Consul 是典型的 CP 系统,牺牲一点可用性,换强一致。这点很关键,后面讲 Raft 的时候你会明白它为什么这么设计。很多选型纠结"Consul 和 Eureka 用哪个",答案就在这里:Eureka 是 AP,优先保证可用,节点断开也能继续拿缓存的服务列表,代价是可能拿到过期信息;Consul 是 CP,宁可短暂不可写,也要保证读到的数据是准的。你要哪种,取决于你的业务能不能容忍"查到一个已经挂了的服务地址"。
它靠什么不丢数据——Raft 和 gossip
Consul 的稳,核心在两层协议,不懂这层容易在故障时瞎操作。我尽量用大白话讲,不堆术语。
第一层是 Raft,管的是"状态准不准"。
Consul 集群里所有要持久化的东西:注册的服务、KV 数据、ACL 配置,都存在 Raft 日志里。Raft 是个一致性算法,通俗点讲,就是集群里选出一个 leader,所有写操作都先经过 leader,leader 把这条日志复制给另外几个 follower,等到超过半数节点确认了,这条记录才算正式生效。
为什么非得过半数?因为要保证"同一时刻只可能有一个 leader 在写"。想象一下网络分区,如果 5 台节点被切成了 3+2 两半,只有 3 台那组能凑出多数派,能继续选 leader;2 台那组凑不够半数,就只能干瞪眼,拒绝服务。这样一来,两个分区不可能同时各有一个 leader 在写数据,数据不会出现"脑裂"。
这里有个词必须焊死在脑子里:Quorum,多数派。 三节点集群,超过半数就是 2 票,所以挂掉 1 台还能正常工作,挂 2 台就歇菜了。这也是为什么生产环境基本都是三节点起步,容忍单点故障。五节点可容忍 2 台挂,但机器成本和维护复杂度上去了。
所以记住这条:Consul 的 server 节点数量,永远要奇数。 3、5、7 这样往上加。偶数会出现脑裂风险,两节点根本凑不出多数派——2 的半数以上还是 2,挂一台就全完,那还不如单机。
第二层是 gossip,管的是"谁还活着"。
gossip 协议(Consul 里叫 Serf)干的是另一件事:节点之间互相传播"我在、你还在不在",维护成员列表和故障检测。它不像 Raft 那样要求强一致,而是像办公室里的八卦一样,你传我、我传他,最终大家都会知道这条消息。好处是极其轻量、能扛住成千上万个成员,坏处是它只关心成员状态,不碰数据一致性。
而且 gossip 用的是 UDP 广播式的随机散布,每秒钟每个节点随机跟几个邻居交换状态,所以成员多的时候也不会像 Raft 那样有中心化的复制压力。它能快速发现"某台机器死了",触发故障处理,但它不负责确认"这台机器上的数据到底写到哪了"。
把这俩分开看就通了:gossip 管"人还在不在",Raft 管"账记得对不对"。 很多 Consul 的诡异问题,其实就是把这两层搞混了,该看 Raft 的时候去看 gossip,或者反过来。
再说说两种 agent 角色,这个必须分清楚:
Server 节点:参与 Raft 投票,存全量数据,负责真正的"记账"。生产至少要三台。它是集群的"大脑",权重最高,动它之前一定要三思。
Client 节点:不存数据、不投票,就是个轻量代理。每个跑业务服务的机器上放一个,服务注册和查询都走它,它再 RPC 转发给 server。这层分离让 server 的压力可控,client 挂了也完全不影响集群一致性——它只是那条"转发通道",通道断了重连就行。
理解了这个分工,你就明白为什么生产架构是"3 台 server + N 台 client":server 撑起一致性,client 贴着业务分布。业务机器再多,server 那三台的核心地位不变。
能用在哪些场景
讲原理你可能还是觉得空,我落地到几个真实场景,看看它到底替你干了什么活。
场景一:微服务的注册中心。 这是最主流的用法。几十上百个服务,各自启动时注册,互相发现。你再也不用维护一张"某某服务在哪台机器哪个端口"的 Excel,服务扩容缩容,Consul 自动感知,调用方自动拿到最新列表。
场景二:DNS 式服务发现。 这是很多人忽略的宝藏用法。Consul 自带一个 DNS 接口(8600 端口),你可以直接 web.service.consul 这样通过域名访问服务。老系统、shell 脚本、甚至人肉 curl,都不用改成 HTTP API 调用,把 /etc/resolv.conf 指到 Consul 就行,接入成本几乎为零。
场景三:动态配置下发。 用 KV 存配置,服务启动时拉一次,还能用 Consul 的 blocking query 监听变化,配置一改,服务秒级感知,不用重启。功能开关、灰度参数这类高频变更的东西,放这里最合适。
场景四:健康检查驱动流量摘除。 配合健康检查,一个服务多实例部署,某个实例 OOM 了,Consul 探活失败自动摘除,调用方就查不到这个死实例了。这种"自动摘除、恢复后自动拉回"的能力,是手写注册中心最容易漏掉的。
场景五:多数据中心容灾。 Consul 支持 WAN federation,多个 datacenter 之间可以联邦、互相做读写转发。这是它跟 etcd 比最突出的差异化能力之一,适合跨地域部署的大型系统。
开始部署:三节点裸机集群
环境假设,我按最典型的来,你把 IP 换成自己的:
- 节点 1:192.168.198.201(consul-1)
- 节点 2:192.168.198.202(consul-2)
- 节点 3:192.168.198.203(consul-3)
- 系统:Ubuntu 22.04 / CentOS 7 都行,下面命令以 Ubuntu 为主,CentOS 把
apt换成yum即可 - 三台机器时间要同步(Raft 对时钟敏感,建议都装上 chrony 或 ntp),防火墙放行下面几个端口
先记住这几个端口,部署时绕不开:
| 端口 | 协议 | 用途 |
|---|---|---|
| 8300 | TCP | server 之间 RPC 通信(Raft 日志复制走这里) |
| 8301 | TCP/UDP | LAN gossip |
| 8302 | TCP/UDP | WAN gossip(跨数据中心才用) |
| 8500 | HTTP | HTTP API + Web UI |
| 8600 | UDP/TCP | DNS 接口 |
8900 是 server 间 RPC 配合 TLS 时可能用到的另一个端口,但默认配置下先记上面这 5 个就行。
第一步:三台都装二进制
我劝你不要 apt install consul。Ubuntu 22.04 官方仓库里的 Consul 是老古董,Hashicorp 早就停止对 1.12 之前版本的安全更新了,装完一堆坑,而且版本旧到跟现代配置语法都对不上。直接下官方二进制,稳,还可控版本。
每台机器都执行(版本号 1.19.2 是示例,你去 releases.hashicorp.com/consul 看当前最新稳定版,替换即可):
# 建专用用户和目录
sudo useradd --system --home /etc/consul.d --shell /bin/false consul
sudo mkdir -p /etc/consul.d /opt/consul
sudo chown -R consul:consul /etc/consul.d /opt/consul
# 下载并解压(把 1.19.2 换成你确认的最新稳定版)
cd /tmp
curl -fLO https://releases.hashicorp.com/consul/1.19.2/consul_1.19.2_linux_amd64.zip
unzip consul_1.19.2_linux_amd64.zip
sudo mv consul /usr/local/bin/
consul version
几点补充说明,都是实际会遇到的:
- 用专用用户跑,不要用 root。Consul 进程不该有 root 权限,万一被攻破,root 直接就没了。
--system建的是系统用户,没登录 shell。 data_dir(这里规划的/opt/consul)必须给 consul 用户写权限,上面chown就是干这个的。consul version能打印版本号,说明装好了。三台都要装,一台都不能少。
第二步:写配置文件
在每一台机器的 /etc/consul.d/consul.hcl 写下面这个文件。我只贴节点 1 的,节点 2、3 把 bind_addr 换成各自的 IP,其他一模一样。
datacenter = "dc1"
data_dir = "/opt/consul"
server = true
bootstrap_expect = 3
bind_addr = "192.168.198.201" # 改成每台自己的内网 IP
client_addr = "0.0.0.0"
retry_join = [
"192.168.198.201",
"192.168.198.202",
"192.168.198.203"
]
ui_config {
enabled = true
}
log_level = "INFO"几个参数单独说一下,这是最容易写错的地方:
bootstrap_expect = 3 是整个集群启动的灵魂。它告诉 Consul:凑齐 3 个 server 之前,别急着启动 Raft 选举。三台都要写一样的 3。如果你写成 1,就会出现每个节点都觉得自己是 leader 的诡异局面,数据直接乱掉。它是集群启动的"发令枪",跟后面说的 bootstrap(单节点强制当 leader)是两码事,千万别混。
server = true 表示这是 server 节点。如果你想把某台机器只当 client(跑业务的那台机器再装一个 client agent),就把这行改成 server = false,同时删掉 bootstrap_expect。但我们现在搭的是纯 server 集群,三台都 true。
retry_join 是自动加入机制。节点启动后会反复尝试连接列表里的地址,直到 join 成功。这样你不需要手动一条条 consul join,尤其适合重启后自动重连——这是生产自愈的关键一环。列表里可以包含自己的地址,没关系,Consul 会自己处理。
client_addr = "0.0.0.0" 是控制 HTTP API 和 DNS 监听哪个网卡。开发环境图省事就 0.0.0.0,生产环境如果你把 API 暴露在公网,一定要改成内网 IP 甚至 127.0.0.1,配合 ACL 一起用。
bind_addr 和 client_addr 是两回事,新手最爱搞混:bind_addr 是节点之间 gossip、RPC 用哪个 IP 通信(要填内网 IP,能彼此互通的那个),client_addr 是 HTTP/DNS API 服务监听哪个地址。前者关乎集群能不能连起来,后者关乎谁能访问你的 API。
写完配个语法检查,别直接启动:
sudo -u consul consul validate /etc/consul.d/consul.hcl输出 Configuration is valid! 就过了。这一步能把拼错 key、漏写的坑在启动前拦住。

第三步:配 systemd 托管
Consul 进程得能开机自启、崩溃自动拉,光靠前台跑 consul agent 不靠谱。三台都建 /etc/systemd/system/consul.service:
[Unit]
Description=Consul Agent
Requires=network-online.target
After=network-online.target
[Service]
User=consul
Group=consul
ExecStart=/usr/local/bin/consul agent -config-dir=/etc/consul.d
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target重点是 Restart=on-failure 配 RestartSec=10,进程意外挂了 10 秒后自动拉起来。LimitNOFILE=65536 把文件句柄数调大,Consul 在高并发下会开很多连接,默认 1024 容易炸,这坑我也踩过——压测一上来,报一堆 too many open files,查半天才发现是这里。
然后三台都执行:
sudo systemctl daemon-reload
sudo systemctl enable consul
sudo systemctl start consul这里有个关键的启动顺序。不要三台同时 systemctl start,最好是先起节点 1,等个几秒,再起节点 2、节点 3。虽然理论上靠 retry_join 乱序也没事,但第一台起来后它是唯一的 server,会进入"等待凑齐 3 个"的状态,这时候日志会刷 Waiting for 3 servers,这是正常的,别慌,等另外两台起来就好。
看日志实时跟一下:
sudo journalctl -u consul -f你能看到它从"等节点"到"选举 leader"到"这个节点成为 follower/leader"的完整过程,比看文档直观多了。
第四步:验证集群
这才是真正能判断"搭没搭成"的环节,别以为 systemctl start 没报错就算完了。我按"层层递进"的顺序给你排好。
先看成员列表(gossip 层):
consul members
正常输出长这样(IP 和节点名是你自己的):
Node Address Status Type Build Protocol DC Partition Segment
kafka-node1 192.168.198.201:8301 alive server 1.19.2 2 dc1 default <all>
kafka-node2 192.168.198.202:8301 alive server 1.19.2 2 dc1 default <all>
kafka-node3 192.168.198.203:8301 alive server 1.19.2 2 dc1 default <all>三台都 alive、Type 都是 server,说明 gossip 层没问题,节点互相看见了。但这只是第一层。
再看 Raft 状态(一致性层,最关键):
consul operator raft list-peers
输出应该是:
[root@kafka-node1 tmp]# consul operator raft list-peers
Node ID Address State Voter RaftProtocol Commit Index Trails Leader By
kafka-node2 7ba95e8f-3f1e-e9b0-ab65-34abd855398c 192.168.198.202:8300 leader true 3 27 -
kafka-node3 76e902a6-6893-0179-8376-c029ebe89e77 192.168.198.203:8300 follower true 3 27 0 commits
kafka-node1 0d4fc1bc-b5ff-7013-7893-defcbac6e4a9 192.168.198.201:8300 follower true 3 27 0 commits
[root@kafka-node1 tmp]# 看到 一个 leader、两个 follower,三个都是 Voter=true,集群就是健康态。如果这里只有 1 个或 2 个节点,说明没凑齐 quorum,去查 retry_join 和 bootstrap_expect。这里还有个细节:能顺便看到每个节点的 commit index,正常情况三个值应该基本一致,如果某个 follower 的 index 落后 leader 很多,说明它同步卡住了,是要出事的前兆。
再测一下 API 和 UI:
http://192.168.198.201:8500/ui/dc1/services
会返回一个 IP:端口,就是当前 leader。浏览器打开 http://192.168.198.201:8500,能看到 Consul 自带的 Web 界面,服务、节点、KV 都能图形化看到。刚接触 Consul 的话,这个 UI 特别适合用来理解数据结构。
最后做一次"真刀真枪"的故障演练,这是我最推荐的一步,比读文档管用十倍:随便挑一台 follower,systemctl stop consul,然后重新 consul members 和 raft list-peers,你会发现剩下的两台还能正常干活,集群没崩。再把这台拉起来,它自己会通过 retry_join 重新加入,数据自动同步回来。这一步能亲手验证"三节点容忍单点故障"这个承诺。
再进一步的话,你可以试着停掉 leader(而不是 follower),观察一下剩余两台会不会自动选出一个新 leader。看到"leader 自动变更、集群继续服务"这一幕,你对 Raft 的理解就落地了。
第五步:注册一个服务试试水
集群起来了,得让它干点正事。把下面这段 JSON 存成 web.json,放到任意一台机器的 /etc/consul.d/ 下,再 consul reload 让它热加载:
{
"service": {
"name": "web",
"port": 8080,
"check": {
"http": "http://localhost:8080/health",
"interval": "10s",
"timeout": "1s"
}
}
}这里面 check 就是健康检查:每 10 秒去探 localhost:8080/health,超时 1 秒就算不健康。服务挂了 Consul 会自动把它标记成 critical,从发现结果里剔除。
放好后热加载:
sudo consul reload验证能不能发现:
curl http://192.168.198.201:8500/v1/catalog/service/web
能返回这个服务的 JSON,就说明注册 + 发现整条链路通了。再顺便试 DNS:
dig @192.168.198.201 -p 8600 web.service.consul
能解析出地址,说明 8600 端口的 DNS 接口也在工作。很多老系统不会改代码调 HTTP API,就直接配一个 /etc/resolv.conf 指向 Consul 的 DNS,用 web.service.consul 这种域名来访问服务,这是它最实用的一个隐藏技能,接入成本几乎为零。
到这里,一个完整可用的三节点 Consul 集群 + 服务注册验证,就算全部跑通了。你可以拿这套直接上测试环境,甚至小规模生产。
踩坑清单,照着避开能少熬三个夜
这几条全是我或者身边人被坑过的,都跟真实事故对得上。我按"血泪程度"排了序。
1. 别在生产环境用单机 -dev 模式,更别 bootstrap 混着 bootstrap_expect。 -dev 是给你本地跑着玩的,数据存在内存里还关安全特性。我之前那个"凌晨三点崩"的故事,根子就是有人拿 dev 模式的数据扛生产。-bootstrap 是让单节点强行当 leader,跟 bootstrap_expect=3 同时写,行为是未定义的,集群会进入一种谁都说不清的混沌状态。
2. server 节点数必须是奇数,别问为什么,记住就行。 3 台最常见,5 台是给超大规模准备的。偶数节点不只是浪费,是真会出事——脑裂风险。
3. 时钟不同步是大坑。 Raft 日志带时间戳,选举超时也依赖时钟,三台机器时间差个几秒钟,可能出现选举超时、日志异常、leader 频繁切换。装好 Consul 之前先把 NTP 或 chrony 配好,这是地基,地基不稳上面全白搭。
4. 别只看 consul members 就下结论说集群健康。 members 看的是 gossip 层,节点 alive 不代表 Raft 层正常。真正的健康标准是 raft list-peers 能凑齐 quorum。故障排查时先分清楚你是在看 gossip 还是 Raft,这个思路对了能少走很多弯路。
5. data_dir 必须每台节点独立、不能 NFS 共享。 Raft 的数据目录要本地磁盘,多台节点共享同一个目录文件,数据直接损坏。另外 data_dir 别放在会被清理的 /tmp 下,也别放在会被容器调度漂移的临时卷里。
6. 防火墙和云安全组,8300/8301/8500 一个都别漏。 最经典的现象:members 能看到自己、看不到别人,十有八九是 8301 的 gossip 端口没放行。跨 AZ、跨地域部署尤其要注意,云端还要同时检查安全组和子网路由两层。
7. KV 读超时的偶发故障,如果是老版本(比如 1.11.x),先怀疑 Raft 心跳调度的问题。有个真实的案例是 1.11.2 版本偶发 kv.get 33000ms 超时,最后发现是 Follower 的 commit index 落后 leader 超过 1000,转发的读请求全卡住。排查姿势:consul operator raft list-peers 看各节点的 commit index 差距,日志里搜 leadership transition、heartbeat timeout、failed to reconcile。版本能升就升,这类老版本的 Raft 调度问题新版本基本都修了。
8. 生产环境务必开 ACL。 默认 Consul 的 HTTP API 是裸奔的,谁都能注册服务、改 KV。上生产第一步先 consul acl bootstrap 生成一个 bootstrap token(带 global-management 策略,相当于 root),然后给每个 agent、每个服务分配最小权限 token。这个 token 只给极少数人,别写进代码仓库,也别贴进聊天记录。
9. client_addr = 0.0.0.0 是把双刃剑。 图方便,但它等于把 8500 的 HTTP API 暴露给所有网卡,公网环境就是裸奔。生产要么绑定内网 IP,要么配 TLS + ACL,两者最好都上。
10. 升级要做版本规划,别跨太多。 Consul 不同大版本之间 Raft 协议、ACL 行为都有变化,跨好几个大版本直接升大概率炸。去看官方的 upgrade 页,按路径一步步来,别学某些人"反正都是 1.x 直接升"的侥幸心理。
11. 每次动配置先 consul validate。 拼错一个 key,Consul 可能直接拒绝启动,深夜里你会对着一条报错日志怀疑人生。把 validate 养成肌肉记忆,比事后补救强一百倍。
12. retry_join 列表里尽量别写公网 IP 或 DNS 容易漂的地址。 用内网固定 IP,别用会变的容器名(除非有稳定 DNS)。否则重启一次,节点可能 join 不到集群,变成一个孤岛节点。
写在最后
Consul 这玩意儿,难的不是把它跑起来——consul agent -dev 一条命令就起了。难的是搞明白它为什么这么设计、挂了该怎么判断、生产怎么配才不翻车。Raft 管数据、gossip 管成员、奇数节点保多数派、bootstrap_expect 撑起集群启动,这四件事你脑子里有数了,遇到 99% 的 Consul 问题都不会再慌。
动手比看十篇文章管用。找三台机器(哪怕是虚拟机),把我上面第二、三、四步完整走一遍,尤其是第四步那个"故意停掉一台节点、再故意停 leader 看自动选举"的演练,做完你就真正理解"三节点为什么能扛住单点故障"了——这种体感,是任何文档都给不了你的。
这篇要是对你有帮助,点个关注不迷路,我会持续更新这种"能照着敲命令、不掺水"的运维实操。后面我还想写 Consul 的 ACL 和 TLS 完整加固、以及跟 etcd 的深度选型对比,想先看哪个,评论区告诉我。
运维路上坑多,咱们一起踩、一起记、一起少加班。
公众号:耕云躬行录
个人博客:躬行笔记