尧图网站建设 
Laravel 缓存最佳实践实战结合 Coolify 源码深入理解 Cache API 的七个关键用法【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify缓存是 Laravel 应用在数据规模、并发与请求量增长后最先需要被认真设计的一层。本指南以 Coolify 仓库中 .cursor/skills/laravel-best-practices/rules/caching.md 这份规则文档为骨架逐一拆解remember()、flexible()、memo()、缓存标签、add()、once()与 failover 存储等七个关键用法并对照 config/cache.php 与 app 目录下的真实实现、测试用例讲清每个 API 的适用场景、底层语义与失效策略。读完你将掌握一套何时用哪个缓存 API、如何做原子写、如何按组失效、如何在生产环境做故障切换的完整判断体系并能直接套用于任何 Laravel 12 项目。一、先从一份规则文档说起缓存最佳实践的整体框架这份caching.md来自仓库内 laravel-best-practices 技能包它与 Eloquent、队列、安全、架构等 20 份规则一起构成 Coolify 在 Laravel 12 开发中的编码准则。规则文档强调一个先决原则——一致性优先在引入新写法之前先看代码库已经采用的模式并跟随它不一致比次优模式更有害。把该技能总览中的缓存要点整理成一张决策地图也是全文的主线需求场景推荐 API一句话要点读多写少、可容忍短暂过期Cache::remember()缓存旁路cache-aside消除手工 get/put 样板高流量键、过期瞬间不能有人卡慢Cache::flexible()stale-while-revalidate过期后先给旧值再后台刷新同请求内多次读同一键Cache::memo()一个请求只打一次 Redis跨请求仍共享缓存一次函数结果只算一次进程内once()纯内存 memo完全不触碰缓存存储幂等去重、一次性标记Cache::add()键不存在才写入原子无竞态临界区互斥部署、SSH 复用等Cache::lock()/block()原子锁可阻塞等待并支持 TTL 释放按组批量失效Cache::tags()仅 redis/memcached/dynamodb 支持生产高可用failover 存储Redis 宕机自动降级到次级存储下文逐条展开并随时回到 Coolify 源码确认这些 API 在真实系统里是怎么被使用的。二、缓存地基Coolify 的默认存储与 key 前缀先看 Coolify 的缓存配置文件 config/cache.phpdefault env(CACHE_DRIVER, redis),默认走redis连接且该 store 声明了redis [ driver redis, connection cache, // 使用 redis.php 中名为 cache 的连接 lock_connection default, // 原子锁使用 default 连接避免与数据互相挤占 ],值得注意的细节是lock_connectionCoolify 把缓存数据与缓存锁拆分到不同 Redis 连接上让Cache::lock()不干扰数据读写。该配置文件同时预置了apc、array、database、file、memcached、dynamodb、octane、null等全部官方 store这意味着文档中提到的 failover、tags 等能力边界都可以回到这份配置逐项验证。key 前缀通过CACHE_PREFIX环境变量控制默认取APP_NAME的 slug 拼_cache_prefix env(CACHE_PREFIX, Str::slug(env(APP_NAME, laravel), _)._cache_),这与规则文档中为 key 设计命名空间、避免跨应用冲突的最佳实践直接呼应——Coolify 的缓存 key 普遍采用领域:实体:id:属性的冒号分层如user:{$userId}:team:{$teamId}配合前缀避免与其他共用 Redis 的应用发生碰撞。依赖侧composer.json 声明了laravel/framework: ^12.65.0与laravel/horizon: ^5.48.2PHP 要求^8.4说明下文涉及的flexible()、memo()、once()等新版 API 均处于可用版本区间。三、Cache::remember()用缓存旁路替代手工 Get/Put这是最基础的缓存写法。规则文档明确指出手工get后判空再put是反模式// 错误样板代码多、易漏分支、可读性差 $val Cache::get(stats); if (! $val) { $val $this-computeStats(); Cache::put(stats, $val, 60); }// 正确声明式缓存旁路 $val Cache::remember(stats, 60, fn () $this-computeStats());remember()把查询 → 缺失时计算并写回 → 带 TTL三件事封装成一个原子外观。第二个参数既可以是秒数也可以是DateTimeInterface例如now()-addMinutes(10)需要永不过期时用rememberForever()并用事件/业务动作显式失效。实战证据一TrustHosts 中的负缓存哨兵Coolify 的 app/Http/Middleware/TrustHosts.php 在hosts()中缓存实例 FQDN避免每个请求都查询一次instance_settings表$fqdnHost Cache::remember(instance_settings_fqdn_host, 300, function () { try { $settings InstanceSettings::get(); if ($settings $settings-fqdn) { $url Url::fromString($settings-fqdn); $host $url-getHost(); return $host ?: ; } } catch (\Exception $e) { // 安装期间表尚未建立返回空字符串使其也能被缓存 } return ; });这里的两个工程细节值得学习负结果也要缓存——查询失败/为空时返回哨兵值而不是让 closure 抛错避免表不存在就每请求重试一次的缓存击穿失效挂在模型事件上——app/Models/InstanceSettings.php 的updated钩子监听fqdn是否变化变化即Cache::forget(instance_settings_fqdn_host)实现修改即失效、最迟 300 秒兜底收敛的双保险。实战证据二用户当前团队的 1 小时缓存app/Models/User.php 的currentTeam()是 remember 的另一个典型以user:{id}:team:{teamId}为键缓存团队解析结果 3600 秒而在切换团队、删除团队等动作点显式Cache::forget见同文件第 367 行与 app/Actions/Team/DeleteTeam.php。这种集中写入、业务点显式失效的模式在 Coolify 中随处可见——app/Services/ChangelogService.php 对 changelog 计数用remember包裹远程请求并在已读/标记场景多处forgetapp/Livewire/GlobalSearch.php 以团队为单位remember300 秒全局搜索索引删除资源时按getCacheKey($teamId)精准失效。需要强调的是remember()的缺失时计算在多进程并发下并非原子——同一时刻多个请求都可能命中缺失分支重复计算。解决并发重建要靠下一节讲到的flexible()或配合Cache::lock()做 single-flight。四、Cache::flexible()为高流量键引入 Stale-While-Revalidate高流量键如全站热榜、公共统计用普通remember()会有一个隐蔽缺陷TTL 到期的瞬间所有并发请求同时看到缓存缺失其中总有一个用户必须等待重新计算——这就是每次过期都有一个倒霉用户卡顿的来源。规则文档给出的对照// 不理想过期瞬间可能出现明显延迟尖峰 Cache::remember(users, 300, fn () User::all()); // 推荐fresh 5 分钟过期后 10 分钟内先提供旧值同时后台 defer 刷新 Cache::flexible(users, [300, 600], fn () User::all());flexible()接收一个[freshTTL, staleTTL]区间数组作为第二个参数距上次写入未超过freshTTL300 秒→ 直接返回新鲜数据超过freshTTL但未超过staleTTL600 秒→立刻把旧值返回给当前请求保证无卡顿同时注册一个defer()延迟闭包在响应结束后的后台进程里重新计算并写回超过staleTTL→ 视为彻底过期同步重建。这一语义特别适合 Coolify 中读放大型的数据。以 app/Services/ChangelogService.php 拉取远端 changelog、或 config 加载的实例级配置这类低频变更、高频读取数据为例改用flexible()能直接把最坏情况的响应时间从重新计算耗时摊平为一次缓存读取耗时。底层关键点是 stale 窗口内的刷新由 defer 异步完成因此要求队列/响应生命周期支持defer()Laravel 11 的Illuminate\Foundation\DeferCoolify 基于 Laravel 12 完全满足该前提。五、请求内的重复缓存命中Cache::memo()vsonce()规则文档区分了两个防重复计算工具它们的层级完全不同// Cache::memo()一个请求内只打一次缓存存储Redis跨请求依然共享缓存 Cache::memo()-get(settings); // 同请求内第 2..5 次调用都命中内存不再产生 Redis 往返 // once()完全不触碰缓存存储纯进程内 memo public function roles(): Collection { return once(fn () $this-loadRoles()); }选择依据如果你只关心同一个请求内被多个服务重复调用的热点方法Cache::memo()会把解析后的值保存在请求级内存中5 次调用只产生 1 次 Redis 往返但数据仍是来自缓存存储的。而once()更轻——它根本不检查 Redis只保证闭包结果在对象/请求生命周期内只执行一次代价是该值无法跨请求共享。Coolify 中once()的大规模应用once()在 Coolify 模型层几乎是标配。最典型的是 app/Models/InstanceSettings.php 的单例读取public static function get() { return once(fn () InstanceSettings::findOrFail(0)); }InstanceSettings是典型的系统里只有一行的配置单例任何地方调用InstanceSettings::get()都应得到同一实例用once()包装后同一请求内无论被 app/Http/Middleware/TrustHosts.php、Livewire 组件还是 Job 调用多少次都只落一次查询。同类写法还出现在 app/Models/Server.php、app/Models/Project.php、app/Models/Service.php、app/Models/Application.php 以及全部 standalone 数据库模型中。更关键的是它的失效配套——InstanceSettings在booted()中监听模型的created与updated事件并执行Once::flush()app/Models/InstanceSettings.php一次性清空全部once()内存缓存确保配置被修改后新请求拿到的是新值。这也是使用once()时必须养成的习惯凡是 memo就必须有明确的刷新/失效时机否则会引入难以排查的幽灵旧值。六、Cache::add()原子条件写天然防重复当你需要的不是锁住一段代码而是确保某个动作全局只执行一次Cache::add()是最轻量的选择。它只在 key 不存在时写入检查与写入在存储端原子完成不存在手工先 has 后 put的竞态窗口// 错误check-then-act 存在竞态 if (! Cache::has(lock)) { Cache::put(lock, true, 10); } // 正确单条原子指令 Cache::add(lock, true, 10);实战证据备份保留清理的 30 分钟去重闸门app/Jobs/CleanupInstanceStuffsJob.php 用它实现备份保留期强制清理任务的全局互斥if (! Cache::add(backup-retention-enforcement, true, 1800)) { // 已有实例正在执行直接跳过本次 return; } // ...执行清理逻辑... Cache::forget(backup-retention-enforcement); // 提前结束时手动释放TTL1800 秒意味着即便清理进程异常退出forget未被执行闸门也会在 30 分钟后自动失效不会把任务永久锁死——这正是原子标记 自动过期兜底的教科书组合。类似的幂等场景还包括 app/Jobs/ScheduledJobManager.php 用Cache::get/put做调度去重$dedupKey并以心跳键scheduled-job-manager:heartbeatTTL 300 秒对外暴露调度器存活状态供 app/Livewire/Server/DockerCleanup.php 这类 UI 组件探测。七、Cache::lock()比 add 更强的临界区控制当防重复之外还需要串行化一段有副作用的代码时规则文档推荐使用Cache::lock()技能总览中还补充了lockForUpdate()。原子锁的核心价值是拿锁与执行之间即使进程崩溃TTL 也能保证锁最终自动释放。实战证据一SSH 多路复用连接的并发防护Coolify 是重度 SSH 工具其 app/Helpers/SshMultiplexingHelper.php 在建立/刷新服务器 SSH 多路复用连接前加锁防止并发任务同时创建 master connectionreturn Cache::lock( self::connectionLockKey($server), // 每台服务器一把锁 config(constants.ssh.mux_lock_ttl) // 锁的持有上限 )-block(config(constants.ssh.mux_lock_timeout), function () use ($server) { if (self::connectionIsReusable($server)) { return true; } if (self::masterConnectionExists($server)) { return self::refreshMultiplexedConnection($server); } return self::establishNewMultiplexedConnection($server); });-block(seconds, closure)表示最多阻塞等待 N 秒拿锁拿不到就抛LockTimeoutException比直接拿锁失败更适用于这件事迟早要轮到本进程做的场景。仓库测试 tests/Feature/SshMultiplexingLockTest.php 明确覆盖了并发拿锁的行为。实战证据二令牌刷新的分布式互斥与缓存去重bootstrap/helpers/gitlab.php 用Cache::lock(gitlab_token_refresh_{$source-id}, 20)保证同一 GitLab 源的 token 刷新只有一个进程执行app/Http/Controllers/Api/SentinelController.php 在 Sentinel 指标推送链路中Cache::lock($lockKey, 10)-block(5, ...)拿到锁后再查哈希与强制推送标志做缓存去重其行为有专门测试 tests/Feature/SentinelPushDeduplicationTest.php 守护app/Console/Commands/AdminDeleteUser.php 对用户删除这类不可逆操作持有 600 秒长锁。锁的命名与 TTL 设计同样有讲究——app/Actions/Shared/DeleteScheduledVolumeBackup.php 以VolumeBackupJob::lockKey($backup-id)为键、$backup-timeout 300为 TTL即任务超时上限再加 300 秒余量保证锁生命周期一定盖过任务执行时长。这也呼应技能总览中retry_after必须大于 jobtimeout的队列准则——锁与任务的 TTL 边界始终是同一类心智模型。八、缓存失效的艺术Tags 组失效 vs 逐键 Forget规则文档指出没有标签时要让一组相关缓存全部失效你必须逐个记住并删除每个 key。Cache::tags()允许你给条目打标签并原子冲刷整组Cache::tags([user-1])-flush();其硬性约束同样写进了规则只有redis、memcached、dynamodb驱动支持 tagsfile与database驱动不支持。以 config/cache.php 中 Coolify 默认的redisstore 为前提tags 完全可用但若你在 CI 或本地退回file/database存储任何Cache::tags()调用都会直接抛异常——这是把 tags 写入共享代码前必须评估的兼容性陷阱。回到 Coolify 的真实代码你会发现它刻意选择了业务事件 逐键 forget而非 tags。证据链如下删除团队时逐键清理该用户的会话缓存app/Actions/Team/DeleteTeam.phpCache::forget(user:{$user-id}:team:{$team-id})同文件第 94 行还清理team:{memberId}团队成员变更时同步失效 app/Livewire/Team/Member.php 中两个相关键FQDN 变更时只失效instance_settings_fqdn_host一个键InstanceSettingschangelog 已读计数变更时按用户逐键forgetChangelogService。这正是规则文档Consistency First的体现Coolify 的缓存键基本都是实体:id型且数量有限失效点分散在明确的事件/动作中逐键 forget 的显式性反而让每条缓存的生命周期可审计只有当你遇到同一请求批量加载几十个 key、希望一次 flush 全部相关条目且能保证存储驱动为 Redis 时tags 才是更优解。九、生产环境的高可用failover 缓存存储规则文档最后一条是关于可用性的如果 Redis 宕机应用应能自动降级到次级存储而不是雪崩。方法是在缓存配置中声明一个failover驱动 storefailover [ driver failover, stores [redis, database], ],随后把默认存储切换为它CACHE_DRIVERfailover。其工作方式为主存储redis发生连接级故障时框架自动把读写路由到备选存储database期间不抛出破坏用户体验的异常主存储恢复后回归。两个值得注意的边界failover 针对的是存储不可用而非key 不存在——它不做跨存储的数据迁移主备之间同一 key 的 TTL、序列化格式需要自洽在 config/cache.php 中databasestore 依赖cache数据表因此启用[redis, database]前需先执行php artisan cache:table迁移filestore 也可以作为备选但要注意多实例部署时的一致性。Coolify 当前默认直接用 redisCACHE_DRIVER缺省即 redis并依赖 Redis 支撑 config/queue.php 背后的 Horizon 队列与锁。若你的部署场景要求Redis 单点故障也能继续服务读请求就可以在配置中叠加上述 failover store让缓存层具备与队列层不同的可用性等级。十、选型总览与落地清单回到 caching.md 全文可以把整篇方法收敛为四句话读路径默认Cache::remember()高流量键换flexible([fresh, stale])消除过期尖峰防重复区分层级同请求内反复调用用Cache::memo()纯计算不落存储用once()并记得在数据变更点flush防并发按强度递进只求全局一次用Cache::add()需要串行执行临界区用Cache::lock(...)-block(...)锁 TTL 必须大于任务最长执行时间失效策略跟随业务key 少、事件明确就逐键forgetCoolify 的现状key 成组、需要原子冲刷且驱动为 Redis 就用Cache::tags()生产环境把默认存储包一层 failover。落地时可对照源码复核每条存储与驱动配置见 config/cache.php锁的工程化用法见 app/Helpers/SshMultiplexingHelper.php 与 app/Http/Controllers/Api/SentinelController.phponce()与事件刷新的配套见 app/Models/InstanceSettings.php缓存行为测试可参考 tests/Feature/SshMultiplexingLockTest.php、tests/Feature/SentinelPushDeduplicationTest.php 与 tests/Feature/VolumeBackupTest.php。把读快、防重、防并发、能失效、可降级这五件事做对缓存层就能从压垮数据库前的最后一根稻草变成你系统里最廉价也最可靠的一层加速器。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Laravel 缓存最佳实践实战：结合 Coolify 源码深入理解 Cache API 的七个关键用法
Laravel 缓存最佳实践实战结合 Coolify 源码深入理解 Cache API 的七个关键用法【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify缓存是 Laravel 应用在数据规模、并发与请求量增长后最先需要被认真设计的一层。本指南以 Coolify 仓库中 .cursor/skills/laravel-best-practices/rules/caching.md 这份规则文档为骨架逐一拆解remember()、flexible()、memo()、缓存标签、add()、once()与 failover 存储等七个关键用法并对照 config/cache.php 与 app 目录下的真实实现、测试用例讲清每个 API 的适用场景、底层语义与失效策略。读完你将掌握一套何时用哪个缓存 API、如何做原子写、如何按组失效、如何在生产环境做故障切换的完整判断体系并能直接套用于任何 Laravel 12 项目。一、先从一份规则文档说起缓存最佳实践的整体框架这份caching.md来自仓库内 laravel-best-practices 技能包它与 Eloquent、队列、安全、架构等 20 份规则一起构成 Coolify 在 Laravel 12 开发中的编码准则。规则文档强调一个先决原则——一致性优先在引入新写法之前先看代码库已经采用的模式并跟随它不一致比次优模式更有害。把该技能总览中的缓存要点整理成一张决策地图也是全文的主线需求场景推荐 API一句话要点读多写少、可容忍短暂过期Cache::remember()缓存旁路cache-aside消除手工 get/put 样板高流量键、过期瞬间不能有人卡慢Cache::flexible()stale-while-revalidate过期后先给旧值再后台刷新同请求内多次读同一键Cache::memo()一个请求只打一次 Redis跨请求仍共享缓存一次函数结果只算一次进程内once()纯内存 memo完全不触碰缓存存储幂等去重、一次性标记Cache::add()键不存在才写入原子无竞态临界区互斥部署、SSH 复用等Cache::lock()/block()原子锁可阻塞等待并支持 TTL 释放按组批量失效Cache::tags()仅 redis/memcached/dynamodb 支持生产高可用failover 存储Redis 宕机自动降级到次级存储下文逐条展开并随时回到 Coolify 源码确认这些 API 在真实系统里是怎么被使用的。二、缓存地基Coolify 的默认存储与 key 前缀先看 Coolify 的缓存配置文件 config/cache.phpdefault env(CACHE_DRIVER, redis),默认走redis连接且该 store 声明了redis [ driver redis, connection cache, // 使用 redis.php 中名为 cache 的连接 lock_connection default, // 原子锁使用 default 连接避免与数据互相挤占 ],值得注意的细节是lock_connectionCoolify 把缓存数据与缓存锁拆分到不同 Redis 连接上让Cache::lock()不干扰数据读写。该配置文件同时预置了apc、array、database、file、memcached、dynamodb、octane、null等全部官方 store这意味着文档中提到的 failover、tags 等能力边界都可以回到这份配置逐项验证。key 前缀通过CACHE_PREFIX环境变量控制默认取APP_NAME的 slug 拼_cache_prefix env(CACHE_PREFIX, Str::slug(env(APP_NAME, laravel), _)._cache_),这与规则文档中为 key 设计命名空间、避免跨应用冲突的最佳实践直接呼应——Coolify 的缓存 key 普遍采用领域:实体:id:属性的冒号分层如user:{$userId}:team:{$teamId}配合前缀避免与其他共用 Redis 的应用发生碰撞。依赖侧composer.json 声明了laravel/framework: ^12.65.0与laravel/horizon: ^5.48.2PHP 要求^8.4说明下文涉及的flexible()、memo()、once()等新版 API 均处于可用版本区间。三、Cache::remember()用缓存旁路替代手工 Get/Put这是最基础的缓存写法。规则文档明确指出手工get后判空再put是反模式// 错误样板代码多、易漏分支、可读性差 $val Cache::get(stats); if (! $val) { $val $this-computeStats(); Cache::put(stats, $val, 60); }// 正确声明式缓存旁路 $val Cache::remember(stats, 60, fn () $this-computeStats());remember()把查询 → 缺失时计算并写回 → 带 TTL三件事封装成一个原子外观。第二个参数既可以是秒数也可以是DateTimeInterface例如now()-addMinutes(10)需要永不过期时用rememberForever()并用事件/业务动作显式失效。实战证据一TrustHosts 中的负缓存哨兵Coolify 的 app/Http/Middleware/TrustHosts.php 在hosts()中缓存实例 FQDN避免每个请求都查询一次instance_settings表$fqdnHost Cache::remember(instance_settings_fqdn_host, 300, function () { try { $settings InstanceSettings::get(); if ($settings $settings-fqdn) { $url Url::fromString($settings-fqdn); $host $url-getHost(); return $host ?: ; } } catch (\Exception $e) { // 安装期间表尚未建立返回空字符串使其也能被缓存 } return ; });这里的两个工程细节值得学习负结果也要缓存——查询失败/为空时返回哨兵值而不是让 closure 抛错避免表不存在就每请求重试一次的缓存击穿失效挂在模型事件上——app/Models/InstanceSettings.php 的updated钩子监听fqdn是否变化变化即Cache::forget(instance_settings_fqdn_host)实现修改即失效、最迟 300 秒兜底收敛的双保险。实战证据二用户当前团队的 1 小时缓存app/Models/User.php 的currentTeam()是 remember 的另一个典型以user:{id}:team:{teamId}为键缓存团队解析结果 3600 秒而在切换团队、删除团队等动作点显式Cache::forget见同文件第 367 行与 app/Actions/Team/DeleteTeam.php。这种集中写入、业务点显式失效的模式在 Coolify 中随处可见——app/Services/ChangelogService.php 对 changelog 计数用remember包裹远程请求并在已读/标记场景多处forgetapp/Livewire/GlobalSearch.php 以团队为单位remember300 秒全局搜索索引删除资源时按getCacheKey($teamId)精准失效。需要强调的是remember()的缺失时计算在多进程并发下并非原子——同一时刻多个请求都可能命中缺失分支重复计算。解决并发重建要靠下一节讲到的flexible()或配合Cache::lock()做 single-flight。四、Cache::flexible()为高流量键引入 Stale-While-Revalidate高流量键如全站热榜、公共统计用普通remember()会有一个隐蔽缺陷TTL 到期的瞬间所有并发请求同时看到缓存缺失其中总有一个用户必须等待重新计算——这就是每次过期都有一个倒霉用户卡顿的来源。规则文档给出的对照// 不理想过期瞬间可能出现明显延迟尖峰 Cache::remember(users, 300, fn () User::all()); // 推荐fresh 5 分钟过期后 10 分钟内先提供旧值同时后台 defer 刷新 Cache::flexible(users, [300, 600], fn () User::all());flexible()接收一个[freshTTL, staleTTL]区间数组作为第二个参数距上次写入未超过freshTTL300 秒→ 直接返回新鲜数据超过freshTTL但未超过staleTTL600 秒→立刻把旧值返回给当前请求保证无卡顿同时注册一个defer()延迟闭包在响应结束后的后台进程里重新计算并写回超过staleTTL→ 视为彻底过期同步重建。这一语义特别适合 Coolify 中读放大型的数据。以 app/Services/ChangelogService.php 拉取远端 changelog、或 config 加载的实例级配置这类低频变更、高频读取数据为例改用flexible()能直接把最坏情况的响应时间从重新计算耗时摊平为一次缓存读取耗时。底层关键点是 stale 窗口内的刷新由 defer 异步完成因此要求队列/响应生命周期支持defer()Laravel 11 的Illuminate\Foundation\DeferCoolify 基于 Laravel 12 完全满足该前提。五、请求内的重复缓存命中Cache::memo()vsonce()规则文档区分了两个防重复计算工具它们的层级完全不同// Cache::memo()一个请求内只打一次缓存存储Redis跨请求依然共享缓存 Cache::memo()-get(settings); // 同请求内第 2..5 次调用都命中内存不再产生 Redis 往返 // once()完全不触碰缓存存储纯进程内 memo public function roles(): Collection { return once(fn () $this-loadRoles()); }选择依据如果你只关心同一个请求内被多个服务重复调用的热点方法Cache::memo()会把解析后的值保存在请求级内存中5 次调用只产生 1 次 Redis 往返但数据仍是来自缓存存储的。而once()更轻——它根本不检查 Redis只保证闭包结果在对象/请求生命周期内只执行一次代价是该值无法跨请求共享。Coolify 中once()的大规模应用once()在 Coolify 模型层几乎是标配。最典型的是 app/Models/InstanceSettings.php 的单例读取public static function get() { return once(fn () InstanceSettings::findOrFail(0)); }InstanceSettings是典型的系统里只有一行的配置单例任何地方调用InstanceSettings::get()都应得到同一实例用once()包装后同一请求内无论被 app/Http/Middleware/TrustHosts.php、Livewire 组件还是 Job 调用多少次都只落一次查询。同类写法还出现在 app/Models/Server.php、app/Models/Project.php、app/Models/Service.php、app/Models/Application.php 以及全部 standalone 数据库模型中。更关键的是它的失效配套——InstanceSettings在booted()中监听模型的created与updated事件并执行Once::flush()app/Models/InstanceSettings.php一次性清空全部once()内存缓存确保配置被修改后新请求拿到的是新值。这也是使用once()时必须养成的习惯凡是 memo就必须有明确的刷新/失效时机否则会引入难以排查的幽灵旧值。六、Cache::add()原子条件写天然防重复当你需要的不是锁住一段代码而是确保某个动作全局只执行一次Cache::add()是最轻量的选择。它只在 key 不存在时写入检查与写入在存储端原子完成不存在手工先 has 后 put的竞态窗口// 错误check-then-act 存在竞态 if (! Cache::has(lock)) { Cache::put(lock, true, 10); } // 正确单条原子指令 Cache::add(lock, true, 10);实战证据备份保留清理的 30 分钟去重闸门app/Jobs/CleanupInstanceStuffsJob.php 用它实现备份保留期强制清理任务的全局互斥if (! Cache::add(backup-retention-enforcement, true, 1800)) { // 已有实例正在执行直接跳过本次 return; } // ...执行清理逻辑... Cache::forget(backup-retention-enforcement); // 提前结束时手动释放TTL1800 秒意味着即便清理进程异常退出forget未被执行闸门也会在 30 分钟后自动失效不会把任务永久锁死——这正是原子标记 自动过期兜底的教科书组合。类似的幂等场景还包括 app/Jobs/ScheduledJobManager.php 用Cache::get/put做调度去重$dedupKey并以心跳键scheduled-job-manager:heartbeatTTL 300 秒对外暴露调度器存活状态供 app/Livewire/Server/DockerCleanup.php 这类 UI 组件探测。七、Cache::lock()比 add 更强的临界区控制当防重复之外还需要串行化一段有副作用的代码时规则文档推荐使用Cache::lock()技能总览中还补充了lockForUpdate()。原子锁的核心价值是拿锁与执行之间即使进程崩溃TTL 也能保证锁最终自动释放。实战证据一SSH 多路复用连接的并发防护Coolify 是重度 SSH 工具其 app/Helpers/SshMultiplexingHelper.php 在建立/刷新服务器 SSH 多路复用连接前加锁防止并发任务同时创建 master connectionreturn Cache::lock( self::connectionLockKey($server), // 每台服务器一把锁 config(constants.ssh.mux_lock_ttl) // 锁的持有上限 )-block(config(constants.ssh.mux_lock_timeout), function () use ($server) { if (self::connectionIsReusable($server)) { return true; } if (self::masterConnectionExists($server)) { return self::refreshMultiplexedConnection($server); } return self::establishNewMultiplexedConnection($server); });-block(seconds, closure)表示最多阻塞等待 N 秒拿锁拿不到就抛LockTimeoutException比直接拿锁失败更适用于这件事迟早要轮到本进程做的场景。仓库测试 tests/Feature/SshMultiplexingLockTest.php 明确覆盖了并发拿锁的行为。实战证据二令牌刷新的分布式互斥与缓存去重bootstrap/helpers/gitlab.php 用Cache::lock(gitlab_token_refresh_{$source-id}, 20)保证同一 GitLab 源的 token 刷新只有一个进程执行app/Http/Controllers/Api/SentinelController.php 在 Sentinel 指标推送链路中Cache::lock($lockKey, 10)-block(5, ...)拿到锁后再查哈希与强制推送标志做缓存去重其行为有专门测试 tests/Feature/SentinelPushDeduplicationTest.php 守护app/Console/Commands/AdminDeleteUser.php 对用户删除这类不可逆操作持有 600 秒长锁。锁的命名与 TTL 设计同样有讲究——app/Actions/Shared/DeleteScheduledVolumeBackup.php 以VolumeBackupJob::lockKey($backup-id)为键、$backup-timeout 300为 TTL即任务超时上限再加 300 秒余量保证锁生命周期一定盖过任务执行时长。这也呼应技能总览中retry_after必须大于 jobtimeout的队列准则——锁与任务的 TTL 边界始终是同一类心智模型。八、缓存失效的艺术Tags 组失效 vs 逐键 Forget规则文档指出没有标签时要让一组相关缓存全部失效你必须逐个记住并删除每个 key。Cache::tags()允许你给条目打标签并原子冲刷整组Cache::tags([user-1])-flush();其硬性约束同样写进了规则只有redis、memcached、dynamodb驱动支持 tagsfile与database驱动不支持。以 config/cache.php 中 Coolify 默认的redisstore 为前提tags 完全可用但若你在 CI 或本地退回file/database存储任何Cache::tags()调用都会直接抛异常——这是把 tags 写入共享代码前必须评估的兼容性陷阱。回到 Coolify 的真实代码你会发现它刻意选择了业务事件 逐键 forget而非 tags。证据链如下删除团队时逐键清理该用户的会话缓存app/Actions/Team/DeleteTeam.phpCache::forget(user:{$user-id}:team:{$team-id})同文件第 94 行还清理team:{memberId}团队成员变更时同步失效 app/Livewire/Team/Member.php 中两个相关键FQDN 变更时只失效instance_settings_fqdn_host一个键InstanceSettingschangelog 已读计数变更时按用户逐键forgetChangelogService。这正是规则文档Consistency First的体现Coolify 的缓存键基本都是实体:id型且数量有限失效点分散在明确的事件/动作中逐键 forget 的显式性反而让每条缓存的生命周期可审计只有当你遇到同一请求批量加载几十个 key、希望一次 flush 全部相关条目且能保证存储驱动为 Redis 时tags 才是更优解。九、生产环境的高可用failover 缓存存储规则文档最后一条是关于可用性的如果 Redis 宕机应用应能自动降级到次级存储而不是雪崩。方法是在缓存配置中声明一个failover驱动 storefailover [ driver failover, stores [redis, database], ],随后把默认存储切换为它CACHE_DRIVERfailover。其工作方式为主存储redis发生连接级故障时框架自动把读写路由到备选存储database期间不抛出破坏用户体验的异常主存储恢复后回归。两个值得注意的边界failover 针对的是存储不可用而非key 不存在——它不做跨存储的数据迁移主备之间同一 key 的 TTL、序列化格式需要自洽在 config/cache.php 中databasestore 依赖cache数据表因此启用[redis, database]前需先执行php artisan cache:table迁移filestore 也可以作为备选但要注意多实例部署时的一致性。Coolify 当前默认直接用 redisCACHE_DRIVER缺省即 redis并依赖 Redis 支撑 config/queue.php 背后的 Horizon 队列与锁。若你的部署场景要求Redis 单点故障也能继续服务读请求就可以在配置中叠加上述 failover store让缓存层具备与队列层不同的可用性等级。十、选型总览与落地清单回到 caching.md 全文可以把整篇方法收敛为四句话读路径默认Cache::remember()高流量键换flexible([fresh, stale])消除过期尖峰防重复区分层级同请求内反复调用用Cache::memo()纯计算不落存储用once()并记得在数据变更点flush防并发按强度递进只求全局一次用Cache::add()需要串行执行临界区用Cache::lock(...)-block(...)锁 TTL 必须大于任务最长执行时间失效策略跟随业务key 少、事件明确就逐键forgetCoolify 的现状key 成组、需要原子冲刷且驱动为 Redis 就用Cache::tags()生产环境把默认存储包一层 failover。落地时可对照源码复核每条存储与驱动配置见 config/cache.php锁的工程化用法见 app/Helpers/SshMultiplexingHelper.php 与 app/Http/Controllers/Api/SentinelController.phponce()与事件刷新的配套见 app/Models/InstanceSettings.php缓存行为测试可参考 tests/Feature/SshMultiplexingLockTest.php、tests/Feature/SentinelPushDeduplicationTest.php 与 tests/Feature/VolumeBackupTest.php。把读快、防重、防并发、能失效、可降级这五件事做对缓存层就能从压垮数据库前的最后一根稻草变成你系统里最廉价也最可靠的一层加速器。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考