使用FrankenPHP在生产环境部署PHP应用的完整指南

前言

FrankenPHP是一个现代化的PHP运行时环境，它集成了高性能的Caddy服务器，为PHP应用提供了开箱即用的生产环境支持。本文将详细介绍如何将基于FrankenPHP的PHP应用部署到生产环境服务器上。

准备工作

创建Dockerfile

首先，我们需要为PHP项目创建一个Dockerfile。这个文件定义了如何构建应用容器镜像：

FROM dunglas/frankenphp

# 设置服务器域名（替换为你的实际域名）
ENV SERVER_NAME=your-domain.com
# 如需禁用HTTPS，使用以下配置：
#ENV SERVER_NAME=:80

# 启用PHP生产环境配置
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

# 将项目文件复制到容器中
COPY . /app/public
# 如果是Symfony或Laravel项目，需要复制整个项目：
#COPY . /app

关键点说明：

1. SERVER_NAME环境变量用于配置Caddy服务器的域名
2. 使用php.ini-production配置确保PHP以生产模式运行
3. 根据框架类型选择正确的文件复制方式

配置Docker Compose

接下来创建compose.yaml文件定义服务：

services:
  php:
    image: dunglas/frankenphp
    restart: always
    ports:
      - "80:80"   # HTTP端口
      - "443:443" # HTTPS端口
      - "443:443/udp" # HTTP/3支持
    volumes:
      - caddy_data:/data   # Caddy证书存储
      - caddy_config:/config # Caddy配置存储

volumes:
  caddy_data:
  caddy_config:

这个配置实现了：

• 自动重启保证服务可用性
• 暴露HTTP/HTTPS端口
• 支持最新的HTTP/3协议
• 持久化存储Caddy的证书和配置

服务器准备

选择服务器方案

虽然教程以某云服务为例，但任何支持Docker的Linux服务器均可。生产环境建议：

1. 至少2GB内存的实例
2. 选择靠近用户的区域
3. 启用自动备份功能

服务器初始化

连接服务器后，建议执行以下基础安全配置：

# 更新系统
apt update && apt upgrade -y

# 创建专用部署用户
adduser deployer
usermod -aG docker deployer

# 配置防火墙
ufw allow 22
ufw allow 80
ufw allow 443
ufw enable

域名与HTTPS配置

DNS记录设置

创建A记录指向服务器IP：

your-domain.com.  IN  A  192.0.2.1

重要提示：

• Let's Encrypt不支持裸IP地址，必须配置域名
• DNS变更可能需要几小时全球生效

证书自动管理

FrankenPHP内置了以下HTTPS功能：

1. 自动从Let's Encrypt获取证书
2. 自动续期证书
3. 默认启用HTTP/2和HTTP/3

部署流程

代码上传方式

推荐几种代码部署方式：

1. Git直接克隆（适合小型项目）

   git clone your-repo-url
   

2. CI/CD管道（推荐生产环境）

   • 通过GitHub Actions等工具构建镜像
   • 推送到私有镜像仓库
   • 在服务器上拉取最新镜像

3. Rsync同步（适合无Git项目）

   rsync -avz --delete ./ root@yourserver:/path/to/app
   

启动服务

# 首次启动
docker compose up -d --build

# 更新部署
docker compose down
git pull origin main
docker compose up -d --build

注意事项：

• 使用--no-cache避免构建缓存问题
• 监控日志：docker compose logs -f
• 设置资源限制防止内存泄漏

高级部署方案

多节点部署

对于高可用需求，可以考虑：

1. Docker Swarm集群

   • 扩展性强
   • 内置服务发现
   • 滚动更新支持

2. Kubernetes

   • 更复杂的编排能力
   • 自动扩缩容
   • 精细的资源管理

性能优化建议

1. 启用OPcache：

   opcache.enable=1
   opcache.memory_consumption=128
   

2. 配置适当的PHP进程数：

   PHP_WORKERS=8
   

3. 使用Redis等外部缓存

监控与维护

基础监控

1. 容器状态：

   docker stats
   

2. 日志收集：

   • 配置logrotate
   • 考虑ELK或Graylog

备份策略

必须定期备份：

1. Caddy的证书存储卷
2. 应用代码
3. 数据库（如使用）

常见问题解决

1. 证书获取失败

   • 检查DNS解析
   • 确保80/443端口可访问
   • 查看Caddy日志

2. 性能问题

   • 调整PHP worker数量
   • 检查OPcache配置
   • 分析慢查询

3. 部署缓存问题

   • 使用--no-cache重建
   • 清理旧镜像

结语

通过FrankenPHP部署PHP应用简化了许多传统部署中的复杂步骤，特别是HTTPS配置和性能优化方面。本文介绍的方法适合大多数中小型项目，大型项目可根据需要扩展为集群部署。