简介

本指南面向在Apache上部署DouPHP的生产环境，聚焦于“可落地”的服务器级优化：包括mod_php与PHP-FPM的选择、虚拟主机配置要点、模块加载顺序、.htaccess重写规则调优、静态资源访问控制、进程与连接管理（MaxRequestWorkers、KeepAlive）、以及安全加固（敏感文件访问控制、目录遍历防护、请求大小限制）。文档中的建议均结合仓库中现有的.htaccess与安全配置进行说明，确保与DouPHP的路由与入口约定一致。

项目结构

DouPHP采用单入口+路由分发模式，前端、后台与API分别通过根目录与子目录的入口脚本处理，URL重写将用户请求统一转发到对应入口。关键文件：

• 根目录 .htaccess：定义敏感文件拒绝访问、Authorization头透传、API/后台/前台的重写规则。
• robots.txt：声明搜索引擎对敏感目录的抓取策略。
• config/config.php：应用级常量与开关（如是否启用admin URL重写等）。
• config/security.php：安全相关配置（可信代理、Host白名单、响应头、限流、会话Cookie硬化）。
• core/web/http/Request.php：读取请求头时兼容apache_request_headers()，用于在特定部署下获取Authorization头。
• core/service/ai/AiStreamer.php：在流式输出场景禁用gzip，避免压缩导致的卡顿。

graph TB
A["客户端"] --> B["Apache 服务器"]
B --> C[".htaccess<br/>重写与访问控制"]
C --> D["index.php<br/>前台入口"]
C --> E["api/index.php<br/>API入口"]
C --> F["admin/index.php<br/>后台入口"]
B --> G["静态资源<br/>images/css/js"]
B --> H["受保护文件<br/>bak/inc/lib/sh/tpl/lbi/dwt/pem"]

核心组件

• URL重写与入口分发：.htaccess将/api/、/admin/与非静态路径重写到对应入口，同时排除常见静态扩展名，减少不必要的PHP解析开销。
• Authorization头透传：当使用Proxy或FastCGI时，Apache会吞掉Authorization头；.htaccess将其复制到环境变量供PHP读取，配合Request.php在部分环境下从apache_request_headers()恢复该头。
• 安全响应头与会话硬化：security.php提供X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS开关及Session Cookie安全选项。
• 流式输出优化：AI流式接口在Apache环境下关闭gzip，避免缓冲阻塞。

架构总览

下图展示了请求从Apache进入后，如何经.htaccess进行访问控制与重写，再交由DouPHP各入口处理。

sequenceDiagram
participant U as "用户浏览器"
participant A as "Apache"
participant R as ".htaccess 重写"
participant P as "PHP 运行时"
participant APP as "DouPHP 入口"
U->>A : HTTP 请求
A->>R : 匹配 FilesMatch / RewriteRule
alt 静态资源
R-->>U : 直接返回静态文件
else API/后台/前台
R->>P : 转发至 index.php / api/index.php / admin/index.php
P->>APP : 初始化框架并路由分发
APP-->>U : 生成响应
end

详细组件分析

组件一：.htaccess 重写与访问控制

