API 教程

本教程将向您展示如何使用 Caddy 的管理 API，它使以可编程的方式进行自动化成为可能。

目标

🔲 运行守护进程
🔲 为 Caddy 提供配置
🔲 测试配置
🔲 替换活动配置
🔲 遍历配置
🔲 使用 @id 标签

先决条件

基本的终端/命令行技能
基本的 JSON 经验
caddy 和 curl 在您的 PATH 中

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

caddy run

这会永远阻塞，但它在做什么？目前...什么也没做。默认情况下，Caddy 的配置（“config”）是空白的。我们可以使用另一个终端中的管理 API 来验证这一点

curl localhost:2019/config/

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

您的第一个配置

为了准备我们的请求，我们需要创建一个配置。Caddy 的配置只是一个 JSON 文档（或任何转换为 JSON 的内容）。

将此保存到 JSON 文件

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

然后上传它

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

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

curl localhost:2019/config/

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

curl localhost:2015
Hello, world!

如果您看到Hello, world!，那么恭喜您 - 它正在工作！在部署到生产环境之前，始终确保您的配置按预期工作，这一点很重要。

让我们将我们的欢迎消息从“Hello world！”更改为更具激励性的内容：“I can do hard things”。在您的配置文件中进行此更改，以便处理程序对象现在看起来像这样

{
	"handler": "static_response",
	"body": "I can do hard things."
}

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

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

为了保险起见，请验证配置是否已更新

curl localhost:2019/config/

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

配置遍历

与其为了一个小更改而上传整个配置文件，不如让我们使用 Caddy API 的强大功能来进行更改，而无需触碰我们的配置文件。

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

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

您可以使用类似的 GET 请求来验证它是否有效，例如

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

您应该看到

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

重要说明：这应该很明显，但是一旦您使用 API 进行不在原始配置文件中的更改，您的配置文件就会变得过时。有几种方法可以解决这个问题

使用 caddy run 命令的 --resume 来使用最后一个活动配置。
不要将配置文件的使用与通过 API 进行的更改混合在一起；拥有一个真相来源。
导出 Caddy 的新配置，使用后续的 GET 请求（不如前两个选项推荐）。

在 JSON 中使用 `@id`

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

我们可以为我们的处理程序对象提供一个 @id 标签，以使其更容易访问

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
	-H "Content-Type: application/json" \
	-d '"msg"'

这将为我们的处理程序对象添加一个属性："@id": "msg"，因此它现在看起来像这样

{
	"@id": "msg",
	"body": "Work smarter, not harder.",
	"handler": "static_response"
}

然后我们可以直接访问它

curl localhost:2019/id/msg

现在我们可以使用更短的路径更改消息

curl \
	localhost:2019/id/msg/body \
	-H "Content-Type: application/json" \
	-d '"Some shortcuts are good."'

然后再次检查它

curl localhost:2019/id/msg/body

使用 @id 标签