数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载本文以 GarbageCollectionRules.md 为骨架系统讲解 lakeFS 垃圾回收Garbage Collection保留策略在 Java SDK 中的数据结构、API 调用方式与服务端实现原理。读完你将掌握如何通过RepositoriesApi读取、写入、删除仓库的 GC 规则理解default_retention_days与按分支规则branches的组合语义并能基于源码定位规则的实际存储与生效逻辑为数据湖对象存储成本治理提供可落地的配置方案。一、模型概览GC 规则由「全局默认 分支覆盖」两层组成GarbageCollectionRules是 lakeFS API版本 1.0.0中用于描述仓库级垃圾回收保留策略的 OpenAPI 模型它只有两个字段结构非常精炼名称类型说明必填defaultRetentionDaysInteger仓库内所有分支的默认保留天数是branchesListGarbageCollectionRule针对特定分支单独设置的保留规则列表是两个字段在 OpenAPI 规范中均被标记为 required见 openapi.yaml也就是说一个合法的 GC 规则对象必须同时包含默认保留天数与分支规则数组数组可为空。1.1 JSON 表示与 Java 属性的映射由于 SDK 由 OpenAPI Generator 自动生成HTTP 传输的 JSON 键名使用 snake_case而 Java 属性使用 camelCase{ default_retention_days: 30, branches: [ { branch_id: main, retention_days: 90 }, { branch_id: experiment, retention_days: 7 } ] }这一点在模型源码的SERIALIZED_NAME常量中有明确体现GarbageCollectionRules.javapublic static final String SERIALIZED_NAME_DEFAULT_RETENTION_DAYS default_retention_days; SerializedName(SERIALIZED_NAME_DEFAULT_RETENTION_DAYS) private Integer defaultRetentionDays; public static final String SERIALIZED_NAME_BRANCHES branches; SerializedName(SERIALIZED_NAME_BRANCHES) private ListGarbageCollectionRule branches new ArrayList();需要特别留意default_retention_days与branches都被加入openapiRequiredFields因此 SDK 反序列化时会强制校验这两个字段是否存在否则抛出IllegalArgumentException见 GarbageCollectionRules.java 中的validateJsonElement逻辑。二、分支级规则 GarbageCollectionRulebranches数组中的每个元素都是 GarbageCollectionRule该模型只有两个字段名称类型说明必填branchIdString分支标识branch ID是retentionDaysInteger该分支的保留天数是对应到 OpenAPI 定义openapi.yamlJSON 键名为branch_id与retention_days在 Java SDK 中则通过链式方法构建GarbageCollectionRule.javanew GarbageCollectionRule() .branchId(main) .retentionDays(90);三、在 Java SDK 中读写 GC 规则RepositoriesApi 实战GC 规则的读取与写入入口集中在RepositoriesApi中RepositoriesApi.java对应三个 REST 端点定义见 openapi.yaml方法HTTP 请求说明getGCRulesGET /repositories/{repository}/settings/gc_rules获取仓库 GC 规则返回GarbageCollectionRules200setGCRulesPUT /repositories/{repository}/settings/gc_rules覆盖式写入 GC 规则204无响应体deleteGCRulesDELETE /repositories/{repository}/settings/gc_rules删除 GC 规则204无响应体3.1 读取仓库 GC 规则完整可运行的示例来源RepositoriesApi.mdimport io.lakefs.clients.sdk.ApiClient; import io.lakefs.clients.sdk.ApiException; import io.lakefs.clients.sdk.Configuration; import io.lakefs.clients.sdk.auth.*; import io.lakefs.clients.sdk.RepositoriesApi; import io.lakefs.clients.sdk.model.GarbageCollectionRules; public class GetGCRulesExample { public static void main(String[] args) { ApiClient defaultClient Configuration.getDefaultApiClient(); defaultClient.setBasePath(https://lakefs.example.com/api/v1); // 配置 HTTP 基础认证用户名/密码或访问密钥对 HttpBasicAuth basic_auth (HttpBasicAuth) defaultClient.getAuthentication(basic_auth); basic_auth.setUsername(YOUR ACCESS KEY ID); basic_auth.setPassword(YOUR SECRET ACCESS KEY); // 也可以使用 cookie_authAPI Key或 jwt_tokenBearer Token认证 // ApiKeyAuth cookie_auth (ApiKeyAuth) defaultClient.getAuthentication(cookie_auth); // HttpBearerAuth jwt_token (HttpBearerAuth) defaultClient.getAuthentication(jwt_token); RepositoriesApi apiInstance new RepositoriesApi(defaultClient); String repository my-repo; // 仓库名称 try { GarbageCollectionRules result apiInstance.getGCRules(repository).execute(); System.out.println(默认保留天数: result.getDefaultRetentionDays()); result.getBranches().forEach(rule - System.out.println(分支 rule.getBranchId() 保留 rule.getRetentionDays() 天)); } catch (ApiException e) { System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); } } }3.2 写入覆盖GC 规则setGCRules的请求体即GarbageCollectionRules对象属于覆盖式语义——整份规则会被整体替换而不是增量合并示例来源RepositoriesApi.mdimport io.lakefs.clients.sdk.RepositoriesApi; import io.lakefs.clients.sdk.model.GarbageCollectionRule; import io.lakefs.clients.sdk.model.GarbageCollectionRules; // 构建规则默认保留 30 天main 分支保留 90 天feature-* 类临时分支保留 7 天 GarbageCollectionRules rules new GarbageCollectionRules() .defaultRetentionDays(30) .addBranchesItem(new GarbageCollectionRule().branchId(main).retentionDays(90)) .addBranchesItem(new GarbageCollectionRule().branchId(feature-data).retentionDays(7)); RepositoriesApi apiInstance new RepositoriesApi(defaultClient); String repository my-repo; try { apiInstance.setGCRules(repository, rules).execute(); System.out.println(GC 规则已更新); } catch (ApiException e) { System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); }值得注意的响应语义写入成功返回204 No Content400表示请求体校验失败、401未认证、403无权限、404仓库不存在、429请求过于频繁、0default表示服务端内部错误。3.3 删除 GC 规则apiInstance.deleteGCRules(repository).execute();删除同样返回 204。删除后仓库将回到未配置规则状态GC 运行前需要重新准备规则数据。3.4 旧版内部端点已废弃在 API 演进过程中/repositories/{repository}/gc/rules下的internalGetGarbageCollectionRules、internalSetGarbageCollectionRules、internalDeleteGarbageCollectionRules已被标记为Deprecated见 InternalApi.md官方建议改用前文的getGCRules/setGCRules/deleteGCRules。此外还提供了setGarbageCollectionRulesPreflightGET /repositories/{repository}/gc/rules/set_allowed用于预检当前用户是否有权限设置 GC 规则openapi.yaml。四、服务端实现规则如何存储与生效4.1 规则以 protobuf 形式存储在对象存储中GC 规则最终由服务端的GarbageCollectionManager持久化到与仓库同命名空间的对象存储上而不是 KV 数据库。从 garbage_collection_manager.go 可以看到其存储路径模板configFileSuffixTemplate %s/retention/gc/rules/config.json即规则文件位于对象存储的{committed_block_storage_prefix}/retention/gc/rules/config.json。SaveRules使用proto.Marshal序列化后调用blockAdapter.Put写入GetRules则读取该对象并proto.Unmarshal解析garbage_collection_manager.go。若文件不存在或为空返回graveler.ErrNotFound——这正是getGCRules接口返回 404 的底层原因。protobuf 消息定义位于 graveler.proto与 API 模型一一对应message GarbageCollectionRules { int32 default_retention_days 1; mapstring, int32 branch_retention_days 2; }注意服务端内部的branch_retention_days是map分支 ID → 保留天数而 API 层把它展开为branches数组——这个转换发生在 API 控制器中见下文。4.2 API 控制器与权限控制HTTP 端点对应的服务端实现位于 pkg/api/controller.goGetGCRules先通过authorize校验retention:GetGarbageCollectionRules权限再从c.Catalog.GetGarbageCollectionRules取出规则将内部 map 转换成apigen.GarbageCollectionRule{BranchId, RetentionDays}数组返回SetGCRules校验retention:SetGarbageCollectionRules权限后将请求体中的branches数组重新折叠回BranchRetentionDaysmap调用c.Catalog.SetGarbageCollectionRules持久化成功返回 204。对应的权限动作常量定义在 pkg/permissions/actions.goGetGarbageCollectionRulesAction retention:GetGarbageCollectionRules SetGarbageCollectionRulesAction retention:SetGarbageCollectionRules4.3 调用链全貌从 Java SDK 到规则落盘完整调用链为RepositoriesApi.getGCRules/setGCRules (Java SDK) → REST: /repositories/{repository}/settings/gc_rules → pkg/api/controller.go 中 Controller.GetGCRules / SetGCRules含权限校验 → pkg/catalog/catalog.go 的 Catalog.GetGarbageCollectionRules / SetGarbageCollectionRules → pkg/graveler/graveler.go 的 Graveler.GetGarbageCollectionRules / SetGarbageCollectionRules → retention.GarbageCollectionManager.GetRules / SaveRules → 对象存储 {prefix}/retention/gc/rules/config.jsonprotobuf 序列化其中Graveler层的实现非常薄graveler.go只是对GarbageCollectionManager的转发。五、保留天数如何决定对象生死active commits 算法GC 规则的价值最终体现在哪些 commit及其引用的对象是活跃的、可以被回收的计算上核心逻辑在 active_commits.go对每个起点 commit分支 HEAD 或游离 commit取保留天数优先查rules.BranchRetentionDays[branchID]查不到才回退到rules.DefaultRetentionDays见 L200-L218。这正是GarbageCollectionRules两段式设计的运行语义branches中命中的分支用分支自己的天数未命中的分支统一使用全局默认值。计算该分支的过期阈值now.AddDate(0, 0, -retentionDays)即当前时刻往前推 N 天L222。沿 commit 祖先链回溯凡是创建时间晚于阈值的 commit其父提交都会被标记为活跃跨越多条路径时取最长的过期阈值L234-L259。这样保证只要某 commit 仍在任一分支的保留期内它引用的对象就不会被回收。由此可以推断retentionDays 0的含义阈值等于当前时刻分支 HEAD 之后几乎不再有 commit 被标记为活跃等价于该分支历史对象尽快进入可回收状态——与 openapi.yaml 示例中default_retention_days: 0的取值语义一致。六、配套模型与进一步阅读GC 规则模型不是孤立存在的它与下列模型/API 共同构成 lakeFS GC 体系GarbageCollectionConfiggracePeriod宽限期单位为秒用于保护近期创建的对象不被收集属于 GC 的全局配置GarbageCollectionPrepareResponseprepare_commits接口的响应包含 GC run 的元数据RepositoriesApi.mdgetGCRules/setGCRules/deleteGCRules的完整文档与示例InternalApi.mdprepareGarbageCollectionCommits同步/异步、prepareGarbageCollectionUncommitted、internalGetGarbageCollectionRules等内部端点openapi.yamlGarbageCollectionRules与GarbageCollectionRule的 OpenAPI Schema 权威定义含 example服务端源码pkg/api/controller.go、pkg/graveler/graveler.go、pkg/graveler/retention/garbage_collection_manager.go、pkg/graveler/retention/active_commits.go、pkg/graveler/graveler.proto。七、实践建议与注意事项先读取再覆盖setGCRules是整体覆盖语义建议先getGCRules拉取现有规则在原有branches基础上追加或修改后再提交避免误删已有分支规则。明确默认值兜底为仓库设置合理的defaultRetentionDays使新分支自动纳入 GC 保护临时分支通过branches设置更短的保留天数可显著降低存储成本。注意 required 校验default_retention_days与branches均为必填构建请求体时二者缺一不可否则服务端会返回 400。权限最小化设置 GC 规则需要retention:SetGarbageCollectionRules权限读取需要retention:GetGarbageCollectionRules权限可通过setGarbageCollectionRulesPreflight预检后再发起写操作。配合宽限期若担心对象被过早回收可结合gracePeriod秒级为最近创建的对象设置保护窗口。通过本文你已经掌握了GarbageCollectionRules从 Java 对象构造、HTTP 调用到服务端 protobuf 落盘、再到 active commits 计算的全链路可以据此在业务代码中安全地自动化管理 lakeFS 仓库的 GC 保留策略。赞分享数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载相关推荐lakeFS Java SDK 中的 GarbageCollectionRule数据湖 GC 保留策略的数据模型与实战lakeFS Java SDK 中的 GarbageCollectionRule数据湖 GC 保留策略的数据模型与实战 本指南以 lakeFS 官方 Java数据工程数据湖大数据对象存储后端Relay 数据驻留与垃圾回收指南理解 presence-of-data、Query Retention 与 GC 策略Relay 数据驻留与垃圾回收指南理解 presence of data、Query Retention 与 GC 策略 Relay 在客户端内存 Store前端开发工具Relay 缓存数据的存续性理解 Relay 垃圾回收、Query Retention 与 GC 策略配置Relay 缓存数据的存续性理解 Relay 垃圾回收、Query Retention 与 GC 策略配置 Relay 的核心设计之一是内置的规范化缓存no前端开发工具上一篇3个场景教你轻松玩转B站视频批量下载BilibiliDown完整指南下一篇Minecraft RCON网页控制台5分钟搭建远程服务器管理平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
