Caddy 入门 – 又见杜梨树

> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [dulishu.top](https://dulishu.top/caddyrumen/)

Caddy 是用 go 实现的，功能强大、可扩展的平台，可以应用在网站、服务以及应用程序等场景下。

Caddy 有如下常用功能：  
web 服务器；  
反向代理；  
负载均衡；  
API 网关；

此外，Caddy 还可以用来做 sidecar proxy, ingress controller, system manager, process supervisor, task scheduler, (any long-running process);

通过 Caddy API, Caddy 的配置是动态和可输出的（exportable）。即使没有指定配置文件，你也可以使用 Caddy。如果你需要使用 Caddy 配置功能，Caddyfile 是一个不错的选择。

**1. 安装 Caddy**

下载可执行的二进制文件，比如我下载的是 caddy_2.3.0_linux_amd64.tar.gz。  
地址：https://github.com/caddyserver/caddy/releases/tag/v2.3.0  
下载完之后解压缩，将可执行文件 caddy 置于 / usr/sbin / 下即可使用。

**2. 运行 Caddy**

```
$ caddy run        #运行 caddy，并阻塞

$ caddy start      #后台执行 caddy

$ caddy stop       #停止 caddy
```

**3.Caddy 配置简介**  
**3.1 使用 JSON 配置 Caddy**  
（1）Caddy 的原生配置语言是 JSON，将如下 JSON 文本保存到文件 caddy.json：

```
{

"apps": {

"http": {

"servers": {

"example": {

"listen": [":2015"],

"routes": [

{

"handle": [{

"handler": "static_response",

"body": "Hello, world!"

}]

}

]

}

}
```

（2）然后通过 curl post 请求，将配置文件上传：

```
$ curl localhost:2019/load \ 
 -X POST \ 
 -H "Content-Type: application/json" \ 
 -d @caddy.json
```

_注：curl 请求的 url——localhost:2019/load， 其中 localhost:2019 是 caddy 服务的 ip:port；其后的 / load 表示设置 Caddy 配置。除了 POST /load，还有 POST /stop, GET /config/[path]， POST /config/[path], PUT /config/[path]， PATCH /config/[path], DELETE /config/[path] 等等。详见参考 [2]_

（3）验证新配置  
使用 curl GET 请求验证我们刚刚上传的配置

```
$ curl localhost:2019/config/

{"apps":{"http":{"servers":{"example":{"listen":[":2015"],"routes":[{"handle":[{"body":"Hello, world!","handler":"static_response"}]}]}}}}}
```

（4）查看配置是否生效  
使用 curl 或浏览器请求配置中的服务

```
$ curl localhost:2015

Hello, world!
```

**3.2 使用 Caddyfile 配置 Caddy**  
如 3.1 所述，使用原生 JSON 配置，需要写入冗长的 JSON 文本。而如果使用 Caddyfile 则可以省略这一部分的工作，让 caddy 的配置适配器 (caddy adapter) 帮我们解析生成所需的 JSON 配置文本。  
（1）将如下配置写入 Caddyfile 文件中

```
:2015

respond "Hello, world!"
```

（2）执行 caddy adapt

```
$ caddy adapt        #若 Caddyfile 不在当前工作目录，这需要 --config 选项指定 Caddyfile 文件路径

2021/04/27 18:56:29.159 INFO    using adjacent Caddyfile

{"apps":{"http":{"servers":{"srv0":{"listen":[":2015"],"routes":[{"handle":[{"body":"Hello, world!","handler":"static_response"}]}]}}}}}
```

如上所示，执行 caddy adapt 后输出了 JSON 配置文本，这即是 config adapter 所做的工作。  
_注：将配置写入 Caddyfile 后，启动 caddy，配置就已经生效了。而使用 caddy adapt 只是将 Caddyfile 转为了 JSON 文本，并不是因为执行 caddy adapt 才会使配置生效，这点要注意。关于 Config Adapter 的详细介绍，见参考 [3]_

**3.3 重载配置**  
在 API 模式和命令行模式下，Caddy 服务都可以实现配置文件的热加载（热更新）。Caddy 的 API 可以优雅的进行配置重载与更新，而在命令行模式下需要执行如下命令进行安全的配置重载：

```
$ caddy reload    #其本质是调用 Caddy API
```

如果在重载配置的过程中遇到任何错误，Caddy 会将配置回滚到上一次有效的配置状态。

有如下几种方法，可以在启动 Caddy 时指定初始配置：  
（1）工作目录有名为 Caddyfile 的配置文件，执行 caddy run 时会自动加载；  
（2）若工作目录不存在 Caddyfile 的配置文件，可以使用–config 选项来指定初始配置文件（如果初始配置文件名不是 Caddyfile，那么同时还需要–adapter 选项，详见参考 [3]）；  
（3）如果一个配置文件之前已经加载过了，再次运行 Caddy 时想要使用上一次加载的配置，使用–resume 选项；

**3.4 JSON vs. Caddyfile**  
现在我们已经知道，Caddyfile 的本质是将其转化为 JSON 文本。那么，在实际应用场景中，应该如何选择呢？这取决于我们的使用场景：

<table><colgroup><col> <col></colgroup><tbody><tr><td>JSON</td><td>Caddyfile</td></tr><tr><td>Full range of Caddy functionality</td><td>Most common parts of Caddy functionality</td></tr><tr><td>Easy to generate</td><td>Easy to craft by hand</td></tr><tr><td>Easily programmable</td><td>Difficult to automate</td></tr><tr><td>Extremely expressive</td><td>Moderately expressive</td></tr><tr><td>Allows config traversal</td><td>Cannot traverse within Caddyfile</td></tr><tr><td>Partial config changes</td><td>Whole config changes only</td></tr><tr><td>Can be exported</td><td>Cannot be exported</td></tr><tr><td>Compatible with all API endpoints</td><td>Compatible with some API endpoints</td></tr><tr><td>Documentation generated automatically</td><td>Documentation is hand-written</td></tr><tr><td>Ubiquitous</td><td>Niche</td></tr><tr><td>More efficient</td><td>More computational</td></tr><tr><td>Kind of boring</td><td>Kind of fun</td></tr><tr><td><div>Learn more: <a href="https://caddyserver.com/docs/json/">JSON structure</a></div></td><td><div>Learn more: <a href="https://caddyserver.com/docs/caddyfile">Caddyfile docs</a></div></td></tr></tbody></table>

**4.API-based or CLI-based**

如前所述，我们通过命令行的形式来操纵 Caddy 配置文件，进而操纵 Caddy 服务。除此之外，我们还可以通过 API 调用的形式来操纵 Caddy 服务。二者的优缺点总结如下。  
需要知道的是，Caddy 命令行，其实是对 Caddy API 的封装调用。

<table><colgroup><col> <col></colgroup><tbody><tr><td>API</td><td>Config files（CLI-based）</td></tr><tr><td>Make config changes with HTTP requests</td><td>Make config changes with shell commands</td></tr><tr><td>Easy to scale</td><td>Difficult to scale</td></tr><tr><td>Difficult to manage by hand</td><td>Easy to manage by hand</td></tr><tr><td>Really fun</td><td>Also fun</td></tr><tr><td><div>Learn more: <a href="https://caddyserver.com/docs/api-tutorial">API tutorial</a></div></td><td><div>Learn more: <a href="https://caddyserver.com/docs/caddyfile-tutorial">Caddyfile tutorial</a></div></td></tr></tbody></table>

多数人的使用方案是 JSON+API, 或 Caddyfile+CLI。

**5. 示例**

在进一步学习 Caddy 之前，先熟悉一下使用 Caddyfile 编写反向代理的基本语法，详见参考 [5]：

```
reverse_proxy [] [] {
 # 需要代理的后端服务

to

...
 # 负载均衡相关配置

lb_policy  []

lb_try_duration

lb_try_interval 
 # 主动健康检查

health_path

health_port

health_interval

health_timeout  health_status

health_body 
 # 被动健康检查

fail_duration

max_fails

unhealthy_status  unhealthy_latency

unhealthy_request_count 
 # streaming

flush_interval

buffer_requests
 # header manipulation

header_up [+|-] [ []]

header_down [+|-] [ []]
 # round trip

transport  {

...

}

}
```

接下来，使用 Caddyfile+CLI 的形式来实现一个反向代理示例（本节只需要使用 upstreams 和 lbpolicy 负载均衡）  
（1）编写 Caddyfile

```
:2015

reverse_proxy /xxxServerAPI/* {

to 10.15.112.151:6868

to 10.15.112.151:6969

lb_policy       least_conn

}
```

其中，  
reverse_proxy 表明使用反向代理；  
/xxxServerAPI/* 是用来过滤或匹配特定请求的规则，即将符合这一规则的请求路由到 to 关键字指定的服务上去；  
lb_policy 是负载均衡策略，此处使用 least_conn，即选择当前请求量最少的后端服务；

（2）启动 caddy 自动加载 Caddyfile

```
$ caddy run    #运行 caddy 服务，当然你也可以使用后台形式运行之（caddy start），这里为了方便观察日志，采用阻塞形式启动 caddy
```

（3）验证配置  
因为是阻塞运行 caddy，这里需要再开一个终端，输入 curl localhost:2019/config/

```
$ curl localhost:2019/config/

{"apps":{"http":{"servers":{"srv0":{"listen":[":2015"],"routes":[{"handle":[{"handler":"reverse_proxy","load_balancing":{"selection_policy":{"policy":"least_conn"}},"upstreams":[{"dial":"10.15.112.151:6868"},{"dial":"10.15.112.151:6969"}]}],"match":[{"path":["/xxxServerAPI/*"]}]}]}}}}}
```

如果你安装了 jq 插件，如下输出会让 JSON 文本更直观：

```
$ curl localhost:2019/config/ | jq

{

"apps": {

"http": {

"servers": {

"srv0": {

"listen": [

":2015"

],

"routes": [

{

"handle": [

{

"handler": "reverse_proxy",

"load_balancing": {

"selection_policy": {

"policy": "least_conn"

}

},

"upstreams": [

{

"dial": "10.15.112.151:6868"

},

{

"dial": "10.15.112.151:6969"

}

]

}

],

"match": [

{

"path": [

"/xxxServerAPI/*"

]

}

]

}

]

}

}
```

在浏览器中输入 localhost:2015/xxxServerAPI/app，就会路由到配置中指定的服务上去，比如 10.15.112.151:6868/xxxServerAPI/app  
至此，一个反向代理 + 负载均衡的 Caddy 服务就配置完成了，是不是很简单。

参考：  
[1] https://caddyserver.com/docs/  
[2] https://caddyserver.com/docs/api#post-load  
[3] https://caddyserver.com/docs/config-adapters  
[4] https://caddyserver.com/docs/api  
[5] https://caddyserver.com/docs/caddyfile/directives/reverse_prox