Apache配置 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

Apache配置

简介

本文件面向在Apache上部署DouPHP项目的运维与开发者，聚焦以下目标：

说明基于.htaccess的URL重写规则（伪静态、API/后台路由、入口统一）
解释需要启用的Apache模块（如mod_rewrite、mod_ssl等）及启用方式
提供虚拟主机配置示例与多站点部署方法
给出Apache层性能优化建议（KeepAlive、缓存头、压缩等）
给出安全加固要点（禁止目录浏览、敏感文件访问控制、HTTPS强制等）

项目结构

本项目采用“单入口+路由分发”的模式：

Web根目录下的.htaccess负责将请求重写到统一的PHP入口或子应用入口
index.php为前台统一入口，负责初始化框架、解析语言前缀、分发路由并输出响应
config/config.php定义关键常量（如ADMIN_DIR、API_DIR、是否开启后台重写等），影响路由行为
_'/.api/.htaccess用于API子应用的独立重写策略（如需）

graph TB
Client["客户端浏览器"] --> Apache["Apache 服务器"]
Apache --> HTAccess[".htaccess<br/>URL重写规则"]
HTAccess --> Index["index.php<br/>前台统一入口"]
Index --> Router["路由分发"]
Router --> Front["前端控制器/业务逻辑"]
subgraph "子应用"
APIHt[".api/.htaccess"]
APIIndex["api/index.php"]
end
HTAccess --> APIHt
APIHt --> APIIndex

核心组件

URL重写与入口统一：通过.htaccess将前台、后台、API的请求统一转发到对应入口，屏蔽真实路径，实现伪静态。
安全限制：对敏感扩展名进行拒绝访问；透传Authorization头以支持后端鉴权。
路由与异常处理：index.php完成框架引导、语言前缀解析、路由分发与异常渲染。

架构总览

下图展示从HTTP请求到PHP响应的完整流程，包括重写阶段与入口处理阶段。

sequenceDiagram
participant C as "客户端"
participant A as "Apache"
participant R as ".htaccess 重写"
participant I as "index.php"
participant S as "路由/控制器"
C->>A : HTTP 请求
A->>R : 匹配重写规则
alt 静态资源命中
R-->>A : 直接返回静态文件
else 动态请求
R->>I : 重写至 index.php?route=...
I->>S : 解析语言前缀并分发路由
S-->>I : 生成响应对象
I-->>C : 发送响应HTML/JSON
end

详细组件分析

.htaccess 重写规则详解

