Caddyfile 用法与配置详解

Caddy 是一个使用 Go 语言编写的可扩展服务器平台。它的核心功能是管理配置。Caddy 的原生配置格式是 JSON，但 Caddyfile 是一个内置的配置适配器，因其语法简洁明了而广受欢迎，尤其适合手动编写配置。Caddyfile 易于编写、易于理解，并足以满足大多数使用场景的需求。

虽然 Caddyfile 是配置 Caddy 的首选方式，但它作为一个配置适配器，在表达能力、灵活性和可编程性方面不如 Caddy 的原生 JSON 结构。如果需要自动化 Caddy 配置或部署，建议使用 JSON 配合 Caddy API。

Caddyfile 核心概念与结构

Caddyfile 的基本思想是：首先指定站点的地址，然后列出该站点所需的功能或特性。

基本结构：

站点块的花括号 {}：

如果 Caddyfile 中只有一个站点块，其大括号 { } 是可选的。例如，localhost respond "Hello, world!" 等同于 localhost { respond "Hello, world!" }。
如果配置多个站点，则必须使用花括号 {} 包裹每个站点的配置来分隔它们。在这种情况下，只有地址出现在花括号外部，而该站点的指令则出现在花括号内部。
开头的花括号 { 必须在其行的末尾，且前面有一个空格。闭合的花括号 } 必须单独占一行。

注释 (Comments)：

注释以 # 符号开始，并持续到行尾。
井号 # 不能出现在标记的中间，它必须前面有空格或出现在行首。

环境变量 (Environment Variables)：

可以在 Caddyfile 中使用环境变量，格式为 {$ENV}。
环境变量在 Caddyfile 解析开始之前被替换。
它们可以展开为空值、部分标记、完整标记，甚至多行和多个标记。
也可以指定默认值，例如 {$DOMAIN:localhost}，当环境变量不存在时会使用默认值 localhost。

全局选项块 (Global Options Block)

Caddyfile 可以以一个特殊的、没有键的全局选项块开始。
如果存在全局选项块，它必须是 Caddyfile 中的第一个块。
全局选项块用于设置适用于全局的选项，或者不特定于任何一个网站的选项。在其中，只能设置全局选项，不能使用常规的站点指令。
该块使用花括号 {} 包裹，例如：{ debug }。

以下是全局选项块中可用的主要选项及其用法和作用的详细列表：

通用选项 (General Options)

TLS 选项 (TLS Options)

服务器选项 (Server Options)

其他选项

站点块（site block）

在可选的全局选项块之后（或如果不存在全局选项块，则作为 Caddyfile 的第一行）。 Caddyfile 由至少一个或多个站点块组成。
每个站点块总是以一个或多个站点地址开始。

多个站点：可以通过用花括号 {} 包裹每个站点块，在同一个 Caddyfile 中定义多个站点。地址之间可以使用空格或逗号分隔。

localhost {
    respond "Hello, world!"
}
localhost:2016 {
    respond "Goodbye, world!"
}

地址 (Addresses)

地址用于指定 Caddy 服务的网站，可以是域名（例如 example.com、localhost、*.example.com）、IP 地址（例如 127.0.0.1），或者包含方案（Scheme）和端口（Port）（例如 http://example.com、:8080）。
地址必须是唯一的，不能多次指定同一个地址。
地址中不能使用占位符，但可以使用 Caddyfile 风格的环境变量，例如 {$SITE_ADDRESS}。
通配符 * 只能用于表示主机名中的一个标签，例如 *.example.com 会匹配 foo.example.com 但不匹配 foo.bar.example.com。
要捕获所有主机，可以省略地址的主机部分，例如只写 https://。

在 Caddyfile 中，地址 (Addresses) 始终出现在站点块的顶部，通常是 Caddyfile 中的第一项内容。地址定义了 Caddy 将服务哪些请求。

以下是 Caddyfile 地址用法的详细介绍：

