Dagger 引擎缓存管理指南深入解析 TypeScript SDK 的 EngineCache 类【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger TypeScript SDK 中EngineCache类展开讲解如何通过dagger.io/dagger的Engine→localCache()访问引擎本地磁盘缓存读取缓存容量策略maxUsedSpace/minFreeSpace/reservedSpace/targetSpace、列举缓存条目entrySet以及按需清理可释放缓存prune。读完本文你将掌握在 Dagger 流水线或诊断脚本中查询、审计与回收引擎缓存的标准方法并理解这些接口背后的 GC 配置与实现原理。本文以 EngineCache.md 为骨架并结合仓库中 client.gen.ts 的 TypeScript 实现、core/engine.go 的核心类型定义、core/schema/engine.go 的 GraphQL 注册、engine/config/config.go 的 GC 配置与 engine/server/gc.go 的清理实现展开。EngineCache 在 Dagger API 中的位置EngineCache是 Dagger GraphQL API 中Engine类型下的一个对象官方定义为 A cache storage for the Dagger engine即 Dagger 引擎的本地磁盘缓存。它对应引擎侧core.EngineCache结构体见 core/engine.gotype EngineCache struct { MaxUsedSpace int field:true doc:The maximum bytes to keep in the cache without pruning. TargetSpace int field:true doc:The target number of bytes to keep when pruning. ReservedSpace int field:true doc:The minimum amount of disk space this policy is guaranteed to retain. MinFreeSpace int field:true doc:The target amount of free disk space the garbage collector will attempt to leave. }从类型描述看EngineCache的核心职责有两块反映当前缓存容量策略四个磁盘空间指标以及提供清理操作入口prune。它不直接承载缓存数据——缓存条目由配套的EngineCacheEntrySet/EngineCacheEntry类型描述。在 core/schema/engine.go 中这些能力被注册为 GraphQL 字段Engine.localCache返回当前引擎的本地缓存对象EngineCache.entrySet返回当前缓存条目集合EngineCache.prune清理可释放条目标记为DoNotCache因为它会改变可变状态。在 GraphQL 层面localCache通过query.EngineLocalCachePolicy()读取引擎侧缓存策略若未配置策略则返回空对象entrySet通过query.EngineLocalCacheEntries(ctx)加载条目见 core/schema/engine.go。从 Client 到 EngineCache访问路径TypeScript SDK 中所有对象都继承自BaseClientEngineCache也不例外export class EngineCache extends BaseClient见 client.gen.ts。访问EngineCache需要经过两级Client.engine()根客户端返回引擎配置与状态对象Engine见 client.gen.tsEngine.localCache()返回本地缓存对象EngineCache对应 Engine.md 中的方法。一个最小访问示例import { connect } from dagger.io/dagger; connect(async (client) { // 逐级获取 EngineCache const cache client.engine().localCache(); // 读取四个磁盘空间策略指标单位字节 const maxUsed await cache.maxUsedSpace(); const minFree await cache.minFreeSpace(); const reserved await cache.reservedSpace(); const target await cache.targetSpace(); console.log({ maxUsed, minFree, reserved, target, }); });构造函数与 ID仅供内部使用EngineCache的构造函数签名与所有 Dagger SDK 客户端对象一致为new EngineCache( ctx?: Context, _id?: EngineCacheID, _maxUsedSpace?: number, _minFreeSpace?: number, _prune?: Void, _reservedSpace?: number, _targetSpace?: number ): EngineCache文档与代码注释都明确指出构造函数仅用于内部使用不要从它创建对象。所有参数以下划线开头属于 SDK 内部的惰性求值缓存当调用某个方法时若对应私有字段已有值则直接返回否则向 GraphQL 端点发起查询见 client.gen.ts。id()方法返回该对象的唯一标识符EngineCacheID类型定义见 EngineCacheID.md。同样遵循惰性模式若_id已存在则直接返回否则执行select(id)查询。四个磁盘空间指标解读缓存容量策略EngineCache最直观的能力是暴露当前缓存清理策略的四个数值指标单位均为字节返回Promisenumber。它们与引擎配置 engine/config/config.go 中GCSpace的字段一一对应方法返回语义对应配置字段JSONmaxUsedSpace()不触发清理时缓存允许占用的最大字节数超过该上限即触发 GC 清扫gc.maxUsedSpaceminFreeSpace()GC 尝试保留的目标空闲磁盘空间gc.minFreeSpacereservedSpace()该策略保证保留的最小磁盘空间低于此阈值的用量不会被回收gc.reservedSpacetargetSpace()一次清理后目标保留的字节数由 GC 策略推导引擎侧在EngineLocalCachePolicy中把配置策略映射为这四个字段见 core/schema/engine.go若引擎未启用本地缓存策略policy nil则返回空EngineCache对象此时四个指标均为 0。配置层面的语义在 engine/config/config.go 中GCSpace的注释给出了精确的语义ReservedSpace该策略保证保留的最小磁盘空间任何低于此阈值的用量都不会在 GC 中被回收MaxUsedSpace该策略允许使用的最大磁盘空间超过此限制的用量会在一次 GC 清扫中被清理MinFreeSpaceGC 试图保留的目标空闲磁盘空间但绝不会让可用空间低于ReservedSpaceSweepSize单次 GC 通过中至少要清扫的空间量可配置但未通过 SDK 直接暴露。需要强调minFreeSpace与reservedSpace的区别前者是目标后者是硬下限。GC 会尽量把空闲空间提升到MinFreeSpace但无论如何不会越过ReservedSpace这条红线。这正是缓存策略设计中防止为了腾空间把缓存清空、反而拖垮下一次构建的关键机制。磁盘空间的三种写法配置中的DiskSpace类型支持三种取值见 config.go 的 JSON Schema 约束纯字节整数如512000000带单位后缀的字符串如512MB、200GB正则^[0-9][0-9.]*([kKmMgGtTpP][iI]?)?[bB]?$百分比字符串如10%正则^[0-9]%$。prune()方法的覆盖参数同样使用这种200GB/50%的字符串格式见下文。entrySet()审计缓存中的条目entrySet(opts?: EngineCacheEntrySetOpts)返回EngineCacheEntrySet即当前缓存中的条目集合。它是进一步审计缓存的入口见 EngineCacheEntrySet.md。EngineCacheEntrySet 与 EngineCacheEntryEngineCacheEntrySet对应 core/engine.go提供两个统计字段和一个枚举方法entryCount()集合中缓存条目的数量diskSpaceBytes()集合中所有条目占用的总磁盘空间entries()返回EngineCacheEntry[]在 schema 中注册于 core/schema/engine.go。EngineCacheEntry描述单个缓存条目见 EngineCacheEntry.md 与 core/engine.go字段如下方法类型含义activelyUsed()boolean该条目是否正被使用createdTimeUnixNano()number条目创建时间Unix 纳秒dagqlCall()string产生该缓存条目的 DagQL 调用description()string条目描述diskSpaceBytes()number条目占用的磁盘空间mostRecentUseTimeUnixNano()number最近一次使用时间Unix 纳秒recordType()string缓存记录类型如regular、internal、frontend、source.local、source.git.checkout、exec.cachemountrecordTypes()string[]该条目所代表的存储记录类型列表审计示例import { connect } from dagger.io/dagger; connect(async (client) { const cache client.engine().localCache(); // 获取条目集合 const set cache.entrySet(); const count await set.entryCount(); const totalBytes await set.diskSpaceBytes(); console.log(缓存条目数: ${count}总占用: ${totalBytes} 字节); // 逐条枚举 const entries await set.entries(); for (const entry of entries) { const desc await entry.description(); const bytes await entry.diskSpaceBytes(); const recordType await entry.recordType(); const created await entry.createdTimeUnixNano(); console.log(- [${recordType}] ${desc || (无描述)} 占用 ${bytes} 字节 创建于 ${created}); } });这类审计对于诊断CI 磁盘被撑爆、判断哪些构建产物仍被引用activelyUsed、以及识别历史遗留缓存对比mostRecentUseTimeUnixNano与当前时间非常实用。prune()按需清理缓存prune(opts?: EngineCachePruneOpts): Promisevoid用于清理缓存中可释放的条目是EngineCache的核心运维操作。其 GraphQL 定义见 core/schema/engine.go底层调用query.PruneEngineLocalCacheEntries。参数详解EngineCachePruneOpts的所有字段均为可选类型定义见 EngineCachePruneOpts.mdTS 端 JSDoc 见 client.gen.ts参数类型说明useDefaultPolicyboolean为true时使用引擎级默认磁盘与结构清理策略若未启用默认磁盘策略磁盘阶段回退为清理所有可释放磁盘缓存条目maxUsedSpacestring覆盖清理前允许保留的最大磁盘空间如200GB或80%reservedSpacestring覆盖清理期间保留的最小磁盘空间如500GB或10%minFreeSpacestring覆盖清理期间的最小空闲磁盘空间目标如20GB或20%targetSpacestring覆盖清理后目标保留的磁盘空间如200GB或50%maxEstimatedBytesnumber覆盖结构元数据估计的最大绝对值字节显式值必须为正省略时使用配置/默认值targetEstimatedBytesnumber覆盖结构元数据估计的目标绝对值字节显式值必须为正且低于解析出的最大值行为规则源码佐证在引擎侧 engine/server/gc.go 中PruneEngineLocalCacheEntries定义了精确的行为模式无任何参数保持传统行为清理所有可释放的磁盘缓存条目显式磁盘参数maxUsedSpace/reservedSpace/minFreeSpace/targetSpace任一非空仅运行磁盘清理阶段显式结构参数maxEstimatedBytes/targetEstimatedBytes仅运行结构元数据清理阶段不会隐式触发磁盘阶段useDefaultPolicy: true且自动 GC 已启用同时运行磁盘与结构两个阶段的默认策略。结构清理DAGQL 缓存元数据的默认值在 gc.go 中定义dagqlCacheDefaultMaxEstimatedBytes int64 4 30 // 4 GiB dagqlCacheDefaultTargetEstimatedBytes int64 3 30 // 3 GiB即默认在结构估计超过 4 GiB 时触发清理目标是回落到 3 GiB。覆盖参数必须满足targetEstimatedBytes maxEstimatedBytes且均为正数否则会返回校验错误见 gc.go。清理示例import { connect } from dagger.io/dagger; connect(async (client) { const cache client.engine().localCache(); // 1) 使用引擎级默认策略清理 await cache.prune({ useDefaultPolicy: true }); // 2) 显式磁盘参数只保留 100GB至少留 10% 空闲 await cache.prune({ maxUsedSpace: 100GB, minFreeSpace: 10%, }); // 3) 只清理结构元数据目标回落到 2GiB低于默认最大值 4GiB await cache.prune({ maxEstimatedBytes: 4 * 1024 * 1024 * 1024, targetEstimatedBytes: 2 * 1024 * 1024 * 1024, }); console.log(缓存清理完成); });底层原理GC 配置与自动清理prune()是显式触发的手动清理而引擎日常的自动回收由 GC 配置驱动。EngineCache的四个策略字段正是这套 GC 配置的投影。完整的配置树定义在 engine/config/config.gotype GCConfig struct { Enabled *bool json:enabled,omitempty // GC 总开关默认开启 DagqlCache DagqlCacheGCConfig json:dagqlCache,omitempty // DAGQL 结构元数据清理 GCSpace // 顶层磁盘空间参数 Policies []GCPolicy json:policies,omitempty // 手动策略列表 }GCSpace内嵌为顶层参数未配置Policies时会基于它自动生成默认策略GCPolicy支持 containerd 过滤器id、parents、description、inuse、mutable、immutable、type、shared、private与KeepDuration保留时长见 config.goDagqlCacheGCConfig用于独立于物理磁盘的 DAGQL 内存缓存结构清理字段为maxEstimatedBytes与targetEstimatedBytes对应prune()中的同名覆盖参数。引擎侧的自动 GC 会按固定节奏检查磁盘压力见 gc.go压力检查每 5 秒一次GC 节流 30 秒会话级 GC 节流 1 分钟根据maxUsedSpace/minFreeSpace/reservedSpace等策略决定是否清扫以及清扫多少。因此通过EngineCache读取的四个指标反映的是引擎接下来会在什么阈值下自动清理的实时视图——在 CI 中打印它们可以帮助你判断缓存是否即将触发自动回收从而在关键时刻主动调用prune()避免构建失败。注意事项与最佳实践构造对象只读接口永远不要直接new EngineCache(...)应通过client.engine().localCache()获取这与 SDK 中所有客户端对象一致。prune()是破坏性操作它清理可释放条目可能加速后续任务的缓存未命中cache miss导致构建变慢。建议仅在磁盘紧张或 CI 收尾阶段使用优先考虑useDefaultPolicy或显式targetSpace避免无差别清空。reservedSpace是底线配置清理参数时reservedSpace保证基本盘不被回收minFreeSpace是目标。理解二者的先后约束可以避免配置出互相矛盾如minFreeSpace 100% - reservedSpace的策略。数值单位四个只读指标以字节返回prune的磁盘覆盖参数接受字节、带单位字符串200GB或百分比50%三种格式结构参数maxEstimatedBytes/targetEstimatedBytes仅接受绝对字节数。主客户端限制从 schema 实现可见localCache、entrySet、prune均调用query.RequireMainClient(ctx)见 core/schema/engine.go 等即这些操作要求以主客户端身份发起而非模块/子会话客户端。版本边界结构清理参数maxEstimatedBytes、targetEstimatedBytes在当前版本被标记为AfterVersion(v1.0.0-0)而useDefaultPolicy标记为BeforeVersion(v1.0.0-0)见 core/schema/engine.go说明 API 正处于演进期升级 Dagger 版本后应复查参数可用性。相关文档与资源EngineCache.md本文主题的原始 API 参考Engine.mdEngine类localCache()的上一级入口EngineCacheEntrySet.md 与 EngineCacheEntry.md缓存条目集合与单条目 APIclient.gen.tsEngineCache的 TypeScript 实现core/engine.goEngineCache/EngineCacheEntrySet/EngineCacheEntry核心类型core/schema/engine.goGraphQL schema 注册与参数解析engine/config/config.goGC 配置结构GCConfig/GCPolicy/GCSpaceengine/server/gc.go自动 GC 与PruneEngineLocalCacheEntries的实现。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dagger 引擎缓存管理指南：深入解析 TypeScript SDK 的 EngineCache 类
Dagger 引擎缓存管理指南深入解析 TypeScript SDK 的 EngineCache 类【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger TypeScript SDK 中EngineCache类展开讲解如何通过dagger.io/dagger的Engine→localCache()访问引擎本地磁盘缓存读取缓存容量策略maxUsedSpace/minFreeSpace/reservedSpace/targetSpace、列举缓存条目entrySet以及按需清理可释放缓存prune。读完本文你将掌握在 Dagger 流水线或诊断脚本中查询、审计与回收引擎缓存的标准方法并理解这些接口背后的 GC 配置与实现原理。本文以 EngineCache.md 为骨架并结合仓库中 client.gen.ts 的 TypeScript 实现、core/engine.go 的核心类型定义、core/schema/engine.go 的 GraphQL 注册、engine/config/config.go 的 GC 配置与 engine/server/gc.go 的清理实现展开。EngineCache 在 Dagger API 中的位置EngineCache是 Dagger GraphQL API 中Engine类型下的一个对象官方定义为 A cache storage for the Dagger engine即 Dagger 引擎的本地磁盘缓存。它对应引擎侧core.EngineCache结构体见 core/engine.gotype EngineCache struct { MaxUsedSpace int field:true doc:The maximum bytes to keep in the cache without pruning. TargetSpace int field:true doc:The target number of bytes to keep when pruning. ReservedSpace int field:true doc:The minimum amount of disk space this policy is guaranteed to retain. MinFreeSpace int field:true doc:The target amount of free disk space the garbage collector will attempt to leave. }从类型描述看EngineCache的核心职责有两块反映当前缓存容量策略四个磁盘空间指标以及提供清理操作入口prune。它不直接承载缓存数据——缓存条目由配套的EngineCacheEntrySet/EngineCacheEntry类型描述。在 core/schema/engine.go 中这些能力被注册为 GraphQL 字段Engine.localCache返回当前引擎的本地缓存对象EngineCache.entrySet返回当前缓存条目集合EngineCache.prune清理可释放条目标记为DoNotCache因为它会改变可变状态。在 GraphQL 层面localCache通过query.EngineLocalCachePolicy()读取引擎侧缓存策略若未配置策略则返回空对象entrySet通过query.EngineLocalCacheEntries(ctx)加载条目见 core/schema/engine.go。从 Client 到 EngineCache访问路径TypeScript SDK 中所有对象都继承自BaseClientEngineCache也不例外export class EngineCache extends BaseClient见 client.gen.ts。访问EngineCache需要经过两级Client.engine()根客户端返回引擎配置与状态对象Engine见 client.gen.tsEngine.localCache()返回本地缓存对象EngineCache对应 Engine.md 中的方法。一个最小访问示例import { connect } from dagger.io/dagger; connect(async (client) { // 逐级获取 EngineCache const cache client.engine().localCache(); // 读取四个磁盘空间策略指标单位字节 const maxUsed await cache.maxUsedSpace(); const minFree await cache.minFreeSpace(); const reserved await cache.reservedSpace(); const target await cache.targetSpace(); console.log({ maxUsed, minFree, reserved, target, }); });构造函数与 ID仅供内部使用EngineCache的构造函数签名与所有 Dagger SDK 客户端对象一致为new EngineCache( ctx?: Context, _id?: EngineCacheID, _maxUsedSpace?: number, _minFreeSpace?: number, _prune?: Void, _reservedSpace?: number, _targetSpace?: number ): EngineCache文档与代码注释都明确指出构造函数仅用于内部使用不要从它创建对象。所有参数以下划线开头属于 SDK 内部的惰性求值缓存当调用某个方法时若对应私有字段已有值则直接返回否则向 GraphQL 端点发起查询见 client.gen.ts。id()方法返回该对象的唯一标识符EngineCacheID类型定义见 EngineCacheID.md。同样遵循惰性模式若_id已存在则直接返回否则执行select(id)查询。四个磁盘空间指标解读缓存容量策略EngineCache最直观的能力是暴露当前缓存清理策略的四个数值指标单位均为字节返回Promisenumber。它们与引擎配置 engine/config/config.go 中GCSpace的字段一一对应方法返回语义对应配置字段JSONmaxUsedSpace()不触发清理时缓存允许占用的最大字节数超过该上限即触发 GC 清扫gc.maxUsedSpaceminFreeSpace()GC 尝试保留的目标空闲磁盘空间gc.minFreeSpacereservedSpace()该策略保证保留的最小磁盘空间低于此阈值的用量不会被回收gc.reservedSpacetargetSpace()一次清理后目标保留的字节数由 GC 策略推导引擎侧在EngineLocalCachePolicy中把配置策略映射为这四个字段见 core/schema/engine.go若引擎未启用本地缓存策略policy nil则返回空EngineCache对象此时四个指标均为 0。配置层面的语义在 engine/config/config.go 中GCSpace的注释给出了精确的语义ReservedSpace该策略保证保留的最小磁盘空间任何低于此阈值的用量都不会在 GC 中被回收MaxUsedSpace该策略允许使用的最大磁盘空间超过此限制的用量会在一次 GC 清扫中被清理MinFreeSpaceGC 试图保留的目标空闲磁盘空间但绝不会让可用空间低于ReservedSpaceSweepSize单次 GC 通过中至少要清扫的空间量可配置但未通过 SDK 直接暴露。需要强调minFreeSpace与reservedSpace的区别前者是目标后者是硬下限。GC 会尽量把空闲空间提升到MinFreeSpace但无论如何不会越过ReservedSpace这条红线。这正是缓存策略设计中防止为了腾空间把缓存清空、反而拖垮下一次构建的关键机制。磁盘空间的三种写法配置中的DiskSpace类型支持三种取值见 config.go 的 JSON Schema 约束纯字节整数如512000000带单位后缀的字符串如512MB、200GB正则^[0-9][0-9.]*([kKmMgGtTpP][iI]?)?[bB]?$百分比字符串如10%正则^[0-9]%$。prune()方法的覆盖参数同样使用这种200GB/50%的字符串格式见下文。entrySet()审计缓存中的条目entrySet(opts?: EngineCacheEntrySetOpts)返回EngineCacheEntrySet即当前缓存中的条目集合。它是进一步审计缓存的入口见 EngineCacheEntrySet.md。EngineCacheEntrySet 与 EngineCacheEntryEngineCacheEntrySet对应 core/engine.go提供两个统计字段和一个枚举方法entryCount()集合中缓存条目的数量diskSpaceBytes()集合中所有条目占用的总磁盘空间entries()返回EngineCacheEntry[]在 schema 中注册于 core/schema/engine.go。EngineCacheEntry描述单个缓存条目见 EngineCacheEntry.md 与 core/engine.go字段如下方法类型含义activelyUsed()boolean该条目是否正被使用createdTimeUnixNano()number条目创建时间Unix 纳秒dagqlCall()string产生该缓存条目的 DagQL 调用description()string条目描述diskSpaceBytes()number条目占用的磁盘空间mostRecentUseTimeUnixNano()number最近一次使用时间Unix 纳秒recordType()string缓存记录类型如regular、internal、frontend、source.local、source.git.checkout、exec.cachemountrecordTypes()string[]该条目所代表的存储记录类型列表审计示例import { connect } from dagger.io/dagger; connect(async (client) { const cache client.engine().localCache(); // 获取条目集合 const set cache.entrySet(); const count await set.entryCount(); const totalBytes await set.diskSpaceBytes(); console.log(缓存条目数: ${count}总占用: ${totalBytes} 字节); // 逐条枚举 const entries await set.entries(); for (const entry of entries) { const desc await entry.description(); const bytes await entry.diskSpaceBytes(); const recordType await entry.recordType(); const created await entry.createdTimeUnixNano(); console.log(- [${recordType}] ${desc || (无描述)} 占用 ${bytes} 字节 创建于 ${created}); } });这类审计对于诊断CI 磁盘被撑爆、判断哪些构建产物仍被引用activelyUsed、以及识别历史遗留缓存对比mostRecentUseTimeUnixNano与当前时间非常实用。prune()按需清理缓存prune(opts?: EngineCachePruneOpts): Promisevoid用于清理缓存中可释放的条目是EngineCache的核心运维操作。其 GraphQL 定义见 core/schema/engine.go底层调用query.PruneEngineLocalCacheEntries。参数详解EngineCachePruneOpts的所有字段均为可选类型定义见 EngineCachePruneOpts.mdTS 端 JSDoc 见 client.gen.ts参数类型说明useDefaultPolicyboolean为true时使用引擎级默认磁盘与结构清理策略若未启用默认磁盘策略磁盘阶段回退为清理所有可释放磁盘缓存条目maxUsedSpacestring覆盖清理前允许保留的最大磁盘空间如200GB或80%reservedSpacestring覆盖清理期间保留的最小磁盘空间如500GB或10%minFreeSpacestring覆盖清理期间的最小空闲磁盘空间目标如20GB或20%targetSpacestring覆盖清理后目标保留的磁盘空间如200GB或50%maxEstimatedBytesnumber覆盖结构元数据估计的最大绝对值字节显式值必须为正省略时使用配置/默认值targetEstimatedBytesnumber覆盖结构元数据估计的目标绝对值字节显式值必须为正且低于解析出的最大值行为规则源码佐证在引擎侧 engine/server/gc.go 中PruneEngineLocalCacheEntries定义了精确的行为模式无任何参数保持传统行为清理所有可释放的磁盘缓存条目显式磁盘参数maxUsedSpace/reservedSpace/minFreeSpace/targetSpace任一非空仅运行磁盘清理阶段显式结构参数maxEstimatedBytes/targetEstimatedBytes仅运行结构元数据清理阶段不会隐式触发磁盘阶段useDefaultPolicy: true且自动 GC 已启用同时运行磁盘与结构两个阶段的默认策略。结构清理DAGQL 缓存元数据的默认值在 gc.go 中定义dagqlCacheDefaultMaxEstimatedBytes int64 4 30 // 4 GiB dagqlCacheDefaultTargetEstimatedBytes int64 3 30 // 3 GiB即默认在结构估计超过 4 GiB 时触发清理目标是回落到 3 GiB。覆盖参数必须满足targetEstimatedBytes maxEstimatedBytes且均为正数否则会返回校验错误见 gc.go。清理示例import { connect } from dagger.io/dagger; connect(async (client) { const cache client.engine().localCache(); // 1) 使用引擎级默认策略清理 await cache.prune({ useDefaultPolicy: true }); // 2) 显式磁盘参数只保留 100GB至少留 10% 空闲 await cache.prune({ maxUsedSpace: 100GB, minFreeSpace: 10%, }); // 3) 只清理结构元数据目标回落到 2GiB低于默认最大值 4GiB await cache.prune({ maxEstimatedBytes: 4 * 1024 * 1024 * 1024, targetEstimatedBytes: 2 * 1024 * 1024 * 1024, }); console.log(缓存清理完成); });底层原理GC 配置与自动清理prune()是显式触发的手动清理而引擎日常的自动回收由 GC 配置驱动。EngineCache的四个策略字段正是这套 GC 配置的投影。完整的配置树定义在 engine/config/config.gotype GCConfig struct { Enabled *bool json:enabled,omitempty // GC 总开关默认开启 DagqlCache DagqlCacheGCConfig json:dagqlCache,omitempty // DAGQL 结构元数据清理 GCSpace // 顶层磁盘空间参数 Policies []GCPolicy json:policies,omitempty // 手动策略列表 }GCSpace内嵌为顶层参数未配置Policies时会基于它自动生成默认策略GCPolicy支持 containerd 过滤器id、parents、description、inuse、mutable、immutable、type、shared、private与KeepDuration保留时长见 config.goDagqlCacheGCConfig用于独立于物理磁盘的 DAGQL 内存缓存结构清理字段为maxEstimatedBytes与targetEstimatedBytes对应prune()中的同名覆盖参数。引擎侧的自动 GC 会按固定节奏检查磁盘压力见 gc.go压力检查每 5 秒一次GC 节流 30 秒会话级 GC 节流 1 分钟根据maxUsedSpace/minFreeSpace/reservedSpace等策略决定是否清扫以及清扫多少。因此通过EngineCache读取的四个指标反映的是引擎接下来会在什么阈值下自动清理的实时视图——在 CI 中打印它们可以帮助你判断缓存是否即将触发自动回收从而在关键时刻主动调用prune()避免构建失败。注意事项与最佳实践构造对象只读接口永远不要直接new EngineCache(...)应通过client.engine().localCache()获取这与 SDK 中所有客户端对象一致。prune()是破坏性操作它清理可释放条目可能加速后续任务的缓存未命中cache miss导致构建变慢。建议仅在磁盘紧张或 CI 收尾阶段使用优先考虑useDefaultPolicy或显式targetSpace避免无差别清空。reservedSpace是底线配置清理参数时reservedSpace保证基本盘不被回收minFreeSpace是目标。理解二者的先后约束可以避免配置出互相矛盾如minFreeSpace 100% - reservedSpace的策略。数值单位四个只读指标以字节返回prune的磁盘覆盖参数接受字节、带单位字符串200GB或百分比50%三种格式结构参数maxEstimatedBytes/targetEstimatedBytes仅接受绝对字节数。主客户端限制从 schema 实现可见localCache、entrySet、prune均调用query.RequireMainClient(ctx)见 core/schema/engine.go 等即这些操作要求以主客户端身份发起而非模块/子会话客户端。版本边界结构清理参数maxEstimatedBytes、targetEstimatedBytes在当前版本被标记为AfterVersion(v1.0.0-0)而useDefaultPolicy标记为BeforeVersion(v1.0.0-0)见 core/schema/engine.go说明 API 正处于演进期升级 Dagger 版本后应复查参数可用性。相关文档与资源EngineCache.md本文主题的原始 API 参考Engine.mdEngine类localCache()的上一级入口EngineCacheEntrySet.md 与 EngineCacheEntry.md缓存条目集合与单条目 APIclient.gen.tsEngineCache的 TypeScript 实现core/engine.goEngineCache/EngineCacheEntrySet/EngineCacheEntry核心类型core/schema/engine.goGraphQL schema 注册与参数解析engine/config/config.goGC 配置结构GCConfig/GCPolicy/GCSpaceengine/server/gc.go自动 GC 与PruneEngineLocalCacheEntries的实现。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考