排障

Caddy 排障围绕 caddy validate、日志与 ACME 证书失败 三类问题。对照 Nginx 的 nginx -t 与 error.log，并串联 dns-troubleshoot 排查域名与证书。

学习目标

用 caddy validate / caddy run --watch 定位配置错误
读懂 access 与 error 日志中的 upstream 失败
处理证书申请失败与 502 反代问题

核心内容

配置校验

caddy validate --config /etc/caddy/Caddyfile
caddy fmt --overwrite /etc/caddy/Caddyfile   # 格式化
caddy run --config /etc/caddy/Caddyfile --watch  # 开发调试

语法错误在 validate 阶段即报错；生产改配置后 先 validate 再 reload。

常见现象速查

502 Bad Gateway       → upstream 未监听 / 错误端口 / Docker 网络不通
404 on /api/foo       → 未 strip_prefix 或 handle 顺序错误
证书一直申请中       → DNS 未指向本机 / 80·443 被挡 / LE 速率限制
redirect 循环         → 后端强制 https 但 X-Forwarded-Proto 未信任
WebSocket / HMR 失败  → 缺 Upgrade 头（见 caddy-proxy）

日志位置：systemd journalctl -u caddy；Docker docker compose logs caddy；文件由 log 指令指定。

ACME 失败排查

dig www.coderoadmap.cn 确认 A 记录（dns-tools）
公网 curl -I http://www.coderoadmap.cn 是否可达（HTTP-01）
查看 /var/lib/caddy 或 Docker 卷 caddy_data 权限
测试环境改用 staging CA（caddy-ssl）

Let's Encrypt 每周申请次数有限，频繁删卷重建会触发限制。

与 Nginx 对照排障

症状	Nginx 查	Caddy 查
配置语法	`nginx -t`	`caddy validate`
upstream	`error.log connect()`	日志 `dial tcp`
证书	certbot logs	journal + ACME 目录
路由	`location` 顺序	`handle` 顺序

生产仍参考 nginx-essentials 运维手册；Caddy 测试机问题按上表平行处理。

排障

排障