Nginx外部代理Docker内PHP-FPM服务的实践指南-php教程-PHP中文网

Nginx外部代理Docker内PHP-FPM服务的实践指南

本教程详细阐述了如何在Docker外部通过Nginx代理Docker容器内部运行的PHP-FPM服务。文章涵盖了两种主要场景：在宿主机上配置独立Nginx进行代理，以及在Kubernetes环境下使用Nginx Ingress Controller进行服务暴露。内容包括Nginx配置示例、网络通信要点和相关最佳实践，旨在帮助开发者高效地部署和管理PHP应用。

1. 理解核心挑战：网络通信与代码同步

当nginx运行在docker外部（宿主机或独立vm）而php-fpm运行在docker容器内部时，核心挑战在于如何让外部nginx能够稳定地与内部php-fpm通信，并确保php代码在两者之间（或至少在php-fpm容器内）是可访问的。php-fpm通常监听9000端口，nginx需要通过fastcgi协议将php请求转发到这个端口。

2. 场景一：宿主机独立Nginx代理Docker容器PHP-FPM

这种场景适用于简单部署、开发环境或非容器编排的单机应用。

2.1 PHP-FPM容器准备

首先，确保你的PHP-FPM容器正在运行，并且其FastCGI端口（默认为9000）已映射到宿主机。例如，使用Bitnami的PHP-FPM镜像：

docker run -d --name my-php-fpm -p 9000:9000 bitnami/php-fpm:latest

登录后复制

这将把容器内部的9000端口映射到宿主机的9000端口。因此，在宿主机上，PHP-FPM服务可以通过127.0.0.1:9000访问。

2.2 Nginx配置详解

在宿主机上配置Nginx，将PHP请求转发到Docker容器暴露的端口。

立即学习“PHP免费学习笔记（深入）”；

