参考：Consul 四大功能速查与命令清单
基于 Consul 1.18 · 核于 2026-08
速查
- Consul 定义：HashiCorp 出品的分布式服务发现 + mesh 平台，CP 型（Raft），一个 Go 二进制打包服务发现/健康检查/KV/多 DC/Connect。
- 四大功能：服务发现（DNS/HTTP）、健康检查（HTTP/TCP/Script/TTL，三态）、KV（CAS/Watch/Session-Lock）、Connect mesh（Sidecar mTLS + Intentions）。
- 架构：Server（3/5 个，Raft 强一致目录）+ Client Agent（每节点一个，注册/探活/Gossip），LAN/WAN Gossip 互联。
- 一致性：Raft（目录/KV 强一致）+ Gossip（节点存活最终一致）分工。CP 型——分区时少数派不可写。
- 健康检查：默认反向探（Agent 探服务），TTL 是主动报。三态 passing/warning/critical，critical 被摘除。
- DNS 端口：8600。
<service>.service.consul只返回 passing。 - 与 Nacos 对比：Consul CP/反向探/DNS/国际；Nacos AP/主动报/配置中心原生/中国事实标准。
- 与 etcd 对比：Consul 业务服务发现开箱即用；etcd 是纯 KV 底座（K8s 用），业务发现要自拼。
一、四大功能速查
| 功能 | 核心 | 关键 API/机制 |
|---|---|---|
| 服务发现 | 服务名 → 健康实例列表 | DNS（<svc>.service.consul）/ HTTP（/v1/health/service/:name?passing=true） |
| 健康检查 | 周期性探活，摘除故障实例 | HTTP/TCP/Script/TTL，interval 周期，三态 |
| KV 存储 | 层级化键值，配置/锁/选举 | /v1/kv/:key，CAS（?cas=）、Watch（?index=&wait=）、Session-Lock |
| Connect mesh | Sidecar mTLS + 授权 | consul connect proxy，Intentions（-allow/-deny） |
二、健康检查类型与状态映射
| 类型 | 字段 | passing 条件 | warning/critical |
|---|---|---|---|
| HTTP | http + interval | 2xx | 429=warning，其他/超时=critical |
| TCP | tcp + interval | 能建立连接 | 连不上=critical |
| Script | args + interval | 退出码 0 | 1=warning，其他=critical |
| TTL | ttl | 服务周期性 check pass | 超时未报=critical |
| Docker | docker_container_id | 容器 running | 非 running=critical |
| gRPC | grpc + interval | SERVING | 其他=critical |
- 默认反向探：HTTP/TCP/Script/gRPC/Docker 都是 Agent 主动探；只有 TTL 是服务主动上报。
deregister_critical_service_after：critical 超该时长自动摘除（防僵尸实例）。
三、常用命令速查
bash
# —— Agent 启动 ——
consul agent -dev # 开发模式（单节点，本机）
consul agent -server -bootstrap-expect=3 -data-dir=/consul/data \
-node=server1 -bind=10.0.0.1 -client=0.0.0.0 # 生产 Server
consul agent -data-dir=/consul/data -node=node1 -bind=10.0.0.5 # Client Agent
consul join 10.0.0.1 # 加入集群
# —— 服务管理 ——
consul catalog list services # 列所有服务
consul catalog nodes -service=order-service # 列某服务的节点
consul services register my-service.json # 注册（配置文件）
consul services deregister order-1 # 反注册
# —— 健康检查 ——
consul health service order-service # 列实例及检查状态
consul health service order-service -passing # 只看健康
consul monitor # 实时日志
# —— KV ——
consul kv put config/db/host 10.0.0.100
consul kv get config/db/host
consul kv get -detailed config/db/host # 含 ModifyIndex
consul kv delete config/db/host
consul kv export config/ # 导出前缀
consul kv import @backup.json # 导入
# —— Connect mesh ——
consul connect proxy -sidecar-for order-service # 启 Sidecar
consul intention create -allow web api # 授权
consul intention check web api # 校验（allowed/denied）
consul intention list
# —— 集群管理 ——
consul members # 节点列表（Gossip 视角）
consul members -wan # 跨 DC 节点
consul operator raft list-peers # Raft 仲裁成员
consul info # 详细状态
consul leave # 优雅离开四、关键 HTTP API
| 方法 | 路径 | 用途 |
|---|---|---|
| PUT | /v1/agent/service/register | 注册服务 |
| PUT | /v1/agent/service/deregister/:id | 反注册 |
| GET | /v1/health/service/:name?passing=true | 查健康实例 |
| GET | /v1/kv/:key | 读 KV |
| PUT | /v1/kv/:key | 写 KV（?cas= CAS，?acquire=/?release= 锁） |
| GET | /v1/kv/:key?index=&wait= | Watch（长轮询） |
| PUT | /v1/session/create | 创建 Session（锁/选举） |
| GET | /v1/catalog/services | 列所有服务 |
| GET | /v1/status/leader | 当前 Raft leader |
五、易错点清单
- 「Consul 是 AP」：错。Consul 服务目录走 Raft，是 CP（分区时少数派不可写）。Nacos 默认 AP 才是 AP。
- 「DNS 查询返回所有实例」：错。DNS 默认只返回
passing，critical/warning自动排除。要含 warning 需改?passing过滤配置或用 HTTP API。 - 「健康检查 interval 越短越好」：错。太短（1s）压被探服务，太长（60s）故障发现慢。经验 5-15s。
- 「TTL 检查能发现所有故障」：错。TTL 靠服务主动上报心跳，业务线程死锁但心跳线程活着时，TTL 探不出来。应配 HTTP 检查双保险。
- 「注册时 name 和 id 是一回事」：错。
name是服务名（多实例同名），id是实例唯一标识。多实例必须显式指定不同id，否则互相覆盖。 - 「Consul KV 能当配置中心用，和 Nacos 一样」：错。Consul KV 是裸 KV，无 Nacos 的 DataId/Group/命名空间/灰度/回滚原语，要做专业配置管理需团队自约定 key 规范或上专门配置中心。
- 「Connect mesh 和 Istio 一样强」：错。Connect 是轻量 mesh（mTLS + Intentions），无 Istio 的细粒度流量拆分（金丝雀/AB/镜像）。Connect 适合已用 Consul 的团队顺手开 mesh，重度流量管理仍要 Istio。
- 「Client Agent 存服务目录」：错。Client Agent 无状态，目录只在 Server（Raft）。Client 只是本地代表，转发给 Server。
- 「consul agent -dev 能用于生产」：错。-dev 是单节点无持久化，仅本地调试。生产必须 Server 集群（3/5 个）+ Client Agent。
六、进阶方向（链接其他叶）
- Etcd —— Consul 目录用的 Raft 与 etcd 同源，对比纯 KV 底座
- Nacos —— Consul 在中国最常被对比的 AP 型注册中心 + 配置中心
- Istio —— Consul Connect 的重量级 mesh 对手，流量管理更细