简介

本文件面向部署DouPHP项目的运维与开发者，提供基于该代码库的Nginx服务器配置指南。内容覆盖server块与location块的语法与最佳实践、URL重写规则（含正则匹配与重定向）、SSL证书与HTTPS强制跳转、反向代理（API与静态资源）、性能优化（worker进程、缓冲区、gzip等），以及负载均衡与高可用性的配置思路。所有建议均结合本项目实际的路由入口与重写行为进行说明，确保落地可操作。

项目结构

该项目采用多入口架构：

• 前台入口：根目录 index.php，通过路由分发处理页面请求
• API入口：/api/index.php，用于前后端分离或小程序调用
• 后台入口：/admin/index.php，管理端点
• 静态资源：theme、images、plugin等资源目录
• 小程序：miniprogram目录，运行时配置位于 site.ts

graph TB
Client["客户端"] --> Nginx["Nginx 反向代理"]
Nginx --> |静态资源| Static["静态目录<br/>theme/images/plugin"]
Nginx --> |前台页面| Front["/index.php"]
Nginx --> |API接口| Api["/api/index.php"]
Nginx --> |后台管理| Admin["/admin/index.php"]

图示来源

• index.php:1-126
• config/config.php:36-46

章节来源

• index.php:1-126
• config/config.php:36-46

核心组件

• 入口与路由：前台入口 index.php 负责初始化并派发路由；API与后台分别有独立入口
• 重写策略：项目同时提供Apache .htaccess重写规则，便于理解Nginx rewrite映射关系
• 运行期开关：小程序侧 site.ts 暴露 rewrite_enable，指示是否启用“伪静态”风格URL生成
• 常量定义：config/config.php 定义了ADMIN_DIR、API_DIR、MINIPROGRAM_DIR等关键路径常量

章节来源

• index.php:1-126
• .htaccess:1-45
• config/config.php:36-46
• miniprogram/default/config/site.ts:1-16

架构总览

Nginx在本项目中承担以下职责：

• 作为反向代理将HTTP请求转发至PHP-FPM（FastCGI）
• 对静态资源直接返回，减少后端压力
• 根据URL模式执行重写，将美观URL映射到index.php或api/index.php
• 可选地开启HTTPS强制跳转与安全头
• 在高并发场景下通过worker与缓存提升吞吐

