# 缓存配置

<cite>
**本文引用的文件**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [.example.env](file://.example.env)
- [clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [site.html](file://public/themes/admin_default/admin/setting/site.html)
- [artDialog.js](file://public/static/js/artDialog/artDialog.js)
- [wind.js](file://public/static/js/wind.js)
- [cookie.js](file://public/static/js/cookie.js)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [vendor/thinkcmf/cmf-app/composer.json](file://vendor/thinkcmf/cmf-app/composer.json)
</cite>

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

## 简介
本指南面向 ThinkCMF 项目，系统性地讲解缓存配置与优化实践，覆盖以下主题：
- 文件缓存：缓存目录设置、权限配置、清理策略
- Redis 缓存：安装与配置、连接参数、持久化与集群
- 页面缓存：静态化生成与缓存失效机制
- 数据缓存：查询结果缓存与会话缓存配置
- 性能监控：命中率统计与内存使用分析
- 防护措施：缓存雪崩与缓存穿透的应对
- 最佳实践与常见问题

说明：当前仓库中未发现直接的 ThinkCMF 缓存配置文件或示例，但通过框架入口、站点设置界面与第三方库依赖可知，ThinkCMF 基于 ThinkPHP 8 并引入了 PSR-16/PSR-6 接口生态。因此，本文在不展示具体代码的前提下，结合现有文件与接口规范，给出可落地的配置步骤与流程图示。

## 项目结构
从入口与站点设置界面出发，可梳理出与缓存相关的关键位置：
- 入口脚本：public/index.php、public/router.php、public/api.php
- 后台设置页：public/themes/admin_default/admin/setting/site.html
- 清理缓存页：public/themes/admin_default/admin/setting/clear_cache.html
- 依赖与接口：composer.json、composer.lock 引入 PSR 缓存接口
- 前端交互：public/static/js 下的 JS 工具（如 artDialog.js、cookie.js）用于前端缓存与状态管理

```mermaid
graph TB
A["入口脚本<br/>public/index.php"] --> B["路由分发<br/>public/router.php"]
A --> C["API 入口<br/>public/api.php"]
D["站点设置页<br/>site.html"] --> E["清理缓存页<br/>clear_cache.html"]
F["Composer 依赖<br/>composer.json"] --> G["PSR 缓存接口<br/>composer.lock"]
H["前端工具<br/>artDialog.js / cookie.js"] --> I["浏览器缓存/本地存储"]
```

**图表来源**
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/themes/admin_default/admin/setting/site.html](file://public/themes/admin_default/admin/setting/site.html)
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/static/js/artDialog/artDialog.js](file://public/static/js/artDialog/artDialog.js)
- [public/static/js/cookie.js](file://public/static/js/cookie.js)

**章节来源**
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/themes/admin_default/admin/setting/site.html](file://public/themes/admin_default/admin/setting/site.html)
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

## 核心组件
- 缓存接口层：通过 PSR-16/PSR-6 接口抽象，便于切换不同后端（文件、Redis、Memcached 等）
- 文件缓存：以文件形式存储键值对，适合开发与小规模生产环境
- Redis 缓存：高性能键值存储，支持持久化、集群与高可用
- 页面缓存：基于模板渲染与静态化输出，结合过期策略与失效机制
- 数据缓存：查询结果缓存与会话缓存，提升数据库访问与用户状态管理效率
- 前端缓存：利用浏览器本地存储与 Cookie 实现轻量级缓存

**章节来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

## 架构总览
下图展示了 ThinkCMF 在请求处理链路中与缓存的交互关系：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Entry as "入口脚本<br/>public/index.php"
participant Router as "路由分发<br/>public/router.php"
participant Ctrl as "控制器/服务层"
participant Cache as "缓存适配器<br/>文件/Redis"
participant DB as "数据库"
Client->>Entry : "HTTP 请求"
Entry->>Router : "分发到路由"
Router->>Ctrl : "执行业务逻辑"
Ctrl->>Cache : "读取/写入缓存"
alt "缓存命中"
Cache-->>Ctrl : "返回缓存数据"
else "缓存未命中"
Ctrl->>DB : "查询数据库"
DB-->>Ctrl : "返回查询结果"
Ctrl->>Cache : "写入缓存"
end
Ctrl-->>Client : "响应内容"
```

**图表来源**
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

## 详细组件分析

### 文件缓存配置
- 缓存目录设置
  - 在应用配置中指定缓存目录路径，确保 Web 进程对该目录具备读写权限
  - 开发环境建议使用相对路径或临时目录，生产环境建议使用独立挂载盘并开启只读挂载策略
- 权限配置
  - 目录权限建议为 0750 或 0770，文件权限 0640 或 0660
  - 避免将缓存目录暴露在 Web 可访问路径下，必要时通过 .htaccess/.htaccess_apache2.4 限制访问
- 清理策略
  - 定期清理过期缓存：按 TTL 扫描并删除过期键
  - 按需清理：在站点设置页提供“清空缓存”入口，调用后端清理接口
  - 监控磁盘占用：设置阈值告警，超过阈值自动触发清理

```mermaid
flowchart TD
Start(["开始"]) --> SetDir["设置缓存目录"]
SetDir --> Perm["配置目录/文件权限"]
Perm --> Protect["限制 Web 访问<br/>.htaccess/.htaccess_apache2.4"]
Protect --> Plan["制定清理计划<br/>定时任务/TTL扫描"]
Plan --> Clear["执行清理动作<br/>清空缓存/删除过期项"]
Clear --> Monitor["监控磁盘占用"]
Monitor --> End(["结束"])
```

**图表来源**
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/themes/.htaccess](file://public/themes/.htaccess)

**章节来源**
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/themes/.htaccess](file://public/themes/.htaccess)

### Redis 缓存安装与配置
- 安装与部署
  - 使用官方包管理器或 Docker 部署 Redis 单机/哨兵/集群模式
  - 生产环境建议启用持久化（RDB/AOF），并配置主从复制与自动故障转移
- 连接参数
  - 主机、端口、密码、数据库索引、超时时间、连接池大小
  - 超时与重试策略：连接超时、读写超时、最大重试次数
- 持久化设置
  - RDB 快照：设定触发条件（时间窗口与变更数量）
  - AOF 追加：选择 fsync 策略（always/everysec/no）
- 集群配置
  - 分片策略：哈希槽分配、节点迁移
  - 高可用：主从复制、Sentinel 监控、自动故障转移
  - 客户端路由：根据键空间哈希选择节点

```mermaid
flowchart TD
A["部署 Redis"] --> B["配置持久化<br/>RDB/AOF"]
B --> C["网络与认证<br/>bind/password"]
C --> D["连接参数<br/>host/port/db/pool"]
D --> E["集群/哨兵<br/>主从/故障转移"]
E --> F["客户端接入<br/>键空间路由"]
```

**图表来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

**章节来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)

### 页面缓存实现
- 静态化生成
  - 将高频访问的页面渲染结果写入静态文件（.html），并设置合理的缓存头
  - 结合 CDN 加速静态资源与页面缓存
- 缓存失效机制
  - 内容更新时主动删除或刷新对应静态文件
  - 设置短 TTL 并配合预热策略，避免冷启动抖动
  - 对动态区块采用片段缓存（Fragment Cache）

```mermaid
sequenceDiagram
participant Admin as "管理员"
participant Site as "站点设置页<br/>site.html"
participant Ctrl as "控制器"
participant FS as "文件系统"
participant CDN as "CDN"
Admin->>Site : "保存站点设置"
Site->>Ctrl : "提交表单"
Ctrl->>FS : "生成/更新静态页面"
FS-->>CDN : "推送静态文件"
CDN-->>Admin : "页面生效"
```

**图表来源**
- [public/themes/admin_default/admin/setting/site.html](file://public/themes/admin_default/admin/setting/site.html)

**章节来源**
- [public/themes/admin_default/admin/setting/site.html](file://public/themes/admin_default/admin/setting/site.html)

### 数据缓存优化
- 查询结果缓存
  - 对稳定查询（如分类树、配置项）设置长 TTL；对热点数据设置短 TTL 并异步刷新
  - 使用带版本号的键前缀，实现灰度更新与回滚
- 会话缓存配置
  - 将 Session 存储迁移到 Redis，开启过期与淘汰策略
  - 配置会话锁与并发控制，避免并发写入冲突
- 前端缓存与本地存储
  - 利用 artDialog.js 的本地缓存能力与 cookie.js 的 Cookie 管理，减少重复请求
  - 注意跨域与安全属性（SameSite、Secure、HttpOnly）

```mermaid
classDiagram
class CacheAdapter {
+get(key)
+set(key, value, ttl)
+delete(key)
+clear()
}
class FileCache {
+dir
+permission
+cleanup()
}
class RedisCache {
+host
+port
+password
+db
+persist()
+cluster()
}
class SessionStore {
+storage
+expire
+lock()
}
CacheAdapter <|-- FileCache
CacheAdapter <|-- RedisCache
SessionStore --> RedisCache : "推荐使用"
```

**图表来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/static/js/artDialog/artDialog.js](file://public/static/js/artDialog/artDialog.js)
- [public/static/js/cookie.js](file://public/static/js/cookie.js)

**章节来源**
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/static/js/artDialog/artDialog.js](file://public/static/js/artDialog/artDialog.js)
- [public/static/js/cookie.js](file://public/static/js/cookie.js)

## 依赖分析
- Composer 依赖
  - 项目通过 PSR-16/PSR-6 接口抽象缓存能力，便于替换后端实现
  - thinkcmf/cmf-app 作为应用包，负责业务模块加载与入口组织
- 入口与路由
  - public/index.php、public/router.php、public/api.php 组成请求入口，缓存策略应贯穿其中间件与控制器层

```mermaid
graph LR
CMFApp["thinkcmf/cmf-app"] --> PSR["PSR 缓存接口"]
PSR --> FileCache["文件缓存实现"]
PSR --> RedisCache["Redis 缓存实现"]
Entry["入口脚本"] --> PSR
```

**图表来源**
- [vendor/thinkcmf/cmf-app/composer.json](file://vendor/thinkcmf/cmf-app/composer.json)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)

**章节来源**
- [vendor/thinkcmf/cmf-app/composer.json](file://vendor/thinkcmf/cmf-app/composer.json)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)

## 性能考虑
- 命中率统计
  - 通过中间件埋点记录缓存命中/未命中次数，计算命中率并生成报表
  - 对慢查询与高延迟键进行标记与报警
- 内存使用分析
  - 监控 Redis/Memcached 的内存使用率、key 数量与碎片率
  - 定期分析大 key 与过期 key，优化数据结构与 TTL
- 并发与锁
  - 对热点键设置分布式锁，避免缓存击穿
  - 控制批量写入频率，避免缓存雪崩

[本节为通用指导，无需列出章节来源]

## 故障排查指南
- 缓存不可用
  - 检查缓存目录权限与磁盘空间；确认 Redis 连接参数正确
  - 查看入口脚本日志，定位中间件与控制器中的异常
- 缓存不一致
  - 核对键命名规则与版本号前缀；检查更新流程是否同步清理旧键
- 页面缓存未生效
  - 确认静态化生成流程已执行；检查 CDN 缓存头与刷新策略
- 前端缓存异常
  - 检查 Cookie 安全属性与 SameSite 设置；确认 artDialog 本地缓存未被浏览器清理

**章节来源**
- [public/index.php](file://public/index.php)
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [public/static/js/cookie.js](file://public/static/js/cookie.js)
- [public/static/js/artDialog/artDialog.js](file://public/static/js/artDialog/artDialog.js)

## 结论
- ThinkCMF 通过 PSR 缓存接口实现了灵活的后端切换能力，文件缓存适合开发与小规模场景，Redis 更适合生产高并发需求
- 页面缓存与数据缓存应结合静态化与 TTL 策略，配合 CDN 与会话缓存提升整体性能
- 建立完善的监控与告警体系，持续优化命中率与内存使用
- 通过防护措施降低缓存雪崩与穿透风险，保障系统稳定性

[本节为总结性内容，无需列出章节来源]

## 附录

### 缓存配置最佳实践清单
- 文件缓存
  - 使用独立目录并限制 Web 访问
  - 设置合理权限与定期清理策略
- Redis
  - 启用持久化与主从复制
  - 合理设置超时与重试策略
  - 集群模式下注意键空间路由与一致性
- 页面缓存
  - 静态化与 CDN 结合
  - 更新即删与预热策略
- 数据缓存
  - 热点数据短 TTL，稳定数据长 TTL
  - 会话缓存迁移至 Redis 并开启过期
- 监控与告警
  - 命中率、内存使用、慢查询与大 key 监控
  - 自动化清理与容量预警

[本节为通用指导，无需列出章节来源]