# 生产环境部署

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

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

## 简介
本文件面向生产环境部署 ThinkCMF 的工程团队与运维人员，提供从准备阶段到上线后的完整实践指南。内容覆盖：预演环境测试、灰度发布与全量部署流程；部署前的环境检查、数据备份与依赖验证；部署过程中的监控与回滚策略；生产环境安全配置（数据库连接、权限与访问控制）；以及部署后的验证与维护流程（功能测试、性能优化与日志监控）。为确保可追溯性，文中所有技术细节均对应仓库中的具体文件与行号。

## 项目结构
- 入口与运行时
  - Web 入口位于 public/index.php，作为应用启动点，负责加载自动加载器并执行 HTTP 应用。
  - 路由重写通过 public/router.php 实现，避免直接访问脚本文件时绕过入口。
- 配置与环境
  - 环境变量采用 .env 方案，示例文件为 .example.env。
  - 配置优先级：.env > data/config 动态配置 > config 静态配置。
- 静态资源与主题
  - public/themes 下包含主题与模板资源，提供 Apache 2.2 与 2.4 的 .htaccess 访问控制示例。
- 依赖与安装
  - 使用 Composer 管理依赖，生产环境建议使用 --no-dev 与优化自动加载参数进行安装。
- 版本与运行环境
  - 推荐 PHP 8.2+，最低 PHP 8.1；需开启 rewrite；支持 Docker 运行。

```mermaid
graph TB
A["Web 服务器<br/>Apache/Nginx"] --> B["public/router.php<br/>路由重写"]
B --> C["public/index.php<br/>应用入口"]
C --> D["vendor/autoload.php<br/>Composer 自动加载"]
C --> E["App()->http->run()<br/>执行 HTTP 应用"]
E --> F["响应输出<br/>send() 与 end()"]
```

**图表来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-37](file://public/index.php#L27-L37)

**章节来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)

## 核心组件
- 应用入口与运行时
  - public/index.php 定义 CMF_ROOT、CMF_DATA、APP_PATH、WEB_ROOT 等路径常量，并加载 vendor/autoload.php 后执行 HTTP 应用。
- 路由与重写
  - public/router.php 在检测到真实文件时直接返回，否则将 SCRIPT_FILENAME 指向入口并包含入口文件，实现伪静态与入口统一。
- 环境与配置
  - .example.env 提供数据库与应用配置示例；.gitignore 将 .env 排除在版本控制之外，避免敏感信息泄露。
  - AGENTS.MD 明确了生产部署的环境检查、安装依赖、配置环境、权限设置与 Web 根目录指向等步骤。
- 安全与访问控制
  - public/themes/.htaccess 与 .htaccess_apache2.4 对 .html/.php/.json 等敏感后缀提供访问限制示例，建议在生产环境中启用。

**章节来源**
- [public/index.php:15-37](file://public/index.php#L15-L37)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [.example.env:1-1](file://.example.env#L1-L1)
- [.gitignore:14](file://.gitignore#L14)
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)
- [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)

## 架构总览
下图展示生产环境部署的关键节点与交互关系，涵盖环境准备、依赖安装、配置注入、权限设定、Web 根目录与路由重写、以及安全加固。

```mermaid
graph TB
subgraph "部署前准备"
P1["环境检查<br/>PHP/MySQL/rewrite"] --> P2["数据备份"]
P2 --> P3["依赖验证<br/>Composer 安装 --no-dev"]
end
subgraph "部署中"
D1["复制 .example.env 为 .env"] --> D2["修改数据库与应用配置"]
D2 --> D3["设置权限<br/>data/ 与 public/upload/"]
D3 --> D4["Web 根目录指向 public/"]
D4 --> D5["路由重写生效<br/>router.php"]
D5 --> D6["应用启动<br/>index.php"]
end
subgraph "安全加固"
S1["启用 .htaccess 访问控制<br/>themes 目录"] --> S2["最小化暴露面<br/>关闭调试与敏感文件"]
end
P3 --> D1
D6 --> S1
```

**图表来源**
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-37](file://public/index.php#L27-L37)
- [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)

## 详细组件分析

### 部署流程：预演环境测试 → 灰度发布 → 全量部署
- 预演环境测试
  - 在隔离环境复刻生产配置，执行完整的安装与初始化流程，验证数据库迁移、静态资源与路由重写。
  - 使用 --no-dev 与优化自动加载参数安装依赖，确保与生产一致。
- 灰度发布
  - 选择少量实例或子域名进行上线，观察健康检查与性能指标，逐步扩大流量。
  - 关键检查点：数据库连接可用性、静态资源加载、API 可用性、鉴权与跨域策略。
- 全量部署
  - 在灰度稳定后，按批次替换剩余实例，完成最终切换与清理。

**章节来源**
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)
- [composer.json:67-72](file://composer.json#L67-L72)

### 部署前准备：环境检查、数据备份与依赖验证
- 环境检查
  - PHP 版本与扩展：参考 README 的推荐与最低要求，确保 rewrite 已启用。
- 数据备份
  - 在部署前对数据库与关键目录（data、public/upload）进行完整备份，记录备份时间戳与校验和。
- 依赖验证
  - 使用 Composer 安装生产依赖，执行 post-autoload-dump 中的脚本以发现服务、发布资源与运行迁移。

**章节来源**
- [README.md:84-94](file://README.md#L84-L94)
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:67-72](file://composer.json#L67-L72)

### 部署过程：监控与回滚策略
- 健康检查
  - 部署后立即对站点首页、关键 API 与数据库连通性进行探测，确认响应时间与状态码。
- 性能监控
  - 关注 CPU、内存、QPS、P95 响应时间与错误率；结合 Web 服务器与应用日志定位瓶颈。
- 异常处理
  - 若出现异常，立即回滚至上一个稳定版本；回滚前确保备份可恢复且数据一致性已验证。
- 回滚步骤
  - 切换回上一版本代码与配置，恢复备份的数据与静态资源，重新执行必要的迁移与缓存清理。

**章节来源**
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)

### 生产环境安全配置
- 数据库连接
  - 在 .env 中配置 DATABASE_* 相关项，确保主机、端口、用户名、密码与字符集正确；生产环境建议启用连接池与超时控制。
- 权限设置
  - data/ 与 public/upload/ 目录需具备写权限；其他目录保持只读，避免不必要的写入。
- 访问控制
  - 启用 themes 目录的 .htaccess 访问控制，阻止直接访问敏感文件；在 Web 服务器层面限制 .env 与日志文件的外部访问。
- 调试与日志
  - 生产环境将 APP_DEBUG 设为 false；集中收集并轮转日志，避免磁盘占满。

**章节来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)
- [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)
- [.gitignore:14](file://.gitignore#L14)

### 部署后验证与维护
- 功能测试
  - 登录后台、创建/编辑内容、上传资源、调用关键 API，确保各模块正常。
- 性能优化
  - 启用 OPcache、静态资源 CDN、Gzip/HTTP/2；根据监控结果调整并发与缓存策略。
- 日志监控
  - 配置统一日志采集与告警，关注错误日志与慢查询日志，定期巡检磁盘与索引。

**章节来源**
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)

