缓存管理

缓存管理用于清理 Redis 中的页面缓存、搜索结果缓存和足迹地理位置缓存。本节介绍后台清理入口、缓存配置和服务器端清理命令。

配置缓存

生产环境的页面缓存和搜索缓存共用 Redis。打开 site.config.ts 的 build.redis，设置 enabled、host、port 和 db，修改后重新执行构建；配置字段见 站点配置。开发环境不启用 Redis，页面按实时 SSR 返回，搜索缓存也不会写入 Redis。

TypeScriptexport const siteConfig = defineSiteConfig({
  build: {
    redis: {
      enabled: true,
      host: "127.0.0.1",
      port: 6379,
      db: 0,
    },
  },
})

页面缓存统一保存 30 分钟，覆盖首页、归档、分类、标签、文章详情、订阅、更新日志、协议、站点地图、关于、地图、友链、留言板和搜索页。文章、分类、标签、评论、友链、订阅、更新日志、旅行地点和附件等内容保存成功后，系统会按受影响的页面自动失效对应缓存，访问页面时重新生成。

搜索结果缓存需要在后台「系统设置」→「高级设置」中启用「搜索缓存」，并设置「缓存过期时间（秒）」。输入范围为 60 至 3600 秒，默认 300 秒；未配置 Redis 时，即使打开此开关也不会写入缓存。完整字段说明见 设置。

打开缓存管理

登录后台，打开「缓存管理」。页面中的清理请求需要当前登录会话和 CSRF 校验；Redis 未配置时，页面会返回「未配置 Redis 连接，无需清理」，不执行删除操作。

清空全部缓存

点击「一键清空全部缓存」，确认后会对当前配置的 Redis 数据库执行 FLUSHDB。该操作会清除页面缓存、搜索缓存、足迹缓存、图标缓存以及同一数据库中的其他缓存键，访问页面后会自动重建；不会删除 PostgreSQL 中的文章、设置等数据，会话也不由 Redis 保存。

清理自定义缓存

在「自定义缓存」区域点击「搜索关键词结果」旁的「清除」，只删除 search:* 搜索结果缓存，不影响页面 ISR 缓存。点击「足迹地理位置」旁的「清除」，会删除 custom:footprint，该缓存默认保存 1 小时，清理后访问地图的访客分布视图会重新计算。

按类别清理

在「按类别清理」区域点击对应按钮，只清理选定页面类别的 ISR 缓存。可清理文章详情、分类页、标签页、首页、归档、订阅、更新日志、协议、站点地图、关于、旅行地图、友链和留言板；清理文章详情会匹配 /content/**，分类页和标签页分别匹配 /category/**、/tag/**，其余按钮对应各自的单页路由。

按关键词清理

在「自定义关键词」中输入缓存键名的一部分，例如 sitemap、content 或 about，点击「清理」或按回车提交。系统会按键名子串匹配并删除所有符合的缓存键，适合清理页面类别按钮未覆盖的缓存；输入空值时不会执行操作。

服务器清理

无法打开后台时，可以在项目根目录执行宝塔面板清理脚本：

Bashbun run clear:redis

该脚本读取 .env 中的 BT_PANEL_URL、BT_API_KEY 和 BT_PROJECT_NAME，通过宝塔 API 清空 Redis 实例的全部 16 个数据库（0 至 15），范围大于后台「一键清空」使用的当前数据库。配置项说明见 .env，运行前确认该 Redis 实例没有其他业务数据。