指令

什么是指令？

指令是 Caddyfile 中的命名命令，它告诉 Caddy 如何处理请求、配置 TLS、修改请求/响应属性等等。每个指令都有特定的用途和语法。

来源

指令类型

Caddy 有两种主要类型的指令

常规指令 (Regular Directives)：配置服务器的各个方面，如 TLS 设置、全局选项等。
处理程序指令 (Handler Directives)：专门创建处理请求和响应的 HTTP 处理程序。

来源

处理程序指令

处理程序指令创建用于处理 HTTP 请求的中间件处理程序。它们通常接受一个可选的匹配器标记，该标记决定何时执行处理程序。示例包括：

respond - 返回静态响应
rewrite - 修改请求
reverse_proxy - 将请求转发到后端
file_server - 提供静态文件

来源

常规指令

这些指令配置服务器的各个方面，不一定创建处理程序。示例包括：

bind - 指定监听的接口
tls - 配置 TLS 设置
log - 设置请求日志
root - 设置站点的根目录

来源

指令注册和处理

指令必须在 Caddy 中注册才能在 Caddyfile 中被识别。这通过 RegisterDirective 和 RegisterHandlerDirective 函数实现。

当 Caddy 处理 Caddyfile 中的指令时，它会：

在注册指令映射中定位指令
调用关联的 unmarshal 函数
传递带有当前标记的辅助对象
收集并处理生成的配置值

来源

指令顺序

指令顺序对 Caddy 的配置至关重要。指令以 directiveOrder 切片确定的特定顺序进行处理，这确保了指令之间的依赖关系得到尊重。

此顺序很重要，因为：

较早的指令可以设置供后续指令使用的变量
重写和重定向应在提供内容之前发生
身份验证应在访问受保护内容之前发生

例如，root 会较早处理，以便基于文件的操作知道去哪里查找文件，而像 file_server 和 reverse_proxy 这样的响应处理程序则在链中靠后。

来源

自定义顺序配置

指令顺序可以通过全局 order 选项进行自定义，允许管理员在需要时调整处理顺序

{
    order method before redir
}

这会将 method 指令放在处理链中 redir 指令之前。

来源

caddyconfig/httpcaddyfile/options.go102-174

指令到 JSON 配置的映射

ConfigValue 分类系统

每个指令生成按“类”分类的 ConfigValue 对象，这些对象决定了它们在最终 JSON 配置中的位置

配置类映射

类	目的	最终 JSON 位置	指令示例
`route`	HTTP 请求路由	`apps.http.servers[].routes[]`	`handle`, `respond`, `file_server`
`bind`	网络绑定	`apps.http.servers[].listen[]`	`bind`
`tls.connection_policy`	TLS 握手策略	`apps.tls.connection_policies[]`	`tls`
`tls.cert_loader`	证书加载	`apps.tls.certificates`	`tls` (带证书文件)
`tls.cert_issuer`	证书颁发	`apps.tls.automation.policies[].issuers[]`	`tls` (ACME/内部)
`custom_log`	访问日志	`logging.logs`	`log`
`error_route`	错误处理	`apps.http.servers[].errors.routes[]`	`handle_errors`
`listener_wrapper`	网络监听器	`apps.http.servers[].listener_wrappers[]`	自定义插件

ServerType.Setup 中的处理流程

主要配置构建过程，源自 caddyconfig/httpcaddyfile/httptype.go56-362

来源

辅助对象和匹配器

指令通常使用 Helper 结构体来访问当前的解析上下文，并使用匹配器创建新的路由

匹配器根据请求路径、主机、头等条件确定何时执行处理程序。处理程序指令自动支持将可选的匹配器标记作为第一个参数。

来源

常见指令模式

许多 Caddy 指令遵循类似的模式：

基本处理程序指令

复杂路由指令

来源

内置指令

Caddy 包含许多按处理顺序组织的内置指令。下表提供了内置指令的全面参考：

