跳到主要内容
安装配置教程

Caddy SSL 证书安装怎么做?Caddyfile 自动 HTTPS 与手动证书完整指南

caddy ssl证书安装 — Caddy SSL 证书安装怎么做?Caddyfile 自动 HTTPS 与手动证书完整指南
核心结论

Caddy 安装 SSL 证书不需要手动跑 certbot:只要域名 A/AAAA 解析到服务器、80/443 可访问,Caddy v2.8+ 会在启动时自动向 Let's Encrypt/ZeroSSL 申请并续期证书,systemd 安装的证书默认存放在 /var/lib/caddy/.local/share/caddy。 最小 Caddyfile 只需 `example.com { reverse_proxy 127.0.0.1:8080 }`,执行 `caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile` 后 `systemctl reload caddy` 即可生效。 手动证书用 `tls /etc/ssl/fullchain.pem /etc/ssl/privkey.pem`,fullchain.pem 必须包含中间证书,否则部分 Android/Java 客户端会报 `unable to get local issuer certificate`。 遇到 429 先看 Let's Encrypt 限额:每注册域名 7 天 50 张、重复证书 5 张/周;测试时用 `acme_ca https://acme-staging-v02.api.letsencrypt.org/directory` 避免消耗生产额度。 验证命令:`openssl s_client -connect example.com:443 -servername example.com -status </dev/null` 应看到 `Verify return code: 0 (ok)` 与 OCSP 响应。

为什么 Caddy 装 SSL 证书会失败?先看自动 HTTPS 的 4 个前提

Caddy 的 Automatic HTTPS 是默认行为,不是可选项。据 Caddy 官方文档(v2 系列,auto_https 默认值为 on),只要站点地址写的是域名、没有加 http:// 前缀、也没有全局关闭 auto_https,Caddy 就会在启动时自动完成 ACME 下单、HTTP-01 或 TLS-ALPN-01 校验、证书落盘,并把 80 端口请求以 308 跳转到 443。所以当 caddy ssl证书安装 失败时,问题几乎不在”装”这一步,而在下面四个前提之一。

前提 1:DNS 必须指向本机,且 AAAA 记录不能是”坑”。很多人只核对了 A 记录就以为万事大吉,但 ACME 服务端在双栈环境下会优先走 IPv6。若 AAAA 指向一台没监听 443 的机器,日志里会出现 Timeout during connect (likely firewall problem)。

# 同时核对 A 与 AAAA,两条都必须指向当前主机
dig +short example.com A
dig +short example.com AAAA

# 本机出口 IP 对照(IPv4 / IPv6)
curl -4 -s https://ifconfig.me; echo
curl -6 -s https://ifconfig.me; echo

前提 2:公网 80/443 必须可达。HTTP-01 走 80,TLS-ALPN-01 走 443(RFC 8737)。云厂商安全组、firewalld、ufw 三层都要放行 80/tcp 与 443/tcp。

# 确认 caddy 真的在监听这两个端口(应看到 caddy 进程)
ss -lntp | grep -E ':80|:443'

# firewalld
firewall-cmd --permanent --add-service=http --add-service=https && firewall-cmd --reload
# ufw
ufw allow 80/tcp && ufw allow 443/tcp

前提 3:CDN 代理方式必须与校验方式匹配。Cloudflare 橙云会在边缘终止 TLS,源站拿不到 ALPN 握手,TLS-ALPN-01 因此不可用;此时 Caddy 仍能靠 HTTP-01 回源拿证。但若你开了”始终使用 HTTPS”或源站只保留 443,就必须改用 DNS-01。

校验方式 使用端口 能否穿透 Cloudflare 橙云 典型适用场景
HTTP-01 80/tcp 可以(需允许回源 80) 单机、无通配符
TLS-ALPN-01 443/tcp 不可以 仅 443 对外开放、无 CDN
DNS-01 无(走 API) 可以 通配符证书、源站只开 443

前提 4:ACME 邮箱与 CA 配置正确。全局块里写 email,否则到期提醒无人接收;调试期务必切到 Let’s Encrypt 暂存环境,避免触发生产限额(据 Let’s Encrypt 文档,同一注册域名每周签发上限为 50 张)。

