Consul HTTP常用接口手册

本手册根据官方资料整理，暂时只收集了最基本最常用的那部分。
由于作者水平有限，涉及企业版和高级功能的接口用法，请您参阅：https://www.consul.io/api-docs 。

代理相关接口：

通常情况下，服务和健康检测是向代理注册的，由代理承担与集群保持数据同步的责任。

代理管理：

查看代理所在主机信息：

返回代理所在主机的运行信息（CPU、内存、硬盘），输出内容视平台不同会有所变化。
用法：
curl \
http://127.0.0.1:8500/v1/agent/host
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/host \
| python -m json.tool
输出：

{
    "CollectionTime": 1639329563697223479,
    "Errors": null,
    "CPU": [
        {
            ......略
        }
    ],
    "Disk": {
            ......略
    },
    "Host": {
            ......略
    },
    "Memory": {
            ......略
    }
}
查看所有代理成员列表：

返回本地代理在集群中看到的成员列表。
相关命令：
consul members
本接口实现的效果与consul members命令相同。
用法：
curl \
http://127.0.0.1:8500/v1/agent/members
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/members \
| python -m json.tool
输出：

[
    {
        "Addr": "192.168.56.101",
        "DelegateCur": 4,
        "DelegateMax": 5,
        "DelegateMin": 2,
        "Name": "node1",
        "Port": 8301,
        "ProtocolCur": 2,
        "ProtocolMax": 5,
        "ProtocolMin": 1,
        "Status": 1,
        "Tags": {
            "acls": "0",
            "bootstrap": "1",
            "build": "1.11.1:2c56447e",
            "dc": "dc1",
            "ft_fs": "1",
            "ft_si": "1",
            "id": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
            "port": "8300",
            "raft_vsn": "3",
            "role": "consul",
            "segment": "",
            "vsn": "2",
            "vsn_max": "3",
            "vsn_min": "2",
            "wan_join_port": "8302"
        }
    }
]
读取本地代理的配置信息：

返回当前代理的配置及相关库版本、网络地址和运动状态信息。
相关命令：
consul info
本接口输出的Stats部分与consul info输出相同。
用法：
curl \
http://127.0.0.1:8500/v1/agent/self
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/self \
| python -m json.tool
输出：

{
    "Config": {
        "Datacenter": "dc1",
        "NodeID": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
        "NodeName": "node1",
        "PrimaryDatacenter": "dc1",
        "Revision": "2c56447e",
        "Server": true,
        "Version": "1.11.1"
    },
    "Coord": {
        "Adjustment": 0,
        "Error": 1.5,
        "Height": 1e-05,
        "Vec": [0,0,0,0,0,0,0,0]
    },
    "Member": {
        "Addr": "192.168.56.101",
        "DelegateCur": 4,
        "DelegateMax": 5,
        "DelegateMin": 2,
        "Name": "node1",
        "Port": 8301,
        "ProtocolCur": 2,
        "ProtocolMax": 5,
        "ProtocolMin": 1,
        "Status": 1,
        "Tags": {
            "acls": "0",
            "bootstrap": "1",
            "build": "1.11.1:2c56447e",
            "dc": "dc1",
            "ft_fs": "1",
            "ft_si": "1",
            "id": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
            "port": "8300",
            "raft_vsn": "3",
            "role": "consul",
            "segment": "",
            "vsn": "2",
            "vsn_max": "3",
            "vsn_min": "2",
            "wan_join_port": "8302"
        }
    },
    "Meta": {
        "consul-network-segment": ""
    },
    "DebugConfig": {
        ......略
    },
    "Stats": {
        ......略
    }
}
重新加载配置：

相关命令：
consul reload
本接口实现的效果与consul reload命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/reload
返回：
不输出任何信息。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/reload
输出：
无

启用/禁用代理维护模式：

在维护模式下，节点将被标记为不可用，并且不会出现在 DNS 或 API 查询中。此 API 调用是幂等的。
维护模式是持久的，但会在代理重新启动时自动恢复到正常状态。
相关命令：
consul maint -enable/-disable
本接口实现的效果与consul maint -enable/-disable命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/maintenance?enable=状态&reason=文字描述
参数：
enable：指定是启用还是禁用维护模式。以URL方式提供。
reason：指定一个文本字符串，解释将节点置于维护模式的原因。以URL方式提供。
返回：
不输出任何信息。
举例：
curl \
--request PUT \
'http://127.0.0.1:8500/v1/agent/maintenance?enable=true&reason=For+API+docs'
输出：
无

监听代理日志流：

代理以chunked的方式阻塞连接，持续推送日志流，直到连接关闭。
相关命令：
consul monitor
本接口实现的效果与consul monitor命令相同。
用法：
curl \
http://127.0.0.1:8500/v1/agent/monitor
参数：
loglevel：指定包含要筛选的日志级别的文本字符串，默认为info。以URL方式提供。
logjson：指定是否以 JSON 格式输出日志，默认为false。以URL方式提供。
返回：
格式视logjson参数而定，默认为文本行。
举例：
curl \
http://127.0.0.1:8500/v1/agent/monitor
输出：

