故障排查 #

概述 #

本文档介绍 Caddy 的常见问题及解决方法，帮助你快速定位和解决问题。

text

┌─────────────────────────────────────────────────────────────┐
│                    故障排查流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│    1. 检查服务状态                                          │
│         ↓                                                   │
│    2. 查看日志                                              │
│         ↓                                                   │
│    3. 验证配置                                              │
│         ↓                                                   │
│    4. 网络诊断                                              │
│         ↓                                                   │
│    5. 定位问题                                              │
│         ↓                                                   │
│    6. 解决问题                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

服务状态检查 #

检查服务运行状态 #

bash

# systemd 服务
sudo systemctl status caddy

# 查看进程
ps aux | grep caddy

# 检查端口
sudo netstat -tlnp | grep caddy
sudo ss -tlnp | grep caddy
sudo lsof -i :80
sudo lsof -i :443

检查 Caddy 版本 #

bash

caddy version

检查 API 状态 #

bash

# 检查管理 API
curl localhost:2019/config/

# 检查服务器状态
curl localhost:2019/config/apps/http/servers

日志分析 #

查看系统日志 #

bash

# systemd 日志
sudo journalctl -u caddy -f

# 查看最近日志
sudo journalctl -u caddy -n 100

# 查看特定时间段
sudo journalctl -u caddy --since "2024-01-01" --until "2024-01-02"

# 过滤错误
sudo journalctl -u caddy | grep -i error

查看文件日志 #

bash

# 实时查看
tail -f /var/log/caddy/access.log

# 查看错误
grep -i error /var/log/caddy/access.log

# JSON 日志分析
cat /var/log/caddy/access.log | jq 'select(.status >= 400)'

启用调试模式 #

caddyfile

{
    debug
}

example.com {
    respond "Debug mode enabled"
}

配置验证 #

验证 Caddyfile #

bash

# 验证语法
caddy validate --config Caddyfile

# 查看转换后的 JSON
caddy adapt --config Caddyfile --pretty

常见配置错误 #

1. 指令顺序错误 #

caddyfile

# 错误：file_server 在 rewrite 之前
example.com {
    file_server
    rewrite * /index.html
}

# 正确：rewrite 在 file_server 之前
example.com {
    rewrite * /index.html
    file_server
}

2. 匹配器语法错误 #

caddyfile

