lakeFS Rust SDK 内部管理 API（InternalApi）深度指南：从安装引导到垃圾回收与分支保护

• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端

lakeFS 官方维护的 Rust 客户端lakefs_sdk（由 OpenAPI Generator 生成）除了提供面向业务开发的公共 API（分支、提交、对象、标签等），还内置了一组被明确标记为internal的管理端点，集中封装在InternalApi中。本文以 clients/rust/docs/InternalApi.md 为骨架，结合 Rust 生成代码、OpenAPI 定义（api/swagger.yml）与 Go 服务端实现（pkg/api/controller.go），系统讲解这 20 个端点的用途、参数、返回类型、认证方式与底层原理，帮助你掌握安装引导、垃圾回收（GC）协调、分支保护规则、仓库元数据、refs 备份恢复、对象暂存等运维与集成能力。

一、InternalApi 是什么：被标记为 internal 的管理端点集合

在 lakeFS 的 API 设计中，InternalApi对应 OpenAPI 定义中tags: internal的一组端点。与BranchesApi、ObjectsApi、RepositoriesApi等面向数据操作的 API 不同，InternalApi主要服务于安装引导、系统配置、垃圾回收、备份恢复、统计上报等运维管理场景，其中不少端点被设计为仅供 lakeFS 自身服务流程调用，SDK 文档也明确注明如 "this endpoint is meant for internal use only"（post_stats_events）。

从 clients/rust/docs/InternalApi.md 的方法清单看，全部 20 个端点的 URL 均以/api/v1为基础路径：

注意：同一份 OpenAPI 定义还会生成其他语言客户端的同名文档（如 clients/python、clients/java），本文聚焦 Rust SDK 的InternalApi实现。

二、在 Rust 项目中引入 lakefs_sdk 并构造配置

2.1 依赖引入

Rust 客户端使用 crate 名lakefs_sdk。根据 clients/rust/README.md，将包放入项目目录后，在Cargo.toml的[dependencies]中加入：

[dependencies] lakefs_sdk = { path = "./lakefs_sdk" }

生成的代码基于reqwest异步 HTTP 客户端，因此所有InternalApi函数均为async fn，需要在异步运行时（如tokio）中调用。

2.2 Configuration 与三种认证方式

InternalApi的每个函数第一个参数都是&configuration::Configuration。从 clients/rust/src/apis/configuration.rs 可以看到其结构与默认值：

pub struct Configuration { pub base_path: String, // 默认 "/api/v1" pub user_agent: Option<String>, // 默认 "OpenAPI-Generator/1.0.0/rust" pub client: reqwest::Client, pub basic_auth: Option<BasicAuth>, // Basic Auth 用户名 + 可选密码 pub oauth_access_token: Option<String>, pub bearer_access_token: Option<String>, // Bearer Token（如 JWT） pub api_key: Option<ApiKey>, }

原文档中几乎所有方法（除get_setup_state、setup、setup_comm_prefs外）都声明了相同的三种授权方式：

• basic_auth：HTTP Basic 认证，对应Configuration.basic_auth，SDK 通过req_builder.basic_auth(...)注入请求头；
• cookie_auth：基于 Cookie 的会话认证；
• jwt_token：Bearer Token 认证，对应Configuration.bearer_access_token，SDK 通过req_builder.bearer_auth(...)注入请求头。

调用示例（获取服务端版本并查询 GC 配置）：

use lakefs_sdk::apis::{configuration::Configuration, internal_api}; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let mut conf = Configuration::new(); conf.base_path = "http://localhost:8000/api/v1".to_owned(); conf.basic_auth = Some(("YOUR_ACCESS_KEY".to_owned(), Some("YOUR_SECRET_KEY".to_owned()))); let version = internal_api::get_lake_fs_version(&conf).await?; println!("lakeFS version: {:?}", version); let gc_config = internal_api::get_garbage_collection_config(&conf).await?; println!("GC config: {:?}", gc_config); Ok(()) }

2.3 统一的请求头与错误处理

从 clients/rust/src/apis/internal_api.rs 的实现可以看出，所有函数都遵循同一套模板：构造 URL → 注入 User-Agent → 注入认证头 → （可选）序列化 JSON body → 执行请求 → 非 4xx/5xx 时反序列化响应，否则构造Error::ResponseError。每个函数还对应一个#[serde(untagged)]的枚举类型，用于描述可能的错误状态，例如：

