# Web 服务器配置

<cite>
**本文引用的文件**
- [public/.htaccess](file://public/.htaccess)
- [public/api.php](file://public/api.php)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/upload/.htaccess](file://public/upload/.htaccess)
- [README.md](file://README.md)
- [composer.json](file://composer.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向部署 ThinkCMF 的运维与开发人员，提供 Apache 与 Nginx 的完整 Web 服务器配置说明，涵盖 URL 重写、虚拟主机、安全头、静态资源处理、FastCGI、反向代理、SSL/TLS 证书（含 Let’s Encrypt 与自签名）、性能优化（Gzip、缓存头、连接池）以及常见错误排查。ThinkCMF 使用 public 目录作为网站根目录，通过入口文件与重写规则实现 MVC 请求分发。

## 项目结构
- 网站根目录：public
- 入口文件：
  - 前端入口：public/index.php
  - API 入口：public/api.php
  - 路由适配器：public/router.php
- URL 重写：public/.htaccess
- 主题与上传目录的安全限制：
  - public/themes/.htaccess_apache2.4
  - public/upload/.htaccess

```mermaid
graph TB
Root["站点根目录<br/>public"] --> Index["前端入口<br/>index.php"]
Root --> API["API 入口<br/>api.php"]
Root --> Router["路由适配器<br/>router.php"]
Root --> HT["重写规则<br/>.htaccess"]
Root --> ThemesSec["主题安全限制<br/>themes/.htaccess_apache2.4"]
Root --> UploadSec["上传目录安全限制<br/>upload/.htaccess"]
```

图表来源
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [composer.json:46-56](file://composer.json#L46-L56)

## 核心组件
- 入口与框架启动
  - public/index.php：定义常量、加载自动加载器、创建并运行 HTTP 应用，输出响应。
  - public/api.php：与 index.php 类似，但指定 API 命名空间与应用路径。
  - public/router.php：若请求的物理文件不存在，则将请求转发至 index.php，便于服务器重写或静态托管场景。
- URL 重写与路由
  - public/.htaccess：启用 mod_rewrite，对 API 与通用路径进行重写，将请求交由 index.php 或 api.php 处理，并设置 Authorization 环境变量。
  - API 入口规则：优先匹配以 api/ 开头的路径，转发至 api.php。
  - 通用规则：若未命中 API，则将请求转发至 index.php。
- 安全与访问控制
  - public/themes/.htaccess_apache2.4：拒绝访问主题目录中的 html/php/json 文件。
  - public/upload/.htaccess：拒绝访问上传目录中的 html/php 文件。
- 运行环境与依赖
  - composer.json：定义 PSR-4 自动加载命名空间（app、api、plugins、themes），确保入口与路由正确解析。

章节来源
- [public/index.php:15-37](file://public/index.php#L15-L37)
- [public/api.php:15-41](file://public/api.php#L15-L41)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [composer.json:46-56](file://composer.json#L46-L56)

## 架构总览
ThinkCMF 的请求流转基于“入口文件 + 重写规则”的模式：
- 客户端请求到达 Web 服务器后，由 .htaccess 将未命中的静态资源请求重写到入口文件。
- 入口文件根据请求路径选择性地将请求交给 API 或前端应用处理。
- 应用层负责业务逻辑与响应生成。

```mermaid
sequenceDiagram
participant C as "客户端"
participant S as "Web 服务器"
participant R as "重写规则<br/>.htaccess"
participant I as "前端入口<br/>index.php"
participant A as "API 入口<br/>api.php"
C->>S : "HTTP 请求"
S->>R : "检查是否命中静态文件"
alt "命中 API 路径"
R-->>A : "重写到 api.php"
A-->>C : "响应"
else "通用路径"
R-->>I : "重写到 index.php"
I-->>C : "响应"
end
```

图表来源
- [public/.htaccess:5-11](file://public/.htaccess#L5-L11)
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [public/api.php:30-41](file://public/api.php#L30-L41)

## 详细组件分析

### Apache 配置要点
- 站点根目录
  - 将 Web 服务器的 DocumentRoot 指向 public 目录，确保入口文件与重写规则生效。
- URL 重写与多应用
  - 启用 mod_rewrite，保留现有 .htaccess 中的 API 与通用重写规则。
  - 保持 Authorization 环境变量设置，避免鉴权丢失。
- 安全头与访问控制
  - 主题目录安全：使用 themes/.htaccess_apache2.4 对 html/php/json 文件进行访问限制。
  - 上传目录安全：使用 upload/.htaccess 对 html/php 文件进行禁止访问。
- 虚拟主机建议
  - 为每个域名配置独立的虚拟主机块，分别指向对应站点的 public 目录。
  - 在虚拟主机中开启 .htaccess 权限与重写模块。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [README.md:96-101](file://README.md#L96-L101)

### Nginx 配置要点
- 站点根目录与入口
  - root 指向 public；location / 优先检查是否存在真实文件，不存在则将请求交由 router.php 或直接到 index.php。
- API 入口映射
  - location ~ ^/api/ 重写到 api.php，保持与 .htaccess 的 API 规则一致。
- FastCGI 设置
  - 将 .php 请求交由 PHP-FPM 处理，使用正确的 fastcgi_params 与 socket/unix 套接字或 TCP 地址。
- 静态资源处理
  - 对 public/static、public/themes、public/upload 等目录设置合理的缓存与访问策略。
- 反向代理
  - 若 ThinkCMF 位于子路径或需前置代理，注意调整 root、location 与重写规则，确保路径前缀一致。

章节来源
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/.htaccess:7-11](file://public/.htaccess#L7-L11)
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [public/api.php:30-41](file://public/api.php#L30-L41)

### 不同服务器的配置差异与注意事项
- Apache
  - 依赖 .htaccess 实现重写与安全限制；需确保 AllowOverride 允许 .htaccess 生效。
  - 主题与上传目录的安全规则在 Apache 2.4 语法与旧语法之间存在差异，应按服务器版本选择对应文件。
- Nginx
  - 重写规则需在 server/location 中显式声明，不能依赖 .htaccess。
  - FastCGI 与 PHP-FPM 的 socket/unix 套接字或 TCP 需与实际环境一致。
- 共同点
  - 入口文件与重写规则必须保持一致，确保 API 与通用路径均能正确分发。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/router.php:13-19](file://public/router.php#L13-L19)

### SSL/TLS 证书配置
- Let’s Encrypt（自动证书）
  - 使用 acme 证书签发工具（如 certbot）申请域名证书，配置 Web 服务器的 ssl_certificate 与 ssl_certificate_key。
  - 强制 HTTPS 访问，重定向 80 端口到 443。
- 自签名证书
  - 生成自签名证书与私钥，配置 ssl_certificate 与 ssl_certificate_key。
  - 浏览器会提示证书不受信任，适合内网或测试环境。
- 服务器配置要点
  - Apache：SSLEngine on，SSLCertificateFile，SSLCertificateKeyFile。
  - Nginx：listen 443 ssl，ssl_certificate，ssl_certificate_key。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)

### 性能优化配置
- Gzip 压缩
  - Apache：启用 deflate 模块，对文本类资源进行压缩。
  - Nginx：gzip on，设置 gzip_types，提升传输效率。
- 缓存头设置
  - 对静态资源（CSS/JS/图片）设置较长的 Cache-Control，结合内容指纹或版本号实现强缓存。
- 连接池与 PHP-FPM
  - 合理设置 PHP-FPM 的进程数、进程池与空闲超时，避免高并发下的连接瓶颈。
- CDN 与静态分离
  - 将 public/static、public/themes、public/upload 等静态资源迁移到 CDN，降低源站压力。

章节来源
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [public/api.php:30-41](file://public/api.php#L30-L41)

## 依赖关系分析
- 入口文件依赖自动加载器与应用实例，通过 composer.json 的 PSR-4 映射解析命名空间。
- 重写规则依赖入口文件与路由适配器，确保请求被正确分发到 API 或前端应用。
- 安全规则依赖服务器模块（Apache 的 mod_rewrite、mod_authz_host；Nginx 的 location 与 deny）。

```mermaid
graph LR
Composer["composer.json<br/>PSR-4 自动加载"] --> Autoload["vendor/autoload.php"]
Autoload --> Index["index.php"]
Autoload --> API["api.php"]
HT["public/.htaccess"] --> Index
HT --> API
Router["public/router.php"] --> Index
ThemesSec["themes/.htaccess_apache2.4"] --> ProtectThemes["保护主题文件"]
UploadSec["upload/.htaccess"] --> ProtectUpload["保护上传文件"]
```

图表来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [public/api.php:30-41](file://public/api.php#L30-L41)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)

章节来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [public/api.php:30-41](file://public/api.php#L30-L41)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)

## 性能考虑
- 传输压缩：启用 Gzip/Deflate，减少带宽占用。
- 静态资源缓存：对 CSS/JS/图片设置长缓存，结合版本号或指纹避免陈旧缓存。
- PHP-FPM：根据并发与内存情况调优进程模型与超时参数。
- CDN：将静态资源迁移至 CDN，降低源站负载与延迟。
- 日志与监控：记录慢请求与错误，持续优化热点路径。

## 故障排除指南
- 404 错误
  - 检查 Web 服务器的 DocumentRoot 是否指向 public。
  - 确认 .htaccess 已启用且 AllowOverride 允许重写。
  - 确保 API 与通用路径的重写规则未被覆盖。
- 500 错误
  - 查看 PHP 错误日志与 Web 服务器错误日志。
  - 确认 vendor/autoload.php 加载成功，PSR-4 命名空间映射正确。
- 重写规则问题
  - Apache：确认 mod_rewrite 已启用，.htaccess 语法正确。
  - Nginx：确认 location 与 try_files/rewrite 规则与 .htaccess 保持一致。
- 安全访问受限
  - 检查主题与上传目录的安全规则是否导致资源无法访问。
  - 确认服务器版本对应的 .htaccess 语法（Apache 2.4 与旧语法差异）。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [composer.json:46-56](file://composer.json#L46-L56)

## 结论
通过将 Web 服务器根目录指向 public、保留并正确配置 .htaccess 的重写规则、落实主题与上传目录的安全限制，并结合 SSL/TLS、Gzip、缓存与 PHP-FPM 优化，可稳定高效地运行 ThinkCMF。在 Apache 与 Nginx 上的关键差异在于重写规则的落地位置与 FastCGI 的配置方式，务必确保两者行为一致。

## 附录
- 环境要求与入口说明可参考项目文档与 composer.json 的自动加载配置。

章节来源
- [README.md:84-101](file://README.md#L84-L101)
- [composer.json:46-56](file://composer.json#L46-L56)