{
    # 全局选项块
    email ops@example.com
    # 仅测试用:切换后签发的证书不被浏览器信任,正式上线请注释掉
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

example.com {
    reverse_proxy 127.0.0.1:8080
}

还有一个常被忽略的根因:系统时间。时钟偏差超过 5 分钟,ACME 握手会直接报 x509: certificate has expired or is not yet valid。用 timedatectl 确认输出里有 System clock synchronized: yes,修正后 systemctl restart caddy 重试即可。证书与私钥默认存放在 /var/lib/caddy/.local/share/caddy/certificates/,排查时可先看该目录下是否已有对应域名的 .crt 与 .key。

Caddy SSL 证书安装的完整 6 步:从安装到 reload

问:caddy ssl证书安装到底要几步?答:6 步——装包、写 Caddyfile、validate、reload、看日志、备份数据目录。关键在于 Caddy 的”自动 HTTPS”默认开启:只要 Caddyfile 里出现裸域名,它就会通过 ACME(RFC 8555)自动申请并续期证书,无需你手写 certbot 或拼接证书链。Caddy 官方文档明确说明,自动 HTTPS 是默认行为,只有显式关闭(auto_https off)或用 tls 指令指定自有证书时才会改变。下面按顺序给出可复制命令。

  1. 安装(Debian/Ubuntu):走 Cloudsmith 官方源,不要用发行版仓库里的旧版本。
    # Debian 12 / Ubuntu 22.04+,需 root 或 sudo
    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 apt update && sudo apt install caddy
    caddy version    # 期望:v2.8.4 h1:q3pe0wpBj1OcHFZ3n/1nl4V4bxOvQ9HrCmoNhHTO1WQ=
    

    caddy version 应显示 v2.8.x 或 v2.9.x;若仍是 2.6.x,说明源没生效,apt policy caddy 可核对候选版本。

  2. 写 Caddyfile:/etc/caddy/Caddyfile 是 Debian 包默认路径,systemd 单元以 --config 指向它。
    sudo tee /etc/caddy/Caddyfile >/dev/null <<'EOF'
    example.com {
    	encode zstd gzip
    	reverse_proxy 127.0.0.1:8080
    }
    EOF
    sudo caddy fmt --overwrite /etc/caddy/Caddyfile   # 统一为 Tab 缩进
    

    不写 tls 指令即走自动签发;Caddy 2.7 起默认 CA 为 Let’s Encrypt,失败会回退 ZeroSSL,可用全局 acme_ca 覆盖。据 Let’s Encrypt 文档,其证书有效期 90 天,而 Caddy 默认在剩余 1/3 有效期时自动续期。

  3. 校验配置:先验证再 reload,避免线上 502。
    sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
    # 成功:Valid configuration
    # 失败示例:Error: adapting config using caddyfile: /etc/caddy/Caddyfile:3:
    #           unrecognized directive: revrse_proxy
    

    报错自带文件与行号,按行修完再进下一步。

  4. 启动与重载:首次 sudo systemctl enable --now caddy;之后每次改配置只用 sudo systemctl reload caddy。这是零停机操作——旧连接按已有超时自然结束,新连接立刻用新配置,适合滚动发布。
    操作 命令 连接影响 适用场景
    reload systemctl reload caddy 不断开,零停机 改路由/反代/证书配置
    restart systemctl restart caddy 连接被重置 升级二进制、改 systemd 单元
  5. 看日志确认签发:sudo journalctl -u caddy -f,正常可见 certificate obtained successfully 与 serving initial configuration。首次签发通常 5–30 秒;DNS 尚未生效或 80 端口被占用时可能拖到 1–3 分钟。若出现 challenge failed,先查 curl -I http://example.com 是否 200。
  6. 备份数据目录:/var/lib/caddy/.local/share/caddy 下有 certificates/、acme/(ACME 账户私钥)、pki/(内部 CA)。
    sudo tar czf caddy-data-$(date +%F).tar.gz -C /var/lib/caddy/.local/share caddy
    # 迁移恢复后必须修权限,否则 Caddy 无法读取私钥
    sudo tar xzf caddy-data-*.tar.gz -C /var/lib/caddy/.local/share
    sudo chown -R caddy:caddy /var/lib/caddy/.local/share/caddy
    sudo chmod 700 /var/lib/caddy/.local/share/caddy
    sudo find /var/lib/caddy/.local/share/caddy -name '*.key' -exec chmod 600 {} ;
    

    目录 700、私钥 600 是 Caddy 自身写入时的权限约定;拷贝时用 cp -a 或 tar 才能保留,否则会触发 permission denied 并重新签发,白白消耗 Let’s Encrypt 的速率限制配额。

完成这 6 步,一次标准的 caddy ssl证书安装 就闭环了:证书由 Caddy 托管,你只维护 Caddyfile 与数据目录。若后续要换成企业自有证书,只需在同一位置追加 tls /path/cert.pem /path/key.pem,其余步骤不变。

Caddyfile 与命令示例:域名站点、反向代理、手动证书三种写法

Caddy 的配置文件写法极度精简,但”自动 HTTPS”与”手动证书”两条路径在语法上只差一行 tls 指令。下面按静态站点、反向代理、手动证书三种真实场景给出可直接复制的片段,并标注适用版本与默认行为。以下示例在 Caddy 2.7.x / 2.8.x 上验证通过(caddy version 可确认)。

静态站点:不写证书路径也能自动签发

只要站点地址是一个公网可解析的域名,Caddy 默认启用 Automatic HTTPS:自动向 Let’s Encrypt 申请证书、自动完成 HTTP→HTTPS 跳转、自动续期。据 Caddy 官方文档,该行为由 auto_https 全局选项控制,默认值为 on。

# /etc/caddy/Caddyfile
example.com {
    root * /var/www/html
    file_server
    encode gzip zstd          # zstd 需 Caddy 2.6+;默认只编译 gzip
    tls {
        protocols tls1.2 tls1.3   # 只限制协议版本,不指定证书 → 仍走 Automatic HTTPS
    }
}

关键点:tls 块内若没有证书文件参数,Caddy 会继续使用内部 ACME 流程,而不是”降级为无证书”。protocols 的可选值为 tls1.0–tls1.3,默认允许 1.2 与 1.3;显式写 tls1.3 会拒绝所有 TLS 1.2 客户端,老旧 Android 与部分 IoT 设备将无法连接。

反向代理:WebSocket 无需额外配置

app.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Real-IP {remote_host}
        health_uri /healthz          # 主动健康检查,默认关闭
        health_interval 10s          # 默认 30s
    }
}

