Web 服务器 Caddy 2 | Haven200

> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [www.shixuen.com](https://www.shixuen.com/zh-CN/linux/services_web_caddy_v2.html)

[![](https://www.shixuen.com/zh-CN/uploads/title/services_web_caddy_v2_title.jpg)](https://www.shixuen.com/zh-CN/uploads/title/services_web_caddy_v2_title.jpg "Stop, COVID-19")

[Stop, COVID-19](https://www.shixuen.com/zh-CN/uploads/title/services_web_caddy_v2_title.jpg "Stop, COVID-19")

因 COVID-19 的原因，终于有了空余时间来升级 [Caddy](https://caddyserver.com/)。[Caddy V2](https://caddyserver.com/) 完全被重构了，与 [Caddy v1](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy.html) 区别非常大，说是两款软件也不为过，所以 [Caddy V2](https://caddyserver.com/)不兼容 [Caddy V1](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy.html) 的插件和配置文件。与其按照官网的步骤去手动升级配置文件，还不如按 [Caddy V2](https://caddyserver.com/)的格式重新写来得方便。

我们需要从 [Caddy 下载页面](https://caddyserver.com/download)下载 [Caddy V2](https://caddyserver.com/)，并将下载的可执行文件放在我们系统的 `PATH` 中。  
可以在 [Caddy 下载页面](https://caddyserver.com/download)获取不同系统或 CPU 架构的可执行文件。同 [Caddy v1](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy.html) 时一样，此页面可以让我们自定义带有不同插件的 [Caddy V2](https://caddyserver.com/)。

[](#a-debian-ubuntu-raspbian "A. Debian,Ubuntu,Raspbian")A. Debian,Ubuntu,Raspbian
----------------------------------------------------------------------------------

我们可以使用 `apt-get` 命令来安装 [Caddy](https://caddyserver.com/)，然后下载 [caddy.service](https://github.com/caddyserver/dist/raw/master/init/caddy.service)文件，使用 `systemd` 来启动 [Caddy](https://caddyserver.com/)。

```
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/gpg/gpg.155B6D79CA56EA34.key' | sudo apt-key add -
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/setup/config.deb.txt?distro=debian&version=any-version' | sudo tee -a /etc/apt/sources.list.d/caddy-stable.list
sudo apt-get update
sudo apt-get install caddy
```

也可以自 [Caddy 下载页面](https://caddyserver.com/download)手动下载包含第三方插件的可执行文件，然后将它放在 `PATH` 下（如 `/usr/local/bin/`），方便我们运行。

```
:~$ curl -o ~/Downloads/caddy "https://caddyserver.com/api/download?os=linux&arch=amd64&p=github.com%2Fmholt%2Fcaddy-webdav&idempotency=79680512439698"
:~$ sudo mv ~/Downloads/caddy /usr/local/bin
:~$ chmod +x /usr/local/bin/caddy
```

[](#b-docker "B. Docker")B. Docker
----------------------------------

按照下面的步骤来安装 [caddy](https://caddyserver.com/)服务。

*   **要求**:
*   `caddy` 可执行文件已经下载完成
*   `systemctl --version` 版本高于 232
*   `sudo` 权限

将我们下载的 [caddy](https://caddyserver.com/)可执行文件放在 `$PATH` 下，并确认可以被执行。

```
:~$ sudo mv caddy /usr/local/bin && sudo chmod +x /usr/local/bin/caddy
:~$ caddy version
v2.3.0 h1:fnrqJLa3G5vfxcxmOH/+kJOcunPLhSBnjgIvjXV/QTA=
```

创建名为 `caddy` 的用户组

```
:~$ sudo groupadd --system caddy
```

创建名为 `caddy` 的用户，并且带有一个可以写入的用户目录。

```
sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy
```

**注意**: 如果使用了 [caddy](https://caddyserver.com/)的配置文件，**必须**确保此文件是可以被用户 `caddy` 可读的。

下一步，创建 `systemd` 服务的配置文件。

[Github-Caddy.service](https://github.com/caddyserver/dist/raw/master/init/caddy.service)

```
:~$ sudo cat > /lib/systemd/system/caddy.service << EOF
# caddy.service
#
# For using Caddy with a config file.
#
# Make sure the ExecStart and ExecReload commands are correct
# for your installation.
#
# See https://caddyserver.com/docs/install for instructions.
#
# WARNING: This service does not use the --resume flag, so if you
# use the API to make changes, they will be overwritten by the
# Caddyfile next time the service is restarted. If you intend to
# use Caddy's API to configure it, add the --resume flag to the
# caddy run command or use the caddy-api.service file instead.

[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
EOF
:~$ sudo systemctl daemon-reload
```

最后，我们就可以使用下面的命令来运行 `caddy` 了。

```
:~$ sudo systemctl start caddy
```

此时，[Caddy](https://caddyserver.com/)的日志被重定向到了 `journalctl` 中，使用下面命令来查看运行日志

```
:~$ sudo journalctl -u caddy --no-pager | less
```

[](#php "PHP")PHP
-----------------

```
{
    http_port   80
    https_port  443
    servers     :443 {
                    protocol {
                        experimental_http3
                    }
                }
    servers     :80 {
                    protocol {
                        allow_h2c
                    }
                }
}

h5ai.shixuen.com {
    root    *   /var/www/media
    tls     haven200@haven200.com
    file_server
    php_fastcgi unix//run/php/php7.4-fpm.sock

@redirected {
        not path /_h5ai/*
        path */
    }
    rewrite @redirected /_h5ai/public/index.php
```

### [](#php-fastcgi "php_fastcgi")php_fastcgi

此指令将指定的请求发送给 PHP FastCGI 服务，如 `php-fpm`。

```
php_fastcgi 127.0.0.1:9000

php_fastcgi /blog/* 127.0.0.1:9000

php_fastcgi unix//run/php/php7.4-fpm.sock
```

[](#webdav "WebDav")WebDav
--------------------------

```
{
    http_port   80
    https_port  443
    servers     :443 {
                    protocol {
                        experimental_http3
                    }
                }
    servers     :80 {
                    protocol {
                        allow_h2c
                    }
                }
}

webdav.shixuen.com {
    root * /var/www/webdav
    route {
        webdav /* {
            root /var/www/webdav
        }
        file_server
    }
    basicauth  {
        test JDJhJDE0JEloaFFCbzBMZG94d1J6ZUVaRWE2ZS5xUkQ2WmM0Y0VlV2lpbmxNRVhESVVvSkZZSTU2TTZL
    }
}
```

此功能需要第三方插件 `http.handlers.webdav` 支持。且此插件**只提供**了 `webdav` 最基本的读取功能，**不支持**写入。

```
:~$ caddy list-modules | grep webdav
http.handlers.webdav
:~$
```

[Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 是一种方便人类阅读的格式。因为它易写、易理解，所以多数人们都喜欢用它来配置 [Caddy](https://caddyserver.com/)。

[](#概念 "概念")概念
--------------

[Caddy-Docs-Concepts](https://caddyserver.com/docs/caddyfile/concepts)

### [](#结构 "结构")结构

[Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 文件的结构如下图：

[![](https://www.shixuen.com/zh-CN/uploads/images/services_web_caddy_v2_01.png)](https://www.shixuen.com/zh-CN/uploads/images/services_web_caddy_v2_01.png "Caddyfile's structure")

[Caddyfile's structure](https://www.shixuen.com/zh-CN/uploads/images/services_web_caddy_v2_01.png "Caddyfile's structure")

重点:

*   ** 全局选项 (global options block)** 必须在文件的最顶端即开头处，此为可选，即配置文件中可以没有它。
*   如果 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 中**不包含**全局选项 (Global options)，那么它的第一行（非注释行）**必须**是网站地址，即网站的域名。
*   所有指令 (directives) 和匹配器 (matchers) **必须**处于站点配置里，即 `{ }` 里。
*   如果 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 中**仅**配置了一个网站，那么它的 `{ }` 是可以省略的。

[](#全局选项-global-options "全局选项(Global Options)")全局选项 (Global Options)
--------------------------------------------------------------------

[Caddy-Docs-Global Options](https://caddyserver.com/docs/caddyfile/options)

[Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 可让您指定全局应用的选项。 一些选项作为默认值，而其他选项则可以定义 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 适配器的行为。

[Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 的最顶部可以是全局选项块。

```
{
    http_port   80
    https_port  443
    servers     :443 {
                    protocol {
                        experimental_http3
                    }
                }
    servers     :80 {
                    protocol {
                        allow_h2c
                    }
                }
}
```

在 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 中，全局选项**只能**有一个**且必须**位于文件的开始处。

*   http_port: 指定服务器的 HTTP 端口。仅限内部使用，并不会改变客户端的 HTTP 端口。默认为 80。
*   https_port: 指定服务器的 HTTPS 端口。仅限服务器内部使用，并不会改变客户端的 HTTPS 端口。默认为 443。
*   server: 自定义跨多个站点的 HTTP 服务端的设置，因为这个功能无法在站点块中正确配置。
*   protocol
*   allow_h2c: 启用 H2C（“明文 HTTP / 2” 或 “ H2 over TCP”）支持，如果客户端支持，它将通过 TCP 协议来传输明文 HTTP/2。 此设置仅适用于未加密的 HTTP 协议。
*   experimental_http3: 启用 HTTP/3 实验性支持。 注意，HTTP/3 暂时并不是一个完整的规范，并且客户端的支持也非常有限。将来该选项会被舍弃。

[](#请求匹配器-request-matchers "请求匹配器(Request Matchers)")请求匹配器 (Request Matchers)
-----------------------------------------------------------------------------

请求匹配器可按特定条件筛选 (或分类) 请求。

在 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 中，紧随指令之后的匹配 (matcher) 标记可以限制该指令的范围。 匹配器标记可以是以下形式之一：

1.  通配符 (Wildcard matchers): * 匹配所有请求 (默认).
2.  路径 (Path matchers): /path 以 `/` 开头来匹配请求的路径。
3.  名称 (Named matchers): @name 以 `@`开头来定义一个名称匹配器。

### [](#通配符-wildcard-matchers "通配符(Wildcard matchers)")通配符 (Wildcard matchers)

通配符 `*` 来匹配所有请求，且仅当需要匹配标识时时才使用。

```
root    *   /var/www/mysite

root /foo/* /var/www/a
```

### [](#路径-path-matchers "路径(Path matchers)")路径 (Path matchers)

由于按路径匹配非常常见，因此可以内联单个路径匹配器，如下所示：

```
redir /old.html /new.html
```

路径匹配的标识**必须**以正斜杠 `/` 开头。

默认情况下路径匹配是路径完全匹配；进行前缀匹配必须附加 `*`。注意，`/foo*` 将匹配 `/foo` 和 `/foo/` 以及 `/foobar`；实际上我们可能需要的是 `/foo/*`。

### [](#名称匹配-named-matchers "名称匹配(Named matchers)")名称匹配 (Named matchers)

所有不是路径或通配符的匹配器**必须**命名为名称匹配器。

定义具有唯一名称的匹配器可使您更灵活，允许您将任何可用的匹配器组合到一个集合中：

```
@name {
    ...
}

@name ...
```

例子:

```
@websockets {
    header Connection *Upgrade*
    header Upgrade    websocket
}
reverse_proxy @websockets localhost:6001
```

此代理**仅**代理名为 “Connection” 的字段（值包含单词 “Upgrade”）和名为 “Upgrade” 的字段（值为 “websocket”）的请求。

与指令一样，名称匹配器**只能**在使用它们的站点块内部进行定义。

名称匹配器定义了一个匹配器集。匹配集里的单个匹配器之间执行 AND 操作，即所有的都必须匹配到。例如，如果匹配集合中同时有指令 (header) 和路径匹配器，则两者都必须匹配。

### [](#标准匹配器-standard-matchers "标准匹配器(Standard matchers)")标准匹配器 (Standard matchers)

*   [expression](https://caddyserver.com/docs/caddyfile/matchers#expression)
*   [file](https://caddyserver.com/docs/caddyfile/matchers#file)
*   [header](https://caddyserver.com/docs/caddyfile/matchers#header)
*   [header_regexp](https://caddyserver.com/docs/caddyfile/matchers#header-regexp)
*   [host](https://caddyserver.com/docs/caddyfile/matchers#host)
*   [method](https://caddyserver.com/docs/caddyfile/matchers#method)
*   [not](https://caddyserver.com/docs/caddyfile/matchers#not)
*   [path](https://caddyserver.com/docs/caddyfile/matchers#path)
*   [path_regexp](https://caddyserver.com/docs/caddyfile/matchers#path-regexp)
*   [protocol](https://caddyserver.com/docs/caddyfile/matchers#protocol)
*   [query](https://caddyserver.com/docs/caddyfile/matchers#query)
*   [remote_ip](https://caddyserver.com/docs/caddyfile/matchers#remote-ip)

```
header <field> [<value>]
```

对请求里 `header` 参数进行匹配。

*   `<field>` 需要检查的 HTTP 头部字段的名字。
*   如果它的前缀为`！`，则表示 HTTP 头部**不允许**包含此字段。
*   `<value>` 为该字段需要匹配的值。
*   如果它的前缀为 `*`，则表示进行前缀模糊匹配。
*   如果它的后缀为 `*`，则表示进行后缀模糊匹配。
*   如果被 `*` 包围，则表示进行字符串模糊匹配。
*   其它情况，则进行精准匹配。

同一个 `header` 下的字段之间进行 ** 与 (AND)** 操作，多个 `header` 之间进行`或(or)` 操作。

##### [](#例1 "例1")例 1

对 HTTP 头部的 `Connection`**与** `server` 字段进行匹配：

*   `Connection` 字段值需包含 `Upgrade`
*   `server` 字段的值必须为 `Caddy`  
    最后匹配结果进行`与(and)` 操作。

```
@foo {
    header {
        Connection *Upgrade*
        server Caddy
    }
}
```

##### [](#例2 "例2")例 2

HTTP 头部 `Foo` 字段的值是否为 `bar`**或**`baz`

```
@foo {
    header Foo bar
    header Foo baz
}
```

##### [](#例3 "例3")例 3

HTTP 头部**不能包含**名为 `Foo` 的字段。

```
@not_foo {
    header !Foo
}
```

#### [](#method "method")method

对 HTTP 的请求方式进行匹配，如 POST / GET /DELETE。请求方式**必须**为大写，如 `POST`。可以同时匹配多个请求方式。

匹配多个请求方式时，这些请求方式之间进行`或(or)` 操作。

```
method GET

method PUT DELETE
```

#### [](#not "not")not

```
not <any other matcher>

not {
    <any other matcher>
}
```

将匹配的结果进行`非`操作。

##### [](#例1-1 "例1")例 1

匹配不包含以 `/css/` **或** `/js/` 开头的请求路径。

这里的`或` 是 `path` 匹配器里的，而非 `not` 匹配器

##### [](#例2-1 "例2")例 2

对 HTTP 请求进行匹配：

*   不以 `/api/` 开头的路径，**或**
*   请求方式不为 `POST`

```
not path /api/*
not method POST
```

##### [](#例3-1 "例3")例 3

同时对 HTTP 请求的多个内容进行匹配：

*   请求路径不以 `/api/` 开头的，**和**
*   请求方法不为 `POST` 的

```
not {
    path /api/*
    method POST
}
```

#### [](#path "path")path

对 HTTP 请求的 `URI` 进行匹配，一般进行精准匹配，使用 `*` 时可以进行模糊匹配：

*   `*` 在后面，进行后缀模糊匹配，如 `/prefix/*`
*   `*` 在前面，则进行前缀模糊匹配，如 `*.suffix`
*   `*` 在两边，则进行子字符串精确匹配，如 `*/contains/*`
*   `*` 在中间，则两边精确匹配中间模糊匹配，如 `/accounts/*/info`

多个路径匹配器之间进行`或(or)` 操作。

[](#指令 "指令")指令
--------------

下面列表的指令为 [Caddy](https://caddyserver.com/)的自有指令，可以用在 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 中。

### [](#指令执行优先级 "指令执行优先级")指令执行优先级

HTTP 处理链被许多指令操控着。这些指令执行的优先级非常重要，因此 [Caddy](https://caddyserver.com/)在其内部为这些指令定义了一套默认的优先级：

```
map
root

header
request_body

redir
rewrite

uri
try_files

basicauth
request_header
encode
templates

handle
handle_path
route
push

respond
metrics
reverse_proxy
php_fastcgi
file_server
acme_server
```

我们可以使用 `route` 指令或在全局选项中使用 `order` 来重新定义指令执行时的优先级。

### [](#log "log")log

允许和设置 HTTP 请求的访问日志。

`log` 指令在 [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) 站点块里进行使用，而非其它地方。

```
log {
    output <writer_module> ...
    format <encoder_module> ...
    level  <level>
}
```

*   `output`: 设置日志记录的位置。默认： stderr
*   `stderr`: 控制台的标准错误通道（默认选项）。
*   `stdout`: 控制台的标准输出通道。
*   `discard`: 无日志输出。
*   `file`: 输出至指定的文本文件。为了防止硬盘空间耗尽默认对日志文件进行轮换。
*   `net`: 网络套接接口。
*   `format`: 对日志进行编码或格式化。默认: 如果检测到 stdout 是终端则为 console 格式，否则为 json 格式。
*   `console`: 对每条日志按 console 格式进行编码以使其易于人类阅读，同时也保留下了某些结构。
*   `json`: 对每条日志按 JSON 结构进行格式化。
*   `single_field`: 仅在日志条目中写入单个字段。对于其中一个字段已经包含我们所需的信息时很有用。
*   `filter`: 定义一个日志编码格式，允许按字段进行过滤。
*   `delete`: 在对日志进行编码时删除指定字段。
*   `ip_mask`: 在字段中将 IP 地址模糊化处理。
*   `level`: 设置日志的等级。 默认等级：INFO

#### [](#例子 "例子")例子

```
example.com {
    root /var/www/
    ...
    log {
        format single_field common_log
    }
}

example.com {
    log {
        output file /var/log/caddy.log {
            roll_size 100mb
            roll_keep 5
            roll_keep_for 720h
        }
        format filter {
            wrap console
            fields {
                request>headers>Authorization delete
            }
        }
    }
}
```

### [](#basicauth "Basicauth")Basicauth

[basicauth](https://caddyserver.com/docs/caddyfile/directives/basicauth), Enables HTTP Basic Authentication, which can be used to protect directories and files with a username and hashed password. **Note that basic auth is not secure over plain HTTP.**

Caddy configuration **does not accept** plaintext passwords; we **MUST** hash them before putting them into the configuration. The caddy hash-password command can help with this.

```
:~$ caddy hash-password
Enter password: test
Confirm password: test
JDJhJDE0JEloaFFCbzBMZG94d1J6ZUVaRWE2ZS5xUkQ2WmM0Y0VlV2lpbmxNRVhESVVvSkZZSTU2TTZL
```

Example:

```
haven200.com {
    ...
    basicauth /secret/* {
        test JDJhJDE0JEloaFFCbzBMZG94d1J6ZUVaRWE2ZS5xUkQ2WmM0Y0VlV2lpbmxNRVhESVVvSkZZSTU2TTZL
    }
}
```

### [](#encode "encode")encode

Encodes responses using the configured encoding(s). A typical use for encoding is compression.

```
haven200.com {
    ...
    
    encode zstd gzip
}
```

### [](#file-server "file_server")file_server

A static file server. It works by appending the request’s URI path to the site’s root path. By default, it enforces canonical URIs; if necessary, requests to directories will be redirected to have a trailing forward slash, and requests to files will be redirected to strip the trailing slash.

Most often, the file_server directive is paired with the root directive to set file root for the whole site.

```
file_server [<matcher>] [browse] {
    root   <path>
    hide   <files...>
    index  <filenames...>
    browse [<template_file>]
}
```

*   `browse` enables file listings for requests to directories that do not have an index file.
*   `root` sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective **only** changes the root for this directive. For other directives (like try_files or templates) to know the same site root, use the root directive, not this subdirective.
*   `hide` is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system paths_, NOT request paths.
*   `index` is a list of filenames to look for as index files. Default: `index.html` `index.txt`
*   `<template_file>` is an optional custom template file to use for directory listings.

#### [](#example-one "Example One")Example One

The file_server directive is usually paired with the root directive to set the root path from which to serve files:

```
haven200.com {
    root    *   /var/www/
    file_server
}
```

#### [](#example-two "Example Two")Example Two

A static file server out of the `/var/www` directory With file listings enabled, and hide all `.git` folders and their contents

```
haven200.com {
    root    *   /var/www/
    file_server browse {
        hide .git
    }
}
```

Manipulates HTTP header fields on the response. It can set, add, and delete header values, or perform replacements using regular expressions.

By default, header operations are performed immediately unless any of the headers are being deleted, in which case the header operations are automatically deferred until the time they are being written to the client.

```
header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
    <field> <find> <replace>
    [+]<field> <value>
    -<field>
    ?<field> <default_value>
    [defer]
}
```

*   `<field>` is the name of the header field. By default, will overwrite any existing field of the same name. Prefix with `+` to add the field instead of replace, or prefix with `-` to remove the field.
*   `<value>` is the header field value, if adding or setting a field.
*   `<default_value>` is the header field value that will be set only if the header does not already exist.
*   `<find>` is the substring or regular expression to search for.
*   `<replace>` is the replacement value; required if performing a search-and-replace.
*   `defer` will force the header operations to be deferred until the response is written out to the client. This is automatically enabled if any of the header fields are being deleted.

#### [](#example "Example")Example

```
header Custom-Header "My value"

header -Hidden

header Location http:// https://

header {
    
    Strict-Transport-Security max-age=31536000

X-Content-Type-Options nosniff

X-Frame-Options DENY

Referrer-Policy no-referrer-when-downgrade
}

header ?Cache-Control "max-age=3600"
reverse_proxy upstream:443
```

### [](#root "root")root

Sets the `root` path of the site, used by various matchers and directives that access the file system. If unset, the default site root is the current working directory.

Specifically, this directive sets the `{http.vars.root}` placeholder.

This directive does not automatically enable serving static files, so it is often used in conjunction with the [file_server directive][toc_haven200_file_server] or the [php_fastcgi directive][toc_haven200_php_fastcgi].

```
root * /var/www/

root /foo/* /var/www/foo
```

### [](#php-fastcgi-1 "php_fastcgi")php_fastcgi

An opinionated directive that proxies requests to a PHP FastCGI server such as php-fpm.

Caddy’s reverse_proxy is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. This directive is actually just a convenient way to use a longer, more common configuration (below).

```
php_fastcgi [<matcher>] <php-fpm_gateways...> {
    root <path>
    split <substrings...>
    env [<key> <value>]
    index <filename>
    resolve_root_symlink
    dial_timeout  <duration>
    read_timeout  <duration>
    write_timeout <duration>

<any other reverse_proxy subdirectives...>
}
```

*   `<php-fpm_gateways...>` are the addresses of the FastCGI servers.
*   `root` sets the root folder to the site. Default: `root` directive.
*   `split` sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the “path info” from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php`
*   `env` sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables.
*   `index` specifies the filename to treat as the directory index file. This affects the file matcher in the expanded form. Default: `index.php`
*   `resolve_root_symlink` enables resolving the root directory to its actual value by evaluating a symbolic link, if one exists.
*   `dial_timeout` is how long to wait when connecting to the upstream socket. Accepts duration values. Default: no timeout.
*   `read_timeout` is how long to wait when reading from the FastCGI server. Accepts duration values. Default: no timeout.
*   `write_timeout` is how long to wait when sending to the FastCGI server. Accepts duration values. Default: no timeout.

#### [](#expanded-form "Expanded form")Expanded form

The `php_fastcgi` directive is the same as the following configuration:

```
route {
    
    @canonicalPath {
        file {
            try_files {path}/index.php
        }
        not path */
    }
    redir @canonicalPath {path}/ 308

@indexFiles {
        file {
            try_files {path} {path}/index.php index.php
            split_path .php
        }
    }
    rewrite @indexFiles {http.matchers.file.relative}

@phpFiles {
        path *.php
    }
    reverse_proxy @phpFiles <php-fpm_gateway> {
        transport fastcgi {
            split .php
        }
    }
}
```

Most modern PHP apps work well with this preset. If yours does not, feel free to borrow from this and customize it as needed instead of using the `php_fastcgi` shortcut.

#### [](#examples "Examples")Examples

```
php_fastcgi 127.0.0.1:9000

php_fastcgi /blog/* 127.0.0.1:9000

php_fastcgi unix//run/php/php7.4-fpm.sock
```

### [](#rewrite "rewrite")rewrite

Rewrites the request internally. A rewrite changes some or all of the request URI.

The `rewrite` directive implies the intent to accept the request, but with modifications. It is mutually exclusive to other rewrite directives in the same block, so it is safe to define rewrites that would otherwise cascade into each other; only the first matching rewrite will be executed.

Because rewrite essentially performs an internal redirect, the [Caddyfile](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy_v2.html#caddyfile-docs) adapter will not fold any subsequent, adjacent handlers into the same route if their matchers happen to be exactly the same. This allows the matchers of the next handlers to be deferred until after the rewrite. In other words, a matcher that matches a request before the rewrite might not match the same request after the rewrite. If you want your rewrite to share a route with other handlers, use the [route](https://caddyserver.com/docs/caddyfile/directives/route) or [handle](https://caddyserver.com/docs/caddyfile/directives/handle) directives.

```
rewrite [<matcher>] <to>
```

*   is the URI to set on the request. Only designated parts will be replaced. The URI path is any substring that comes before `?`. If `?` is omitted, then the whole token is considered to be the path.

#### [](#examples-1 "Examples")Examples

```
rewrite * /foo.html

rewrite /api/* ?a=b

rewrite /api/* ?{query}&a=b
```

引用:

*   [caddy v1](https://www.shixuen.com/zh-CN/linux/zh-CN/linux/services_web_caddy.html)
*   [Caddy-website](https://caddyserver.com/)
*   [Caddy-docs](https://caddyserver.com/docs)