敏感文件保护：对bak/inc/lib/sh/tpl/lbi/dwt/pem等扩展名拒绝访问，防止源码泄露。
Authorization头透传：当存在Authorization头时，将其复制到环境变量供PHP读取，便于后端实现Basic Auth或Token校验。
静态入口映射：将index.html映射到index.php，便于SEO与统一入口。
API路由重写：
- /api/xxx -> api/index.php?route=xxx
- /api -> api/index.php
后台路由重写：
- 优先处理/admin/service与/admin/service/xxx，避免与物理目录冲突
- 其他/admin/* -> admin/index.php?route=...
- /admin -> admin/index.php
前台路由重写：
- 非静态、非真实文件的请求统一重写为 index.php?route=...

flowchart TD
Start(["收到请求"]) --> CheckStatic{"是否静态资源?"}
CheckStatic --> |是| ServeStatic["直接返回静态文件"]
CheckStatic --> |否| PathMatch{"路径匹配"}
PathMatch --> |/api/*| ToAPI["重写至 api/index.php?route=..."]
PathMatch --> |/admin/*| ToAdmin["重写至 admin/index.php?route=..."]
PathMatch --> |其他| ToFront["重写至 index.php?route=..."]
ToAPI --> End(["结束"])
ToAdmin --> End
ToFront --> End
ServeStatic --> End

前台入口 index.php 的工作流

设置框架路由委托，加载前端路由解析器
解析语言前缀并写入Request，随后清理$_GET['route']
执行Init引导、路由分发、响应发送
捕获并重定向、业务异常、未捕获异常的统一处理与渲染

sequenceDiagram
participant H as "HTTP 请求"
participant I as "index.php"
participant B as "Init/Bootstrap"
participant RT as "Route/Router"
participant RSP as "Response"
H->>I : 进入前台入口
I->>B : 初始化框架
I->>RT : 分发路由
RT-->>I : 返回响应对象
I->>RSP : 发送响应并退出

配置项与重写开关

config/config.php中定义了ADMIN_DIR、API_DIR、MINIPROGRAM_DIR以及ADMIN_REWRITE等常量，影响后台路由与重写行为。
若开启后台重写，需确保Apache允许.htaccess生效，并在虚拟主机中正确配置AllowOverride。

API子应用重写（可选）

_'/.api/.htaccess可用于API子应用的独立重写策略，例如将/api/*进一步细分或添加额外安全限制。
若使用此文件，请确保父级.htaccess不会拦截该路径，或在必要时合并规则。

依赖关系分析

Apache模块依赖
- mod_rewrite：必须启用，否则所有重写规则失效
- mod_ssl：建议使用，配合虚拟主机配置HTTPS
- mod_headers/mod_expires：用于设置缓存头与压缩
应用内依赖
- index.php依赖路由与Init引导
- .htaccess依赖Apache重写引擎
- config/config.php中的常量影响路由与目录结构

graph LR
Apache["Apache"] --> ModRewrite["mod_rewrite"]
Apache --> ModSSL["mod_ssl"]
Apache --> ModHeaders["mod_headers"]
Apache --> VHost["虚拟主机"]
VHost --> DocRoot["网站根目录"]
DocRoot --> HTAccess[".htaccess"]
HTAccess --> Index["index.php"]
Index --> Config["config/config.php"]

性能考虑

KeepAlive
- 建议开启KeepAlive，合理设置KeepAliveTimeout与MaxKeepAliveRequests，减少TCP握手开销
缓存头
- 对静态资源（图片、CSS、JS）设置Cache-Control与Expires，提升重复访问性能
压缩
- 启用Gzip/Deflate压缩文本类资源，降低带宽占用
重写性能
- 将静态资源排除出重写判断（已在.htaccess中通过扩展名过滤），减少不必要的重写计算
日志与监控
- 合理配置访问日志与错误日志级别，结合APM或系统监控观察瓶颈

故障排查指南

404或路由无效
- 检查Apache是否启用mod_rewrite且AllowOverride All
- 确认.htaccess位于网站根目录且被Apache读取
- 核对.htaccess中的重写规则顺序与条件
后台无法访问
- 检查config/config.php中ADMIN_DIR是否与目录一致
- 若开启后台重写，确认Apache允许重写并正确配置虚拟主机
权限问题
- 确认storage、images、theme等目录具备读写权限
异常页面
- 根据index.php中的异常处理逻辑，调试时可临时开启调试模式查看详细堆栈
- 生产环境应关闭调试，返回友好错误或JSON错误

结论

通过.htaccess与index.php的配合，DouPHP实现了清晰的URL重写与统一入口分发。在生产环境中，建议：

启用并正确配置mod_rewrite、mod_ssl等必要模块
使用虚拟主机隔离多站点，分别配置域名、根目录与重写策略
强化安全：禁用目录浏览、限制敏感文件访问、强制HTTPS
优化性能：开启KeepAlive、设置缓存头、启用压缩
建立完善的日志与监控机制，便于快速定位问题

附录

虚拟主机配置示例（HTTPS + 重写）

以下为概念性示例，实际参数按环境调整：

监听端口443，启用SSL证书
DocumentRoot指向网站根目录
AllowOverride All以启用.htaccess
开启必要的模块：rewrite、ssl、headers、expires

<VirtualHost *:443>
    ServerName www.example.com
    DocumentRoot "/path/to/webroot"
    SSLEngine on
    SSLCertificateFile "/path/to/cert.pem"
    SSLCertificateKeyFile "/path/to/key.pem"

    <Directory "/path/to/webroot">
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # 可选：强制HTTPS
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>

常见Apache模块启用清单

mod_rewrite：启用URL重写
mod_ssl：启用HTTPS
mod_headers：设置响应头（如缓存、安全头）
mod_expires：设置过期时间
mod_deflate/gzip：启用压缩

安全加固要点

禁止目录浏览：Options -Indexes
限制敏感文件访问：已在.htaccess中对特定扩展名拒绝访问
强制HTTPS：在虚拟主机或.htaccess中重定向HTTP到HTTPS
安全响应头：X-Frame-Options、X-Content-Type-Options、Strict-Transport-Security等

添加日期：2026-10-05