顺序	指令	类型	目的	基本语法
1	`tracing`	处理器	启用分布式追踪	`tracing`
2	`map`	处理器	创建变量映射	`map {expression} {variable}`
3	`vars（变量）`	处理器	设置请求变量	`vars key value`
4	`fs`	处理器	设置文件系统上下文	`fs <filesystem>`
5	`root`	常规	设置文档根目录	`root [matcher] <path>`
6	`log_append`	处理器	附加到日志字段	`log_append <field> <value>`
7	`log_skip`	处理器	跳过请求的日志记录	`log_skip [matcher]`
8	`log_name`	处理器	设置日志器名称	`log_name <names...>`
9	`header`	处理器	操作 HTTP 头	`header [matcher] <field> <value>`
10	`copy_response_headers`	处理器	复制响应头	`copy_response_headers <fields...>`
11	`request_body`	处理器	读取请求体	`request_body [matcher]`
12	`redir`	处理器	执行 HTTP 重定向	`redir [matcher] <to> [code]`
13	`method`	处理器	重写 HTTP 方法	`method [matcher] <method>`
14	`rewrite`	处理器	重写请求 URI	`rewrite [matcher] <to>`
15	`uri`	处理器	修改 URI 组件	`uri [matcher] <operation> <value>`
16	`try_files`	处理器	按顺序尝试文件	`try_files <files...>`
17	`basic_auth`	处理器	HTTP 基本认证	`basic_auth [matcher] <realm>`
18	`forward_auth`	处理器	将认证转发到外部服务	`forward_auth [matcher] <url>`
19	`request_header`	处理器	设置请求头	`request_header [matcher] <field> <value>`
20	`encode`	处理器	压缩响应	`encode [matcher] <encodings...>`
21	`push`	处理器	HTTP/2 服务器推送	`push [matcher] <resources...>`
22	`intercept`	处理器	拦截响应	`intercept [matcher]`
23	`templates`	处理器	服务器端模板	`templates [matcher]`
24	`invoke`	处理器	调用命名路由	`invoke <route_name>`
25	`handle`	处理器	分组其他指令	`handle [matcher] { ... }`
26	`handle_path`	处理器	剥离路径前缀	`handle_path <prefix> { ... }`
27	`route`	处理器	高级路由	`route [matcher] { ... }`
28	`abort`	处理器	中止请求处理	`abort [matcher]`
29	`error`	处理器	返回错误状态	`error [matcher] <status> <message>`
30	`copy_response`	处理器	复制响应	`copy_response [matcher]`
31	`respond`	处理器	返回静态响应	`respond [matcher] <status> <body>`
32	`metrics`	处理器	启用指标收集	`metrics [matcher]`
33	`reverse_proxy`	处理器	反向代理到后端	`reverse_proxy [matcher] <upstreams...>`
34	`php_fastcgi`	处理器	PHP FastCGI 代理	`php_fastcgi [matcher] <address>`
35	`file_server`	处理器	提供静态文件	`file_server [matcher]`
36	`acme_server`	处理器	ACME 协议服务器	`acme_server [matcher]`

核心配置指令

这些指令配置了基本的服务器行为

指令	类型	目的	基本语法
`bind`	常规	网络接口绑定	`bind <addresses...>`
`tls`	常规	TLS/HTTPS 配置	`tls [email\|cert_file key_file]`
`log`	常规	访问和错误日志	`log [name] { ... }`
`handle_errors`	常规	错误页面处理	`handle_errors [status_codes...] { ... }`

来源

指令配置示例

核心基础设施指令

`bind` 指令

配置监听的网络接口和协议

bind 127.0.0.1:8080
bind 192.168.1.100 {
    protocols h1 h2 h3
}

配置选项来自 caddyconfig/httpcaddyfile/builtins.go63-84

protocols - 指定 HTTP 协议版本 (h1, h2, h2c, h3)

`tls` 指令

具有多个选项的综合 TLS 配置

# Email for ACME registration
tls user@example.com

# Manual certificate and key files
tls cert.pem key.pem

# Advanced configuration
tls {
    protocols tls1.2 tls1.3
    ciphers TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    curves secp384r1
    client_auth {
        mode require
        trusted_leaf_cert_file ca.pem
    }
    alpn h2 http/1.1
    ca https://acme-staging-v02.api.letsencrypt.org/directory
    dns cloudflare
    on_demand
}