2021-12-13T02:29:26.772+0800 [INFO]  agent: Node entered maintenance mode
2021-12-13T02:29:26.772+0800 [INFO]  agent: Synced check: check=_node_maintenance
2021-12-13T02:29:40.739+0800 [INFO]  agent: Node left maintenance mode
2021-12-13T02:29:40.741+0800 [INFO]  agent: Deregistered check: check=_node_maintenance
配置代理加入集群：

相关命令：
consul join
本接口实现的效果与consul join命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/join/:address
参数：
wan：指定尝试通过 WAN 池加入，默认为false。以URL方式提供。
返回：
输出操作结果信息。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/join/1.2.3.4

配置代理正常退出：

通知本代理从集群中脱离，并且其它代理也会从自己的成员列表中删除自己。操作完成后，代理退出。
相关命令：
consul leave
本接口实现的效果与consul leave命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/leave
返回：
不输出任何信息。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/leave
输出：
无

强制移除故障代理：

当某个代理发生故障后，集群会标识该代理不可用，并且会尝试恢复该代理。可以使用本命令强制移故障代理。
相关命令：
consul force-leave
本接口实现的效果与consul force-leave命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/force-leave/:node
参数：
prune：指定是否从成员列表中强制删除节点，默认为false。以URL方式提供。
wan：指定只应从 WAN 池中删除代理，默认为false。以URL方式提供。
返回：
不输出任何信息。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/force-leave/node1
输出：
无

健康检测：

支持系统级和应用级健康检测的管理。
如果健康检测与服务相关联，则认为它是应用级，否则为系统级。系统级健康检测主要关注节点的健康状态，而应用级则主要关注服务实例的健康状态。
健康检测可以在配置文件中定义，也可以在运行时通过HTTP接口添加。通过HTTP接口创建的健康检测也会在该结点进行持久化。

支持多种健康检测类型，包括：

  1. 定时脚本检测
    调用外部应用程序来执行健康状况检测，以适当的退出代码退出，并可能产生一些输出。输出限制为4KB，大于4kb的输出将被截断。
    默认情况下，脚本检查将配置30秒的超时时间，超时后Consul将尝试强制终止检测脚本和它产生的任何子进程。
    在Consul 0.9.0和更高版本中，代理必须配置-enable-script-checks=true以启用脚本检测。
  2. 定时HTTP检测
    调用HTTP向指定的URL发送请求，服务的状态取决于HTTP响应代码：任何2xx代码都被视为检测通过，429是太多请求的警告，其他任何状态码都代表检测失败。
    默认情况下，HTTP检查是GET请求，除非method字段指定了不同的方法。可以通过header字段来设置其它header字段信息，以字符串列表映射的形式设置。
    同样的，输出限制为4KB，大于4kb的输出将被截断。HTTP检查也支持SSL。默认要求有效的SSL证书，可以通过设置TLSSkipVerify为true关闭证书检查。
  3. 定时TCP检测
    调用TCP连接对指定的IP:PORT地址进行检测，服务的状态取决于连接尝试是否成功。
  4. 定时TTL检测
    TTL检测会在TTL时间内保留上次的检测状态，检测状态必须通过HTTP接口定期更新，如果外部系统无法在给定的TTL内更新状态，则检查设置为失败状态。
    这个检测机制依靠应用程序直接报告其健康状况。例如，健康的应用程序可以定期向HTTP端点发送状态更新;如果应用程序失败，TTL将过期，健康检查进入危险状态。
获取本地代理的健康检测列表：

用法：
curl \
http://127.0.0.1:8500/v1/agent/checks
参数：
filter：指定用于在返回数据之前筛选查询结果的表达式，默认为空。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/checks \
| python -m json.tool
输出：

{
    "mem": {
        "CheckID": "mem",
        "CreateIndex": 0,
        "Definition": {},
        "ExposedPort": 0,
        "Interval": "10s",
        "ModifyIndex": 0,
        "Name": "Memory utilization",
        "Node": "node1",
        "Notes": "",
        "Output": "fork/exec /usr/local/bin/check_mem.py: no such file or directory",
        "ServiceID": "",
        "ServiceName": "",
        "ServiceTags": [],
        "Status": "critical",
        "Timeout": "5s",
        "Type": "script"
    }
}
向本地代理注册健康检测：

