Caddy

开始

入门指南

一次走完：运行守护进程、调用 API、写第一份配置、零停机重载。

这篇教程会带你过一遍 Caddy 的基础用法，帮你建立起一个完整的心智模型。

准备

  • 基本的终端操作能力，会用一个文本编辑器
  • PATH 里有 caddy 和 curl

运行守护进程

不带子命令的 caddy 只会打印帮助文本。要作为守护进程启动，用 run：

终端
caddy run

这条命令会一直阻塞。它此刻在做什么？其实什么都没做，因为默认配置是空的。可以在另一个终端里用管理 API 确认这一点：

终端
curl localhost:2019/config/

你的第一份配置

Caddy 的配置本质上就是一份 JSON 文档。把它存成 caddy.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

验证一下配置生效了没有：

终端
curl localhost:2015
Hello, world!

看到 Hello, world! 就说明通了。部署到生产之前，先确认配置确实如你所料，永远是个好习惯。

你的第一个 Caddyfile

为了输出一句 Hello world，刚才那套流程确实有点繁琐。同样一份配置，写成 Caddyfile 是这样：

Caddyfile
:2015
respond "Hello, world!"

存成一个没有扩展名、名为 Caddyfile 的文件。先 Ctrl+C 停掉 Caddy，然后执行caddy adapt：

终端
caddy adapt

你会看到 JSON 输出。我们刚才用的是配置适配器，它把 Caddyfile 转成了 Caddy 原生的 JSON 结构。

其实这一步可以省掉。只要当前目录有一个叫 Caddyfile的文件，并且没有另外指定配置，Caddy 就会自动加载、适配并直接运行它：

终端
caddy run

JSON 与 Caddyfile 怎么选

JSONCaddyfile
容易由程序生成适合手工编写
容易编程操作不便自动化
表达能力极强表达能力适中
覆盖 Caddy 全部功能覆盖大部分功能
支持配置遍历不支持在 Caddyfile 内遍历
可以只改一部分只能整份替换
可以导出不能导出
兼容所有 API 端点只兼容部分端点
文档自动生成文档手写
更高效开销略高

两种方式都能配合 Caddy 的 API 使用，但只有 JSON 能用上全部功能。走适配器时，唯一可用的端点是/load。

API 还是配置文件

底层来看，配置文件最终也要经过 Caddy 的 API 端点，caddy命令只是把这些调用包装了一下。

API配置文件
用 HTTP 请求改配置用 shell 命令改配置
容易横向扩展难以横向扩展
不便人工维护便于人工维护

两种工作流可以混用，但不建议：一个服务器最好只有一个配置来源。多数人最终会落在 「JSON 配 API」或者「Caddyfile 配 CLI」这两种组合上。

启动、停止与后台运行

caddy run 是最常用的方式，做成系统服务时尤其如此。如果想让它到后台去跑，用caddy start：

终端
caddy start
caddy stop

后台运行时 Ctrl+C 帮不了你，得自己调 caddy stop，或者调 API 的/stop 端点。

零停机重载配置

所有会加载或修改配置的 API 端点都是优雅的、零停机的。

改完配置文件后，用 caddy reload 做一次优雅的替换：

终端
caddy reload

它底层还是走 API：加载并（如有必要）适配配置文件，然后在不停机的情况下替换掉正在运行的配置。如果新配置有错，Caddy 会回滚到上一份能用的配置。严格来说，新配置会先于旧配置启动，所以有那么一瞬间两份配置同时在跑。