• Host 头匹配：如果指定了主机名（例如 localhost），Caddy 只会处理 Host 头匹配的请求。这意味着如果站点地址是 localhost，Caddy 将不会匹配对 127.0.0.1 的请求。
• 通配符 (*)：通配符只能用于表示主机名中的一个标签。例如，*.example.com 匹配 foo.example.com，但不匹配 foo.bar.example.com。单个 * 匹配 localhost 但不匹配 example.com。
• 自动 HTTPS：
  • Caddy 默认自动为所有站点提供 HTTPS 服务。
  • 它会自动更新和管理证书，并将 HTTP (默认端口 80) 请求自动重定向到 HTTPS (默认端口 443)。
  • 任何主机匹配器 (host matcher) 都会触发自动 HTTPS。
  • Caddy 使用 Smallstep 库的本地 CA 为非公共站点生成和签署证书。
  • 对于公共域名，Caddy 通过 ACME CA (如 Let’s Encrypt 或 ZeroSSL) 获取证书。
  • 要获得公共信任证书，主机名必须符合特定要求，例如不能是 localhost 或 IP 地址，并且通配符只能是左侧的单个标签。
• 按需 TLS (On-Demand TLS)：如果在启动或重新加载服务器时不知道所有域名，或者域名尚未正确配置，按需 TLS (On-Demand TLS) 非常有用。在这种情况下，可以省略地址的主机部分，例如只写 https://。
• 端口绑定：默认情况下，站点绑定到所有网络接口。可以使用 bind 指令或 default_bind 全局选项来覆盖此设置。
• 环境变量：地址中不能使用 Caddyfile 的占位符 ({})。但是，可以使用 Caddyfile 风格的环境变量，它们在 Caddyfile 解析之前进行替换。例如：{$SITE_ADDRESS} file_server。

指令 (Directives)

指令 是 Caddyfile 中 功能性关键词，用于自定义站点的服务方式。它们 必须 出现在 站点块 (site block) 内。

结构与语法:

• 指令是站点块中每行第一个单词。
• 指令可以带有 参数 (arguments)，这些参数出现在指令后的同一行上。如果单个参数值中包含空格，则需要使用双引号 "" 或反引号 `` 括起来。
• 有些指令可以开启自己的 指令块 (directive block)，其中包含 子指令 (subdirectives)。子指令出现在指令块内每行的开头。
• 通常，指令不能嵌套在其他指令块内，除非它们被设计用于分组其他指令，例如 handle 和 route 块。

功能和示例:

Caddy 默认提供了许多标准指令，用于实现各种功能。例如：

• file_server: 用于从磁盘提供文件服务。例如：localhost { file_server }。
• reverse_proxy: 强大且可扩展的反向代理。例如：localhost { reverse_proxy localhost:9000 }。
• respond: 将硬编码的响应写入客户端。
• tls: 自定义 TLS 设置。
• encode: 对响应进行编码（通常是压缩）。
• log: 启用访问/请求日志记录。
• redir: 向客户端发出 HTTP 重定向。
• root: 设置站点根目录的路径。

指令顺序 (Directive Order):

• 许多指令会操作 HTTP 处理程序链。这些指令的评估顺序很重要，因此 Caddy 内部有一个 默认的硬编码顺序。
• 可以使用 order 全局选项 或 route 指令来覆盖或自定义此顺序。
• route 指令会将其内部的指令视为一个单一单元，并 保留指令出现的顺序，不受默认排序规则的影响。

配置复用:

import 指令: 用于包含代码片段或文件，以在多个站点块中复用配置。

• 如果参数与已定义的片段不匹配，Caddy 会尝试将其作为文件导入。
• import 指令可以在 Caddyfile 中的任何位置出现（除了作为另一个指令的参数）。

命名路由 (Named Routes): 这是一个实验性功能，允许定义特殊的块，以 &(name) 语法开头，并在多个站点中通过 invoke 指令重复使用。这对于减少内存使用尤其有用，如果相同的路由需要在许多不同的站点中使用。

匹配器 (Matchers)

匹配器 用于根据特定条件 过滤 (classify) 请求。通过使用匹配器，可以精确指定某个指令适用于哪些请求。

语法与类型:

在 Caddyfile 中，紧随指令后的第一个参数可以是 匹配器标记 (matcher token)，它限制了该指令的作用范围。匹配器标记有以下三种形式：

1. * (通配符): 匹配所有请求 (默认行为)。如果省略匹配器标记，则等同于通配符匹配。
2. /path (路径匹配器): 以斜杠 / 开头，用于匹配请求路径。
   • 路径匹配是精确的，但不区分大小写。
   • 可以使用通配符 *：
     • 仅在末尾，进行前缀匹配 (/prefix/*)。
     • 仅在开头，进行后缀匹配 (*.suffix)。
     • 在两边，进行子串匹配 (*/contains/*)。
     • 在中间，进行全局匹配 (/accounts/*/info)。
   • 在指令排序算法中，单个路径匹配器优先排序，并按特异性从最特异到最不特异排序。
