简介

本指南面向部署 DouPHP 的运维与开发者，提供在 Apache 与 Nginx 上的完整 Web 服务器配置方案。内容涵盖：

• Apache .htaccess 的 URL 重写、MIME 类型、缓存控制与安全限制
• Nginx location 块、rewrite 规则、反向代理与 HTTPS 重定向
• SSL 证书配置要点
• CDN 集成策略
• Gzip/浏览器缓存/静态资源优化等性能调优

DouPHP 通过统一的入口文件与路由层解析请求，Web 服务器只需将请求正确转发到对应入口即可。

项目结构

DouPHP 采用多入口架构：

• 前台入口：根目录 index.php
• API 入口：api/index.php
• 后台入口：admin/index.php
• 统一路由规则：config/route.php 与 core/web/routing/*

graph TB
Client["客户端"] --> WebServer["Web 服务器<br/>Apache/Nginx"]
WebServer --> |URL 重写| Front["前台入口<br/>index.php"]
WebServer --> |URL 重写| Api["API 入口<br/>api/index.php"]
WebServer --> |URL 重写| Admin["后台入口<br/>admin/index.php"]
Front --> Router["路由层<br/>config/route.php + RouteRules"]
Api --> Router
Admin --> Router

图示来源

• .htaccess:10-45
• index.php:16-44
• api/index.php:16-39
• admin/index.php:16-40
• config/route.php:15-356

核心组件

• 入口与路由：三个入口分别设置路由委托并分发请求；路由风格由 config/route.php 集中管理。
• 安全与访问控制：.htaccess 对敏感扩展名进行拒绝访问；透传 Authorization 头以支持 Basic Auth。
• 存储与上传：config/file.php 定义磁盘与上传默认策略（如允许扩展名、缩略图目录）。

架构总览

请求从 Web 服务器进入后，根据路径前缀被重写至不同入口，再由各自入口初始化框架并交由路由层匹配处理。

sequenceDiagram
participant C as "客户端"
participant A as "Apache/Nginx"
participant F as "前台入口<br/>index.php"
participant R as "路由层"
participant S as "业务控制器"
C->>A : HTTP 请求
A->>F : 重写为 index.php?route=...
F->>R : 设置路由委托并分发
R-->>S : 匹配规则并调用控制器
S-->>F : 返回响应对象
F-->>C : 发送响应

图示来源

• .htaccess:17-45
• index.php:26-44
• config/route.php:15-356

详细组件分析

Apache 配置（.htaccess）

• 安全限制：禁止直接访问备份/模板/脚本等敏感扩展名。
• 认证头透传：将 Authorization 头复制到环境变量，供 PHP 读取。
• 静态入口：将 index.html 指向 index.php。
• API 重写：将 /api/* 映射到 api/index.php，保留查询参数。
• 后台重写：将 /admin/* 映射到 admin/index.php，特殊处理 service 子路径。
• 前台重写：将非静态资源请求统一转发到 index.php。

flowchart TD
Start(["收到请求"]) --> CheckStatic{"是否静态资源?"}
CheckStatic --> |是| Serve["直接返回静态文件"]
CheckStatic --> |否| PathCheck{"路径前缀"}
PathCheck --> |/api/*| ToApi["重写到 api/index.php"]
PathCheck --> |/admin/*| ToAdmin["重写到 admin/index.php"]
PathCheck --> |其他| ToFront["重写到 index.php"]
ToApi --> End(["结束"])
ToAdmin --> End
ToFront --> End

图示来源

• .htaccess:10-45

Nginx 配置要点

• location 块划分：
  • 静态资源 location：开启 gzip、设置缓存头、关闭日志或降低级别。
  • API location：将 /api/* 转发到后端 PHP-FPM 的入口。
  • 后台 location：将 /admin/* 转发到后台入口。
  • 默认 location：将所有非静态请求转发到前台入口。
• rewrite 规则：
  • 若启用 PATH_INFO 模式，可基于 $request_uri 提取 route 段。
  • 若使用 URL 重写，确保不重复改写已存在的物理文件/目录。
• 反向代理：
  • 如需将 API 或后台独立部署，可在 Nginx 中用 proxy_pass 指向后端服务。
• HTTPS 与证书：
  • 监听 443 端口并配置 ssl_certificate 与 ssl_certificate_key。
  • 将 80 端口的 HTTP 请求 301 重定向到 HTTPS。

提示：Nginx 的具体 server/location/rewrite 指令需结合站点域名、根目录与 PHP-FPM 监听地址进行配置。

SSL 证书与 HTTPS 重定向

• Apache：
  • 启用 mod_ssl，并在虚拟主机中指定证书与私钥。
  • 在 80 端口添加 301 重定向到 https:// 域名。
• Nginx：
  • 在 443 server 块中配置 ssl_certificate 与 ssl_certificate_key。
  • 在 80 server 块中添加 return 301 https://$host$request_uri。
• 应用层：
  • 确保生成的链接与回调地址使用 HTTPS。
  • 小程序与第三方回调需配置可信域名与证书。

CDN 集成

• 静态资源：
  • 将 theme、images、miniprogram 等静态目录托管到 CDN，并在页面中替换为 CDN 域名。
  • 利用 CDN 缓存策略（Cache-Control、ETag）提升加载速度。
• 动态加速：
  • 对 API 与后台页面开启边缘缓存或动态加速（谨慎使用，避免缓存用户态数据）。
• 回源配置：
  • 配置回源白名单与鉴权头透传，确保仅允许必要头部通过。
• 版本化：
  • 对静态资源使用文件名哈希或版本号，便于更新时强制刷新缓存。

性能优化（Gzip、浏览器缓存、静态资源）

• Gzip/Brotli：
  • 在 Web 服务器层开启压缩，对 HTML/CSS/JS/JSON 等文本类型进行压缩。
• 浏览器缓存：
  • 为静态资源设置较长的 Cache-Control 与 Expires，配合版本化策略。
  • 对频繁变动的资源使用短缓存或无缓存。
• 静态资源优化：
  • 图片使用现代格式（WebP/AVIF），按需生成缩略图。
  • 合并与压缩前端资源，减少请求数与体积。
• 路由与模板：
  • 合理配置路由风格以减少复杂正则匹配开销。
  • 模板输出开启缓冲与压缩。

依赖关系分析

• 入口与路由：
  • 前台、API、后台入口均依赖核心路由层进行分发。
  • 路由风格与规则集中在 config/route.php，运行时由 RouteRules 读取与缓存。
• URL 构建与分类 slug：
  • UrlBuilder 负责预热分类行缓存，提升短地址模块的分类链生成效率。

graph LR
Index["前台入口<br/>index.php"] --> RouterCore["路由层<br/>RouteRules"]
Api["API 入口<br/>api/index.php"] --> RouterCore
Admin["后台入口<br/>admin/index.php"] --> RouterCore
RouterCore --> Rules["路由规则<br/>config/route.php"]
RouterCore --> UrlB["URL 构建<br/>UrlBuilder"]

图示来源

• index.php:26-44
• api/index.php:27-39
• admin/index.php:26-40
• core/web/routing/RouteRules.php:23-42
• config/route.php:15-356
• core/web/routing/UrlBuilder.php:888-923

性能优化建议

• 服务器层：
  • 开启 Gzip/Brotli 压缩，针对文本类型生效。
  • 为静态资源设置长期缓存，配合版本化与 CDN。
  • 调整连接池与超时参数，避免慢请求拖垮服务。
• 应用层：
  • 合理配置路由风格，减少复杂正则匹配。
  • 使用缓存机制（内存/Redis）降低数据库压力。
  • 对大文件上传与下载进行分片与限速。
• 监控与诊断：
  • 开启错误日志与慢查询日志，定期分析瓶颈。
  • 使用性能分析工具定位热点代码与接口。

故障排查指南

• 无法访问后台或 API：
  • 检查 .htaccess 或 Nginx 的 rewrite/location 是否正确转发到对应入口。
  • 确认入口文件的权限与 PHP 环境正常。
• 静态资源 404：
  • 确认 Web 服务器未拦截静态文件，且路径正确。
  • 检查 CDN 回源与缓存策略。
• 认证失败：
  • Apache 下确认 Authorization 头透传已启用。
  • Nginx 下确认 proxy_set_header 透传了必要头部。
• 异常处理：
  • 前台与后台入口在捕获异常时会记录日志并根据调试模式输出友好提示或 JSON 错误。

结论

DouPHP 的 Web 服务器配置核心在于“正确的入口转发”与“安全的访问控制”。通过 .htaccess 或 Nginx 将请求路由到前台、API 与后台入口，并结合 SSL、CDN 与缓存策略，可获得稳定、安全且高性能的部署效果。建议在上线前完成 HTTPS 强制、静态资源缓存与错误日志配置，并进行端到端测试验证。

附录

• 常见入口与重写对照：
  • 前台：/xxx -> index.php?route=xxx
  • API：/api/xxx -> api/index.php?route=xxx
  • 后台：/admin/xxx -> admin/index.php?route=xxx
• 路由风格：
  • 通过 config/route.php 选择适合的前台 URL 风格，兼顾 SEO 与可读性。