Documentation
a project

入门

欢迎来到Caddy! 本教程将探讨使用Caddy的基础知识,并帮助你在高层次上熟悉它。

目标:

  • 🔲 运行守护程序
  • 🔲 试试API
  • 🔲 给Caddy一个配置
  • 🔲 测试配置
  • 🔲 制作一个Caddy文件
  • 🔲 使用配置适配器
  • 🔲 从一个初始配置开始
  • 🔲 比较JSON和Caddyfile
  • 🔲 比较API和配置文件
  • 🔲 在后台运行
  • 🔲 零停机时间的配置重新加载

前提:

  • 基本的终端/命令行技能
  • 基本的文本编辑器技能
  • caddycurl 在你的 PATH 中

如果你从软件包管理器安装了Caddy,Caddy可能已经作为一个服务在运行。如果是这样,请在进行本教程之前停止该服务。

我们从运行它:

caddy

哎呀;没有子命令,caddy命令只显示帮助文本。你可以在忘记做什么的时候使用它。

要将 Caddy 作为守护程序启动,请使用 run 子命令:

caddy run

这将永远阻塞,但它在做什么?此刻……什么都没有。默认情况下,Caddy 的配置(“config”)为空。我们可以在另一个终端中使用 admin 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 \
	-X POST \
	-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 存储在其他地方或将其命名为 Caddyfile 以外的其他名称:

caddy adapt --config /path/to/Caddyfile

你会看到JSON输出! 这里发生了什么?

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

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

现在,在当前文件夹中有一个Caddy文件,让我们再次进行caddy运行:

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 功能 Caddy 功能的最常见部分
易于生成 易于手工制作
易于编程 难以自动化
极具表现力 适度表达
允许配置遍历 无法在 Caddyfile 中遍历
部分配置更改 仅整个配置更改
可以导出 不可以导出
与所有 API 端点兼容 与一些 API 端点兼容
文档自动生成 文档是手写的
无处不在 安置于适当地方
更高效 更多计算方法
有点无聊 有点意思
了解更多: JSON 结构 了解更多: Caddyfile 文档

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

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

API 与配置文件

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

API 配置文件
使用 HTTP 请求更改配置 使用 shell 命令进行配置更改
易于扩展 难以扩展
难以手动管理 易于手动管理
真的很有趣 也很有趣
了解更多: API 教程 了解更多: Caddyfile 教程

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 会回滚到上一个工作配置。