Caddy 2 配置参数详解

Caddy 2.11.7 配置参数详解：Caddyfile 全局块与站点块指令、root/file_server/encode/log/reverse_proxy 等常用指令的适配 JSON 对照、环境变量、管理 API 与生产配置模板，全部基于实测回显

CaddyCaddyWeb 服务器与反向代理2026/10/08

Caddy 2 配置参数详解

目标：详解 Caddy 2.11.7 的配置体系与常用参数。Caddy 原生配置为 JSON，Caddyfile 是内置适配器；本文档给出常用指令的适配 JSON 对照、参数说明与生产配置模板，全部对照实测 caddy adapt --pretty 输出。

环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Caddy 版本：v2.11.7（apt 官方源安装）
  • 配置文件：/etc/caddy/Caddyfile
  • 管理端口：localhost:2019（Admin API）

前置条件

  • 已按《Ubuntu 22.04 安装 Caddy 指南》完成安装
  • 掌握基础 Caddyfile 语法（caddy fmt 可自动格式化）

参数查看与修改方式

  • 查看完整模块清单：caddy list-modules（实测 137 个模块）。

  • 查看当前运行配置：curl http://localhost:2019/config/。

  • 查看 Caddyfile 适配 JSON：

    caddy adapt --config /etc/caddy/Caddyfile --pretty

  • 修改配置：编辑 Caddyfile 后 sudo caddy reload --config /etc/caddy/Caddyfile 热加载；或通过 Admin API POST /load。

参数总览

Caddyfile 分两大类块：

块类型位置作用
全局块 { ... }文件最顶部（首个站点地址之前）全局设置：admin、email、storage、debug 等
站点块地址 { ... }每站点路由与处理指令

常用指令（站点块内）：

指令作用
root设置站点根目录
file_server静态文件服务（含 browse 目录浏览）
encode内容编码压缩（gzip/zstd/brotli）
reverse_proxy反向代理
log访问日志
tlsTLS/证书配置
redir重定向
handle_path按路径前缀分发路由

一、全局配置块

{
    admin localhost:2019      # 管理端点地址
    email admin@example.com   # ACME 证书注册邮箱
    debug                     # 开启调试日志
}

💡 说明：admin 可关闭（admin off）或指定监听地址；email 用于自动 HTTPS 的证书申请通知。

二、站点地址与 root/file_server

:8080 {
    root * /usr/share/caddy
    file_server
}

对应适配 JSON（实测 --pretty 摘录）：

"routes": [{
    "handle": [
        { "handler": "vars", "root": "/usr/share/caddy" },
        { "handler": "file_server" }
    ]
}]
参数说明实测默认值
root * 路径站点根目录（* 通配任意路径前缀）当前目录
file_server静态文件服务启用 index 文件，默认 index.html
file_server browse目录浏览关闭

三、encode 内容压缩

encode zstd gzip

对应 JSON（实测摘录）：

"handle": [{
    "encodings": { "gzip": {}, "zstd": {} },
    "handler": "encode",
    "prefer": ["zstd", "gzip"]
}]
参数说明
zstdZstandard 压缩（压缩率高）
gzip传统 gzip（兼容性好）
brotliBrotli 压缩
顺序prefer 按声明顺序优先返回

四、log 访问日志

log {
    output stdout
    format console
}

对应 JSON（实测摘录）：

"logging": {
    "logs": {
        "log0": {
            "writer": { "output": "stdout" },
            "encoder": { "format": "console" },
            "include": ["http.log.access.log0"]
        }
    }
}
参数说明常用取值
output日志输出stdout / stderr / 文件路径
format日志格式console（可读） / json
level日志级别INFO（默认）/ DEBUG / WARN / ERROR
log 站点内该站点的访问日志覆盖全局默认

五、reverse_proxy 反向代理

:8080 {
    reverse_proxy /api/* 127.0.0.1:9000
}
参数说明
reverse_proxy [路径] 上游地址路径可含通配符；上游地址可多个（负载均衡）
--change-host-header改写 Host 头为上游地址
--header-up / --header-down注入/改写请求/响应头
lb_policy负载均衡策略（round_robin / ip_hash 等）
health_uri / health_port主动健康检查

对应 JSON 关键片段：

"handle": [{
    "handler": "reverse_proxy",
    "upstreams": [ { "dial": "127.0.0.1:9000" } ],
    "load_balancing": { "policy": { "name": "round_robin" } }
}]

六、tls 与自动 HTTPS

example.com {
    tls internal          # 内部自签证书（内网/测试）
    # tls /path/cert.pem /path/key.pem   # 指定证书文件
    reverse_proxy 127.0.0.1:9000
}
参数说明
tls internal使用内置 CA 签发证书（内网用）
tls <cert> <key>手动指定证书与私钥
tls email xxx站点级 ACME 邮箱
不写 tls 指令默认自动 HTTPS（公网域名）

七、redir 重定向

http://old.example.com {
    redir https://new.example.com{uri} permanent
}

生产配置模板

适用场景：16GB 内存、公网域名、静态站 + 反向代理混合。

{
    admin localhost:2019
    email admin@example.com
}

example.com {
    encode zstd gzip
    root * /srv/www
    log {
        output /var/log/caddy/access.log
        format json
    }
}

api.example.com {
    reverse_proxy 127.0.0.1:9000 {
        lb_policy round_robin
    }
}

💡 说明：/var/log/caddy 目录需存在且有写权限（apt 安装默认创建并属 caddy 用户）。

常见问题

Q1：caddy reload 提示配置不合法 A：先 caddy validate --config /etc/caddy/Caddyfile 定位语法错误；站点地址与 listen 冲突时先 caddy stop。

Q2：反向代理 502 A：检查上游地址端口是否可达：curl http://127.0.0.1:9000/；确认 reverse_proxy 路径匹配。

Q3：encode 后页面仍不压缩 A：客户端需带 Accept-Encoding 头；确认 encode 指令在 file_server/reverse_proxy 之前（同一 handle 顺序）。

Q4：admin API 被外部访问 A：admin 默认只监听 localhost:2019；生产可 admin off 或限制监听地址。

参考链接

Caddy 2 配置参数详解 - Quzuo