API教程

本教程将向你展示如何使用Caddy的管理API，这使得以可编程方式实现自动化成为可能。

目标：

  • 🔲 运行守护程序
  • 🔲 给 Caddy 一个配置
  • 🔲 测试配置
  • 🔲 替换活动配置
  • 🔲 遍历配置
  • 🔲 使用@id标签

必备：

  • 基本的终端/命令行技能
  • 基本的JSON经验
  • PATH支持caddy和curl

要启动 Caddy 守护程序，请使用run子命令：

  1. caddy run

这永远阻塞，但它在做什么？此刻……什么都没有。默认情况下，Caddy的配置（“config”）为空白。我们可以使用另一个终端中的管理API来验证这一点：

  1. curl localhost:2019/config/

我们可以通过给它一个配置来使Caddy变得有用。一种方法是向 /load端点发出 POST 请求。就像任何 HTTP 请求一样，有很多方法可以做到这一点，但在本教程中，我们将使用curl。

你的第一个配置

为了能发起请求，我们需要进行配置。Caddy的配置只是一个JSON文档 （或任何能转换为JSON的文件）。

将下面的内容保存到JSON文件：

  1. {
  2.     "apps": {
  3.         "http": {
  4.             "servers": {
  5.                 "example": {
  6.                     "listen": [":2015"],
  7.                     "routes": [
  8.                         {
  9.                             "handle": [{
  10.                                 "handler": "static_response",
  11.                                 "body": "Hello, world!"
  12.                             }]
  13.                         }
  14.                     ]
  15.                 }
  16.             }
  17.         }
  18.     }
  19. }

然后上传：

  1. curl localhost:2019/load \
  2.     -X POST \
  3.     -H "Content-Type: application/json" \
  4.     -d @caddy.json

我们可以验证 Caddy 是否通过另一个 GET 请求应用了我们的新配置：

  1. curl localhost:2019/config/

通过在浏览器中访问localhost:2015或使用curl命令来测试它是否有效：

  1. curl localhost:2015
  2. Hello, world!

如果你看到Hello, world!，就恭喜啦——它已经工作了！确保你的配置按预期工作始终是一个好主意，尤其是在部署到生产环境之前。

  1. {
  2.     "handler": "static_response",
  3.     "body": "I can do hard things."
  4. }

保存配置文件，然后通过再次运行相同的POST请求来更新Caddy的活动配置：

  1. curl localhost:2019/load \
  2.     -X POST \
  3.     -H "Content-Type: application/json" \
  4.     -d @caddy.json

为了更好地衡量，请验证配置是否已更新：

  1. curl localhost:2019/config/

通过在浏览器中刷新页面（或再次运行curl）来测试它，你将看到一条鼓舞人心的消息！

遍历配置

让我们使用 Caddy API 的强大功能来进行更改，而不需要修改我们的配置文件，而不是上传整个配置文件。

通过像我们上面所做的那样替换整个配置来对生产服务器进行少量更改可能是危险的；这就像拥有对文件系统的 root 访问权限。Caddy 的 API 允许你限制更改的范围，以确保配置的其他部分不会被意外更改。 使用请求 URI 的路径，我们可以遍历配置结构并仅更新消息字符串（如果被剪裁，请确保向右滚动）：

Instead of uploading the entire config file for a small change, let’s use a powerful feature of Caddy’s API to make the change without ever touching our config file.

使用请求 URI 的路径，我们可以遍历配置结构并仅更新消息字符串（如果被遮挡，请确保向右滚动）：

  1. curl \
  2.     localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
  3.     -X POST \
  4.     -H "Content-Type: application/json" \
  5.     -d '"Work smarter, not harder."'

你可以验证它是否适用于类似的GET请求，例如：

  1. curl localhost:2019/config/apps/http/servers/example/routes

你应该看到：

  1. [{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]

重要提示： 显而易见，一旦你使用API进行配置，原始配置文件并不会被修改，这样你的配置文件就过时了。有几种方法可以处理这个问题：

  • 使用--resume作为caddy run命令的最后一个参数。
  • 不要混合使用配置文件和API两种方式进行更改; 始终使用同一种方式。
  • 使用GET请求导出Caddy的新配置 (不如前两个选项推荐)。

在JSON中使用@id

配置遍历当然有用，但是路径有点长，你不觉得吗？

我们可以给我们的处理对象一个@id标签，使它更容易访问：

  1. curl \
  2.     localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
  3.     -X POST \
  4.     -H "Content-Type: application/json" \
  5.     -d '"msg"'

这给我们的处理对象添加了一个属性：”@id”: “msg”，所以它现在看起来像这样：

  1. {
  2.     "@id": "msg",
  3.     "body": "Work smarter, not harder.",
  4.     "handler": "static_response"
  5. }

然后我们可以直接访问它：

  1. curl localhost:2019/id/msg

现在我们也通过更短的路径更改消息：

  1. curl \
  2.     localhost:2019/id/msg/body \
  3.     -X POST \
  4.     -H "Content-Type: application/json" \
  5.     -d '"Some shortcuts are good."'

并再次检查：

  1. curl localhost:2019/id/msg/body