用法：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/check/register
参数：
Name：指定健康检测项的名称，必填项。
ID：此健康检测项的唯一ID，默认为空，可由代理自动生成，可选项。
Notes：指定人类可识别的字符串。
Interval：指定运行此健康检测的频率。这是脚本、HTTP、TCP等类型所必需的。
Timeout：指定脚本、HTTP、TCP或其它检查的超时时间，默认10S。
DeregisterCriticalServiceAfter：指定健康检测失败后，超过多长时间取消注册。
Args：指定一个用于脚本检测的命令行参数列表。
HTTP：指定一个HTTP URL的检测，默认为空。
Method：指定HTTP的请求方法，默认为GET。
Body：指定HTTP的请求消息体，默认为空。
Header：指定HTTP的附加请求头，默认为空。
TLSSkipVerify：对HTTPS来说，指定忽略证书检查，默认false。
TCP：指定一个IP:PORT进行连接检测，默认为空。
TTL：指定一个TTL检测，默认10S。
返回：
成功无输出，失败返回错误描述。
举例：
下面增加一个脚本检查。
编辑载体文件payload.json，内容如下：
{
"ID": "mem",
"Name": "Memory utilization",
"DeregisterCriticalServiceAfter": "90m",
"Args": ["/usr/local/bin/check_mem.py", "-limit", "256MB"],
"Interval": "10s",
"Timeout": "5s"
}
执行命令：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/check/register
输出：
无

从本地代理注销指定健康检测：

用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/deregister/:check_id
参数：
check_id：指定要取消注册的检查的唯一ID，如果ID不存在，则不执行任何操作。
返回：
成功无输出，失败返回错误描述。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/deregister/mem
输出：
无

重置TTL健康检测：

用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/pass/:check_id
参数：
check_id：指定要取消注册的健康检测的唯一ID，如果ID不存在，则不执行任何操作。
note：指定人类可读的描述。以URL方式提供。
返回：
成功无输出，失败返回错误描述。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/pass/ttl
输出：
无

TTL检测只能用于TTL类型，使用下面的载体文件创建TTL检测：
{
"ID": "ttl",
"Name": "ttl check",
"DeregisterCriticalServiceAfter": "90m",
"TTL": "30s"
}

本地服务管理：

同健康检测一样，可以通过配置文件添加服务，也可以通过HTTP接口动态添加。

获取本地代理注册的所有服务列表：

如果服务有定义应用内健康检测，此接口响应并不展示。
查看应用内健康检测需要使用健康检测相关接口。
用法：
curl \
http://127.0.0.1:8500/v1/agent/services
参数：
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/services \
| python -m json.tool
输出：

{
    "web1": {
        "Address": "",
        "Datacenter": "dc1",
        "EnableTagOverride": false,
        "ID": "web1",
        "Meta": {},
        "Port": 80,
        "Service": "web",
        "Tags": [
            "rails"
        ],
        "Weights": {
            "Passing": 1,
            "Warning": 1
        }
    }
}
获取本地某个服务ID的完整服务定义：

同样的，本接口也不返回应用内健康检测定义。
用法：
curl \
http://127.0.0.1:8500/v1/agent/service/:service_id
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/agent/service/web1 \
| python -m json.tool
输出：

{
    "Address": "",
    "ContentHash": "57d9f57dcdf58e5c",
    "Datacenter": "dc1",
    "EnableTagOverride": false,
    "ID": "web1",
    "Meta": {},
    "Port": 80,
    "Service": "web",
    "Tags": [
        "rails"
    ],
    "Weights": {
        "Passing": 1,
        "Warning": 1
    }
}
获取本地指定服务名的所有实例运行状况：

用法：
curl \
http://localhost:8500/v1/agent/health/service/name/:service_name
参数：
format：指定返回的消息格式，支持JSON(json)和纯文本(text)，默认为JSON。以URL方式提供。
返回：
格式视format参数而定。
举例：
curl \
http://localhost:8500/v1/agent/health/service/name/web \
| python -m json.tool
输出：

[
    {
        "AggregatedStatus": "passing",
        "Checks": [],
        "Service": {
            "Address": "",
            "Datacenter": "dc1",
            "EnableTagOverride": false,
            "ID": "web1",
            "Meta": {},
            "Port": 80,
            "Service": "web",
            "Tags": [
                "rails"
            ],
            "Weights": {
                "Passing": 1,
                "Warning": 1
            }
        }
    }
]
获取本地指定服务ID的实例运行状况：

用法：
curl \
http://localhost:8500/v1/agent/health/service/id/:service_id
参数：
format：指定返回的消息格式，支持JSON(json)和纯文本(text)，默认为JSON。以URL方式提供。
返回：
格式视format参数而定。
举例：
curl \
http://localhost:8500/v1/agent/health/service/id/web1 \
| python -m json.tool
输出：

{
    "AggregatedStatus": "passing",
    "Checks": [],
    "Service": {
        "Address": "",
        "Datacenter": "dc1",
        "EnableTagOverride": false,
        "ID": "web1",
        "Meta": {},
        "Port": 80,
        "Service": "web",
        "Tags": [
            "rails"
        ],
        "Weights": {
            "Passing": 1,
            "Warning": 1
        }
    }
}
向本地代理注册/更新服务：

