- name
- consul-api
- description
- >
Consul API
HashiCorp Consul HTTP API 操作指南。提供服务发现、KV 存储、健康检查和服务网格管理能力。
Quick Start
Base URL: http://127.0.0.1:8500/v1/
认证方式:
# 方式 1: X-Consul-Token header (推荐)
curl -H "X-Consul-Token: <token>" http://127.0.0.1:8500/v1/agent/members
# 方式 2: Bearer token
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8500/v1/agent/members常用查询参数:
dc- 指定数据中心ns- 指定命名空间 (Enterprise)pretty- 格式化 JSON 输出wait=<duration>- 阻塞查询等待时间index=<num>- 阻塞查询索引
Service Discovery (Catalog)
列出所有服务
GET /catalog/services
GET /catalog/services?dc=dc1返回: {"service-name": ["tag1", "tag2"], ...}
查询服务的所有实例
GET /catalog/service/:service_name
GET /catalog/service/redis?dc=dc1&ns=default列出所有节点
GET /catalog/nodes
GET /catalog/nodes?near=_agent注册服务
PUT /catalog/register
{
"Node": "node1",
"Address": "192.168.1.1",
"Service": {
"Service": "redis",
"ID": "redis-1",
"Tags": ["primary", "v1"],
"Address": "127.0.0.1",
"Port": 6379
}
}注销服务
PUT /catalog/deregister
{
"Node": "node1",
"ServiceID": "redis-1"
}Key-Value Store
读取 KV
GET /kv/:key # 单个 key
GET /kv/:prefix?recurse # 递归读取前缀下所有 key
GET /kv/:prefix?keys # 只返回 key 列表
GET /kv/:key?raw # 返回原始值 (text/plain)返回值是 base64 编码，需解码:
curl -s http://127.0.0.1:8500/v1/kv/my-key | jq -r '.[0].Value' | base64 -d写入 KV
PUT /kv/:key
PUT /kv/:key?flags=123 # 附加 flags
PUT /kv/:key?cas=100 # Check-And-Set (乐观锁)
curl -X PUT -d 'my value' http://127.0.0.1:8500/v1/kv/my-key删除 KV
DELETE /kv/:key # 删除单个 key
DELETE /kv/:prefix?recurse # 删除前缀下所有 key
DELETE /kv/:key?cas=100 # Check-And-Set 删除分布式锁
# 获取锁
PUT /kv/:key?acquire=<session-id>
# 释放锁
PUT /kv/:key?release=<session-id>Health Checks
查询节点健康状态
GET /health/node/:node查询服务的健康检查
GET /health/checks/:service
GET /health/checks/redis?passing # 只返回 passing 状态查询健康的服务实例
GET /health/service/:service
GET /health/service/redis?passing # 只返回健康实例按状态查询
GET /health/state/passing
GET /health/state/warning
GET /health/state/critical
GET /health/state/any健康状态: passing, warning, critical
ACL (Access Control)
创建 Token
PUT /acl/create
{
"Name": "my-token",
"Type": "client",
"Rules": "key \"secret/\" { policy = \"read\" }"
}列出 Tokens
GET /acl/list
GET /acl/token/self # 当前 token 信息读取/更新 Token
GET /acl/token/:accessor_id
PUT /acl/token/:accessor_idAgent Operations
查看 Agent 成员
GET /agent/members查看 Agent 自身信息
GET /agent/self查看本地服务
GET /agent/services
GET /agent/service/:service_id注册服务 (Agent 端点)
PUT /agent/service/register
{
"Name": "redis",
"ID": "redis-1",
"Tags": ["primary"],
"Address": "127.0.0.1",
"Port": 6379,
"Check": {
"HTTP": "http://localhost:6379/health",
"Interval": "10s"
}
}注销服务 (Agent 端点)
PUT /agent/service/deregister/:service_idService Mesh (Connect)
查询 Connect 服务
GET /catalog/connect/:service
GET /health/connect/:service?passing查询 Ingress Gateway
GET /health/ingress/:service服务意图 (Intentions)
GET /connect/intentions
POST /connect/intention
{
"SourceName": "web",
"DestinationName": "db",
"Action": "allow"
}
DELETE /connect/intention/:idSessions (分布式锁)
创建 Session
PUT /session/create
{
"Name": "my-lock",
"TTL": "30s",
"Behavior": "delete"
}返回: {"ID": "session-uuid"}
查询 Session
GET /session/info/:session-id
GET /session/node/:node销毁 Session
PUT /session/destroy/:session-idTransactions
原子操作多个 KV 或 Catalog 操作:
PUT /txn
[
{"KV": {"Verb": "set", "Key": "key1", "Value": "dGVzdA=="}},
{"KV": {"Verb": "get", "Key": "key2"}},
{"Service": {"Verb": "register", "Service": {...}}}
]支持的 Verb:
- KV:
set,get,delete,check-index,lock,unlock - Service:
register,deregister
Blocking Queries
使用 index 或 wait 实现长轮询:
# 等待 key 变化
GET /kv/my-key?index=100
GET /kv/my-key?wait=5m&index=100响应头 X-Consul-Index 返回当前索引。
Error Handling
常见 HTTP 状态码:
200- 成功404- 资源不存在400- 请求格式错误403- ACL 权限不足500- 服务器错误
响应头:
X-Consul-Index- 当前状态索引X-Consul-KnownLeader- 是否有已知 leaderX-Consul-LastContact- 最后联系 leader 的时间X-Consul-Default-ACL-Policy- 默认 ACL 策略
References
For detailed API specifications, see:
- api-reference.md - Complete API endpoint reference