# 生产环境部署

<cite>
**本文引用的文件**   
- [README.md](file://README.md)
- [AGENTS.MD](file://AGENTS.MD)
- [.example.env](file://.example.env)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [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)
- [public/themes/admin_default/admin/setting/site.html](file://public/themes/admin_default/admin/setting/site.html)
</cite>

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

## 简介
本指南面向 ThinkCMF 在生产环境的部署与运维，覆盖服务器准备、应用部署、负载均衡、监控告警、日志管理、备份与灾备、性能优化以及部署后的验证与维护。ThinkCMF 基于 ThinkPHP 8.x，采用多应用与插件体系，入口统一指向 public 目录并通过重写实现 URL 美化；API 通过独立入口 public/api.php 提供 RESTful 接口，并支持 Swagger 文档插件。

## 项目结构
- 入口与根目录
  - 入口文件：public/index.php、public/api.php
  - URL 重写：public/.htaccess
  - 路由转发：public/router.php
- 配置与环境
  - 环境变量示例：.example.env
  - Composer 依赖与自动加载：composer.json
- 静态资源与上传
  - 静态资源：public/static、public/themes、public/plugins
  - 上传目录：public/upload（公开）、data/upload（私有）
- 安全与访问控制
  - 目录访问控制：public/themes/.htaccess、public/themes/.htaccess_apache2.4、public/upload/.htaccess

```mermaid
graph TB
A["Web 服务器<br/>Nginx/Apache"] --> B["public/.htaccess<br/>URL 重写"]
B --> C["public/index.php<br/>前台入口"]
B --> D["public/api.php<br/>API 入口"]
C --> E["vendor/autoload.php<br/>Composer 自动加载"]
D --> E
E --> F["应用运行时<br/>data/runtime"]
F --> G["日志与缓存"]
```

**图表来源**
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)

**章节来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [composer.json:1-77](file://composer.json#L1-L77)

## 核心组件
- 入口与重写
  - public/index.php 与 public/api.php 分别作为前台与 API 的应用入口，统一通过 vendor/autoload.php 加载依赖。
  - public/.htaccess 实现 URL 重写，将 /api/* 路由至 api.php，其余路由至 index.php。
- 配置与环境
  - .example.env 提供环境变量示例（调试、时区、数据库等），生产环境需复制为 .env 并关闭调试。
  - composer.json 定义 PHP 版本要求、必需扩展、自动加载与安装后脚本。
- 目录权限与安全
  - data/ 与 public/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/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [.example.env:1-1](file://.example.env#L1-L1)
- [composer.json:1-77](file://composer.json#L1-L77)

## 架构总览
ThinkCMF 生产部署建议采用“反向代理 + 应用服务器集群”的架构，Nginx 作为入口反向代理，后端多实例 PHP-FPM 提供应用服务，数据库与缓存独立部署，静态资源可接入 CDN。

```mermaid
graph TB
subgraph "客户端"
U["浏览器/移动客户端"]
end
subgraph "边缘层"
RP["Nginx 反向代理"]
end
subgraph "应用层"
S1["PHP-FPM 实例 1"]
S2["PHP-FPM 实例 2"]
S3["PHP-FPM 实例 3"]
end
subgraph "数据与存储"
DB["MySQL/MariaDB"]
FS["对象存储/CDN"]
end
U --> RP
RP --> S1
RP --> S2
RP --> S3
S1 --> DB
S2 --> DB
S3 --> DB
S1 --> FS
S2 --> FS
S3 --> FS
```

[本图为概念性架构示意，不直接映射具体源文件，故无图表来源]

## 详细组件分析

### 服务器准备与系统更新
- 系统与内核
  - 使用稳定 Linux 发行版，保持内核与系统软件包更新。
  - 关闭不必要的服务与防火墙开放策略，仅暴露 Web 与数据库端口。
- 安全补丁
  - 定期执行安全更新，关注 PHP、Nginx/Apache、MySQL/MariaDB 的安全公告。
  - 配置 fail2ban 或同类入侵防护工具，限制暴力破解尝试。
- 性能调优
  - 调整内核参数（如文件句柄、网络缓冲）以适配高并发场景。
  - 启用 gzip/HTTP/2，合理设置连接超时与 keepalive。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

### 应用部署流程
- 环境检查
  - PHP 版本与扩展：参考 AGENTS.MD 的运行环境要求（PHP >= 8.1，必需扩展：ext-json、ext-curl、ext-pdo、ext-mbstring、ext-zip）。
  - 数据库：MySQL 5.7+ 或 MariaDB 10.2+，字符集 utf8mb4，存储引擎 InnoDB。
- 依赖安装
  - 生产环境使用 composer install --no-dev --optimize-autoloader 安装依赖。
  - 安装后自动执行：service:discover、vendor:publish、migrate:run。
- 配置文件设置
  - 复制 .example.env 为 .env，修改数据库配置与时区，设置 APP_DEBUG=false。
  - 动态配置优先级：.env > data/config/ > config/（静态配置）。
- 目录权限
  - 设置 data/ 与 public/upload/ 可写，确保运行时缓存与上传文件可写。
- Web 服务器配置
  - 将 Web 根目录指向 public/，确保 .htaccess 生效，开启 rewrite。
  - API 访问通过 /api/* 路由至 public/api.php。

```mermaid
flowchart TD
Start(["开始"]) --> CheckEnv["检查 PHP 与扩展"]
CheckEnv --> InstallDeps["composer install --no-dev<br/>优化自动加载"]
InstallDeps --> CopyEnv["复制 .example.env 为 .env"]
CopyEnv --> SetDB["填写数据库配置<br/>设置 APP_DEBUG=false"]
SetDB --> FixPerms["设置 data/ 与 public/upload/ 可写"]
FixPerms --> WebRoot["配置 Web 根目录为 public/"]
WebRoot --> Done(["完成"])
```

**图表来源**
- [AGENTS.MD:32-51](file://AGENTS.MD#L32-L51)
- [AGENTS.MD:744-776](file://AGENTS.MD#L744-L776)
- [composer.json:67-76](file://composer.json#L67-L76)
- [.example.env:1-1](file://.example.env#L1-L1)

**章节来源**
- [AGENTS.MD:32-51](file://AGENTS.MD#L32-L51)
- [AGENTS.MD:744-776](file://AGENTS.MD#L744-L776)
- [composer.json:67-76](file://composer.json#L67-L76)
- [.example.env:1-1](file://.example.env#L1-L1)

### 负载均衡配置（Nginx 反向代理与应用集群）
- Nginx 反向代理
  - 将 /api/* 路由至 public/api.php，其余静态与动态请求交由 public/index.php 处理。
  - 启用 gzip/HTTP/2，设置合理的超时与缓冲。
- 应用服务器集群
  - 使用多个 PHP-FPM 实例（至少 2 个以上），结合健康检查与自动重启策略。
  - 使用 Keepalived 或 LVS/Haproxy 实现高可用与故障切换。
- 静态资源与缓存
  - 静态资源（public/static、public/themes）可由 Nginx 直接提供或接入 CDN。
  - 启用 OPcache、Redis/内存缓存，减少数据库压力。

```mermaid
sequenceDiagram
participant C as "客户端"
participant N as "Nginx 反向代理"
participant P as "PHP-FPM 实例"
participant DB as "MySQL"
C->>N : 请求 /api/...
N->>P : 反向代理到 public/api.php
P->>DB : 查询/写入
DB-->>P : 返回结果
P-->>N : 响应
N-->>C : 返回响应
C->>N : 请求 /
N->>P : 反向代理到 public/index.php
P->>DB : 查询/写入
DB-->>P : 返回结果
P-->>N : 响应
N-->>C : 返回响应
```

[本图为概念性流程示意，不直接映射具体源文件，故无图表来源]

**章节来源**
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/index.php:1-37](file://public/index.php#L1-L37)

### 监控与告警
- 系统监控
  - CPU、内存、磁盘、网络 I/O、连接数、文件句柄等指标采集与阈值告警。
- 应用监控
  - PHP-FPM 进程数、队列长度、慢请求统计、错误日志聚合。
  - Nginx 请求速率、响应时间、错误率、上游失败率。
- 业务监控
  - 关键 API 响应时间与成功率、数据库查询慢 SQL、业务关键事件埋点。
- 告警渠道
  - 邮件、短信、IM（如钉钉/企业微信）、Webhook。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

### 日志管理与分析
- 访问日志
  - Nginx 访问日志记录请求路径、状态码、响应时间、客户端 IP、User-Agent。
- 错误日志
  - Nginx 错误日志、PHP-FPM 错误日志、应用运行时日志（data/runtime）。
- 审计日志
  - 后台登录、关键操作、API 访问鉴权与异常行为记录。
- 收集与分析
  - 使用 ELK/EFK 或 Loki/Grafana/Thanos 等方案集中收集与检索。
  - 对慢日志与错误日志建立规则化告警。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

### 备份与灾难恢复
- 数据备份
  - 全量/增量数据库备份策略，定期校验与异地容灾。
- 配置备份
  - .env、Nginx/Apache 配置、PHP-FPM 配置、ThinkCMF 动态配置（data/config）。
- 上传与静态资源
  - public/upload 与 CDN 静态资源的版本化与快照备份。
- 恢复流程
  - 制定 RTO/RPO 指标，演练恢复步骤，验证数据一致性与业务可用性。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

### 性能优化建议
- PHP-FPM 调优
  - pm、pm.max_children、pm.start_servers、pm.min_spare_servers、pm.max_spare_servers、pm.process_idle_timeout 等参数按并发与内存评估调整。
  - 启用 OPcache、APCu，合理设置 opcode 缓存大小。
- 数据库优化
  - 合理索引、慢查询日志、读写分离、连接池、查询缓存（如适用）。
- CDN 与静态资源
  - 将静态资源（CSS/JS/图片）接入 CDN，开启压缩与缓存头。
- 应用侧优化
  - 合理使用缓存（Redis/Memcached）、异步任务队列、数据库连接复用。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

### 部署后的验证与维护
- 功能验证
  - 前台页面、后台登录、API 接口、Swagger 文档、文件上传、CDN 静态资源。
- 性能验证
  - 压测工具模拟峰值流量，观察响应时间、错误率、资源占用。
- 安全验证
  - 关闭调试、删除演示代码、强化数据库与文件权限、定期扫描漏洞。
- 维护操作
  - 定期备份、依赖更新、安全补丁、日志轮转与归档。

[本节为通用实践说明，不直接分析具体文件，故无章节来源]

## 依赖分析
- 运行时依赖
  - ThinkPHP 框架、ThinkORM、ThinkCMF 核心包、数据库迁移工具、验证码、邮件组件等。
- 自动加载与脚本
  - PSR-4 自动加载映射 app/、api/、plugins/、themes/。
  - 安装后自动执行服务发现、资源发布与数据库迁移。

```mermaid
graph LR
CJ["composer.json"] --> V["vendor/"]
V --> A["PSR-4 自动加载<br/>app/, api/, plugins/, themes/"]
CJ --> S["安装后脚本<br/>service:discover / vendor:publish / migrate:run"]
```

**图表来源**
- [composer.json:46-76](file://composer.json#L46-L76)

**章节来源**
- [composer.json:1-77](file://composer.json#L1-L77)

## 性能考虑
- 入口与重写
  - public/.htaccess 将 /api/* 与常规请求分别路由至 api.php 与 index.php，减少不必要的入口复杂度。
- 目录权限与安全
  - 主题与上传目录的 .htaccess 限制敏感文件直接访问，降低安全风险与资源泄露可能。
- CDN 与静态资源
  - 后台设置项支持 CDN 根路径配置，便于将静态资源迁移至 CDN，减轻服务器压力。

**章节来源**
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [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)
- [public/themes/admin_default/admin/setting/site.html:192-210](file://public/themes/admin_default/admin/setting/site.html#L192-L210)

## 故障排查指南
- 404/重写问题
  - 确认 Web 根目录指向 public/，且 .htaccess 生效；检查 RewriteEngine 与 RewriteRule。
- API 访问异常
  - 确认 /api/* 路由已转发至 public/api.php；检查命名空间与路由配置。
- 权限与上传失败
  - 检查 data/ 与 public/upload/ 可写；确认上传目录访问控制规则未阻断合法请求。
- 环境变量与数据库
  - 确认 .env 已正确复制并设置 APP_DEBUG=false；数据库连接参数与字符集一致。

**章节来源**
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [.example.env:1-1](file://.example.env#L1-L1)

## 结论
ThinkCMF 生产部署的关键在于：严格的服务器准备与安全加固、清晰的应用入口与重写规则、完善的负载均衡与缓存策略、健全的监控告警与日志分析、可靠的备份与灾备流程，以及持续的性能优化与维护。遵循本指南可显著提升系统的稳定性、安全性与可维护性。

## 附录
- 环境与依赖参考
  - 运行环境与推荐版本、必需扩展、数据库要求
  - Composer 依赖与自动加载、安装后脚本
- 配置参考
  - .env 环境变量示例与优先级
  - Web 服务器重写规则与入口文件

**章节来源**
- [AGENTS.MD:32-51](file://AGENTS.MD#L32-L51)
- [AGENTS.MD:716-741](file://AGENTS.MD#L716-L741)
- [README.md:84-94](file://README.md#L84-L94)
- [composer.json:1-77](file://composer.json#L1-L77)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)