Caddy 的 reverse_proxy 默认使用 HTTP/1.1 与后端通信,并自动透传 Upgrade、Connection 头,因此 WebSocket、gRPC-Web 无需像 Nginx 那样手写 proxy_set_header Upgrade $http_upgrade。若后端是纯 gRPC(HTTP/2),需显式加 transport http { versions h2c }。

手动证书:企业已有证书时的写法

shop.example.com {
    tls /etc/ssl/shop/fullchain.pem /etc/ssl/shop/privkey.pem
    reverse_proxy 127.0.0.1:3000
}

fullchain.pem 必须按”站点证书 → 中间证书”顺序拼接,顺序颠倒会导致部分客户端报 unable to get local issuer certificate。privkey.pem 推荐 RSA 2048 或 ECDSA P-256;据 OpenSSL 文档,ECDSA P-256 在同等安全强度下握手更快、证书更小。可用 openssl x509 -in fullchain.pem -noout -subject -issuer 校验链路。

全局块:指定 ACME 邮箱与 CA

{
    email ops@example.com
    acme_ca https://acme-v02.api.letsencrypt.org/directory
    # 仅企业自建 ACME(step-ca / Smallstep)才需要下一行:
    # acme_ca_root /etc/ssl/certs/isrgrootx1.pem
}

不填 email 时 Caddy 仍能签发,但会失去证书到期提醒。acme_ca 默认值即 Let’s Encrypt 生产环境目录;切换 Let’s Encrypt 测试环境应改为 https://acme-staging-v02.api.letsencrypt.org/directory,避免触发速率限制(据 Let’s Encrypt 文档,同一注册域名每周 50 张)。

内网/本地测试:tls internal

localhost {
    tls internal
    respond "OK"
}

tls internal 使用 Caddy 自建本地 CA 签发,浏览器需手动信任根证书,路径通常为 /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt(以 caddy environ 输出的 XDG_DATA_HOME 为准)。

命令速查与模块检查

# 前台调试,日志直接输出到终端
caddy run --config /etc/caddy/Caddyfile --adapter caddyfile

# 零停机热重载(修改 Caddyfile 后执行)
caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile

# 校验语法但不启动
caddy validate --config /etc/caddy/Caddyfile

# 查看已编译模块(DNS 插件、tls 相关)
caddy list-modules | grep -E 'dns.providers|tls'

若 list-modules 输出中没有 dns.providers.cloudflare 等条目,说明当前二进制未包含该 DNS 插件,DNS-01 挑战将失败并报 no solver found for challenge type DNS-01——此时需用 xcaddy build --with github.com/caddy-dns/cloudflare 重新编译。这也解释了为什么”caddy ssl证书安装”在内网场景下常需要自定义构建,而公网域名场景开箱即用。

场景 关键指令 证书来源 是否需要开放 80 端口
公网静态站 tls { protocols ... } Let’s Encrypt(自动) 是(HTTP-01 挑战)
反向代理 reverse_proxy Let’s Encrypt(自动) 是
已有商业证书 tls cert key 手动文件 否
内网/本地 tls internal Caddy 本地 CA 否

自动 ACME、DNS-01、手动证书怎么选?参数与场景对比表

选方案之前先回答三个问题:服务器的 80 和 443 端口能不能从公网直接访问?需不需要一张 *.example.com 泛域名证书?证书必须来自企业自建 CA 或已采购的商业 CA 吗?三个答案基本就锁定了方案——绝大多数单机公网站点用 Caddy 默认的 Automatic HTTPS 就够了,连一行 TLS 配置都不用写;只有泛域名、内网源站、CDN 回源受限这几种情况才需要切换到 DNS-01。下面这张表是 caddy ssl证书安装 的决策依据。

方案 适用场景 关键配置 续期方式 注意事项
自动 HTTP-01 公网 80/443 直连 站点块写域名即可,Automatic HTTPS 默认开启 Caddy 自动续期,90 天证书剩余约 30 天时开始 80 端口必须可达
自动 TLS-ALPN-01 80 被封但 443 可达 默认启用,无需额外配置 自动 CDN 橙云(仅代理模式)下不可用
DNS-01 无法开放 80/443、泛域名 编译 DNS provider 插件 + tls { dns cloudflare {env.CF_API_TOKEN} } 自动 需要 CA 可验证的 API Token
手动证书 企业 CA、已有商业证书 tls cert.pem key.pem 自行续期 + reload 证书链必须完整

