入门指南

欢迎使用Caddy！本教程会带你了解使用Caddy的基础，并在较高层次上建立整体认知。

目标：

• 🔲 运行守护进程
• 🔲 体验API
• 🔲 给Caddy加载配置
• 🔲 验证配置
• 🔲 编写Caddyfile
• 🔲 使用配置适配器
• 🔲 用初始配置启动
• 🔲 对比JSON与Caddyfile
• 🔲 对比API与配置文件
• 🔲 后台运行
• 🔲 配置无停机重载

前提条件：

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

如果你是通过包管理器安装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在其他位置，或者文件名不是Caddyfile：

caddy adapt --config /path/to/Caddyfile

你会看到JSON输出！这里发生了什么？

我们刚刚使用了配置适配器把Caddyfile转换成了Caddy原生JSON结构。

虽然我们可以拿到输出后再发一次API请求，但这些步骤可省略，因为caddy命令本身就能帮你完成。若当前目录有名为Caddyfile的文件，且未指定其他配置，Caddy会自动加载它、完成适配并立即运行。

现在当前目录已经有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 API使用。但若使用JSON，你能获得完整的Caddy功能与API能力；若使用配置适配器，通过API加载或修改配置的方式仅限/load端点。

API vs. 配置文件

你还需要决定你的工作流是偏API还是偏CLI。（同一台服务器上你_可以_同时用API和配置文件，但不推荐：最好保持单一事实来源。）

选择API工作流还是配置文件工作流，与是否使用配置适配器是正交关系：你可以使用JSON并存成文件后走CLI；反过来，也可以通过API使用Caddyfile。

但多数人会采用JSON+API或Caddyfile+CLI这两种组合。

如你所见，Caddy非常适合多种场景与部署方式！

Start, stop, run

由于Caddy是服务器程序，它会持续运行。这意味着执行caddy run后，终端不会返回，除非进程被终止（通常是Ctrl+C）。

虽然caddy run最常见且通常是推荐方式（尤其在做系统服务时），你也可以用caddy start让Caddy在后台运行：

caddy start

这样你就能继续使用当前终端，这在某些交互式无头环境里很方便。

之后你需要自行停止进程，因为Ctrl+C不能帮你停后台进程：

caddy stop

也可以调用API的/stop端点。

Reloading config

你的服务支持配置无停机重载/变更。

所有用于加载或修改配置的API端点都支持零停机、平滑生效。

但在命令行使用时，很多人会想用Ctrl+C停掉服务，再重启以应用新配置。不要这么做：服务启停与配置变更是两件事，这样会造成停机。

应改用caddy reload命令做平滑变更：

caddy reload

它本质上仍是调用底层API：加载配置（必要时先适配为JSON），然后无停机地平滑替换活动配置。

如果加载新配置出现错误，Caddy会回滚到最后一份可用配置。