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 对象现在看起来像这样

{
	"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`

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

我们可以给我们的 handler 对象一个 @id 标签，使其更容易访问

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

这为我们的 handler 对象添加了一个属性："@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 标签