Caddy

自动 HTTPS 到底省掉了什么

传统做法是 certbot 或 acme.sh：申请证书、配置续期定时任务、处理续期失败。少一步就掉链子——续期任务静默失败，证书过期那天才发现。

Caddy 把这件事写进了协议本身：Caddyfile 里出现一个真实域名，Caddy 就自动去申请证书并自己续期，不用配任何定时任务。

最小配置只有一行：

caddyexample.com {
    root * /var/www/html
    file_server
}

这一个块做了三件事：监听 80 与 443、为 example.com 申请并续期证书、把 /var/www/html 当静态目录发出去。

端口不能省

80 和 443 要同时留着。80 端口不是「http 的备用口」，验证和跳转都要用：Let's Encrypt 的 HTTP-01 验证走 80 端口，所有 http 请求也靠它跳到 https。

Caddy 默认在这两个端口上监听。改端口配置去做非标准端口当然可以，但那样就失去了自动 HTTPS——证书验证和跳转都依赖标准端口。

容器里要注意：镜像默认不会占用宿主机的 80/443，映射时显式写出来。

bashdocker run -d -p 80:80 -p 443:443 -p 443:443/udp \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  caddy

443 的 UDP 也要映射。这是 HTTP/3（基于 QUIC）用的，只映射 TCP 的话 HTTP/3 不会生效——不会坏，只是回落成 HTTP/2。追求完整行为才需要它。

内网地址不申请证书

localhost、IP 地址、.local 结尾的域名这类内部主机名不触发证书申请，Caddy 直接按 HTTP 处理。所以本地调试不需要任何证书配置。

想让内网域名也用上正规证书，用 tls internal 签一张自签证书：

caddynas.lan {
    tls internal
    reverse_proxy localhost:8080
}

自签证书浏览器会警告，要手动信任。用 caddy trust 可以装进本机信任库。

改配置不要重启

生产环境改配置用 caddy reload，不要 stop 再 start。 重启意味着几秒到几十秒的连接中断，reload 是平滑的。

bashcaddy validate --config /etc/caddy/Caddyfile
caddy reload  --config /etc/caddy/Caddyfile

caddy validate 值得单独说一句：它不只检查语法，还会真的加载并初始化所有模块，因此能抓出「语法对但证书文件不存在」这类问题。caddy adapt 只做语法转换，抓不到。

写完先 validate 再 reload，比 reload 失败后回滚省事。

bashcaddy fmt --overwrite /etc/caddy/Caddyfile

caddy fmt --overwrite 会把 Caddyfile 按规范缩进整理好。手写的 Caddyfile 缩进常常乱七八糟，格式化之后 diff 清晰得多。

反向代理

代理到本地服务，reverse_proxy 一行就够：

caddyapi.example.com {
    reverse_proxy localhost:3000
}

WebSocket 不需要额外配置，Caddy 会自动处理 Upgrade 头。

前面挂静态资源、后面兜 API，一个文件里写完：

caddyexample.com {
    handle /api/* {
        reverse_proxy localhost:3000
    }
    handle {
        root * /var/www/html
        file_server
    }
}

handle 块按顺序匹配，第一个命中的生效，所以具体的放前面，兜底的放最后。这个顺序和 nginx 的 location 相反，写反了会全被兜底块吃掉。

文件在哪

Caddy 官方没有强制配置文件的统一位置——除了当前目录下的 Caddyfile 会被自动找到。包管理器安装的版本把配置文件放在 /etc/caddy/Caddyfile。

macOS 与 Windows 用 Homebrew / Chocolatey / Scoop 装的，配置文件位置随安装方式变，用 caddy adapt 不带参数跑一次能看出它当前读的是哪个文件。

数据目录不能当缓存清。 里面有 TLS 私钥、证书、OCSP staple。删掉不会立刻坏，但下次启动要重新走一遍验证和申请。