FrankenPHP 项目中集成 Caddy HTTP 缓存模块的实践指南

在构建高性能 PHP 应用时，缓存机制是提升性能的关键因素之一。本文将详细介绍如何在 FrankenPHP 项目中成功集成 Caddy 的 HTTP 缓存功能，特别是使用 Souin 缓存模块的完整实现过程。

背景与挑战

FrankenPHP 是一个创新的 PHP 运行时环境，它结合了 PHP 和 Go 的优势。当开发者尝试为其添加 HTTP 缓存支持时，遇到了几个技术难题：

1. 构建过程中出现符号重定位错误
2. 模块依赖关系复杂导致编译失败
3. 缓存配置与实际效果不符的问题

解决方案实现

正确的 Dockerfile 配置

通过多次实践验证，以下是能够成功构建 FrankenPHP 并集成 Souin 缓存模块的 Dockerfile 配置要点：

FROM dunglas/frankenphp:latest-builder AS builder
COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy

RUN apt-get update && apt-get install --no-install-recommends -y git

ENV CGO_ENABLED=1 XCADDY_SETCAP=1 XCADDY_GO_BUILD_FLAGS="-ldflags \"-w -s -extldflags '-Wl,-z,stack-size=0x80000'\""
RUN xcaddy build \
    --output /usr/local/bin/frankenphp \
    --with github.com/dunglas/frankenphp=./ \
    --with github.com/dunglas/frankenphp/caddy=./caddy/ \
    --with github.com/dunglas/mercure/caddy \
    --with github.com/dunglas/vulcain/caddy \
    --with github.com/dunglas/caddy-cbrotli \
    --with github.com/darkweak/souin/plugins/caddy@65cb24114d76a7de3f4e8c7b8ef7df3efd028899 \
    --with github.com/darkweak/souin@65cb24114d76a7de3f4e8c7b8ef7df3efd028899 \
    --with github.com/darkweak/storages/otter/caddy

FROM dunglas/frankenphp:latest AS frankenphp_upstream
COPY --from=builder --link /usr/local/bin/frankenphp /usr/local/bin/frankenphp

关键点说明：

• 必须安装 git 工具用于模块获取
• 需要指定特定版本的 Souin 及其插件以确保兼容性
• 必须包含 caddy-cbrotli 模块以支持压缩功能

Caddyfile 配置

正确的缓存配置需要添加到 Caddyfile 中：

{
    order cache before rewrite
    cache {
        api {
            souin
        }
    }
    
    # 其他配置...
}

API Platform 配置

在 API Platform 的配置文件中，需要正确设置缓存参数：

api_platform:
    defaults:
        stateless: true
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']
            public: true  # 必须显式设置为 public
    
    http_cache:
        invalidation:
            urls: ['http://caddy/souin-api/souin']
            purger: api_platform.http_cache.purger.souin

常见问题排查

1. 缓存不生效问题：

   • 确保应用运行在生产模式，开发模式下 Symfony 会自动添加 no-cache 头
   • 必须显式设置 Cache-Control 为 public

2. 构建失败问题：

   • 检查所有依赖模块的版本兼容性
   • 确保构建环境中安装了必要的工具链

3. 性能调优建议：

   • 根据实际业务场景调整缓存时间
   • 合理设置 Vary 头以确保缓存键的正确性

实现效果验证

成功配置后，响应头中应包含以下关键字段：

Cache-Control: public
Etag: "75d700cecda6aee64bef38d0666e85e7-zstd"
Surrogate-Key: /api/resource/1

这些头信息表明缓存机制已正常工作，后续请求将直接从缓存中获取响应，显著提升应用性能。

总结

通过本文的详细指导，开发者可以顺利在 FrankenPHP 项目中实现高效的 HTTP 缓存机制。正确的配置不仅能够提升应用性能，还能减少后端服务器的负载。在实际部署时，建议根据具体业务需求进一步调整缓存策略，以达到最佳的性能优化效果。