3. @name (命名匹配器): 指定一个 命名匹配器。
   • 所有非路径或通配符的匹配器都必须是命名匹配器。
   • 定义语法：@name { ... } 或单行形式 @name ...。
   • 使用方法：将 @name 作为指令的第一个参数。
   • 逻辑组合: 命名匹配器集中的匹配器默认是 AND 关系，即所有匹配器都必须匹配。对于更复杂的布尔逻辑，推荐使用 expression 匹配器。 示例:

   example.com {
       @websockets {
           header Connection *Upgrade*
           header Upgrade websocket
       }
       reverse_proxy @websockets localhost:6001
       reverse_proxy localhost:8080
   }
   

   此配置将 HTTP/1.1 WebSocket 请求代理到 localhost:6001，其他请求到 localhost:8080。

标准请求匹配器:

Caddy 提供了多种标准请求匹配器，它们提供了丰富的过滤条件：

• client_ip <ranges...>: 根据客户端 IP 地址或 CIDR 范围匹配请求。private_ranges 是匹配所有私有 IPv4 和 IPv6 地址范围的快捷方式。
• expression <cel...>: 使用 CEL (Common Expression Language) 表达式匹配，支持复杂的布尔逻辑、Caddy 占位符以及将其他匹配器作为函数使用。
• file: 匹配请求路径对应的是否存在文件。
• header <field> [ <value> ]: 根据请求头字段匹配。支持精确匹配、前缀、后缀、子串匹配，以及通过 ! 进行否定匹配。
• header_regexp [ <name> ] <field> <regexp>: 基于正则表达式匹配请求头，支持命名捕获组。
• host <hosts...>: 根据 Host 请求头匹配。多个 host 匹配器之间是 OR 关系。
• method <verbs...>: 根据 HTTP 请求方法 (verb) 匹配。多个 method 匹配器之间是 OR 关系。
• not { <matchers...> }: 对其内部的匹配结果取反。
• path <paths...>: 根据请求路径匹配。
• path_regexp [ <name> ] <regexp>: 基于正则表达式匹配请求路径，支持命名捕获组。
• protocol <protocol_name>: 根据请求协议匹配，如 http, https, grpc, http/2+。
• query <key>=<val>...: 根据查询字符串参数匹配。同一键的多个值之间是 OR 关系，不同键之间是 AND 关系。
• remote_ip <ranges...>: 根据直接对等端的 IP 地址匹配。
• vars <variable> <values...>: 根据请求上下文中的变量或占位符的值匹配。支持匹配多个值（OR 关系）。
• vars_regexp [ <name> ] <variable> <regexp>: 基于正则表达式匹配变量值，支持命名捕获组。

响应匹配器 (Response Matchers):

• 响应匹配器通常出现在某些指令的配置内部，用于在响应被写入客户端时做出决策。
• status <code>...: 根据 HTTP 状态码匹配，支持范围匹配（如 2xx, 3xx）。
• header <field> [ <value> ]: 根据响应头字段匹配。与请求头匹配器类似，支持多种匹配方式和否定。

完整 Caddyfile 示例配置与说明

以下是一个结合了多种 Caddyfile 配置项的完整示例，包括全局选项、多个站点、常用指令和匹配器：

# 全局选项块 - 必须是文件的第一个块
{
    # 启用调试模式，生成详细日志用于故障排除
    debug

    # 配置自动 HTTPS 相关设置
    auto_https off # 禁用自动 HTTPS，通常用于本地开发或特定场景
    # email admin@example.com # 生产环境建议设置，用于 ACME 注册和通知
    # dns cloudflare {env.CLOUDFLARE_API_TOKEN} # 生产环境通配符证书需要DNS质询

    # 配置日志记录器，不同于 HTTP 请求日志
    log {
        output file /var/log/caddy/caddy.log
        level INFO
    }

    # 定义HTTP服务器的宽限期，在配置更改或停止时
    grace_period 5s

    # 配置本地PKI，自定义本地CA的名称
    pki {
        ca local {
            name "My Custom Caddy Local CA"
            root_cn "Custom Caddy Root CA - 2024"
        }
    }
}