自动 HTTP-01 和 TLS-ALPN-01 到底差在哪?差在挑战走哪个端口:HTTP-01 在 80 端口放一个 /.well-known/acme-challenge/ 文本文件,TLS-ALPN-01(RFC 8737)则在 443 上完成一次带 acme-tls/1 ALPN 扩展的 TLS 握手。据 Caddy 官方 Automatic HTTPS 文档,Caddy 默认会同时尝试这两种挑战,哪个先成功用哪个,因此不需要 DNS API、也不需要额外配置,是单机站点的默认最优解。上线前可以先确认端口真实可达:

# 验证 80 端口对外可达(HTTP-01 前提);返回 404 也算通,说明端口没被墙
curl -sS -o /dev/null -w 'http-01 port80: %{http_code}n' http://example.com/.well-known/acme-challenge/probe

# 验证 443 端口可达(TLS-ALPN-01 前提)
curl -sS -o /dev/null -w 'tls-alpn port443: %{http_code}n' https://example.com/

# 查看 Caddy 实际用了哪种挑战(v2.8.x,需 debug 日志)
journalctl -u caddy -n 200 | grep -Ei 'challenge|acme'

DNS-01 为什么必须自己编译?因为 DNS provider 属于 Caddy 的可选模块,官方二进制只内置了最常见的几个。用 xcaddy 构建(需要 Go 1.21+,插件版本随主版本对应):

# 构建带 Cloudflare DNS 插件的 Caddy,v2.8.4 为示例版本号
xcaddy build v2.8.4 
  --with github.com/caddy-dns/cloudflare

# 构建完成后替换系统二进制并重启
./caddy version
sudo systemctl restart caddy
# /etc/caddy/Caddyfile —— 泛域名只能用 DNS-01
*.example.com, example.com {
	# Token 走环境变量,避免明文写进配置文件
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}
	reverse_proxy 10.0.0.10:8080
}

# systemd 注入环境变量:systemctl edit caddy 中加入
# [Service]
# Environment=CF_API_TOKEN=xxxxxxxx

如果忘了编译插件,Caddy 会直接拒绝启动,报错是可检索的原文:loading module 'dns.providers.cloudflare': unknown module: 'dns.providers.cloudflare'。

手动证书什么时候值得用?当证书来自企业 CA、或已经买了商业证书、或源站在完全隔离的内网时。此时 Caddy 只负责“部署”不负责“申请”,也不会自动续期:

# /etc/caddy/Caddyfile —— 手动证书必须用完整链文件
example.com {
	tls /etc/caddy/certs/fullchain.pem /etc/caddy/certs/privkey.pem
	encode gzip
	reverse_proxy 127.0.0.1:3000
}

# 续期后热加载(不中断连接),二选一
certbot renew --deploy-hook "systemctl reload caddy"
caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile

只给 cert.pem 而不给 fullchain.pem 是最高频的坑,客户端会报 unable to get local issuer certificate;同时注意 key 文件权限 600、属主必须能被 caddy 用户读取。

成本与默认值。Let’s Encrypt 与 ZeroSSL 均免费(据 Let’s Encrypt 文档,证书有效期 90 天,官方建议在到期前 30 天续期,与 Caddy 默认“剩余 1/3 生命周期时续期”一致);商业 DV 约 100–500 元/年,OV 约 1000–3000 元/年。Caddy 本身 Apache-2.0 免费,tls 指令默认 protocols tls1.2 tls1.3,不要为了兼容老设备再打开 TLS 1.0/1.1——它们已被 RFC 8996 正式弃用。

真实报错与排查:429、连接超时、443 占用、证书链不完整

这六类报错占了 Caddy 证书问题的九成以上。先看速查表,再逐条给出可复制的排查命令;按表中“验证命令”先确认根因,再改配置,比盲目重启 Caddy 快得多。

报错关键片段 根因 一条验证命令 处理方向
listen tcp :443: bind: address already in use Nginx/Apache 已监听 443 ss -lntp | grep ':443' 停前置服务,或 Caddy 改 :8443
acme: error: 429 ... too many certificates (5) Let’s Encrypt 重复证书限额 查 caddy 数据目录是否存在 切 staging,等 7 天
Timeout during connect (likely firewall problem) 80/443 被安全组拦截或 DNS 未生效 dig +short 域名 放行端口、等 TTL
/.well-known/acme-challenge/... 返回 404 前置 Nginx/CDN 抢 80,或站点写成 http:// curl -I http://域名/.well-known/... 让 Caddy 独占 80,或改 DNS-01
x509: certificate signed by unknown authority 缺中间证书 openssl verify -CAfile chain.pem fullchain.pem 补 fullchain,至少 2 段证书
tls: no certificates configured for that SNI 访问域名不在 Caddyfile 站点块内 openssl s_client -servername 错误域名 补站点块或泛域名证书

1. 443 端口被占用怎么办?先定位 PID 再决定“停谁”,不要两个进程同时监听 443:

# 找到占用 443 的进程(需 root)
ss -lntp | grep ':443'
# 典型输出:LISTEN 0 511 0.0.0.0:443 users:(("nginx",pid=1234,fd=6))

systemctl stop nginx && systemctl disable nginx   # 方案 A:让 Caddy 独占 80/443

# 方案 B:Caddyfile 改成高位端口,由前置代理转发 TLS
example.com:8443 {
    reverse_proxy 127.0.0.1:8080
}

Caddy v2 的自动 HTTPS 默认监听 80 和 443(见 caddyserver.com/docs/automatic-https),端口被占时 ACME 校验也会连带失败,所以务必先解决绑定冲突。

2. 429 限额触发后能不能马上重试?不能。据 Let’s Encrypt 速率限制文档(letsencrypt.org/docs/rate-limits/),同一组域名每 168 小时最多签发 5 张重复证书,重试只会继续消耗失败验证配额(每小时每主机名 5 次)。改用 staging CA 测试:

{
    email admin@example.com
    # 测试期指向 staging,避免消耗生产配额;上线前删掉此行
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

生产环境只能等满 7 天。反复签发最常见的原因是误删了 Caddy 数据目录(默认 $XDG_DATA_HOME/caddy,systemd 部署下多为 /var/lib/caddy/.local/share/caddy),证书缓存丢失后每次重启都重新申请——这本质上是 caddy ssl证书安装流程中最容易自己踩的坑。

3. 超时和 404 怎么区分?超时是网络层不通,404 是应用层有人替你回了响应。从外网机器执行:

dig +short example.com                       # 核对解析 IP 是否为当前服务器
curl -I http://example.com/.well-known/acme-challenge/test
# 超时 → 安全组/防火墙放行 80、443
# 404  → 80 端口被 Nginx/CDN 抢走,或 Caddyfile 写成了 http://example.com(会禁用自动 HTTPS)

无法开放 80 时,改用 DNS-01(需用 xcaddy 编译对应 DNS 插件):

tls {
    dns cloudflare {env.CF_API_TOKEN}   # 需 Caddy 构建时包含 caddy-dns/cloudflare 模块
}

4. 客户端报“未知颁发机构”是证书问题还是信任问题?先数证书段数:

grep -c 'BEGIN CERTIFICATE' fullchain.pem    # 正常应 ≥ 2(叶子 + 中间)
openssl verify -CAfile chain.pem fullchain.pem
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null

fullchain.pem 只有 1 段就说明漏了中间证书;若是企业私有 CA,则要在客户端安装根证书,而非改服务器。

5. SNI 报错怎么复现?用错误域名主动触发,确认 Caddy 是否有对应站点块:

openssl s_client -connect 1.2.3.4:443 -servername wrong.example.com </dev/null
# 返回 tls: no certificates configured for that SNI 即确认无匹配站点

修复方式是补上该域名的站点块,或为通配场景配置泛域名证书。若这些报错都已排除,手动证书场景请继续核对 tls <cert> <key> 的文件权限与路径,这是 caddy ssl证书安装 中仅次于限额的高频失败点。

如何验证 Caddy SSL 证书已生效?6 条命令与预期输出

证书签发成功 ≠ 浏览器信任。验证的核心是”三看”:看 HTTP 层是否强制跳转、看 TLS 握手返回的证书链是否完整、看客户端校验结果是否为 0。下面 6 条命令按”从外到内”的顺序排列,任一条不符合预期,基本能定位到具体环节。

1)HTTPS 主站是否 200,且由 Caddy 直接响应?

curl -I https://example.com
# 预期输出(节选)
# HTTP/2 200
# server: Caddy
# strict-transport-security: max-age=31536000

看到 HTTP/2 200 说明 TLS 握手与 HTTP/2 协商都正常。注意:据 Caddy 官方文档,Caddy v2 默认不发送 HSTS 头,若这里缺 strict-transport-security,不是证书问题,而是需要在 Caddyfile 里显式加一行 header Strict-Transport-Security "max-age=31536000; includeSubDomains"(默认无 max-age,取值建议 ≥31536000 秒)。

2)HTTP 是否强制跳转到 HTTPS?

curl -I http://example.com
# HTTP/1.1 308 Permanent Redirect
# Location: https://example.com/

Caddy 的 Automatic HTTPS 默认行为就是 301/308 跳转,返回 308 而非 301 属于正常现象(保留请求方法)。若返回 200,说明站点被显式配置成了 http:// 站点块,需要检查 Caddyfile 里的站点地址。

3)证书主体、签发者与有效期是否正确?

openssl s_client -connect example.com:443 -servername example.com -tls1_2 /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R11
# notBefore=...  notAfter=...

-servername 必须带,否则 SNI 缺失会拿到默认证书。据 Let’s Encrypt 文档,其证书有效期固定为 90 天,notAfter 距今约 60~90 天属正常;若只剩几天,检查 Caddy 的自动续期是否被防火墙或 80 端口占用阻断(续期走 HTTP-01 或 TLS-ALPN-01)。issuer 为 R10/R11/E5/E6 均属当前 Let’s Encrypt 中间证书体系。

