🧲 缓存与队列
本页说明 SunAdmin 后端缓存和队列相关约定。缓存用于提升高频读取性能，并让配置、字典、装修页等低频变更数据可以稳定失效；队列用于处理 AI 用量记录、耗时任务和后续可扩展的异步业务。
🎯 本页目标
读完本页后，应能判断：
- 哪些数据适合缓存。
- 缓存 key 应该如何命名。
- 后台保存数据后应该如何失效缓存。
- 队列任务适合处理什么。
- AI 用量记录如何切换同步 / 异步模式。
⚙️ 缓存配置
缓存配置集中在：
text
config/sunadmin.php| 配置 | 说明 |
|---|---|
config_cache | 系统配置缓存，默认前缀 sunadmin:config，TTL 300 秒 |
dict_cache | 字典缓存，默认前缀 sunadmin:dict，TTL 300 秒 |
hot_cache | 公共配置、装修页、语言包等热点缓存 |
cache_versions | 缓存版本号 key，用于批量失效 |
site_status | 用户端站点开关缓存，TTL 60 秒 |
🧾 缓存 key 约定
推荐缓存键格式：
text
sunadmin:{module}:{type}:{biz-key}
sunadmin:{module}:{type}:v{version}:{biz-key}示例：
text
sunadmin:config:group:storage
sunadmin:dict:type:bank
sunadmin:decorate:page:v3:index命名建议：
- 用英文小写和冒号分段。
- key 中包含模块、类型和业务标识。
- 需要批量失效的热点数据优先加入版本号。
- 不要把用户敏感信息、Token、密钥直接拼进缓存 key。
♻️ 缓存失效优先级
配置、装修页、语言包这类高频读、低频写的数据，优先采用“版本号 + 实际缓存键”的失效方式。
推荐优先级：
- 版本号失效。
- 精确
forget。 - TTL 自然过期。
不要只依赖 TTL 处理配置或装修页更新，否则后台保存后前台可能继续读取旧数据。
🧩 常见缓存场景
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 系统配置 | GroupedConfigService | 按配置分组缓存，保存后清理分组缓存 |
| 数据字典 | DictService | 按 type_key 缓存，字典项变更后清理对应类型 |
| 站点状态 | site_status 缓存 | 用户端中间件高频读取，保存站点开关后要同步清理 |
| 装修页 | 版本号缓存 | 页面保存后 bump 版本，让前端重新读取 |
| 语言包 | 版本号缓存 | 语言内容修改后刷新版本 |
| 模块运行时 | 进程内缓存 | 模块安装、启用、停用、卸载、删除后自动刷新模块注册和 MCP 工具发现 |
| AI 用量 | 队列或同步写入 | 请求量较大时建议异步记录 |
📬 队列
队列适合处理“可以延后执行、不应该阻塞当前请求”的任务，例如：
- AI 用量记录。
- 大文件处理。
- 消息通知。
- 批量导入导出。
- 后台耗时统计。
- 后续业务模块的异步回调处理。
项目根 composer.json 的 dev 脚本会启动：
bash
# 开发环境监听队列任务，失败后立即暴露错误
php artisan queue:listen --tries=1 --timeout=0生产环境应根据部署方式选择 queue:work、Supervisor、systemd 或容器进程托管队列。
🤖 AI 用量异步记录
AI 用量记录可通过 config/sunadmin.php 的 async.ai_usage 开关异步化。
| 配置 | 说明 |
|---|---|
SUNADMIN_AI_USAGE_ASYNC | 是否异步记录 AI 用量 |
SUNADMIN_AI_USAGE_QUEUE_CONNECTION | 队列连接 |
SUNADMIN_AI_USAGE_QUEUE | 队列名，默认 ai |
SUNADMIN_AI_USAGE_TRIES | 尝试次数，默认 3 |
示例：
env
SUNADMIN_AI_USAGE_ASYNC=true
SUNADMIN_AI_USAGE_QUEUE_CONNECTION=redis
SUNADMIN_AI_USAGE_QUEUE=ai
SUNADMIN_AI_USAGE_TRIES=3开发环境可以同步记录，生产环境如果 AI 请求较多，建议开启异步并运行队列 worker。
🧯 排查顺序
| 问题 | 排查 |
|---|---|
| 后台保存配置后前端仍是旧值 | 是否清理配置分组缓存，是否 bump public_config 版本 |
| 字典修改后下拉选项不变 | 是否清理对应 type_key 字典缓存 |
| 站点开关不立即生效 | 是否清理 site_status 缓存 |
| 新增模块 MCP 工具不出现 | 是否已安装并启用模块；常驻进程是否重启；是否执行过模块启用命令刷新运行时缓存 |
| 队列任务不执行 | 队列 worker 是否启动，连接和队列名是否一致 |
| AI 用量没记录 | 同步/异步配置、队列 worker、ai_usages 表数据 |
| 队列重复执行 | Job 是否幂等，重试次数和异常处理是否合理 |