# 环境要求

<cite>
**本文引用的文件**
- [composer.json](file://composer.json)
- [README.md](file://README.md)
- [database.yml](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml)
- [AGENTS.MD](file://AGENTS.MD)
- [.gitignore](file://.gitignore)
- [public/.htaccess](file://public/.htaccess)
- [public/themes/.htaccess](file://public/themes/.htaccess)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/upload/.htaccess](file://public/upload/.htaccess)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)
</cite>

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

## 简介
本文件面向 ThinkCMF 的部署与运维人员，系统梳理并明确以下环境要求与配置要点：
- 服务器硬件最低配置建议（CPU、内存、磁盘空间、带宽）
- 操作系统兼容性（Linux、Windows、macOS）
- PHP 运行环境要求（版本、必需扩展、推荐扩展）
- Web 服务器要求（Apache 2.4+、Nginx 1.10+）
- 数据库要求（MySQL 5.7+、MariaDB、PostgreSQL）
- Composer 工具使用要求
- 不同部署场景下的环境配置对比表

上述内容均基于仓库中的配置文件、安装与部署文档、示例环境变量与重写规则等证据进行归纳总结。

## 项目结构
从部署视角看，ThinkCMF 的 Web 根目录应指向 public/，入口脚本为 public/index.php；安装程序与数据库配置位于 vendor/thinkcmf/cmf-install 下；环境变量示例位于 AGENTS.MD；重写规则位于 public/.htaccess；主题与上传目录的安全规则分别位于 public/themes/.htaccess 与 public/upload/.htaccess。

```mermaid
graph TB
A["Web 根目录<br/>public/"] --> B["入口脚本<br/>public/index.php"]
A --> C["重写规则<br/>public/.htaccess"]
A --> D["主题目录<br/>public/themes/"]
A --> E["上传目录<br/>public/upload/"]
F["安装与数据库配置<br/>vendor/thinkcmf/cmf-install"] --> G["数据库配置模板<br/>database.yml"]
H["环境变量示例<br/>AGENTS.MD"] --> I[".env 示例与部署步骤"]
J[".gitignore"] --> K["敏感文件与忽略项"]
```

图表来源
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [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)
- [database.yml:1-23](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L23)
- [AGENTS.MD:716-777](file://AGENTS.MD#L716-L777)
- [.gitignore:1-17](file://.gitignore#L1-L17)

章节来源
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [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)
- [database.yml:1-23](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L23)
- [AGENTS.MD:716-777](file://AGENTS.MD#L716-L777)
- [.gitignore:1-17](file://.gitignore#L1-L17)

## 核心组件
- PHP 运行时与扩展：根据 composer.json，PHP 版本要求不低于 8.1.0，并声明了 json、curl、pdo、mbstring、zip 等扩展为必需。
- Web 服务器：README 与 .htaccess 显示项目依赖 URL 重写（rewrite），且提供了 Apache 的重写规则；未发现官方 Nginx 配置文件，但可基于重写规则自行适配。
- 数据库：database.yml 指定默认数据库类型为 mysql；同时 AGENTS.MD 的“环境变量”章节给出 DATABASE_TYPE=mysql 的示例，表明 MySQL/MariaDB 为主要支持对象。
- Composer：AGENTS.MD 提供生产环境安装依赖的命令与参数，体现 Composer 在部署中的使用方式。
- 环境变量与配置：AGENTS.MD 展示了 .env 的配置项与优先级；README 的“环境推荐/最低环境要求”提供了版本建议与基础条件。

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [README.md:84-94](file://README.md#L84-L94)
- [database.yml:1-2](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L2)
- [AGENTS.MD:716-777](file://AGENTS.MD#L716-L777)

## 架构总览
下图展示 ThinkCMF 的典型部署拓扑：客户端通过 Web 服务器接收请求，经 URL 重写后交由 PHP-FPM 解释执行，应用访问数据库与缓存等基础设施。

```mermaid
graph TB
Client["客户端浏览器"] --> Web["Web 服务器<br/>Apache 2.4+/Nginx 1.10+"]
Web --> PHP["PHP 运行时<br/>8.1+ + 必需扩展"]
PHP --> App["ThinkCMF 应用层"]
App --> DB["数据库<br/>MySQL 5.7+/MariaDB"]
App --> Cache["缓存/会话存储"]
```

图表来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [database.yml:1-2](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L2)
- [AGENTS.MD:716-777](file://AGENTS.MD#L716-L777)

## 详细组件分析

### PHP 环境要求
- 版本要求：PHP >= 8.1.0（来自 composer.json 的 require 字段）。
- 必需扩展：json、curl、pdo、mbstring、zip（来自 composer.json 的 require 字段）。
- 推荐扩展：README 的“环境推荐”建议使用 PHP 8.2；未在 composer.json 中声明额外推荐扩展，但可结合业务场景按需启用（如 gd、exif、intl 等）。
- 安装与部署：生产环境建议使用 Composer 安装依赖并优化自动加载（参考 AGENTS.MD 的部署步骤）。

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [README.md:84-94](file://README.md#L84-L94)
- [AGENTS.MD:748-757](file://AGENTS.MD#L748-L757)

### Web 服务器要求
- Apache
  - 重写模块：必须启用 rewrite（mod_rewrite）。
  - 重写规则：仓库提供 Apache 的 .htaccess 重写规则，将 API 与普通请求转发至入口脚本。
  - 安全规则：主题与上传目录包含 .htaccess，限制对特定文件类型的访问。
- Nginx
  - 未提供官方 Nginx 配置文件；可依据 public/.htaccess 的重写规则自行适配，确保 API 与静态路由正确转发至入口脚本。

章节来源
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [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)

### 数据库要求
- 类型与驱动：database.yml 默认类型为 mysql；AGENTS.MD 的环境变量示例 DATABASE_TYPE=mysql，表明 MySQL/MariaDB 为主要支持对象。
- 版本建议：README 的“环境推荐”为 MySQL 5.7+；“最低环境要求”为 MySQL 5.5。
- 其他支持：未在 composer.json 或安装配置中发现 PostgreSQL 的直接声明；若需 PostgreSQL，建议在自定义配置中验证兼容性。

章节来源
- [database.yml:1-2](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L2)
- [AGENTS.MD:716-735](file://AGENTS.MD#L716-L735)
- [README.md:84-94](file://README.md#L84-L94)

### Composer 工具使用
- 安装依赖：生产环境建议使用 Composer 安装并优化自动加载（参考 AGENTS.MD 的部署步骤）。
- 插件与包：仓库包含多个 thinkcmf/* 包，Composer 作为包管理工具贯穿安装与运行。

章节来源
- [AGENTS.MD:748-757](file://AGENTS.MD#L748-L757)
- [composer.json:37-41](file://composer.json#L37-L41)

### 环境变量与配置优先级
- .env 优先级最高，随后为 data/config 动态配置，最后为 config 静态配置。
- AGENTS.MD 提供了数据库相关的关键环境变量示例，便于快速配置。

章节来源
- [AGENTS.MD:716-741](file://AGENTS.MD#L716-L741)

### 安全与目录权限
- 目录权限：生产环境需确保 data/ 与 public/upload/ 可写（参考 AGENTS.MD 的部署步骤）。
- 访问控制：主题与上传目录的 .htaccess 对 html/php/json 等文件类型进行访问限制，提升安全性。

章节来源
- [AGENTS.MD:748-768](file://AGENTS.MD#L748-L768)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [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)

## 依赖分析
- 应用依赖 ThinkCMF 的核心包（cmf-app、cmf-install、cmf-api 等），这些包在 composer.json 中声明。
- 运行时依赖 PHP 8.1+ 与若干扩展，这些在 composer.json 的 require 字段中明确。
- 安装与部署流程通过 Composer 自动化脚本（post-autoload-dump）执行服务发现、发布与迁移等任务。

```mermaid
graph LR
CMF["ThinkCMF 应用"] --> Core["thinkcmf/cmf-app"]
CMF --> Install["thinkcmf/cmf-install"]
CMF --> API["thinkcmf/cmf-api"]
CMF --> Root["thinkcmf/cmf-root"]
CMF --> PHP["PHP 8.1+ + 扩展"]
```

图表来源
- [composer.json:37-41](file://composer.json#L37-L41)
- [composer.json:30-42](file://composer.json#L30-L42)

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:67-72](file://composer.json#L67-L72)

## 性能考虑
- PHP 版本：建议使用较新的稳定版本（如 PHP 8.2）以获得更好的性能与兼容性。
- 扩展：启用必要的扩展（json、curl、pdo、mbstring、zip）是基础；根据业务可选启用图像处理、国际化等扩展。
- Web 服务器：开启 gzip/HTTP/2、合理配置缓存头与静态资源压缩可显著提升性能。
- 数据库：使用 MySQL 5.7+ 并优化索引、查询与连接池；避免慢查询与锁竞争。
- 部署：生产环境使用 Composer 优化自动加载与类映射，减少请求时的 IO 开销。

## 故障排查指南
- 重写未生效
  - 确认 Web 服务器已启用 rewrite 模块，且 public/.htaccess 的规则已正确加载。
  - 检查站点根目录是否指向 public/。
- 权限问题
  - data/ 与 public/upload/ 目录不可写会导致安装或上传失败；按 AGENTS.MD 的步骤赋予适当权限。
- 数据库连接
  - 检查 .env 中的数据库配置项（主机、端口、用户名、密码、字符集、前缀等），确保与 database.yml 的字段一致。
- 安全访问
  - 主题与上传目录的 .htaccess 会阻止对 php/html/json 等文件的直接访问；如出现异常，检查规则是否被覆盖或未生效。

章节来源
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [AGENTS.MD:748-768](file://AGENTS.MD#L748-L768)
- [database.yml:1-23](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L23)

## 结论
- ThinkCMF 的运行与部署以 PHP 8.1+ 为核心，配合 json、curl、pdo、mbstring、zip 等扩展。
- Web 服务器需启用 rewrite，Apache 的重写规则已提供；Nginx 需参照重写规则自行适配。
- 数据库主要支持 MySQL/MariaDB，版本建议 MySQL 5.7+；未在仓库中发现对 PostgreSQL 的直接声明。
- 生产环境建议使用 Composer 安装依赖并优化自动加载，严格控制目录权限与安全访问。

## 附录

### 不同部署场景下的环境配置对比表
- 开发环境
  - PHP：8.1+（建议 8.2）
  - 扩展：json、curl、pdo、mbstring、zip
  - Web：Apache 2.4+（启用 rewrite）
  - 数据库：MySQL 5.7+
  - 工具：Composer
  - 配置：.env 优先级最高
- 生产环境
  - PHP：8.1+（建议 8.2）
  - 扩展：json、curl、pdo、mbstring、zip
  - Web：Apache 2.4+（启用 rewrite）或 Nginx（需自行适配重写规则）
  - 数据库：MySQL 5.7+（MariaDB）
  - 工具：Composer（生产安装优化自动加载）
  - 配置：.env 优先级最高，data/config 次之，config 最低
  - 安全：严格控制 data/ 与 public/upload/ 权限，启用 .htaccess 访问限制

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [README.md:84-94](file://README.md#L84-L94)
- [public/.htaccess:1-14](file://public/.htaccess#L1-L14)
- [AGENTS.MD:716-777](file://AGENTS.MD#L716-L777)
- [database.yml:1-23](file://vendor/thinkcmf/cmf-install/src/install/data/database.yml#L1-L23)