入门
欢迎来到Caddy! 本教程将探讨使用Caddy的基础知识,并帮助你在高层次上熟悉它。
目标:
- 🔲 运行守护程序
- 🔲 试试API
- 🔲 给Caddy一个配置
- 🔲 测试配置
- 🔲 制作一个Caddy文件
- 🔲 使用配置适配器
- 🔲 从一个初始配置开始
- 🔲 比较JSON和Caddyfile
- 🔲 比较API和配置文件
- 🔲 在后台运行
- 🔲 零停机时间的配置重新加载
前提:
- 基本的终端/命令行技能
- 基本的文本编辑器技能
caddy
和curl
在你的 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 会回滚到上一个工作配置。