将具有可选运行状况检查的服务添加/更新到本地代理。
代理负责管理其本地服务的状态，并将有关其本地服务的更新发送到服务器，以使全局编录保持同步。
相关命令：
consul services register
本接口实现的效果与consul services register命令相同。
用法：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/service/register?replace-existing-checks=true
参数：
replace-existing-checks：对请求进行检查，删除没有健康检查的部分。以URL方式提供。
Name：指定服务名称，必选。
ID：指定服务ID，如果未指定，默认为服务名称。
Tags：指定标记，用于筛选。
Address：指定服务的地址。
Port：指定服务的端口。
Meta：指定 KV 元数据。
Weights：指定服务的权重。
Check：指定健康检测。具体设置请参考健康检测部分。
返回：
成功无输出，失败返回错误描述。
举例：
编辑载体文件payload.json，内容如下：
{
"Name": "redis",
"ID": "redis1",
"Tags": ["primary", "v1"],
"Address": "127.0.0.1",
"Port": 6379,
"Meta": {
"redis_version": "4.0"
},
"EnableTagOverride": false,
"Check": {
"DeregisterCriticalServiceAfter": "30m",
"Args": ["/usr/local/bin/check_redis.py"],
"Interval": "10s",
"Timeout": "5s"
},
"Weights": {
"Passing": 10,
"Warning": 1
}
}
执行命令：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/service/register?replace-existing-checks=true
输出：
无

从本地代理中移除指定服务：

服务移除后，其相关的健康检查也一并被清理。
相关命令：
consul services deregister
本接口实现的效果与consul services deregister命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/deregister/:service_id
返回：
成功无输出，失败返回错误描述。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/deregister/redis1
输出：
无

启用/禁用某个服务的维护模式：

相关命令：
consul maint -enable/-disable -service=service_id
本接口实现的效果与consul maint -enable/-disable -service=service_id命令相同。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/maintenance/:service_id?enable=true&reason=For+the+docs
参数：
enable：指定是启用还是禁用维护模式。以URL方式提供。
reason：指定一个文本字符串，解释将节点置于维护模式的原因。以URL方式提供。
返回：
成功无输出，失败返回错误描述。
举例：
curl \
--request PUT \
'http://127.0.0.1:8500/v1/agent/service/maintenance/web?enable=true&reason=For+the+docs'
输出：
无

目录相关接口：

获取所有数据中心列表：

相关命令：
consul catalog datacenters
本接口输出与consul catalog datacenters输出相同。
用法：
curl \
http://127.0.0.1:8500/v1/catalog/datacenters
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/catalog/datacenters
输出：
["dc1"]

获取在指定数据中心注册的节点：

相关命令：
consul catalog nodes
本接口输出与consul catalog nodes输出相同。
用法：
curl \
http://127.0.0.1:8500/v1/catalog/nodes
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
near：指定一个中心节点，按平均通信往返时间排序。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/catalog/nodes \
| python -m json.tool
输出：

[
    {
        "Address": "192.168.56.101",
        "CreateIndex": 5,
        "Datacenter": "dc1",
        "ID": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
        "Meta": {
            "consul-network-segment": ""
        },
        "ModifyIndex": 7,
        "Node": "node1",
        "TaggedAddresses": {
            "lan": "192.168.56.101",
            "lan_ipv4": "192.168.56.101",
            "wan": "192.168.56.101",
            "wan_ipv4": "192.168.56.101"
        }
    }
]
获取在指定数据中心注册的服务：

仅仅列出注册的服务名称，不包括服务ID列表。
相关命令：
consul catalog services
本接口输出与consul catalog services输出相同。
用法：
curl \
http://127.0.0.1:8500/v1/catalog/services
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/catalog/services \
| python -m json.tool
输出：

{
    "consul": [],
    "web": [
        "rails"
    ]
}
获取在指定数据中心注册的指定服务的实例列表：

用法：
curl \
http://127.0.0.1:8500/v1/catalog/service/:service_name
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
near：指定一个中心节点，按平均通信往返时间排序。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/catalog/service/web \
| python -m json.tool
输出：

[
    {
        "Address": "192.168.56.101",
        "CreateIndex": 8,
        "Datacenter": "dc1",
        "ID": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
        "ModifyIndex": 8,
        "Node": "node1",
        "NodeMeta": {
            "consul-network-segment": ""
        },
        "ServiceAddress": "",
        "ServiceConnect": {},
        "ServiceEnableTagOverride": false,
        "ServiceID": "web1",
        "ServiceKind": "",
        "ServiceMeta": {},
        "ServiceName": "web",
        "ServicePort": 80,
        "ServiceProxy": {
            "Expose": {},
            "MeshGateway": {},
            "Mode": ""
        },
        "ServiceSocketPath": "",
        "ServiceTags": [
            "rails"
        ],
        "ServiceWeights": {
            "Passing": 1,
            "Warning": 1
        },
        "TaggedAddresses": {
            "lan": "192.168.56.101",
            "lan_ipv4": "192.168.56.101",
            "wan": "192.168.56.101",
            "wan_ipv4": "192.168.56.101"
        }
    }
]
获取在指定节点上注册的服务的实例列表：