sequenceDiagram
participant C as "客户端"
participant N as "Nginx"
participant F as "PHP-FPM"
participant I as "index.php"
participant A as "api/index.php"
C->>N : GET /product/123
N->>N : 匹配location / (非静态)
N->>F : fastcgi_pass 转发
F->>I : 解析路由并响应
Note over N,I : 若为 /api/* 则转发至 api/index.php
C-->>N : 200 OK + HTML/JSON

图示来源

• index.php:26-44
• .htaccess:20-27

详细组件分析

server块与location块的最佳实践

• server块
  • 监听端口：默认80与443（HTTPS）
  • 域名：建议使用server_name绑定主域名与www子域
  • 根目录：指向项目public或根目录（取决于部署方式）
  • 错误页：自定义404/502/503等错误页，提升用户体验
• location块
  • 静态资源：使用location ~* .(jpg|jpeg|png|gif|ico|css|js)$ 直接返回，并设置缓存头
  • PHP入口：location ~ .php$ 使用fastcgi_pass到PHP-FPM
  • 前端路由：location / 捕获所有未命中静态文件的请求，并重写到index.php
  • API路由：location /api/ 重写到/api/index.php
  • 后台路由：location /admin/ 重写到/admin/index.php
  • 安全：拒绝访问隐藏文件、敏感扩展名（如.pem、tpl、dwt等）

章节来源

• .htaccess:1-45
• config/config.php:36-46

URL重写规则与正则匹配

• 项目提供的.htaccess展示了典型重写逻辑：
  • 静态入口：index.html -> index.php
  • API入口：/api/(.*) -> /api/index.php?route=$1
  • 后台入口：/admin/(.*) -> /admin/index.php?route=$1
  • 前台入口：/([^?]*) -> /index.php?route=$1
• Nginx等价实现要点：
  • 使用if或rewrite指令匹配路径
  • 使用正则表达式捕获参数，例如 (.+)
  • 使用last或break控制重写流程
  • 避免循环重写，注意顺序与优先级

flowchart TD
Start(["请求进入"]) --> CheckStatic{"是否静态资源?"}
CheckStatic --> |是| ServeStatic["直接返回静态文件"]
CheckStatic --> |否| CheckApi{"是否 /api/* ?"}
CheckApi --> |是| ToApi["重写到 /api/index.php"]
CheckApi --> |否| CheckAdmin{"是否 /admin/* ?"}
CheckAdmin --> |是| ToAdmin["重写到 /admin/index.php"]
CheckAdmin --> |否| ToFront["重写到 /index.php"]
ToApi --> End(["结束"])
ToAdmin --> End
ToFront --> End
ServeStatic --> End

图示来源

• .htaccess:17-45

章节来源

• .htaccess:17-45

SSL证书与HTTPS强制重定向

• 在server块中启用ssl，指定证书与私钥路径
• 配置HTTP到HTTPS的301重定向，保证全站加密
• 推荐启用HSTS、安全头（X-Frame-Options、X-Content-Type-Options等）
• 对于API与后台，同样适用HTTPS强制策略

章节来源

• config/config.php:36-46

反向代理配置（API与静态资源）

• API反向代理：将/api/*转发到后端服务（如Node/Java/Python），或直接交由PHP-FPM处理
• 静态资源：优先由Nginx直接返回，减少后端负载
• 跨域与CORS：如需跨域，配置Access-Control-Allow-Origin等头
• 超时与缓冲：针对大文件或长连接调整proxy_read_timeout、proxy_buffer_size等

章节来源

• index.php:26-44
• .htaccess:20-27

性能优化配置

• worker进程：根据CPU核数设置worker_processes与worker_connections
• 缓冲区：合理设置client_body_buffer_size、proxy_buffer_size、proxy_buffers
• gzip压缩：启用gzip_types包含text/html、application/json、text/css、application/javascript
• 缓存：对静态资源设置expires与Cache-Control，提高命中率
• 日志：按模块拆分access_log与error_log，便于监控与分析

章节来源

• config/config.php:36-46

负载均衡与高可用性

• upstream：定义多个后端节点，使用轮询、权重、ip_hash等策略
• keepalive：保持与后端的长连接，降低握手开销
• 健康检查：结合外部工具或Nginx Plus进行主动健康检查
• 故障转移：配置backup节点，在主节点不可用时自动切换

章节来源

• index.php:26-44

依赖关系分析

• 入口依赖：index.php依赖core/bootstrap.php进行框架初始化
• 路由依赖：front路由层读取config/route.php与site.rewrite开关决定URL风格
• 小程序依赖：miniprogram/site.ts中的rewrite_enable镜像站点重写开关，影响前端URL生成
• 常量依赖：config/config.php中的ADMIN_DIR、API_DIR、MINIPROGRAM_DIR影响location与重写规则

graph LR
Index["index.php"] --> Bootstrap["core/bootstrap.php"]
Index --> Route["front路由层"]
Route --> ConfigRoute["config/route.php"]
Route --> SiteRewrite["site.rewrite"]
Miniprogram["miniprogram/site.ts"] --> RewriteFlag["rewrite_enable"]
Config["config/config.php"] --> Paths["ADMIN/API/MINIPROGRAM_DIR"]

图示来源

• index.php:16-44
• config/config.php:36-46
• miniprogram/default/config/site.ts:12-16

章节来源

• index.php:16-44
• config/config.php:36-46
• miniprogram/default/config/site.ts:12-16

性能优化建议

• 启用HTTP/2与TLS会话复用，提升首屏速度
• 对静态资源启用CDN缓存，减轻源站压力
• 使用Gzip/Brotli压缩，减少传输体积
• 调整PHP-FPM池大小与请求队列，避免瓶颈
• 监控关键指标：QPS、延迟、错误率、缓存命中率

故障排查指南

• 404问题：检查location / 的重写是否正确，确认index.php存在且可执行
• 502/504问题：检查PHP-FPM状态与超时配置，确认后端服务正常
• 权限问题：确保Nginx用户对静态资源有读权限，对上传目录有写权限
• HTTPS问题：检查证书路径与权限，确认HTTP->HTTPS重定向生效
• 路由异常：核对config/route.php与site.rewrite开关，确保URL风格一致

章节来源

• .htaccess:17-45
• index.php:26-44

结论

通过合理的Nginx配置，可以显著提升DouPHP项目的安全性、性能与可维护性。建议在生产环境启用HTTPS、静态资源缓存、gzip压缩，并根据业务流量调整worker与缓冲区参数。对于API与后台，应单独配置location与重写规则，确保路由清晰、易于扩展。

附录：Nginx站点配置示例

以下为基于本项目结构的Nginx配置要点（示意性，需结合实际部署调整）：

• server块
  • listen 80; server_name example.com www.example.com;
  • return 301 https://$host$request_uri; （HTTP->HTTPS重定向）
  • listen 443 ssl; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem;
• location块
  • location ~* .(jpg|jpeg|png|gif|ico|css|js)$ { expires 30d; add_header Cache-Control "public, immutable"; }
  • location /api/ { rewrite ^/api/(.*)$ /api/index.php?route=$1 last; }
  • location /admin/ { rewrite ^/admin/(.*)$ /admin/index.php?route=$1 last; }
  • location / { rewrite ^(.*)$ /index.php?route=$1 last; }
  • location ~ .php$ { fastcgi_pass unix:/run/php/php-fpm.sock; include fastcgi_params; }
• 安全与性能
  • 禁用敏感扩展访问：deny all for .pem/.tpl/.dwt等
  • 启用gzip：gzip on; gzip_types text/plain application/json text/css application/javascript;
  • 设置超时：proxy_read_timeout 60s; client_max_body_size 50m;