• 敏感文件拒绝访问：对bak/inc/lib/sh/tpl/lbi/dwt/pem等后缀进行拒绝，防止源码或模板被下载。
• Authorization头透传：将HTTP Authorization复制到环境变量，便于后端读取。
• 静态资源短路：对ico/gif/jpg/jpeg/png/js/css等扩展名跳过重写，直接由Apache返回，降低PHP负载。
• API/后台/前台路由：
  • /api/* 映射到 api/index.php?route=...
  • /admin/* 映射到 admin/index.php?route=...
  • 其他非静态路径映射到 index.php?route=...

flowchart TD
Start(["请求到达"]) --> CheckExt{"是否静态扩展?"}
CheckExt -- 是 --> ServeStatic["直接返回静态文件"]
CheckExt -- 否 --> MatchAPI{"是否 /api/* ?"}
MatchAPI -- 是 --> ToAPI["重写为 api/index.php?route=..."]
MatchAPI -- 否 --> MatchAdmin{"是否 /admin/* ?"}
MatchAdmin -- 是 --> ToAdmin["重写为 admin/index.php?route=..."]
MatchAdmin -- 否 --> ToFront["重写为 index.php?route=..."]
ToAPI --> End(["结束"])
ToAdmin --> End
ToFront --> End
ServeStatic --> End

组件二：Authorization头透传与读取

• Apache/FastCGI可能吞掉Authorization头，.htaccess将其复制到环境变量。
• Request.php在部分部署下通过apache_request_headers()读取Authorization头，保证鉴权流程可用。

sequenceDiagram
participant B as "浏览器"
participant A as "Apache"
participant H as ".htaccess"
participant PHP as "PHP"
participant R as "Request.php"
B->>A : 携带 Authorization 头
A->>H : 匹配条件
H->>A : 设置环境变量 HTTP_AUTHORIZATION
A->>PHP : 传递请求
PHP->>R : 读取请求头
R-->>PHP : 返回 Authorization 值
PHP-->>B : 继续鉴权流程

组件三：安全配置与响应头

• security.php定义了可信代理、可信Host、安全响应头（X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS）以及会话Cookie硬化（httponly、secure、samesite、use_strict_mode）。
• 建议在生产环境开启HSTS（仅HTTPS），并严格限定trusted_hosts，避免Host头注入风险。

组件四：流式输出与压缩

• AI流式接口在Apache环境下禁用gzip，以避免压缩缓冲导致流式响应卡顿。
• 若业务需要压缩，请评估流式场景下的权衡，或在反向代理层按需处理。

依赖关系分析

• .htaccess 与入口脚本：重写规则将不同前缀的请求路由到对应的入口脚本，形成稳定的请求分发边界。
• Request.php 与 Apache 头处理：在特定部署下依赖apache_request_headers()以恢复Authorization头。
• security.php 与中间件：安全响应头与会话策略由框架中间件在响应阶段下发，需与Apache/反向代理的安全头策略协调，避免重复或冲突。

graph LR
HT[".htaccess"] --> IN["入口脚本"]
IN --> REQ["Request.php"]
SEC["security.php"] --> MID["安全中间件"]
REQ --> IN
MID --> IN

性能注意事项

以下为面向Apache服务器的通用优化建议，结合DouPHP的URL重写与入口特点给出实践要点：

• mod_php 与 PHP-FPM 选择

  • 高并发/多站点：优先PHP-FPM，进程隔离更好、内存更可控、易于水平扩展。
  • 低并发/单站点：mod_php 简单但进程共享内存，易受大对象影响，稳定性较差。
  • 建议：生产环境默认PHP-FPM；如需极致简化且负载极低，可考虑mod_php。

• 虚拟主机配置优化

  • 为每个站点独立vhost，限制日志轮转与磁盘配额。
  • 合理设置DocumentRoot与AllowOverride，尽量将重写规则放入vhost而非.htaccess，减少每请求的文件系统开销。
  • 启用Gzip/Brotli压缩（注意流式响应场景，参考AI流式禁用gzip的做法）。

• 模块加载顺序优化

  • 先加载静态处理器（如mod_deflate、mod_expires），再加载PHP处理器，减少不必要的PHP调用。
  • 仅启用必要模块，避免冗余模块增加启动时间与内存占用。

• .htaccess 重写性能调优

  • 将常用重写规则移至vhost配置，减少每请求读取.htaccess的开销。
  • 保持静态扩展短路（ico/gif/jpg/jpeg/png/js/css），避免命中重写。
  • 条件判断尽量前置，减少无效匹配。

• 静态资源访问控制

  • 对图片、CSS、JS等静态资源启用缓存头（Cache-Control/Expires）。
  • 对敏感后缀（bak/inc/lib/sh/tpl/lbi/dwt/pem）拒绝访问，已在.htaccess中实现。

• Apache 进程与连接管理

  • MaxRequestWorkers：根据CPU核数与PHP-FPM子进程内存估算，避免OOM。
  • KeepAlive：开启并设置合理超时，提升长连接复用率。
  • Timeout/KeepAliveTimeout：按业务RT调整，避免慢请求拖垮工作进程。
  • MPM选择：prefork（mod_php）或worker/event（PHP-FPM）按部署模式选择。

• 安全加固

  • 禁止目录浏览（Options -Indexes）。
  • 限制请求体大小（LimitRequestBody）与上传大小（upload_max_filesize/post_max_size）。
  • 限制HTTP方法（仅允许GET/POST/HEAD等）。
  • 启用安全响应头（X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS）。

故障排查指南

• 无法获取Authorization头

  • 检查.htaccess是否已透传Authorization到环境变量。
  • 确认Request.php是否能通过apache_request_headers()读取该头。
  • 若使用反向代理，确保透传Authorization头。

• 流式响应卡顿

  • 检查是否在Apache环境下启用了压缩；必要时在流式接口禁用gzip。
  • 评估上游代理（如CDN/负载均衡）的缓冲策略。

• 404或路由异常

  • 核对.htaccess重写规则是否与入口约定一致。
  • 检查config/config.php中是否启用了admin URL重写开关。

• 安全告警

  • 确认security.php中HSTS、SameSite、Secure等选项符合部署环境。
  • 校验robots.txt是否正确屏蔽了敏感目录。

结论

通过对DouPHP的.htaccess重写规则、安全配置与请求头处理的深入分析，可在Apache环境下实现高效、安全的部署。建议生产环境优先采用PHP-FPM、将重写规则下沉至vhost、精细化控制静态资源缓存与压缩、并结合security.php强化安全响应头与会话策略。对于流式接口，谨慎处理压缩与缓冲，确保用户体验。

附录

• 建议的检查清单
  • 已启用敏感文件拒绝访问（.htaccess FilesMatch）。
  • 已透传Authorization头并在PHP侧正确读取。
  • 静态资源短路生效，减少PHP解析。
  • security.php中HSTS、SameSite、Secure等选项已按环境启用。
  • robots.txt已屏蔽敏感目录。
  • 生产环境已关闭调试开关（DOU_DEBUG）。