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 指令指定自有证书时才会改变。下面按顺序给出可复制命令。
- 安装(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可核对候选版本。 - 写 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 有效期时自动续期。 - 校验配置:先验证再 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报错自带文件与行号,按行修完再进下一步。
- 启动与重载:首次
sudo systemctl enable --now caddy;之后每次改配置只用sudo systemctl reload caddy。这是零停机操作——旧连接按已有超时自然结束,新连接立刻用新配置,适合滚动发布。
操作 命令 连接影响 适用场景 reload systemctl reload caddy不断开,零停机 改路由/反代/证书配置 restart systemctl restart caddy连接被重置 升级二进制、改 systemd 单元 - 看日志确认签发:
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。 - 备份数据目录:
/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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。