4)OCSP stapling 是否生效?

openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -A1 "OCSP response"
# OCSP Response Status: successful (0x0)

Caddy 对由其托管的证书默认启用 OCSP stapling,无需额外配置。若输出 no response sent,常见原因是使用了手动加载的证书(tls cert.pem key.pem)而中间证书链未拼接完整。

5)客户端视角的链验证结果是否为 0?

curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result} %{time_total}n' https://example.com
# 200 0 0.123

ssl_verify_result 为 0 表示链验证通过;非 0(如 20 = unable to get local issuer certificate)优先排查服务器是否漏发中间证书,其次检查客户端 ca-certificates 包版本。

6)配置语法与进程状态是否健康?

caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
# 2024/05/01 10:00:00.000 INFO  using config from file  {"file": "/etc/caddy/Caddyfile"}
# Valid configuration

systemctl status caddy --no-pager | head -n 5
# Active: active (running)
journalctl -u caddy --since "1 hour ago" | grep -i error

caddy validate 自 Caddy v2.5 起提供,务必带 --adapter caddyfile,否则会按 JSON 解析而报错。journalctl 无输出才代表近一小时没有 error 级日志;出现 tls.obtain 相关 error 通常是 80/443 端口被占用或 DNS 未指向本机。

外部交叉验证可用 SSL Labs 与 testssl.sh:

工具 / 命令 检查项 合格标准 不通过时的排查方向
curl -I https:// HTTP 状态、HSTS、server 头 HTTP/2 200、server: Caddy HSTS 需手动配置 header 指令
curl -I http:// 强制跳转 308 Permanent Redirect 站点地址写成了 http://
openssl x509 CN / issuer / 有效期 CN 匹配域名,issuer 为 LE,有效期 90 天 续期失败、端口被拦
openssl -status OCSP stapling OCSP Response Status: successful 手动证书未带中间链
curl -w '%{ssl_verify_result}' 链验证 0 缺中间证书 / CA 包过旧
testssl.sh --fast example.com 协议版本、套件 TLS 1.0/1.1 关闭,TLS 1.3 开启 旧版 Caddy 或自定义 tls 配置

其中 SSL Labs 直接打开 https://www.ssllabs.com/ssltest/analyze.html?d=example.com,重点看 Certificate 一栏是否 “Chain issues: None”、Protocols 是否只勾选 TLS 1.2/1.3;testssl.sh 的 --fast 模式约 30 秒出结果,适合放进 CI 做上线前的回归检查。至此,Caddy SSL 证书安装是否真正生效,已能从服务端配置、TLS 握手、客户端信任三个层面同时得到印证。

生产环境加固:TLS 版本、HSTS、OCSP、续期与备份

Caddy 默认的 TLS 版本是多少,还需要手写 tls 指令吗?

Caddy v2(当前稳定版 2.8.x)基于 Go 标准库,默认最低 TLS 1.2、最高 TLS 1.3,开箱即用就满足 PCI DSS 与 RFC 8996 的要求——后者已于 2021 年正式弃用 TLS 1.0/1.1。因此 tls { protocols tls1.2 tls1.3 } 属于”显式声明”而非”必需配置”,写出来的价值在于让审计人员一眼看到策略,同时防止后续升级或全局 options 覆盖时被悄悄放宽。不要为老设备加回 tls1.0,Mozilla 服务器 TLS 指南明确建议现代站点只保留 1.2 与 1.3。

tls 子指令 默认值(Caddy 2.8) 备注
protocols tls1.2 tls1.3 可写 tls1.0–tls1.3,不建议低于 1.2
alpn h2 http/1.1 HTTP/3 由站点级 protocols h1 h2 h3 控制
ciphers Go 自动协商 TLS 1.3 套件不可配置,由 Go 固定

HSTS 能不能一上线就写一年加 preload?

不建议。HSTS 是”单向承诺”:浏览器一旦缓存 max-age,在到期前你用 HTTP 访问都会被强制跳转,证书出问题就直接全站不可达。上线首日先给 5 分钟窗口观察,确认全站(含子域、API、静态资源)都是 HTTPS 后再逐级放大:max-age=300 跑 1–2 天 → max-age=31536000; includeSubDomains → 确认无混合内容后再追加 preload 并向 hstspreload.org 提交(Chromium 内置列表更新有数月延迟,撤回同样困难)。

example.com {
	# 观察期:先只加 max-age=300,稳定后替换为下面注释中的完整值
	header Strict-Transport-Security "max-age=300; includeSubDomains"
	# header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

	tls {
		protocols tls1.2 tls1.3   # 显式锁定,防止被全局 options 放宽
	}
	reverse_proxy 127.0.0.1:8080
}

手动证书的 OCSP 和 fullchain 怎么验证?

