安装方式#

# Linux 官方脚本（含 systemd 服务）
curl -sfL https://get.caddyserver.com | bash -s personal

# Homebrew
brew install caddy

# Docker
docker run -p 80:80 -p 443:443 \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  caddy:2-alpine

# 自定义模块
xcaddy build v2.8.4 \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/mholt/caddy-dynamicdns

Ubuntu 环境部署示例#

官方推荐通过 Cloudsmith 仓库安装，以便跟随稳定版更新：

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

安装完成后，Caddy 以 caddy 系统用户运行并注册为 systemd 服务：

sudo systemctl status caddy
sudo systemctl enable --now caddy

反向代理 Node.js（端口 3000）示例：

1. 编辑 /etc/caddy/Caddyfile：

   example.com {
     reverse_proxy 127.0.0.1:3000
     encode zstd gzip
     header {
       Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
     }
   }
   

2. 确认 DNS A/AAAA 记录指向服务器，放行 80/443 端口（如使用 UFW：sudo ufw allow 80,443/tcp）。

3. 使用内置格式化与配置校验：

   sudo caddy fmt --overwrite /etc/caddy/Caddyfile
   sudo caddy validate --config /etc/caddy/Caddyfile
   

4. 热重载并查看日志：

   sudo systemctl reload caddy
   journalctl -u caddy -f
   

首次访问 https://example.com 即可看到自动颁发的 Let’s Encrypt 证书，后续续期与 OCSP 由 Caddy 自行处理。若需要自定义证书目录，可在 /etc/caddy/Caddyfile 顶部使用全局段 storage file_system { root /var/lib/caddy } 或挂载远程存储。

Hello Reverse Proxy#

Caddyfile:

example.com {
  reverse_proxy 127.0.0.1:3000
}

执行：

caddy run --config Caddyfile --watch

打开浏览器访问 https://example.com 即自动申请证书并转发请求。

多域名站点 + 自动重定向#

{
  email admin@example.com
  auto_https disable_redirects # 自定义重定向
}

example.com, www.example.com {
  @httpScheme protocol http
  handle @httpScheme {
    redir https://{host}{uri} permanent
  }

  encode zstd gzip

  reverse_proxy {
    to app1:8080 app2:8080
    lb_policy least_conn
    health_interval 20s
    health_timeout 5s
  }

  log {
    output file /var/log/caddy/example.log {
      roll_size 20MB
      roll_keep 7
    }
    format json
  }
}

动态配置（Admin API）#

curl -X POST http://localhost:2019/load -H "Content-Type: application/json" -d @config.json

配置片段（JSON）：

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [{ "host": ["api.example.com"] }],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [{ "dial": "api:9000" }]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

TLS 自动化选项#

*.tenant.example.com {
  tls {
    on_demand            # 客户首次访问时动态申请证书
    issuer acme {
      email tls@example.com
      dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
    renew_before 720h    # 提前 30 天续期
  }

  reverse_proxy {host}.backend.internal:8443
}

On-Demand TLS 需配合访问控制（例如 tls.on_demand ask https://tenant-registry/api/check）避免被恶意滥用。

HTTP/3 与 QUIC 调优#

• 默认开启 HTTP/3；如需关闭：auto_https disable_certs + servers { protocols { enable h3 disable h1 h2 } }。
• 对移动端可增加 header Response add Alt-Svc "h3=\":443\"; ma=86400"。

缓存与边缘处理#

https://assets.example.com {
  root * /var/www/assets
  file_server

  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    Cache-Control "public, max-age=31536000, immutable"
  }

  handle_path /api/* {
    reverse_proxy backend:8080
    header_up X-Forwarded-Proto {scheme}
    header_up X-Request-Id {http.request.id}
  }
}