用法：
curl \
http://127.0.0.1:8500/v1/catalog/node/:node
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/catalog/node/node1 \
| python -m json.tool
输出：

{
    "Node": {
        "Address": "192.168.56.101",
        "CreateIndex": 5,
        "Datacenter": "dc1",
        "ID": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
        "Meta": {
            "consul-network-segment": ""
        },
        "ModifyIndex": 7,
        "Node": "node1",
        "TaggedAddresses": {
            "lan": "192.168.56.101",
            "lan_ipv4": "192.168.56.101",
            "wan": "192.168.56.101",
            "wan_ipv4": "192.168.56.101"
        }
    },
    "Services": {
        "consul": {
            "Address": "",
            "Connect": {},
            "CreateIndex": 5,
            "EnableTagOverride": false,
            "ID": "consul",
            "Meta": {
                "non_voter": "false",
                "raft_version": "3",
                "read_replica": "false",
                "serf_protocol_current": "2",
                "serf_protocol_max": "5",
                "serf_protocol_min": "1",
                "version": "1.11.1"
            },
            "ModifyIndex": 5,
            "Port": 8300,
            "Proxy": {
                "Expose": {},
                "MeshGateway": {},
                "Mode": ""
            },
            "Service": "consul",
            "Tags": [],
            "Weights": {
                "Passing": 1,
                "Warning": 1
            }
        },
        "web": {
            "Address": "",
            "Connect": {},
            "CreateIndex": 8,
            "EnableTagOverride": false,
            "ID": "web1",
            "Meta": null,
            "ModifyIndex": 8,
            "Port": 80,
            "Proxy": {
                "Expose": {},
                "MeshGateway": {},
                "Mode": ""
            },
            "Service": "web",
            "Tags": [
                "rails"
            ],
            "Weights": {
                "Passing": 1,
                "Warning": 1
            }
        }
    }
}

健康检测相关接口：

获取指定节点上的健康检测列表：

用法：
curl \
http://127.0.0.1:8500/v1/health/node/:node
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/health/node/node1 \
| python -m json.tool
输出：

[
    {
        "CheckID": "serfHealth",
        "CreateIndex": 5,
        "Definition": {},
        "ExposedPort": 0,
        "Interval": "",
        "ModifyIndex": 5,
        "Name": "Serf Health Status",
        "Node": "node1",
        "Notes": "",
        "Output": "Agent alive and reachable",
        "ServiceID": "",
        "ServiceName": "",
        "ServiceTags": [],
        "Status": "passing",
        "Timeout": "",
        "Type": ""
    }
]
获取指定服务名的健康检测列表：

用法：
curl \
http://127.0.0.1:8500/v1/health/checks/:service_name
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
near：指定一个中心节点，按平均通信往返时间排序。以URL方式提供。
node-meta：指定格式为 的所需节点元数据键/值对。此参数可以多次指定，并将结果筛选到具有指定键/值对的节点。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/health/checks/web \
| python -m json.tool
输出：
[
{
"CheckID": "service:web1",
"CreateIndex": 40362,
"Definition": {},
"ExposedPort": 0,
"Interval": "",
"ModifyIndex": 40362,
"Name": "Service 'web' check",
"Node": "node1",
"Notes": "",
"Output": "Get "http://localhost:8080": dial tcp [::1]:8080: connect: connection refused",
"ServiceID": "web1",
"ServiceName": "web",
"ServiceTags": [
"rails"
],
"Status": "critical",
"Timeout": "",
"Type": "http"
}
]

获取指定服务名的所有服务实例列表：

用法：
curl \
http://127.0.0.1:8500/v1/health/service/:service_name
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
near：指定一个中心节点，按平均通信往返时间排序。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
passing：指定服务器应仅返回所有检查都处于该状态的节点，默认false。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/health/service/web?passing \
| python -m json.tool
输出：