pub enum SetupError { Status400(models::Error), Status409(models::Error), // setup 已被调用过 Status429(), DefaultResponse(models::Error), UnknownValue(serde_json::Value), }

这意味着你可以用模式匹配精确处理 HTTP 状态码对应的业务错误，而不是笼统地接收字符串。

三、安装引导三件套：get_setup_state / setup / setup_comm_prefs

这是三个无需认证（文档标注 "No authorization required"）的端点，用于 lakeFS 的首次初始化流程。

3.1 get_setup_state：检查安装状态

GET /setup_lakefs

• 参数：无
• 返回：models::SetupState（模型定义见 clients/rust/src/models/setup_state.rs）

pub struct SetupState { pub state: Option<State>, // initialized | not_initialized pub comm_prefs_missing: Option<bool>, // 通信偏好是否缺失 pub login_config: Option<Box<models::LoginConfig>>, }

在 OpenAPI 定义（api/swagger.yml）中该端点响应 200 返回SetupState，另有 429（请求过多）。典型用法：客户端在 UI 或 CLI 启动时先调用它判断服务端是否已经初始化，再决定是否进入 setup 流程。

3.2 setup：创建第一个用户

POST /setup_lakefs

• 参数：setup: models::Setup（必需），模型见 clients/rust/src/models/setup.rs
• 返回：models::CredentialsWithSecret（含生成的访问密钥与密钥对）

Setup模型的字段与 OpenAPI 定义一致：

从 swagger.yml 定义看，POST /setup_lakefs成功返回 200CredentialsWithSecret，若初始化已被调用过则返回 409（setup was already called）。Go 服务端对应 pkg/api/controller.go 中的Setup方法，负责创建首个用户并返回一次性访问凭据。

3.3 setup_comm_prefs：设置通信偏好

POST /setup_comm_prefs

• 参数：comm_prefs_input: models::CommPrefsInput（必需）
• 返回：空响应体

同样无需认证，对应服务端 controller.go 的SetupCommPrefs。结合SetupState.comm_prefs_missing字段，可以判断安装后是否还缺少通信偏好配置，从而补全初始化流程。

四、服务器配置与版本信息查询

这一组 GET 端点均需要认证，用于在集成时探测服务端能力。

在 pkg/api/controller.go 中分别对应GetStorageConfig（L1852）、GetGarbageCollectionConfig（L5529）、GetUsageReportSummary（L6037）等实现。这类端点常用于客户端在启动时做能力协商：例如读取StorageConfig判断是否支持预签名 URL，从而决定走直传还是经服务端代理的写路径。

五、垃圾回收（GC）协调 API：InternalApi 的重头戏

lakeFS 的垃圾回收需要先由服务端把"活跃引用"整理成数据集，再由独立的 GC 任务消费。InternalApi中围绕 GC 提供了完整的准备/查询/规则管理端点。

5.1 prepare_garbage_collection_commits：同步准备活跃 commit 列表

POST /repositories/{repository}/gc/prepare_commits

• 参数：repository: String（路径参数，必需）
• 返回：models::GarbageCollectionPrepareResponse，字段见 garbage_collection_prepare_response.rs：

pub struct GarbageCollectionPrepareResponse { pub run_id: String, // 本次 GC job 的唯一标识 pub gc_commits_location: String, // commits CSV 表位置（按 run_id 分区） pub gc_addresses_location: String, // 过期地址 parquet 表位置（按 run_id 分区） pub gc_commits_presigned_url: Option<String>, // 下载 commits CSV 的预签名 URL }

Go 服务端实现（controller.go）清晰展示了调用链：

1. 先校验权限PrepareGarbageCollectionCommitsAction；
2. 调用c.Catalog.PrepareExpiredCommits(ctx, repository)生成 commits CSV 与地址位置；
3. 通过c.BlockAdapter.GetPreSignedURL(...)生成预签名下载地址（若失败仅告警，不影响响应）；
4. 返回 201GarbageCollectionPrepareResponse。

在 swagger.yml 中该端点响应 201（"paths to commit dataset"），错误包括 400/401/403/404/429。

5.2 prepare_garbage_collection_commits_async 与 status：异步版本

对于大型仓库，同步准备可能耗时较长，因此提供了异步任务版本：

POST /repositories/{repository}/gc/prepare_commits/async GET /repositories/{repository}/gc/prepare_commits/status?id={id}

• prepare_garbage_collection_commits_async(repository)返回models::TaskCreation（含任务id），服务端立即响应 202（见 controller.go，内部调用c.Catalog.PrepareExpiredCommitsAsync）；
• prepare_garbage_collection_commits_status(repository, id)通过查询参数id（"Unique identifier of the prepare GC commits task"）查询任务进度，返回models::PrepareGarbageCollectionCommitsStatus（模型见 prepare_garbage_collection_commits_status.rs）。

推荐的 GC 集成流程：

1. 调用prepare_garbage_collection_commits_async拿到task_id；
2. 轮询prepare_garbage_collection_commits_status直到任务完成；
3. 通过预签名 URL 拉取 commits 数据集，交给 GC 任务消费。

5.3 prepare_garbage_collection_uncommitted：保存未提交元数据

POST /repositories/{repository}/gc/prepare_uncommited

• 参数：prepare_gc_uncommitted_request: Option<models::PrepareGcUncommittedRequest>（可选 body，模型见 prepare_gc_uncommitted_request.rs）
• 返回：models::PrepareGcUncommittedResponse（模型见 prepare_gc_uncommitted_response.rs）

注意 URL 中 "uncommitted" 在服务端定义为prepare_uncommited（少一个 t），调用时以文档/代码实际路径为准。服务端实现见 controller.go 的PrepareGarbageCollectionUncommitted，用于清理未提交对象占用的物理空间。

5.4 已废弃的 GC 规则管理端点与迁移

InternalApi中还保留了一组旧版 GC 规则端点，文档明确标注Deprecated：

• internal_get_garbage_collection_rules(repository)返回models::GarbageCollectionRules；
• internal_set_garbage_collection_rules(repository, garbage_collection_rules)接收models::GarbageCollectionRules（模型见 garbage_collection_rules.rs），返回空响应；
• internal_delete_garbage_collection_rules(repository)返回空响应。

从 clients/rust/README.md 的端点清单可以看到，新的 GC 规则管理已迁移到RepositoriesApi：get_gc_rules（GET /repositories/{repository}/settings/gc_rules）、set_gc_rules（PUT ...）、delete_gc_rules（DELETE ...）。新代码应优先使用RepositoriesApi的对应方法。

5.5 权限预检：set_garbage_collection_rules_preflight

GET /repositories/{repository}/gc/rules/set_allowed

• 参数：repository: String（必需）
• 返回：空响应体

用于在真正设置 GC 规则前校验当前用户权限（服务端返回 204 表示"有权"），避免因权限不足导致写操作失败。同类预检还有create_branch_protection_rule_preflight（GET /repositories/{repository}/branch_protection/set_allowed）。

六、分支保护规则管理

分支保护用于阻止对特定分支的写操作。InternalApi中提供了预检、创建、删除、查询四个端点，其中后三个已在 swagger.yml 中标记deprecated: true（api/swagger.yml）。

参数与返回：

• internal_create_branch_protection_rule(repository, branch_protection_rule)：body 为models::BranchProtectionRule，其唯一字段是pattern: String，语义为 "fnmatch pattern for the branch name, supporting*and?wildcards"（见 branch_protection_rule.rs）；
• internal_get_branch_protection_rules(repository)：返回Vec<models::BranchProtectionRule>；
• internal_delete_branch_protection_rule(repository, internal_delete_branch_protection_rule_request)：body 为models::InternalDeleteBranchProtectionRuleRequest（模型见 internal_delete_branch_protection_rule_request.rs）。

与 GC 规则类似，新的分支保护规则管理已迁移到RepositoriesApi的set_branch_protection_rules/get_branch_protection_rules（路径为/repositories/{repository}/settings/branch_protection），新代码应优先使用后者。

七、仓库元数据与对象暂存

7.1 set_repository_metadata / delete_repository_metadata

POST /repositories/{repository}/metadata DELETE /repositories/{repository}/metadata

• set_repository_metadata(repository, repository_metadata_set)：body 为models::RepositoryMetadataSet（模型见 repository_metadata_set.rs）。服务端语义（见 controller.go）为：只新增或更新给定 key，不会移除已有 key；
• delete_repository_metadata(repository, repository_metadata_keys)：body 为models::RepositoryMetadataKeys（模型见 repository_metadata_keys.rs），删除指定 key。

两者均返回空响应体，Content-Type: application/json，Accept: application/json。

7.2 get_metadata_object：按 ID 获取元数据对象

GET /repositories/{repository}/metadata/object/{type}/{object_id}

参数：

返回std::path::PathBuf（预签名 URL 或本地临时路径），Accept为application/octet-stream, application/json。对应服务端实现见 controller.go。

7.3 create_commit_record

POST /repositories/{repository}/commits

• 参数：repository: String、commit_record_creation: models::CommitRecordCreation（必需）
• 返回：空响应体

对应服务端 controller.go 的CreateCommitRecord。注意它不同于CommitsApi面向业务的分支提交（POST /repositories/{repository}/branches/{branch}/commits），这里直接向仓库写入 commit record，属于内部数据维护路径。

7.4 stage_object：暂存对象元数据

PUT /repositories/{repository}/branches/{branch}/objects?path={path}

• 路径参数：repository、branch（均 required）；
• 查询参数：path（"relative to the branch"，必需）；
• body：models::ObjectStageCreation（必需）；
• 返回：models::ObjectStats（模型见 object_stats.rs）。

ObjectStageCreation的字段（见 object_stage_creation.rs）：

该端点允许客户端绕过"上传再链接"的两段式流程，直接把已存在于对象存储中的对象登记到分支上，是数据导入、元数据回填类工具的核心入口。配套的upload_object_preflight（GET /repositories/{repository}/branches/{branch}/objects/stage_allowed?path={path}）用于在暂存前校验写权限，返回空响应体。

7.5 create_symlink_file：生成 symlink 文件

POST /repositories/{repository}/refs/{branch}/symlink?location={location}

• 路径参数：repository、branch（均 required）；
• 查询参数：location: Option<String>，描述为 "path to the table data"；
• 返回：models::StorageUri（模型见 storage_uri.rs）。

该端点面向 Spark/Deltalake 等"表数据目录 + symlink manifest"场景。服务端实现（controller.go）的流程是：读取仓库 →c.Catalog.ListEntries分页列出location下的全部条目 → 按目录分组收集物理地址 → 调用writeSymlink为每个目录生成symlink.txt（内容为按行排列的物理地址，写入路径形如<lakefs_prefix>/<repo>/<branch>/<path>/symlink.txt）→ 返回 201 与StorageURI{location}。代码中响应结构为apigen.StorageURI { Location: metaLocation }，其中 metaLocation 指向仓库命名空间下 lakeFS 前缀位置。

八、refs 备份与恢复：dump_refs / restore_refs

这两个端点用于仓库元数据（tags、commits、branches）的导出与恢复，文档均标注Deprecated: a new API will introduce long running operations。

RefsDump包含三个 meta-range ID（见 refs_dump.rs）：

pub struct RefsDump { pub commits_meta_range_id: String, pub tags_meta_range_id: String, pub branches_meta_range_id: String, }

即导出结果分别以三个 metarange 的形式落在对象存储中；restore_refs通过RefsRestore（模型见 refs_restore.rs）引用这些 metarange 恢复仓库。服务端实现见 controller.go（DumpRefs）与 L4080（RestoreRefs）。

从 clients/rust/README.md 可知，新一代长任务 API 已经出现在RepositoriesApi中：dump_submit/dump_status/restore_submit/restore_status（路径/repositories/{repository}/dump与/repositories/{repository}/restore）。备份恢复场景应迁移到这些新端点。

九、统计上报：post_stats_events

POST /statistics

• 参数：stats_events_list: models::StatsEventsList（必需）
• 返回：空响应体

文档明确注明 "post stats events, this endpoint is meant for internal use only"。服务端实现见 controller.go 的PostStatsEvents。模型 stats_events_list.rs 与 stats_event.rs 定义了事件列表结构。该端点通常由 lakeFS 自身的统计收集器使用，普通业务代码不应依赖。

十、常见调用模式与注意事项

1. 认证差异：get_setup_state、setup、setup_comm_prefs三个端点无需认证；其余端点需要basic_auth/cookie_auth/jwt_token之一。setup只在get_setup_state返回not_initialized时可调用，重复调用会得到 409。
2. 请求头差异：带 body 的写操作（setup、set_repository_metadata、stage_object、internal_set_garbage_collection_rules、create_commit_record、restore_refs等）要求Content-Type: application/json；get_metadata_object的Accept为application/octet-stream, application/json；get_usage_report_summary的Accept为application/json, application/text；其余大多数端点Accept: application/json。
3. 废弃端点识别：文档/OpenAPI 定义中deprecated的端点（internal_get/set/delete_garbage_collection_rules、internal_get/create/delete_branch_protection_rule、dump_refs、restore_refs）会被更成熟的RepositoriesApi端点取代，集成时注意版本兼容。
4. Rust 关键字处理：get_metadata_object的参数名为r#type，调用时写作r#type: "commits"即可。
5. 异步任务轮询：使用prepare_garbage_collection_commits_async后，务必保存返回的TaskCreation.id，用于后续prepare_garbage_collection_commits_status(repository, id)查询。

总结

InternalApi是 lakeFS Rust SDK 中面向运维与内部集成的完整管理面：从首次部署的setup三件套，到 GC 的同步/异步准备与状态查询，再到分支保护、仓库元数据、对象暂存、refs 备份恢复与统计上报。结合 clients/rust/src/apis/internal_api.rs 的生成实现、api/swagger.yml 的契约定义与 pkg/api/controller.go 的服务端逻辑，可以确认每个端点的参数、返回模型、状态码与底层行为。建议在使用时留意文档标注的废弃信息，及时迁移到RepositoriesApi中对应的新端点（GC 规则、分支保护规则、dump/restore 长任务），以获得长期兼容性。

• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端