开始上手

欢迎来到 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/

这不是您的网站：localhost:2019 上的管理端点用于控制 Caddy，并且默认情况下仅限于 localhost。

尝试 API

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

您的第一个配置

为了准备我们的请求，我们需要创建一个配置。在其核心，Caddy 的配置只是一个 JSON 文档。

将其保存到 JSON 文件（例如 caddy.json）

{

"apps": {

"http": {

"servers": {

"example": {

"listen": [":2015"],

"routes": [

{

"handle": [{

"handler": "static_response",

"body": "Hello, world!"

}]

}

]

}

}

}

}

}

您不必使用配置文件，但为了本教程，我们将会使用。Caddy 的 管理 API 专为其他程序或脚本使用而设计。

然后上传它

curl localhost:2019/load \

-H "Content-Type: application/json" \

-d @caddy.json

给 Caddy 一个配置

我们可以通过另一个 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（无扩展名）的文件中。

创建一个 Caddyfile

如果 Caddy 已经在运行，请停止它 (Ctrl+C)，然后运行

caddy adapt

或者，如果您将 Caddyfile 存储在其他位置或将其命名为 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 vs. Caddyfile

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

Caddyfile 看起来比 JSON 更容易，但您应该始终使用它吗？每种方法都有优点和缺点。答案取决于您的需求和用例。

JSON

Caddyfile

易于生成

易于手工制作

易于编程

难以自动化

极具表现力

适度表现力

Caddy 功能的全部范围

Caddy 功能的大部分

允许配置遍历

无法在 Caddyfile 中遍历

部分配置更改

仅限整体配置更改

可以导出

无法导出

与所有 API 端点兼容

与某些 API 端点兼容

文档自动生成

文档是手写的

无处不在

小众

更高效

更多计算

有点无聊

有点有趣

了解更多：JSON 结构

了解更多：Caddyfile 文档

您需要决定哪种最适合您的用例。

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

比较 JSON 和 Caddyfile

API vs. 配置文件

在底层，即使是配置文件也通过 Caddy 的 API 端点；caddy 命令只是为您封装了这些 API 调用。

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

API

配置文件

使用 HTTP 请求进行配置更改

使用 shell 命令进行配置更改

易于扩展

难以扩展

难以手动管理

易于手动管理

真的很有趣

也很有趣

了解更多：API 教程

了解更多：Caddyfile 教程

使用适当的工具（例如：任何 REST 客户端应用程序），手动管理服务器的 API 配置是完全可行的。

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

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

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

比较 API 和配置文件

启动、停止、运行

由于 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 将回滚到上次正常工作的配置。

从技术上讲，新配置在旧配置停止之前启动，因此在短暂的时间内，两个配置都在运行！如果新配置失败，它将中止并显示错误，而旧配置只是不会停止。

零宕机时间配置重载