在 Ubuntu 上安装 Caddy：2026 真正能跑的 APT 配方

Caddy 是唯一默认带自动 HTTPS的主流 web server。在配置里写一个主机名，
它就自动通过 ACME 申请 Let’s Encrypt 证书、设好续期 cron、把 HTTP 重定向到
HTTPS，不用你动一根手指。HTTP/3 也是默认开。Caddyfile 语法干净现代，
每个发行版都是单二进制安装。截至本文撰写时，当前稳定版是 Caddy v2.11.4
（2026-06-03 发布，Matt Holt / ZeroSSL GmbH 维护，Apache-2.0 协议）。

这是给 Ubuntu 22.04 / 24.04 的 2026 官方安装指南，覆盖官方 APT 源、
systemd 单元、三种配置模式（Caddyfile / JSON / API），以及”为什么 Caddy
比 nginx 在某些场景更顺手”的理由。

为什么是 Caddy，简短版

  • HTTPS 自动搞定。 当站点块的第一个 token 是主机名时，Caddy 通过 ACME
    申请公开信任的证书（默认 Let’s Encrypt；ZeroSSL 也支持）。完全自动续期，
    用 CertMagic 在后台跑，不需要 cron 或 shell 脚本。
  • 默认现代。 HTTP/2 和 HTTP/3 (QUIC) 开箱即用。SO_REUSEPORT 支持多核扩展。
    响应默认开 zstd + gzip 压缩。
  • Caddyfile。 一种精简的声明式 DSL，通过 caddy adapt 编译成 JSON。
    nginx 要 30 行搞的事，Caddyfile 90% 两行。
  • Go 原生 JSON 配置（+ gRPC API），如果你想程序化驱动 Caddy——每个
    Caddyfile 内部都是它。用 xcaddy 编译自定义模块，嵌进一个静态二进制。

继续留在 nginx 的两个真实原因：复杂的存量 nginx.conf 要重写；或者你需要某个
没有 Caddy 等价物的第三方 nginx 模块。如果是从零开始，Caddy 是更快的那条路。

安装 —— 官方 Cloudsmith APT 源

Ubuntu universe 仓库里有个 ESM 维护的 Caddy，但版本落后上游大约一年。建议直接
装 Caddy 官方源（Cloudsmith 托管、有签名）：

Bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' 
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' 
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg 
                /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Cloudsmith 的 .deb.txt pipeline 会从同一个 URL 自动选择 Debian/Ubuntu
对应的发行版——不用手动编辑每个 distro 的 source 文件。

如果老的 Ubuntu ESM 包压住了 Cloudsmith 的版本（少见，但如果你 apt policy caddy 看到 universe 版本优先级更高，就 pin 一下）：

Bash
# /etc/apt/preferences.d/caddy-priority
Package: caddy
Pin: origin dl.cloudsmith.io
Pin-Priority: 600

然后 sudo apt update 重装。

安装完会自动启动 caddy.service 并 enable。如果 80 或 443 端口已经被
占用（通常是 nginx 或 apache），启动会失败——先把占用的服务停了：

Bash
sudo systemctl stop nginx apache2
sudo systemctl start caddy
caddy version          # → v2.11.4

三种配置模式

Caddy 的原生配置形式只有一种（Go struct 序列化成 JSON），但你写这个配置有
三个途径：

  1. Caddyfile——对人友好的 DSL。写在 /etc/caddy/Caddyfile。caddy run
    / caddy reload 会自动检测。95% 的日常用法都在这里。
  2. JSON——规范配置。可以手写（少见），也可以由 Caddyfile 通过
    caddy adapt --config Caddyfile --pretty 产出，还可以在运行时通过 API
    驱动。
  3. API——把 JSON POST 到 admin socket 的 /config/
    （默认 localhost:2019，如果你启动 Caddy 时开了 admin listener）。
    在容器化环境里动态添加 vhost 很好用。

APT 包自带的 caddy.service 跑的是 caddy run --environ --config /etc/caddy/Caddyfile，所以日常就是用 Caddyfile。

一份能用的 Caddyfile，从头到尾

最小可用的 Caddyfile：

Caddyfile
# 全局选项（可选；如果有的话必须在最上面）
{
    email admin@example.com    # 证书续期失败时收通知
}

example.com {
    root * /var/www/example.com
    encode zstd gzip
    file_server
}