Caddy 对自动签发的托管证书会自动做 OCSP stapling 并缓存响应,握手不会因等待 OCSP 而阻塞。手动证书(tls /etc/caddy/fullchain.pem /etc/caddy/privkey.pem)则要求 fullchain.pem 必须包含中间证书,否则部分安卓和旧客户端报 unable to get local issuer certificate。需要说明的是,据 Let’s Encrypt 官方公告《Ending OCSP Support in 2025》,LE 已在 2025 年逐步关闭 OCSP 响应服务,因此 LE 证书的 stapling 结果可能为空,这属正常现象,不必强行开启。

# 1) 查看协商协议、是否带回 OCSP stapling
openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -E "Protocol|OCSP Response Status|Verify return code"

# 2) 确认 HSTS 与安全头已下发
curl -sI https://example.com | grep -iE "strict-transport-security|x-content-type"

证书什么时候续期,怎么提前发现快过期?

托管证书默认在剩余约 1/3 生命周期时续期,90 天的 Let’s Encrypt 证书即提前约 30 天。日志里搜 certificate obtained successfully 可确认续期动作;再用 -checkend 做兜底告警(返回非 0 表示已进入阈值内):

CERT=/var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/example.com/example.com.crt
openssl x509 -in "$CERT" -noout -enddate
# 2592000 秒 = 30 天,进入窗口返回 1,可直接接入 cron/监控
openssl x509 -in "$CERT" -checkend 2592000 -noout || echo "WARN: 证书 30 天内到期"

迁移服务器要备份哪些目录?恢复后为什么 Caddy 起不来?

只需两处:/etc/caddy/Caddyfile 与 /var/lib/caddy/.local/share/caddy(后者存放账户密钥、证书与私钥)。恢复后忘记改属主是最常见的坑,典型报错为 loading certificates: open /var/lib/caddy/.local/share/caddy/.../privkey.pem: permission denied,Caddy 会直接拒绝加载配置。目录保持 700、私钥 600 是 Caddy 自身的安全约束。

# 备份
tar -czf caddy-$(date +%F).tar.gz /etc/caddy/Caddyfile /var/lib/caddy/.local/share/caddy

# 恢复后修正权限,否则 Caddy 拒绝读取私钥
chown -R caddy:caddy /var/lib/caddy/.local/share/caddy
chmod 700 /var/lib/caddy/.local/share/caddy
find /var/lib/caddy/.local/share/caddy -name "*.key" -exec chmod 600 {} ;
caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy

安全响应头怎么加才不会把页面搞白屏?

先用零风险的三件套(MIME 嗅探、点击劫持、Referrer 泄漏),CSP 单独走:先 Content-Security-Policy-Report-Only 收集违规报告跑一周,再切到强制模式。Mozilla Observatory 的评分逻辑也是”渐进收紧”,一次性上 default-src 'self' 往往会拦掉内联脚本、CDN 字体和第三方统计,表现为控制台一片 Refused to load ...。

header {
	X-Content-Type-Options nosniff
	X-Frame-Options SAMEORIGIN
	Referrer-Policy strict-origin-when-cross-origin
	# 观察期用 Report-Only,确认无违规后去掉 -Report-Only 改为强制
	Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report"
}

Caddy 与 Nginx+certbot、宝塔、Cloudflare 的差异与迁移注意

Caddy 和 Nginx + certbot 的核心差别是什么?一句话:Caddy 把 ACME 客户端编译进了二进制,进程启动即申请证书,并在证书剩余寿命不足 1/3 时自动续期(Let’s Encrypt 90 天证书约在第 60 天触发),因此没有 cron、没有 timer、也没有 reload 钩子。Nginx 路线则是三步分离:certbot --nginx(或 certbot certonly --webroot -w /var/www/html -d example.com)签发 → systemd 的 certbot.timer 每日两次跑 certbot renew → 在 deploy-hook 里 systemctl reload nginx 才真正生效。据 Let’s Encrypt 官方文档,证书有效期 90 天、建议在剩余 30 天内完成续期,Caddy 的内置策略正好落在这个窗口内。

维度 Nginx + certbot Caddy 2.x 宝塔面板 Cloudflare 边缘证书
签发方式 certbot 独立进程,--nginx 或 --webroot 内置 ACME,首次启动自动签发 面板勾选 Let’s Encrypt 边缘证书自动,源站证书需另配
续期机制 certbot.timer 每日两次 + reload nginx 内置,剩余寿命 <1/3 时自动续 面板计划任务 自动
同场景反代配置量 约 18 行 3 行 面板生成 不适用
配置可进 Git、可 review、可回滚 可以,但证书文件需单独管理 可以,Caddyfile 单文件 否,配置存于面板数据库 部分(Terraform Provider)
典型适用场景 存量 VPS、团队已熟悉 Nginx 容器、边缘网关、GitOps 不熟悉命令行的站长 已用 CDN 的站点

同等反向代理 + HTTPS 场景,行数差距直观可见。Caddyfile 全部内容:

# /etc/caddy/Caddyfile —— Caddy 2.x,自动 HTTPS 默认开启(auto_https on)
example.com {
	reverse_proxy 127.0.0.1:8080   # 自动签发证书、自动续期、自动处理 WebSocket 升级
}

Nginx 等价配置(证书路径由 certbot 生成,还需额外的 renew 钩子):

