Caddy项目中PHP-FPM访问日志SCRIPT_NAME参数的正确设置

背景介绍

在使用Caddy作为Web服务器配合PHP-FPM处理PHP请求时，开发者经常会遇到一个日志记录问题：PHP-FPM的访问日志中所有请求都显示为GET 200 /index.php，而丢失了实际的请求路径信息。这给日志分析和调试带来了不便。

问题本质

这个问题的根源在于FastCGI协议中SCRIPT_NAME参数的设置方式。Caddy默认实现遵循了CGI规范(RFC 3875)，该规范明确规定：

SCRIPT_NAME值中不应包含PATH_INFO部分

因此，Caddy在默认配置下只传递PHP脚本的基本路径(如/index.php)，而不包含后续的请求路径信息。

技术规范解析

根据CGI 1.1规范(RFC 3875)第4.1.13节：

1. SCRIPT_NAME表示正在执行的脚本的虚拟路径
2. 该值不应包含PATH_INFO部分
3. 主要用于脚本自引用URL的生成

而PATH_INFO则是请求URI中脚本名称之后的部分，用于传递额外的路径信息。

解决方案

虽然规范不建议在SCRIPT_NAME中包含路径信息，但实际应用中，许多开发者希望日志能记录完整请求路径。Caddy提供了灵活的配置方式来实现这一需求：

php_fastcgi 127..0.1:9000 {
    env SCRIPT_NAME /index.php{http.request.orig_uri}
}

这个配置通过环境变量重写，将原始请求URI附加到脚本名称后，使PHP-FPM日志能够记录完整路径。

注意事项

1. 规范合规性：此方案虽实用，但偏离了CGI规范，可能在某些特殊场景下引发兼容性问题
2. 性能影响：额外的字符串处理会带来极小的性能开销
3. 日志分析：修改后日志格式变化可能影响现有日志分析工具

最佳实践建议

1. 对于需要详细日志的场景，建议同时保留原始日志和增强日志
2. 考虑使用Caddy的日志中间件在代理层记录完整请求信息
3. 在PHP应用中通过$_SERVER['REQUEST_URI']获取完整路径，而非依赖SCRIPT_NAME

总结

Caddy作为现代化Web服务器，在遵循规范的同时也提供了足够的灵活性。开发者可以根据实际需求，在规范合规性和实用日志记录之间做出平衡选择。理解CGI/FastCGI协议中各个参数的含义和规范要求，有助于做出更合理的架构决策。