入门指南

欢迎使用 Caddy！本教程将探索 Caddy 的基础用法，帮助您从高层次了解它。

目标：

• 🔲 运行守护进程
• 🔲 尝试 API
• 🔲 给 Caddy 一个配置
• 🔲 测试配置
• 🔲 创建 Caddyfile
• 🔲 使用配置适配器
• 🔲 使用初始配置启动
• 🔲 比较 JSON 和 Caddyfile
• 🔲 比较 API 和配置文件
• 🔲 在后台运行
• 🔲 零停机配置重载

前提条件：

• 基本的终端/命令行技能
• 基本的文本编辑器技能
• 在 PATH 中有 caddy 和 curl

如果您通过包管理器安装了 Caddy，Caddy 可能已经作为服务运行。如果是这样，请在进行本教程之前停止该服务。

让我们开始运行它：

caddy

哎呀；没有子命令时，caddy 命令只显示帮助文本。您可以在任何时候忘记该怎么做时使用它。

要启动 Caddy 作为守护进程，使用 run 子命令：

caddy run

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

curl localhost:2019/config/

我们可以通过给 Caddy 一个配置来使其变得有用。这可以通过多种方式完成，但我们将在下一节中使用 curl 向 /load 端点发送 POST 请求。

您的第一个配置

为了准备我们的请求，我们需要创建一个配置。Caddy 的配置本质上就是一个 JSON 文档。

将此保存为 JSON 文件（例如 caddy.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!，那么恭喜 -- 它工作了！确保您的配置按预期工作总是一个好主意，特别是在部署到生产环境之前。

您的第一个 Caddyfile

对于 Hello World 来说，刚才的操作有点复杂。

配置 Caddy 的另一种方式是使用 Caddyfile。我们上面用 JSON 写的相同配置可以简单地表示为：

:2015

respond "Hello, world!"

将其保存为当前目录中名为 Caddyfile 的文件（无扩展名）。

如果 Caddy 已经在运行，请停止它（Ctrl+C），然后运行：

caddy adapt

或者如果您将 Caddyfile 存储在其他地方或使用了其他名称：

caddy adapt --config /path/to/Caddyfile

您将看到 JSON 输出！这里发生了什么？

我们刚刚使用了一个配置适配器将我们的 Caddyfile 转换为 Caddy 的原生 JSON 结构。

虽然我们可以获取该输出并发出另一个 API 请求，但我们可以跳过所有这些步骤，因为 caddy 命令可以为我们完成。如果当前目录中有一个名为 Caddyfile 的文件且没有指定其他配置，Caddy 将加载 Caddyfile，为我们适配它，并立即运行它。

现在当前文件夹中有了 Caddyfile，让我们再次执行 caddy run：

caddy run

或者如果您的 Caddyfile 在其他地方：

caddy run --config /path/to/Caddyfile

（如果它的名称不是以 "Caddyfile" 开头，您需要指定 --adapter caddyfile。）

您现在可以再次尝试加载您的站点，您将看到它正在工作！

如您所见，您可以通过几种方式使用初始配置启动 Caddy：

• 当前目录中名为 Caddyfile 的文件
• --config 标志（可选使用 --adapter 标志）
• --resume 标志（如果之前加载了配置）

JSON 与 Caddyfile

现在您知道 Caddyfile 只是为您转换为 JSON。

Caddyfile 似乎比 JSON 更容易，但您是否应该始终使用它？每种方法都有优缺点。答案取决于您的需求和使用场景。

您需要决定哪种方式最适合您的使用场景。

重要的是要注意，JSON 和 Caddyfile（以及任何其他支持的配置适配器）都可以与 Caddy 的 API 一起使用。但是，如果您使用 JSON，您将获得 Caddy 的全部功能和 API 特性。如果使用配置适配器，使用 API 加载或更改配置的唯一方式是通过 /load 端点。

API 与配置文件

您还需要决定您的工作流程是基于 API 还是基于 CLI。（您可以在同一服务器上同时使用 API 和配置文件，但我们不推荐这样做：最好有一个真实的来源。）

选择 API 或配置文件工作流程与使用配置适配器是正交的：您可以使用 JSON 但将其存储在文件中并使用命令行界面；相反，您也可以将 Caddyfile 与 API 一起使用。

但大多数人会使用 JSON+API 或 Caddyfile+CLI 的组合。

如您所见，Caddy 非常适合各种使用场景和部署！

启动、停止、运行

由于 Caddy 是一个服务器，它会无限期运行。这意味着在执行 caddy run 后，您的终端将保持阻塞状态，直到进程终止（通常使用 Ctrl+C）。

虽然 caddy run 是最常用的，通常也是推荐的（特别是在制作系统服务时！），但您也可以使用 caddy start 来启动 Caddy 并让它在后台运行：

caddy start

这将让您再次使用终端，这在某些交互式无头环境中很方便。

然后您需要自己停止进程，因为 Ctrl+C 不会为您停止它：

caddy stop

或使用 API 的 /stop 端点。

重载配置

您的服务器可以执行零停机配置重载/更改。

所有加载或更改配置的 API 端点 都是优雅的，可以实现零停机。

但是，当使用命令行时，您可能会想使用 Ctrl+C 来停止服务器，然后重新启动它以获取新配置。不要这样做：停止和启动服务器与配置更改是正交的，会导致停机时间。

相反，使用 caddy reload 命令进行优雅的配置更改：

caddy reload

这实际上只是在底层使用 API。它将加载您的配置文件，并在必要时将其适配为 JSON，然后优雅地替换活动配置，而不会造成停机。

如果加载新配置时出现任何错误，Caddy 将回滚到最后一个正常工作的配置。