[
    {
        "Checks": [
            {
                "CheckID": "serfHealth",
                "CreateIndex": 5,
                "Definition": {},
                "ExposedPort": 0,
                "Interval": "",
                "ModifyIndex": 5,
                "Name": "Serf Health Status",
                "Node": "node1",
                "Notes": "",
                "Output": "Agent alive and reachable",
                "ServiceID": "",
                "ServiceName": "",
                "ServiceTags": [],
                "Status": "passing",
                "Timeout": "",
                "Type": ""
            }
        ],
        "Node": {
            "Address": "192.168.56.101",
            "CreateIndex": 5,
            "Datacenter": "dc1",
            "ID": "ec3c13cf-6c38-7643-3305-44fe559fea3c",
            "Meta": {
                "consul-network-segment": ""
            },
            "ModifyIndex": 7,
            "Node": "node1",
            "TaggedAddresses": {
                "lan": "192.168.56.101",
                "lan_ipv4": "192.168.56.101",
                "wan": "192.168.56.101",
                "wan_ipv4": "192.168.56.101"
            }
        },
        "Service": {
            "Address": "",
            "Connect": {},
            "CreateIndex": 8,
            "EnableTagOverride": false,
            "ID": "web1",
            "Meta": null,
            "ModifyIndex": 8,
            "Port": 80,
            "Proxy": {
                "Expose": {},
                "MeshGateway": {},
                "Mode": ""
            },
            "Service": "web",
            "Tags": [
                "rails"
            ],
            "Weights": {
                "Passing": 1,
                "Warning": 1
            }
        }
    }
]
获取指定状态的所有健康检查列表：

用法：
curl \
http://127.0.0.1:8500/v1/health/state/:state
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
near：指定一个中心节点，按平均通信往返时间排序。以URL方式提供。
node-meta：指定格式为 的所需节点元数据键/值对。此参数可以多次指定，并将结果筛选到具有指定键/值对的节点。以URL方式提供。
filter：指定用于在返回数据之前筛选查询结果的表达式。以URL方式提供。
返回：
格式为application/json，内容为具体的json消息体。
举例：
curl \
http://127.0.0.1:8500/v1/health/state/passing \
| python -m json.tool
输出：

[
    {
        "CheckID": "serfHealth",
        "CreateIndex": 5,
        "Definition": {},
        "ExposedPort": 0,
        "Interval": "",
        "ModifyIndex": 5,
        "Name": "Serf Health Status",
        "Node": "node1",
        "Notes": "",
        "Output": "Agent alive and reachable",
        "ServiceID": "",
        "ServiceName": "",
        "ServiceTags": [],
        "Status": "passing",
        "Timeout": "",
        "Type": ""
    }
]

KV操作相关接口：

可用于分布式服务配置存储。
但是需要注意各个数据中心之间的KV是不同步的，并且每个KV的值大小限制为512KB。

写入KV操作：

相关命令：
consul kv put
本接口实现的效果与consul kv put命令相同。
用法：
curl \
--request PUT \
--data @contents \
http://127.0.0.1:8500/v1/kv/:key
或
curl \
--request PUT \
--data-binary @contents \
http://127.0.0.1:8500/v1/kv/:key
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
cas：指定CAS操作。以URL方式提供。
flags：附加标志。以URL方式提供。
acquire：提供要在锁定获取操作中使用的会话ID。以URL方式提供。
release：提供要在释放操作中使用的会话ID。以URL方式提供。
返回：
格式为application/json，成功内容为true，失败为false。
举例：
curl \
--request PUT \
--data 123 \
http://127.0.0.1:8500/v1/kv/test
输出：
true

读取KV操作：

相关命令：
consul kv get
本接口实现的效果与consul kv get命令相同。
用法：
curl \
http://127.0.0.1:8500/v1/kv/:key
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
recurrse：指定查找是否应为递归查找并视为前缀而不是文本匹配项，默认为false。以URL方式提供。
返回：
格式为application/json。
举例：
curl \
http://127.0.0.1:8500/v1/kv/test \
| python -m json.tool
输出：

[
    {
        "CreateIndex": 21883,
        "ModifyIndex": 21883,
        "LockIndex": 0,
        "Key": "test",
        "Value": "MTIz",
        "Flags": 0
    }
]

说明：
CreateIndex：表示创建条目时间的内部索引值。
ModifyIndex：表示修改条目时间的内部索引值。
LockIndex：表示锁定条目时间的内部索引值。
Key：键名。
Value：Base64编码后的键值。
Flags：附加标志。

删除KV操作：

相关命令：
consul kv delete
本接口实现的效果与consul kv delete命令相同。
用法：
curl \
--request DELETE \
http://127.0.0.1:8500/v1/kv/:key
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
cas：指定CAS操作。以URL方式提供。
recurse：指定删除具有指定前缀的所有键，否则将仅删除完全匹配的密钥，默认为false。以URL方式提供。
返回：
格式为application/json，成功内容为true，失败为false。
举例：
curl \
--request DELETE \
http://127.0.0.1:8500/v1/kv/test
输出：
true

会话操作相关接口：

会话机制可用于构建分布式锁。
会话作为节点、健康检查和KV数据之间的绑定层，旨在提供粒度锁定。

一个会话可以同时关联多个对象。