## 依赖分析
- 运行时依赖
  - PHP 版本与扩展：>= 8.1.0，必需扩展包括 json、curl、pdo、mbstring、zip。
  - ThinkCMF 核心包：cmf-app、cmf-api、cmf-install、cmf-appstore、cmf-root。
- 安装与初始化
  - 安装完成后，post-autoload-dump 脚本会触发服务发现、资源发布与数据库迁移，确保应用处于就绪状态。

```mermaid
graph LR
A["composer.json<br/>require 与 scripts"] --> B["vendor/<包>"]
B --> C["post-autoload-dump<br/>service:discover"]
B --> D["post-autoload-dump<br/>vendor:publish"]
B --> E["post-autoload-dump<br/>migrate:run"]
```

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

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

## 性能考虑
- 自动加载优化
  - 使用 --optimize-autoloader 与 --classmap-authoritative，减少文件系统扫描与类映射查找开销。
- 缓存与静态化
  - 启用 OPcache、Redis 或文件缓存；对静态资源启用 CDN 与长缓存策略。
- 数据库优化
  - 合理索引、连接池、慢查询日志与 SQL 分析；避免 N+1 查询与大事务。
- Web 层优化
  - 启用 Gzip/Deflate、HTTP/2、Keep-Alive；合理配置缓存头与 ETag。

**章节来源**
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)

## 故障排查指南
- 无法访问或 404
  - 确认 Web 根目录指向 public/，路由重写已生效；检查 public/router.php 是否被正确调用。
- 数据库连接失败
  - 检查 .env 中 DATABASE_* 配置是否正确；确认网络连通性与防火墙策略。
- 权限问题导致写入失败
  - 确认 data/ 与 public/upload/ 目录权限；检查 SELinux/AppArmor 或 Windows 权限策略。
- 调试信息泄露
  - 确保 APP_DEBUG=false；检查 .env 是否被误提交到版本控制（.gitignore 已排除）。
- 主题或模板访问异常
  - 检查 themes 目录的 .htaccess 访问控制是否启用；确认文件权限与路径大小写。

**章节来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [.example.env:1-1](file://.example.env#L1-L1)
- [.gitignore:14](file://.gitignore#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)

## 结论
生产环境部署 ThinkCMF 的关键在于“准备充分、分步验证、安全优先、可观测回退”。通过严格的预演与灰度策略、完善的监控与回滚预案、以及严谨的安全配置与权限治理，可显著降低上线风险并提升稳定性。建议将本文档作为标准作业程序（SOP），在每次发布前对照执行。

## 附录
- 环境与版本
  - 推荐：PHP 8.2+，MySQL 5.7+，开启 rewrite。
- 部署脚本建议
  - 将安装、配置、权限、回滚等步骤封装为自动化脚本，减少人为失误。
- 参考文档
  - README 与 AGENTS.MD 中的环境要求、部署步骤与配置优先级说明。

**章节来源**
- [README.md:84-94](file://README.md#L84-L94)
- [AGENTS.MD:744-777](file://AGENTS.MD#L744-L777)