Consul KV 键值存储

Consul 自带一个轻量键值存储，常用来放动态配置与功能开关，配合 Consul Template（第 11 章）还能把 KV 变化自动渲染成配置文件，实现配置热更新。

命令行基本操作

put/get/delete 三条命令覆盖读写删：

consul kv put app/port 8080
# 输出：Success! Data written to: app/port
consul kv get app/port
# 输出：8080
consul kv put app/port 9090           # 覆盖写
consul kv delete app/port
# 输出：Success! Deleted key: app/port
consul kv get -recurse app            # 递归读取某前缀下全部键

Key 的层级结构

key 用斜杠组织成类似目录的层级，但并没有真正的目录，/ 只是名字的一部分：

键	用途示例
app/port	应用监听端口
app/debug	功能开关，true/false
redis/host	下游依赖的地址

consul kv put app/port 8080
consul kv put app/debug true
consul kv get -recurse app
# 输出：app/debug:true
# 输出：app/port:8080

HTTP API 与原子操作

KV 也走 HTTP 接口：GET/PUT/DELETE /v1/kv/<key>，加 ?recurse 递归。consul kv put 的 -cas 参数做原子比较写：仅当当前版本等于指定 index 才写入，避免并发覆盖。

锁的语义由会话（session）提供：先创建会话，再用 acquire/release 抢放锁，多个 worker 抢同一任务时只有一个能成功：

# 创建会话（记住返回的会话 ID）
curl -X PUT http://127.0.0.1:8500/v1/session/create -d '{"Name":"job-lock"}'
# 输出：{"ID":"8f8c9c3e-..."}   ← 记下这个 ID
# 抢锁：acquire 参数带上会话 ID，写成功返回 true
curl -X PUT "http://127.0.0.1:8500/v1/kv/job/lock?acquire=8f8c9c3e-..." -d owner1
# 输出：true
# 释放锁；持有会话的节点若挂掉，锁也会被自动释放
curl -X PUT "http://127.0.0.1:8500/v1/kv/job/lock?release=8f8c9c3e-..."

典型场景

• 功能开关：改一个 KV 值全局即时生效，无需发版；
• 动态配置：数据库地址、限流阈值放 KV，服务启动读取或监听变化；
• 简易选主：结合会话锁在多个 worker 中选出唯一执行者。

大小限制提醒

单条 KV 值上限 512KB，别当数据库用。超大、高吞吐的数据应放 Redis/数据库，KV 只放小而关键的信息；整体迁移可用 consul kv export/import 导出导入。

小结

KV 适合放"小而变"的配置与开关，斜杠组织路径，CAS 与会话锁支撑简单协调。超过 512KB 或写频繁的场景交给专用存储，各归其位才能发挥 Consul 的价值。