# Snippets 或 Named Routes (可选，可在这里定义)
# 例如，定义一个通用的日志配置片段
(common_logging) {
    log {
        output stdout
        format json
    }
}

# 第一个站点块：本地开发环境的静态文件服务
# 使用环境变量设置地址，并提供默认值
{$DEV_SITE_ADDRESS:localhost:8080} {
    # 导入通用日志配置片段
    import common_logging

    # 设置站点根目录
    root * /var/www/mywebapp/public

    # 启用响应压缩（Gzip和Zstandard）
    encode gzip zstd

    # 启用模板处理
    templates

    # 文件服务器，如果找不到index文件则显示目录列表
    file_server browse

    # 定义一个命名匹配器 `@api_path`，匹配 /api/ 路径下的所有请求
    @api_path path /api/*

    # 使用命名匹配器 `@api_path`，将匹配到的请求反向代理到后端API服务
    handle @api_path {
        reverse_proxy localhost:9001
    }

    # 另一个命名匹配器 `@admin_ip`，匹配特定IP地址的请求
    @admin_ip client_ip 192.168.1.100

    # 如果请求来自管理IP，则响应 "Admin Access Granted"
    respond @admin_ip "Admin Access Granted" 200

    # 捕获所有未被处理的请求
    handle {
        respond "Hello from Dev Server!"
    }
}

# 第二个站点块：生产环境的反向代理服务，支持通配符证书和不同子域处理
*.example.com {
    # 配置 TLS，使用 DNS 质询来获取通配符证书
    tls {
        # 假设已安装了 `caddy-dns/cloudflare` 模块
        dns cloudflare {$CLOUDFLARE_API_TOKEN}
    }

    # 定义子域 `foo.example.com` 的处理逻辑
    @foo_subdomain host foo.example.com
    handle @foo_subdomain {
        reverse_proxy foo_backend:8080
    }

    # 定义子域 `bar.example.com` 的处理逻辑
    @bar_subdomain host bar.example.com
    handle @bar_subdomain {
        reverse_proxy bar_backend:8080
    }

    # 默认回退处理：如果请求的子域没有明确处理，则中止请求
    handle {
        abort
    }
}

# 第三个站点块：一个简单的重定向示例
old-site.com {
    # 将所有请求重定向到新域名
    redir https://new-site.com{uri} permanent
}

运行和管理 Caddy

1. 创建 Caddyfile：在工作目录中创建一个名为 Caddyfile 的文本文件（无扩展名）。
2. 启动 Caddy：
   • 在前台运行（推荐）：caddy run。如果当前目录中存在 Caddyfile 文件，Caddy 将自动加载、适配并运行它。如果 Caddyfile 在其他位置，可以使用 caddy run --config /path/to/Caddyfile。
   • 在后台运行：caddy start。请注意，使用 caddy start 启动的进程，需要使用 caddy stop 来关闭服务器。
3. 重新加载配置：
   • 当更改 Caddyfile 后，可以使用 caddy reload 命令来热加载更新的配置，而无需停止并重新启动 Caddy。这会向 Caddy 的管理 API 发送一个请求。
   • 或者，也可以直接使用 API 发送配置。
4. 停止 Caddy：使用 caddy stop 命令停止 Caddy 进程。
5. 权限问题：
   • 如果 Caddy 需要绑定到低端口（如 80 或 443），可能需要提升权限。
   • 在 Linux 上，可以使用 sudo setcap cap_net_bind_service=+ep $(which caddy) 命令来授予 Caddy 绑定到低端口的权限。请记住，在替换 Caddy 二进制文件后，需要再次运行此命令。
6. 查看 JSON 配置：
   • 可以使用 caddy adapt 命令将 Caddyfile 转换为 Caddy 的原生 JSON 配置结构。
   • 示例：caddy adapt --config /path/to/Caddyfile。
7. 其他常用命令：
   • caddy file-server：快速启动一个生产就绪的文件服务器。
   • caddy reverse-proxy：快速启动一个生产就绪的反向代理。
   • caddy validate：测试配置文件是否有效。
   • caddy environ：打印 Caddy 的环境信息，有助于排查默认配置问题。

Caddyfile 凭借其简洁的语法和强大的自动 HTTPS 功能，使得配置和管理 Web 服务器变得异常简单。通过理解其核心概念、指令和匹配器的用法，可以轻松地构建和维护各种复杂的站点配置。