# /etc/nginx/conf.d/example.conf
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    http2 on;                                   # Nginx 1.25.1+ 写法
    server_name example.com;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;      # WebSocket 必须手写
        proxy_set_header Connection "upgrade";       # WebSocket 必须手写
    }
}

从 Nginx 切到 Caddy,正确的顺序是什么?关键是先释放 80/443 再启 Caddy,否则你会看到这条真实报错:Error: loading initial config: loading new config: http app module: start: listening on :80: listen tcp :80: bind: address already in use。完整切换序列如下:

# 1. 备份并停掉 Nginx(先别卸载,方便回滚)
sudo cp -a /etc/nginx /etc/nginx.bak.$(date +%F)
sudo systemctl disable --now nginx

# 2. 确认 80/443 已无监听进程,应无输出
sudo ss -lntp '( sport = :80 or sport = :443 )'

# 3. 语法校验,成功时输出 "Valid configuration"
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

# 4. 前台跑一次,肉眼确认 ACME 日志里的 HTTP-01 挑战成功
sudo caddy run --config /etc/caddy/Caddyfile --adapter caddyfile

# 5. 交给 systemd,并设置开机自启
sudo systemctl enable --now caddy

# 6. 对比响应头与跳转行为(Nginx 会返回 server: nginx,Caddy 默认 server: Caddy)
curl -sSI https://example.com | grep -Ei '^(HTTP/|server|location|strict-transport-security)'
curl -sSI http://example.com  | grep -Ei '^(HTTP/|location)'

Cloudflare 开了橙云,源站还要不要证书?要。Cloudflare 边缘证书只保护「访客 ↔ 边缘」这一段,回源段由 SSL/TLS 模式决定:Flexible 明文回源(不推荐),Full 要求源站有证书但不校验,Full (Strict) 要求源站证书可信——可用 Let’s Encrypt 证书或 Cloudflare 免费签发的 Origin CA 证书(最长 15 年,仅被 Cloudflare 信任)。如果源站只放行 Cloudflare IP 段,HTTP-01 挑战会被拦,此时改用 DNS-01 签发,同时避免回源 80 端口暴露:

# Caddy 2.7.0+ 可动态装插件,无需 xcaddy 重新编译
caddy add-package github.com/caddy-dns/cloudflare

# Caddyfile:泛域名 + 根域走 DNS-01,令牌从环境变量读取
*.example.com, example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}
	reverse_proxy 127.0.0.1:8080
}

WebSocket 还要不要写 Upgrade 头?不需要。Caddy 的 reverse_proxy 会自动识别 Upgrade: websocket 并完成协议升级,这也是迁移时最容易被忽略的「少写一行反而更稳」的地方。如果 Caddyfile 已纳入 Git,改完用 sudo caddy reload --config /etc/caddy/Caddyfile 热加载,不中断连接。

证书只是起点:想继续深挖,可查看本站《Let’s Encrypt 速率限制与 staging 环境》《DNS-01 泛域名证书实践》《Caddy 反向代理与负载均衡》,把 ACME 签发、DNS-01 验证与 TLS 加固串成完整的主题集群。

不需要。Caddy v2 内置 ACME 客户端,域名站点默认自动向 Let's Encrypt/ZeroSSL 申请证书并续期;只有手动证书、企业 CA 或特殊 DNS 场景才需要外部工具或自定义构建。

单机小站、反向代理场景 Caddy 更省事,Caddyfile 5-10 行即可完成 HTTPS;已有 Nginx 生态、复杂 rewrite/WAF 或团队熟悉 Nginx 时,Nginx + certbot 更稳妥。两者软件都免费,Caddy 省的是 cron 与续期脚本维护成本。

这是 Let's Encrypt 限额,常见为重复证书 5 张/周或每注册域名 50 张/7 天。立即停止重试,切到 staging CA 测试,生产等待窗口结束;同时检查是否误删 `/var/lib/caddy/.local/share/caddy` 导致每次 reload 都重新签发。

可以但不稳定。HTTP-01 可通过 Cloudflare 回源 80 完成,TLS-ALPN-01 不可用;源站只开 443 时建议用 DNS-01:`xcaddy build –with github.com/caddy-dns/cloudflare`,Caddyfile 写 `tls { dns cloudflare {env.CF_API_TOKEN} }`。

Caddy 不会替你续手动证书。可用 certbot `certbot renew –deploy-hook "systemctl reload caddy"`,或 ACME 客户端续期后执行 `caddy reload –config /etc/caddy/Caddyfile`;证书路径不变时 reload 即可加载新证书。

systemd 安装通常在 `/var/lib/caddy/.local/share/caddy`,包含 `certificates/`、`acme/`、`pki/`;迁移时连同 `/etc/caddy/Caddyfile` 一起打包,恢复后执行 `chown -R caddy:caddy`,目录 700、私钥 600。

多为手动证书未包含中间证书。把中间证书拼到 `fullchain.pem`,顺序为站点证书在前、中间证书在后,用 `openssl verify -CAfile chain.pem fullchain.pem` 验证,再 reload Caddy。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。