Caddy进阶之Caddy API

对Caddy有了初步认知之后，我们知道Caddy常见的使用方案是JSON+API或Caddyfile+CLI。本文将进一步介绍，如何使用JSON搭配Caddy API管理Caddy服务的相关内容。

1.Caddy API简介

通过HTTP形式访问Caddy的管理终端，我们可以对Caddy的配置进行各种操作，Caddy默认的管理终端地址是：localhost:2019。
值得一提的是，Caddy配置具有持久性。比如，对Caddy配置每一次的有效更改，都会被保存到磁盘上。当因为某种原因导致Caddy服务宕机，你可以通过–resume选项（caddy run –resume）重启Caddy服务，并使得Caddy配置恢复到服务宕机前最新的配置状态。

Caddy常用API介绍如下
（1）POST /load
作用：设置或覆盖当前配置，阻塞调用。
对配置的更改是轻量级且高效的，并不会导致Caddy服务宕机，如果配置更新失败，Caddy服务会将配置回滚到上一次的配置状态。
示例：

其中，
-H 选项中的Content-Type头，指明了请求正文中使用的配置格式为json。如果你的配置文件为其它Caddy支持的格式，需要在此指明；
-d，指定了配置文件数据，且-d会移除文件中的换行符。如果需要保留换行符，请用–data-binary替代。比如：

（2）POST /stop
作用：关闭Caddy服务并安全退出。如果只停止配置而不退出Caddy服务，使用DELETE /config/
示例：

（3）GET /config/[path]
作用：将指定路径上的Caddy配置输出，返回格式为JSON。
示例1，输出完整的配置：

示例2，输出监听地址：

（4）POST /config/[path]
作用：修改path指定路径上的配置，为请求体中的JSON数据。
如果目标路径指向的是一个JSON数组，此API的作用是将请求体中的JSON配置项追加到数组中，此外，若path路径以/…结尾，表明/…前的元素为数组，也可以将一个或多个请求中的JSON配置项追加到此数组中；（类似于go语言中slice对象的append方法）
如果目标路径指向的是一个JSON对象，次API的作用是设置或更新这个对象；
示例1，追加一个地址：

示例2，追加多个地址：

（5）PUT /config/[path]
作用：在path指定路径上新增一个配置，配置为请求体中的JSON数据。类似于POST /config/[path]，不同点在于PUT要求path指定的对象是不存在的，因为PUT旨在新建一个值。（见示例2）
如果目标路径指向的是数组中的一个索引位置，则将请求体中的JSON配置插入此位置；
如果目标路径指向的是一个对象，则使用请求体中的JSON配置创建一个新值；
示例1，在listen[0]插入一个地址：

示例2，修改body对象：（错误的示例）

报错，修改body对象的值失败，可见PUT API要求path指定的元素必须是不存在的。

思考，如果我们确实想要修改这个body对象而不是新建一个body对象，应该怎么做呢？
使用POST方法，如下所示：

（6）PATCH /config/[path]
作用：替换path指定路径的对象，替换为请求中的JSON数据。
示例：替换监听地址

（7）Delete /config/[path]
作用：删除path指定路径上的对象。
示例1，删除服务example：

示例2，卸载整个配置：

2.使用@id

通过上面Caddy API的介绍，我们发现如果需要修改JSON配置中的某一个对象，首先需要通过path来指定待修改对象。如果这个对象的修改很频繁，就显得有些繁琐。所以，Caddy提供了@id特性，将某一个对象用@id标示，之后的修改可以直接通过@id来操作。
比如，将某一个反向代理的配置做如下@id标示：

当修改upstreams时，path可以这样指定为：

 

参考：
[1] https://caddyserver.com/docs/api