主要配置选项来自 caddyconfig/httpcaddyfile/builtins.go117-605

protocols - 最低和最高 TLS 版本
ciphers - 允许的加密套件
curves - 支持的椭圆曲线
client_auth - 客户端证书认证
alpn - 应用层协议协商
ca - ACME 证书颁发机构端点
dns - ACME 的 DNS 挑战提供商
on_demand - 启用按需证书颁发
issuer - 自定义证书颁发模块
get_certificate - 自定义证书管理器

`root` 指令

设置文档根目录，带可选匹配器

root /var/www/html
root /path/* /var/www/special

从 caddyconfig/httpcaddyfile/builtins.go610-643 支持一个或两个参数，其中第二个参数在指定匹配器时为路径。

请求处理指令

`vars` 指令

设置请求变量供其他指令使用

vars {
    user_type "premium"
    api_version "v2"
}
vars /admin/* admin_section true

使用 caddyconfig/httpcaddyfile/builtins.go660-664 中的 VarsMiddleware

`redir` 指令

执行带灵活代码选项的 HTTP 重定向

redir /old /new
redir /temp /new temporary
redir /perm /new permanent
redir /custom /new 307
redir /js-only /new html

重定向代码来自 caddyconfig/httpcaddyfile/builtins.go675-746

permanent - HTTP 301
temporary - HTTP 302 (默认)
html - 带 JavaScript/meta 重定向的 HTTP 200
自定义数字代码 (3xx 范围或 401)

`respond` 指令

返回带可自定义内容的静态响应

respond "Hello World"
respond /api/* "API under maintenance" 503
respond "Not found" 404 {
    close
}

通过 caddyconfig/httpcaddyfile/builtins.go749-753 支持完整的 StaticResponse 配置

高级路由指令

`handle` 和 `route` 指令

创建复杂的请求路由逻辑

handle /api/* {
    reverse_proxy localhost:8080
}

route {
    @websocket {
        header Connection *Upgrade*
        header Upgrade websocket
    }
    reverse_proxy @websocket localhost:8081
    
    file_server
}

两者都通过 caddyconfig/httpcaddyfile/builtins.go789-791 和 caddyconfig/httpcaddyfile/builtins.go772-787 解析子指令作为完整的路由配置

`handle_errors` 指令

自定义错误页面处理

handle_errors {
    @5xx expression {http.error.status_code} >= 500
    rewrite @5xx /errors/5xx.html
    file_server
}

handle_errors 404 {
    respond "Custom 404 page" 404
}

支持状态码过滤和完整的子路由配置，来自 caddyconfig/httpcaddyfile/builtins.go793-866

`invoke` 指令

调用其他地方定义的命名路由

(common_headers) {
    header X-Server "Caddy"
    header X-Version "2.0"
}

example.com {
    invoke common_headers
    file_server
}

通过 caddyconfig/httpcaddyfile/builtins.go869-887 管理命名路由注册

日志指令

`log` 指令

配置自定义日志记录，支持多种输出和格式

log {
    output file /var/log/access.log
    format json
    level INFO
}

log admin_log {
    hostnames admin.example.com
    output file /var/log/admin.log {
        roll_size 100MB
        roll_keep 5
    }
    format console
}

来自 caddyconfig/httpcaddyfile/builtins.go906-1153 的全面日志配置，支持：

多个输出模块 (file, stdout, stderr, discard)
各种格式编码器 (json, console 等)
日志采样和过滤
主机名特定日志记录

来源

caddyconfig/httpcaddyfile/builtins.go58-1181

指令处理流程

当 Caddy 处理 Caddyfile 时，指令会经历以下阶段：

来源

创建自定义指令

要创建自定义指令，您需要：

定义一个带有 UnmarshalCaddyfile 方法的处理程序结构体
在初始化期间注册您的指令
实现 unmarshaling 逻辑

示例实现

来源

结论

指令是 Caddy 配置的基本构建块。它们提供了一种结构化的方式，通过 Caddyfile 格式定义服务器行为。了解指令的工作原理对于创建有效的 Caddy 配置和使用自定义功能扩展 Caddy 至关重要。

指令