本文目录
排查准备：确认环境与日志访问权限
在开始排查之前，请确保你拥有服务器的 SSH 访问权限，并且能够查看 Caddy 日志。Caddy 日志对于区分路由错误（404）和上游故障（502）至关重要。使用 caddy 命令或系统日志管理器访问最近的日志条目。确认 Caddy 正在运行，并通过检查启动错误来验证你的 Caddyfile 是否有效。如果你无法访问日志，你就无法准确诊断问题出在 Caddy 的路由逻辑还是后端服务的可用性上。
第一步：通过 Caddy 日志区分 404 与 502 错误类型
打开 Caddy 日志，搜索特定的错误代码。502 Bad Gateway 通常表示 Caddy 无法连接到上游服务器或收到了无效响应。404 Not Found 通常意味着请求路径未匹配任何已定义的处理器，或者文件服务器无法找到资源。查找提及 "upstream" 的日志条目以识别 502 错误，或查找 "no match" 或 "file not found" 以识别 404 错误。这种初步分类可以防止你在错误的配置部分上浪费时间。如果日志显示连接被拒绝，问题很可能在于上游服务。如果显示路径不匹配，请专注于你的路由指令。
第二步：排查 502 错误：验证上游服务状态与监听地址
对于 502 错误，请验证上游服务是否正在运行，并监听正确的地址和端口。在服务器上使用 ss -tlnp 或 netstat -tlnp 检查哪些端口处于活动状态。将此输出与 Caddyfile 中的 reverse_proxy 指令进行比较。例如，如果你的 Caddyfile 指定了 reverse_proxy localhost:8080，请确保你的应用程序确实正在监听 8080 端口。如果应用程序绑定到 127.0.0.1，但 Caddy 试图通过不同的接口连接，或者端口相差一个，你将得到 502 错误。如果上游服务似乎挂起，请重启它。此外，检查上游是否返回有效的 HTTP 响应；某些应用程序可能会在特定请求上崩溃，从而导致间歇性 502。
第三步：排查 404 错误：检查 handle_path 路径前缀剥离与静态目录
如果你正在代理子路径（例如 /api），请确保路径前缀被正确处理。handle_path 指令会隐式地从请求 URI 中剥离匹配的路径前缀，然后再将其传递给下一个处理器。例如，如果你使用 handle_path /api/*，对 /api/users 的请求将被转发到上游作为 /users。如果你的上游应用程序期望完整的路径 /api/users，你应该使用 handle 而不是 handle_path，或者调整应用程序的路由。如果你使用了 handle_path 但应用程序返回 404，很可能是因为应用程序无法识别剥离后的路径。通过检查上游日志来查看它接收到的路径，以测试这一点。
第四步：检查文件服务器与根目录配置
对于静态文件，请确保 file_server 指令与正确的 root 指令配对。file_server 会将请求的 URI 路径附加到站点的根路径。如果你的根设置为 /var/www/html，并且你请求 /images/logo.png，Caddy 将查找 /var/www/html/images/logo.png。如果该确切位置不存在文件，你将得到 404。验证文件权限和所有权。此外，请注意 file_server 强制使用规范 URI；对不以斜杠结尾的目录的请求将被重定向。如果你看到静态资源的 404，请仔细检查根路径和磁盘上的实际文件位置。
第五步：检查大文件上传时的请求体限制与版本要求
如果你的 404 或 502 错误专门发生在文件上传期间，请检查 request_body 指令。默认情况下，Caddy 可能会限制请求体的大小。如果你正在上传大文件，你可能需要增加 max_size 限制。例如，request_body { max_size 100MB } 允许最大 100 兆字节的上传。如果请求体超过此限制，Caddy 将返回 413 Payload Too Large 错误，这可能会被误解或导致上游超时，进而导致 502。请注意，request_body 的 set 子指令在 v2.10.0+ 中是实验性的。确保你的 Caddy 版本支持你正在使用的指令。如果你没有上传大文件，这一步骤是不必要的。
验证与回退：测试访问与配置热加载
在对 Caddyfile 进行更改后，使用 caddy reload 应用更改以避免停机。然后，使用终端中的 curl -I 测试之前失败的特定 URL。检查响应头中的 HTTP 状态码。如果返回 200 OK，则问题已解决。监控 Caddy 日志几分钟，以确保没有新的错误出现。如果问题仍然存在，请将更改恢复到上一个已知良好的配置。在进行重大更改之前，请备份你的 Caddyfile。这允许你在修复引入新问题时可以快速回滚。如果可能，请始终在测试环境中测试，然后再将更改应用到生产环境。
验证上游与传输选项
在排查持续的 502 或 404 错误时，参考官方 Caddyfile reverse_proxy 文档检查传输行为和上游配置，可确保负载均衡、主动健康检查和请求头重写正常运作。若需处理更复杂的多层架构，建议阅读单服务器生产架构怎么画：反向代理、应用、数据库与端口边界以规划严密的端口边界，或通过502、504 与 HTTPS 故障怎么查：从 DNS 到应用的分层排错进行分层排错。
资料来源
下一步
按当前任务继续，不必一次读完所有内容。