当发生以下情形时，会话会被销毁：

  1. 会话关联的节点销毁
  2. 关联的任一健康检测注销
  3. 关联的任一健康检测进入Critical状态
  4. 会话被显示删除
  5. 会话TTL到期
    会话被销毁后，根据创建会话时指定的行为执行相应的动作。
创建会话：

用法：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/session/create
参数：
Name：指定会话的可读名称。
Node：指定节点的名称，必须引用已注册的节点。
LockDelay：指定锁定延迟的持续时间。
Behavior：控制会话无效时要采取的行为。可选值：release（默认）、delete。
release——导致任何持有的锁被释放。
delete——导致删除任何持有的锁。
TTL：指定会话的持续时间（介于 10 秒和 86400 秒之间）。如果提供，则在 TTL 到期之前未续订会话，则该会话将失效。
返回：
格式为application/json，成功内容为创建的UUID。
举例：
准备负载文件payload.json，内容如下：
{
"LockDelay": "10s",
"Name": "sess1",
"Node": "node1",
"Behavior": "delete",
"TTL": "60s"
}
执行：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/session/create
输出：
{"ID":"c8615b6c-55c7-bc7d-1a71-4e427269d6ac"}

删除会话：

销毁具有给定名称的会话。如果会话 UUID 格式不正确，则返回错误。
如果会话 UUID 不存在或已过期，则仍返回 200（操作是幂等的）。
用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/destroy/:uuid
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，成功内容为true，失败为false。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/destroy/c8615b6c-55c7-bc7d-1a71-4e427269d6ac
输出：
true

续订会话：

用法：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/renew/:uuid
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，如果会话存在返回json内容，否则返回[]。
举例：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/renew/c8615b6c-55c7-bc7d-1a71-4e427269d6ac
输出：

[
    {
        "Behavior": "delete",
        "CreateIndex": 23154,
        "ID": "c8615b6c-55c7-bc7d-1a71-4e427269d6ac",
        "LockDelay": 10000000000,
        "ModifyIndex": 23154,
        "Name": "sess1",
        "Node": "node1",
        "NodeChecks": [
            "serfHealth"
        ],
        "ServiceChecks": null,
        "TTL": "60s"
    }
]
读取会话信息：

用法：
curl \
http://127.0.0.1:8500/v1/session/info/:uuid
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，如果会话存在返回json内容，否则返回[]。
举例：
curl \
http://127.0.0.1:8500/v1/session/info/c8615b6c-55c7-bc7d-1a71-4e427269d6ac \
| python -m json.tool
输出：

[
    {
        "Behavior": "delete",
        "CreateIndex": 23095,
        "ID": "c8615b6c-55c7-bc7d-1a71-4e427269d6ac",
        "LockDelay": 10000000000,
        "ModifyIndex": 23095,
        "Name": "sess1",
        "Node": "node1",
        "NodeChecks": [
            "serfHealth"
        ],
        "ServiceChecks": null,
        "TTL": "60s"
    }
]
获取指定节点的会话列表：

用法：
curl \
http://127.0.0.1:8500/v1/session/node/:node
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，如果会话存在返回json内容，否则返回[]。
举例：
curl \
http://127.0.0.1:8500/v1/session/node/node1
输出：

[
    {
        "Behavior": "delete",
        "CreateIndex": 23128,
        "ID": "2b932f71-711c-bdd3-c7b6-3f3c8cacf0a6",
        "LockDelay": 10000000000,
        "ModifyIndex": 23128,
        "Name": "sess1",
        "Node": "node1",
        "NodeChecks": [
            "serfHealth"
        ],
        "ServiceChecks": null,
        "TTL": "60s"
    }
]
获取所有会话列表：

用法：
curl \
http://127.0.0.1:8500/v1/session/list
参数：
dc：指定要操作的数据中心，默认为当前代理所属的数据中心。以URL方式提供。
返回：
格式为application/json，如果会话存在返回json内容，否则返回[]。
举例：
curl \
http://127.0.0.1:8500/v1/session/list
输出：

[
    {
        "Behavior": "delete",
        "CreateIndex": 23140,
        "ID": "ef73ad18-af5a-1bbb-e317-9e33e30cd304",
        "LockDelay": 10000000000,
        "ModifyIndex": 23140,
        "Name": "sess1",
        "Node": "node1",
        "NodeChecks": [
            "serfHealth"
        ],
        "ServiceChecks": null,
        "TTL": "60s"
    }
]

分布式锁的应用：

步骤：

  1. 创建会话，指定TTL超时时间和超时操作行为release。
    这里指定超时时间是为了防止死锁。
  2. 创建或更新KV，并使用acquire参数关联上一步返回的会话ID。
    这里会尝试以加锁的方式占用会话，如果入锁成功，则创建或更新KV，并将二者建立关联。
  3. 如果上一步执行失败，命令并不会阻塞，需延时一段时间主动尝试，直到操作成功。
  4. 在超时时间内，锁的持有者用完锁，主动释放锁。
  5. 在超时时间内，如果锁的持有者想继续持有锁，需主动续租会话。