server {
    listen 80;
    server_name localhost; # 替换为你的域名或IP
    root /var/www/html;    # 替换为你的项目代码在宿主机上的路径

    error_log /var/log/nginx/localhost.error.log;
    access_log /var/log/nginx/localhost.access.log;

    location / {
        # 尝试直接服务文件，如果不存在则回退到index.php
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php(/|$) {
        # 将PHP请求转发到PHP-FPM容器，通过宿主机的映射端口访问
        fastcgi_pass 127.0.0.1:9000; # 或宿主机IP:9000，如果FPM端口映射到特定IP
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params; # 包含Nginx默认的FastCGI参数

        # 核心参数：定义PHP脚本在PHP-FPM容器内的绝对路径
        # 这里的 $document_root 对应 Nginx 配置中的 'root' 指令的值
        # 为了让FPM正确找到文件，宿主机上的 Nginx root 目录
        # 需要与 FPM 容器内的代码路径通过 Docker 卷进行同步。
        # 例如，如果宿主机 /var/www/html 挂载到 FPM 容器的 /app 目录，
        # 则此处应改为 fastcgi_param SCRIPT_FILENAME /app$fastcgi_script_name;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS off; # 根据实际情况配置HTTPS状态
    }
}

登录后复制

配置要点说明：

fastcgi_pass 127.0.0.1:9000;: 这是关键，它指示Nginx将FastCGI请求发送到宿主机的9000端口，该端口由Docker映射到PHP-FPM容器。如果你的PHP-FPM容器端口映射到宿主机某个特定的IP（例如，如果你运行在虚拟机中，且容器映射到虚拟机的内部IP），则应使用该IP。
root /var/www/html;: 这个路径是Nginx用来查找静态文件和确定PHP脚本路径的基准。
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;: 这个参数告诉PHP-FPM要执行哪个PHP文件。$document_root是Nginx配置中root指令的值。非常重要的一点是：为了让PHP-FPM容器能够找到并执行这个文件，宿主机上的root目录（/var/www/html）中的PHP代码必须与PHP-FPM容器内部的相应路径保持一致。这通常通过Docker的卷挂载（docker run -v /var/www/html:/app ...）来实现，并将SCRIPT_FILENAME设置为容器内部的路径（例如/app$fastcgi_script_name;）。如果Nginx的root目录与FPM容器的document_root通过卷挂载完全一致，则使用$document_root$fastcgi_script_name是可行的。

2.3 注意事项

端口映射: 确保PHP-FPM容器的端口已正确映射到宿主机，以便Nginx能够访问。
代码同步: PHP应用程序代码必须同时存在于Nginx可以访问的宿主机文件系统（如果Nginx需要服务静态文件或解析PHP文件路径）和PHP-FPM容器内部（供PHP-FPM执行）。最常见的做法是使用Docker卷将宿主机上的代码目录挂载到PHP-FPM容器中。
网络模式: 如果PHP-FPM容器使用--network host模式启动，它将直接使用宿主机的网络栈，此时Nginx可以直接通过localhost:9000访问PHP-FPM，无需端口映射。但这种模式会牺牲一些容器隔离性。
安全性: 生产环境中应配置HTTPS，并确保Nginx和PHP-FPM的日志记录和错误处理到位。

3. 场景二：Kubernetes环境下Nginx Ingress Controller代理PHP-FPM服务

在Kubernetes集群中，Nginx Ingress Controller作为集群的入口点，可以专门配置来代理FastCGI服务，从而实现对PHP-FPM容器的外部访问。

3.1 核心组件

Pod: 运行PHP-FPM应用程序的容器实例。
Service: 为Pod提供稳定的网络访问点。
Ingress: 定义外部流量如何路由到集群内部Service的规则，Nginx Ingress Controller会根据这些规则来配置其内部的Nginx。
ConfigMap: 用于存储FastCGI参数，如SCRIPT_FILENAME。

3.2 Kubernetes资源定义示例

首先，定义PHP-FPM的Pod和Service：

Pod (example-app.yaml):

钉钉 AI 助理

钉钉AI助理汇集了钉钉AI产品能力，帮助企业迈入智能新时代。

查看详情

apiVersion: v1
kind: Pod
metadata:
  name: example-app
  labels:
    app: example-app
spec:
  containers:
  - name: example-app
    image: example-app:1.0 # 替换为你的PHP-FPM镜像
    ports:
    - containerPort: 9000
      name: fastcgi

登录后复制

Service (example-service.yaml):

apiVersion: v1
kind: Service
metadata:
  name: example-service
spec:
  selector:
    app: example-app
  ports:
  - port: 9000        # Service监听的端口
    targetPort: 9000  # Pod容器暴露的端口
    name: fastcgi

登录后复制

接下来，定义一个ConfigMap来存储FastCGI参数，特别是SCRIPT_FILENAME。这允许Nginx Ingress Controller知道PHP-FPM容器内部的脚本路径。

ConfigMap (example-cm.yaml):

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-cm
data:
  # SCRIPT_FILENAME 指向 PHP-FPM 容器内部的入口文件路径
  # 例如，如果你的 PHP 代码挂载在容器的 /app 目录下，并且入口文件是 index.php
  SCRIPT_FILENAME: "/app/index.php" # 根据你的应用入口文件路径调整

登录后复制

最后，定义Ingress资源，利用Nginx Ingress Controller的特定注解来启用FastCGI代理。

Ingress (example-ingress.yaml):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-app
  annotations:
    kubernetes.io/ingress.class: "nginx" # 指定使用 Nginx Ingress Controller
    nginx.ingress.kubernetes.io/backend-protocol: "FCGI" # 启用 FastCGI 协议
    nginx.ingress.kubernetes.io/fastcgi-index: "index.php" # FastCGI 默认索引文件
    nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-cm" # 引用 FastCGI 参数 ConfigMap
spec:
  rules:
  - host: app.example.com # 你的域名
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              name: fastcgi

登录后复制

3.3 注意事项

Nginx Ingress Controller: 确保你的Kubernetes集群已经安装并运行了Nginx Ingress Controller。
backend-protocol: "FCGI": 这个注解是核心，它告诉Nginx Ingress Controller将请求以FastCGI协议转发到后端服务。
fastcgi-params-configmap: 通过ConfigMap来管理FastCGI参数，特别是SCRIPT_FILENAME，可以灵活地指定PHP-FPM容器内部的脚本路径，而无需修改Ingress定义。
代码管理: 在Kubernetes中，通常通过PersistentVolumeClaim (PVC) 或ConfigMap来将代码和配置注入到PHP-FPM Pod中。确保SCRIPT_FILENAME与容器内代码的实际路径匹配。
域名解析: app.example.com需要正确解析到Nginx Ingress Controller的外部IP地址。

4. 总结与最佳实践

无论选择哪种方式，外部Nginx代理Docker内的PHP-FPM都是实现高性能PHP应用部署的有效手段。

独立Nginx: 适用于开发、测试环境或资源受限的单机部署。优点是配置直接、易于理解和调试。缺点是扩展性较差，且需要手动管理网络和代码同步。
Kubernetes Ingress Controller: 适用于生产环境和需要高可用、可伸缩性的容器编排场景。它提供了强大的路由、负载均衡和SSL终止能力，与Kubernetes生态系统紧密集成。但其配置相对复杂，需要对Kubernetes有一定了解。

通用最佳实践：