含义：

  • example.com 是监听地址也是 SNI 证书请求。Caddy 通过 ACME 给
    example.com（以及块里任何额外主机名）申请公开信任证书，自动续期。
  • root * 设磁盘路径，* 是 path matcher（匹配所有请求路径）。
  • encode zstd gzip 加响应压缩。默认 zstd 优先，gzip 兜底。
  • file_server 从 root 提供静态文件。没有这一行，Caddy 2 会 404——
    （不像 Caddy 1 自动 serve 静态文件）。

PHP 应用后接 PHP-FPM（比如带漂亮固定链接的 WordPress）：

Caddyfile
blog.example.com {
    root * /var/www/wordpress
    encode zstd gzip
    php_fastcgi unix//run/php/php8.3-fpm.sock {
        index index.php
    }

    @notFound not file
    rewrite @notFound /index.php?{query}

    file_server
}

rewrite @notFound /index.php?{query} 是漂亮固定链接的关键——不匹配真实文件
的请求会被内部重写到 /index.php，PHP-FPM 再把它交给 WordPress 的 front
controller 路由。

Node 应用跑在 localhost:3000：

Caddyfile
app.example.com {
    encode zstd gzip
    reverse_proxy localhost:3000
}

写完。不用 proxy_set_header Host 或 proxy_set_header X-Forwarded-For——
Caddy 默认就检测 WebSocket 升级、设置正确的 forwarded headers。

Caddy 实际打包的 systemd 单元

官方单元来自 caddyserver/dist，APT 包就是 verbatim 装的它：

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

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

[Install]
WantedBy=multi-user.target

两点值得提：

  • AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE，不只是
    CAP_NET_BIND_SERVICE。CAP_NET_ADMIN 是 HTTP/3 / QUIC 套接字控制和某些
    套接字选项需要的。如果你不要 HTTP/3 想硬化，可以用 drop-in 覆盖：
    sudo systemctl edit caddy → 设置 CapabilityBoundingSet=CAP_NET_BIND_SERVICE。
  • ExecReload=... --force，不是 kill -HUP。Caddy 在进程内重载；老配置
    会保留到新配置启动成功，然后原子切换。

坑（2026 版）

有几件事初次部署必踩。省下你第二次 Google：

  • 忘记 file_server。 Caddy 2 不会默认 serve 静态文件（不像 Caddy 1）。
    光一个 root * /path 加啥都没用，全 404——直到加 file_server。
  • 作用域不能套娃。 file_server 只作用在一个 site block 里。如果你有两个
    site block 从重叠的路径里 serve，要在每个里都设 root。
  • Snap 仓库的 Caddy 不是官方。 sudo snap install caddy 装的是 Yuzukosho
    发布的社区 snap。不由 caddyserver 维护。snap 里的描述文档可能落后好几个
    大版本。没特别理由就用 APT 源。
  • Cloudsmith 仓库 URL 结尾是 /debian/，但 .deb.txt pipeline 会自动选
    Ubuntu 别——别自己改那个 URL，会改坏。
  • 反向代理的超时要调。 reverse_proxy 默认值挺合理，但慢上游要调
    transport：reverse_proxy localhost:3000 { transport http { dial_timeout 5s response_header_timeout 30s } }。
  • 自定义模块要 caddy:2-builder。 如果你需要第三方模块（比如 Cloudflare
    DNS 验证拿通配证书），用 caddy:2-builder 作基础镜像 xcaddy 编译自定义
    二进制。APT 装的二进制只包含标准模块集。

什么时候切去 Caddy / 什么时候别切

切的情况：

  • 每个新项目都从 TLS 开始，不想再为 Let’s Encrypt 写客户端/cron/钩子脚本。
  • 想要默认开 HTTP/3。
  • 配置主要是静态——site 块、文件服务、反向代理——没有太复杂的重写逻辑。

不切的情况：

  • 有大量存量 nginx.conf，里面有复杂的 if / map / set 块，重写代价大。
  • 依赖某个特定的第三方 nginx 模块（比如 nginx-mod-perl、Pagespeed），它们没
    有 Caddy 等价物。
  • 需要 stream (TCP/UDP) 代理——Caddy 在 2.10 (2025) 加了这功能，但文档比
    nginx stream 模块没那么久经考验。

TL;DR

任何 Ubuntu 22.04 / 24.04 上的 2026 新部署：

Bash
# 一次性
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' 
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' 
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg 
                /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

# 日常
$EDITOR /etc/caddy/Caddyfile
sudo systemctl reload caddy

这就是全部故事。HTTPS、HTTP/3、反向代理、PHP-FPM——全都直接 work。

参考资料

最后修改： 2026年7月16日

作者

评论

发表评论

您的邮箱地址不会被公开。