# 错误：匹配器语法
@api path /api/*

# 正确：匹配器定义
@api {
    path /api/*
}

3. 缺少根目录 #

caddyfile

# 错误：file_server 没有根目录
example.com {
    file_server
}

# 正确：指定根目录
example.com {
    root * /var/www/html
    file_server
}

网络诊断 #

检查端口监听 #

bash

# 检查 80 端口
sudo lsof -i :80

# 检查 443 端口
sudo lsof -i :443

# 检查所有监听端口
sudo netstat -tlnp

检查防火墙 #

bash

# ufw 状态
sudo ufw status

# 开放端口
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# iptables 检查
sudo iptables -L -n

DNS 解析检查 #

bash

# 检查域名解析
dig example.com +short
nslookup example.com
host example.com

# 检查 DNS 传播
dig @8.8.8.8 example.com

连接测试 #

bash

# 测试 HTTP
curl -v http://example.com

# 测试 HTTPS
curl -v https://example.com

# 测试特定端口
curl -v http://example.com:8080

# 测试响应头
curl -I https://example.com

常见问题 #

证书问题 #

证书获取失败 #

bash

# 检查日志
sudo journalctl -u caddy | grep -i acme

# 常见原因：
# 1. 域名未解析到服务器
# 2. 80/443 端口不可访问
# 3. 防火墙阻止
# 4. 证书频率限制

解决方法：

bash

# 1. 检查域名解析
dig example.com +short

# 2. 开放端口
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 3. 使用测试 CA

caddyfile

{
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

通配符证书问题 #

bash

# 通配符证书需要 DNS 验证
# 检查 DNS 插件是否安装
caddy list-modules | grep dns

解决方法：

bash

# 安装 DNS 插件
xcaddy build --with github.com/caddy-dns/cloudflare

caddyfile

*.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
}

权限问题 #

绑定端口失败 #

bash

# 错误：bind: permission denied
# 原因：非 root 用户无法绑定 80/443 端口

# 解决方法 1：使用 setcap
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

# 解决方法 2：使用 sudo
sudo caddy run --config Caddyfile

# 解决方法 3：使用非特权端口
# Caddyfile 中使用 :8080 而不是 :80

文件访问权限 #

bash

# 错误：permission denied
# 检查文件权限
ls -la /var/www/html
ls -la /var/log/caddy

# 修复权限
sudo chown -R caddy:caddy /var/www/html
sudo chown -R caddy:caddy /var/log/caddy

代理问题 #

后端连接失败 #

bash

# 检查后端服务
curl localhost:3000

# 检查网络连接
telnet localhost 3000

# 检查防火墙
sudo ufw status

解决方法：

caddyfile

example.com {
    reverse_proxy localhost:3000 {
        # 增加超时
        transport http {
            dial_timeout 10s
            response_header_timeout 30s
        }
        
        # 健康检查
        health_uri /health
        health_interval 10s
    }
}

WebSocket 连接断开 #

caddyfile

ws.example.com {
    reverse_proxy localhost:3000 {
        transport http {
            read_timeout 0
            write_timeout 0
        }
    }
}

性能问题 #

响应慢 #

bash

# 检查系统资源
top
htop
free -m

# 检查网络延迟
ping example.com
traceroute example.com

# 检查 DNS 解析时间
dig example.com

优化方法：

caddyfile

example.com {
    # 启用压缩
    encode gzip zstd
    
    # 启用缓存
    @static path *.css *.js *.png *.jpg
    header @static Cache-Control "public, max-age=31536000"
    
    # 连接池优化
    reverse_proxy localhost:3000 {
        transport http {
            keepalive 90s
            keepalive_idle_conns 100
        }
    }
}

内存占用高 #

bash

# 检查内存使用
ps aux --sort=-%mem | head

# 检查 Caddy 内存
pmap $(pgrep caddy)

解决方法：

caddyfile

{
    # 禁用不需要的功能
    admin off
}

example.com {
    # 减少日志
    log {
        output file /var/log/caddy/access.log {
            roll_size 50mb
            roll_keep 5
        }
    }
}

调试技巧 #

使用 curl 调试 #

bash

# 详细输出
curl -v https://example.com

# 只看响应头
curl -I https://example.com

# 发送特定请求头
curl -H "Host: example.com" http://localhost

# 跟随重定向
curl -L https://example.com

# 测试压缩
curl -H "Accept-Encoding: gzip" -I https://example.com

# 测试特定路径
curl https://example.com/api/test

使用 openssl 调试 #

bash

# 测试 TLS 连接
openssl s_client -connect example.com:443

# 查看证书信息
openssl s_client -connect example.com:443 | openssl x509 -noout -text

# 测试 TLS 版本
openssl s_client -connect example.com:443 -tls1_2
openssl s_client -connect example.com:443 -tls1_3

使用 tcpdump 抓包 #

bash

# 抓取 HTTP 流量
sudo tcpdump -i eth0 port 80 -w http.pcap

# 抓取 HTTPS 流量
sudo tcpdump -i eth0 port 443 -w https.pcap

# 实时查看
sudo tcpdump -i eth0 port 80 -A

使用 strace 跟踪 #

bash

# 跟踪系统调用
sudo strace -p $(pgrep caddy) -f

# 跟踪网络调用
sudo strace -p $(pgrep caddy) -e trace=network

问题排查清单 #

服务无法启动 #

[ ] 检查配置文件语法
[ ] 检查端口是否被占用
[ ] 检查文件权限
[ ] 检查日志错误信息

证书获取失败 #

[ ] 检查域名解析
[ ] 检查端口可达性
[ ] 检查防火墙规则
[ ] 检查证书频率限制

代理不工作 #

[ ] 检查后端服务状态
[ ] 检查网络连接
[ ] 检查代理配置
[ ] 检查超时设置

性能问题 #

[ ] 检查系统资源
[ ] 检查网络延迟
[ ] 检查压缩配置
[ ] 检查缓存配置

获取帮助 #

官方资源 #

官方文档：https://caddyserver.com/docs/
GitHub Issues：https://github.com/caddyserver/caddy/issues
社区论坛：https://caddy.community/

提问模板 #

text

**环境信息：**
- Caddy 版本：
- 操作系统：
- 安装方式：

**问题描述：**
[详细描述问题]

**配置文件：**
```caddyfile
[你的 Caddyfile]

日志输出：

text

[相关日志]

已尝试的解决方法：

方法 1
方法 2

text


## 总结

故障排查的关键步骤：

1. **检查状态** - 确认服务是否正常运行
2. **查看日志** - 从日志中找到错误信息
3. **验证配置** - 确保配置文件正确
4. **网络诊断** - 检查网络连通性
5. **逐步排查** - 排除可能的原因

记住：大多数问题都可以通过查看日志找到原因！