举例：
准备载体文件payload.json，内容如下：
{
"LockDelay": "10s",
"Name": "sess1",
"Node": "node1",
"Behavior": "release",
"TTL": "300s"
}
执行命令创建会话：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/session/create
输出：
{"ID":"050f54b7-0ef6-97d6-212f-02144fce45a5"}
然后继续执行命令创建KV：
curl \
--request PUT \
--data 123 \
http://127.0.0.1:8500/v1/kv/test?acquire=050f54b7-0ef6-97d6-212f-02144fce45a5
输出：
true
若想释放锁执行命令：
curl \
--request PUT \
--data 123 \
http://127.0.0.1:8500/v1/kv/test?release=050f54b7-0ef6-97d6-212f-02144fce45a5
若想续租会话执行命令：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/renew/050f54b7-0ef6-97d6-212f-02144fce45a5 \
| python -m json.tool

需续租约的分布式配置应用：

步骤：

  1. 创建会话，指定TTL超时时间和超时操作行为delete。
  2. 创建或更新KV，并使用acquire参数关联上一步返回的会话ID。
  3. 定期续订会话，若没有及时续订，则超时后会话和KV均被删除。

举例：
准备载体文件payload.json，内容如下：
{
"LockDelay": "10s",
"Name": "sess1",
"Node": "node1",
"Behavior": "delete",
"TTL": "300s"
}
执行命令创建会话：
curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/session/create
输出：
{"ID":"87288297-6e53-d5d2-f592-a1e599c0fef5"}
然后继续执行命令创建KV：
curl \
--request PUT \
--data 123 \
http://127.0.0.1:8500/v1/kv/test?acquire=87288297-6e53-d5d2-f592-a1e599c0fef5
输出：
true
继续执行命令续租：
curl \
--request PUT \
http://127.0.0.1:8500/v1/session/renew/87288297-6e53-d5d2-f592-a1e599c0fef5 \
| python -m json.tool
输出：

[
    {
        "Behavior": "delete",
        "CreateIndex": 23237,
        "ID": "87288297-6e53-d5d2-f592-a1e599c0fef5",
        "LockDelay": 10000000000,
        "ModifyIndex": 23237,
        "Name": "sess1",
        "Node": "node1",
        "NodeChecks": [
            "serfHealth"
        ],
        "ServiceChecks": null,
        "TTL": "300s"
    }
]
读取会话信息：

curl \
http://127.0.0.1:8500/v1/session/info/87288297-6e53-d5d2-f592-a1e599c0fef5 \
| python -m json.tool
输出与会话续租输出相同，略。

读取KV：

curl \
http://127.0.0.1:8500/v1/kv/test \
| python -m json.tool
输出：

[
    {
        "CreateIndex": 23244,
        "Flags": 0,
        "Key": "test",
        "LockIndex": 1,
        "ModifyIndex": 23244,
        "Session": "87288297-6e53-d5d2-f592-a1e599c0fef5",
        "Value": "MTIz"
    }
]

可以看到KV有关联LockIndex和Session。

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 213,752评论 6赞 493
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 91,100评论 3赞 387
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 159,244评论 0赞 349
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 57,099评论 1赞 286
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 66,210评论 6赞 385
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 50,307评论 1赞 292
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 39,346评论 3赞 412
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 38,133评论 0赞 269
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 44,546评论 1赞 306
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,849评论 2赞 328
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,019评论 1赞 341
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 34,702评论 4赞 337
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 40,331评论 3赞 319
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,030评论 0赞 21
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,260评论 1赞 267
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 46,871评论 2赞 365
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 43,898评论 2赞 351

推荐阅读更多精彩内容

  • consul
    [转] 1. 什么是consul？ 是一个服务管理软件。支持多数据中心下，分布式高可用的，服务发现和配置共享。co...
    baboon阅读 3,039评论 0赞 7
  • Consul 的安装与基本使用
    什么是 Consul​ Consul是一种服务网格解决方案，提供具有服务发现，配置和分段功能的全功能控制平面。这些...
    P_ursuit阅读 2,674评论 0赞 0
  • Consul运维和监控
    简介 这个章节中的内容包含一系列运维高级指南，包括高级网络配置、安全设置、中断恢复、监控和故障排除。 Consul...
    fossilman阅读 5,616评论 0赞 1
  • consul acl 简单记录
    记录consul acl的简单实践 一 准备阶段 1 准备acl.json 写入如下信息 { "acl_dat...
    wwq2020阅读 440评论 0赞 0
  • consul
    Consul是一个分布式高可用的系统，它有以下特点： 服务发现：Consul客户能够注册一个服务，比如api或my...
    aneirin阅读 6,102评论 0赞 4