ZenML Service Account API Keys 完全指南REST API 端点、轮换机制与 CLI 实战【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 通过「服务账户Service Account API Key」机制为自动化工作流CI/CD 流水线、定时任务、远程 Agent提供机器身份认证。本文基于开源仓库中 API Keys 参考文档 与其配套的 Rotate 参考文档结合服务端端点实现、数据模型与 CLI 源码完整讲解 API Key 的创建、查询、更新、删除与轮换Rotation五个核心操作以及底层模型字段、权限校验与密钥存储细节。读完本文你将能够通过curl或zenmlCLI 独立完成服务账户 API Key 的全生命周期管理。一、背景为什么需要服务账户与 API KeyZenML 是一个面向 MLOps 的端到端平台其 ZenML Server 通过 REST API 暴露所有功能。当 CI/CD 流水线、定时任务或远程 Agent 需要以机器身份而非交互式用户身份访问 ZenML Server 时服务账户Service Account与 API Key 就是标准认证方案服务账户一种机器身份实体隶属于服务账户体系见 Service Accounts 参考文档API Key绑定在某个服务账户之下的密钥凭据用于通过Authorization头或zenml login --api-key方式完成认证。从服务端路由定义看API Key 的全部端点都挂在服务账户资源之下路由前缀为/api/v1/service_accounts且APIRouter同时使用service_accounts与api_keys两个标签见 service_accounts_endpoints.py路径常量定义在 constants.py 与 constants.pyAPI_KEYS /api_keys API_KEY_ROTATE /rotate SERVICE_ACCOUNTS /service_accounts二、API 端点总览API Key 管理共包含6 个端点5 个位于主文档1 个轮换端点在配套文档中全部以/api/v1/service_accounts/{service_account_id}/api_keys为基路径方法路径用途GET/api/v1/service_accounts/{service_account_id}/api_keys列出某服务账户下的所有 API KeyPOST/api/v1/service_accounts/{service_account_id}/api_keys为服务账户创建新的 API KeyGET/api/v1/service_accounts/{service_account_id}/api_keys/{api_key_name_or_id}获取单个 API Key 详情PUT/api/v1/service_accounts/{service_account_id}/api_keys/{api_key_name_or_id}更新 API Key改名、改描述、启停用DELETE/api/v1/service_accounts/{service_account_id}/api_keys/{api_key_name_or_id}删除 API KeyPUT/api/v1/service_accounts/{service_account_id}/api_keys/{api_key_name_or_id}/rotate轮换重新生成API Key其中{service_account_id}为服务账户 UUID{api_key_name_or_id}既可以传 API Key 的名称也可以传其 UUID——从端点签名api_key_name_or_id: Union[str, UUID]可以看出二者皆被接受见 service_accounts_endpoints.py。所有端点均要求通过认证未认证请求统一返回401根据操作类型还可能返回404资源不存在、409冲突、422参数校验失败等错误码路由层通过responses{...}声明了这些错误响应同文件 L89-L95、L272-L275。三、核心数据模型请求、响应与内部编码在 api_key.py 中定义了整套 API Key 的 Pydantic 模型理解这些模型是正确调用 REST API 的前提。3.1 请求模型创建 API Key 的请求体APIKeyRequest仅有两个可选填字段见 api_key.py字段类型说明namestrAPI Key 名称必填最大长度受STR_FIELD_MAX_LENGTH限制descriptionOptional[str]描述信息可选最大长度受TEXT_FIELD_MAX_LENGTH限制更新 API Key 的请求体APIKeyUpdate支持三个可空字段见 api_key.py字段类型说明nameOptional[str]新的名称descriptionOptional[str]新的描述activeOptional[bool]是否启用设为false可立即吊销该 Key 的登录能力但保留记录3.2 响应模型的关键字段APIKeyResponse将字段拆分为 body、metadata、resources 三部分其中 body 与 metadata 暴露给 API 调用方body 部分见 api_key.pykey明文 API Key 值仅在创建或轮换后的响应中返回一次其余查询返回null——这与 CLI 提示「Please store it safely as it will not be shown again」完全一致active是否启用默认trueservice_account该 Key 所属的服务账户对象。metadata 部分见 api_key.pydescription描述retain_period_minutes轮换后旧 Key 的保留时长分钟last_login最近一次使用该 Key 登录的时间戳last_rotated最近一次轮换的时间戳。3.3 密钥的编码与存储底层原理API Key 并非明文存储。从源码看存在两套机制对外编码APIKey.encode()将{id, key}JSON 做 Base64 编码并加上ZENML_API_KEY_PREFIX前缀形成对外可见的密钥串decode_api_key()负责反向解析见 api_key.py。服务端存储APIKeyInternalResponse.verify_key()使用passlib的 bcrypt 方案CryptContext(schemes[bcrypt])校验密钥哈希并刻意在哈希缺失时仍执行一次校验以规避 CWE-204 响应差异攻击见 api_key.py。这也解释了为什么 API 文档反复强调明文 Key 只在创建/轮换时出现一次服务端只保留其哈希。四、端点逐个详解4.1 列出 API KeyGET .../api_keys参数路径参数service_account_id查询参数支持分页、排序与过滤。APIKeyFilter提供name、description、active、last_login、last_rotated等过滤条件并强制将查询范围限定在指定服务账户见 api_key.py。响应分页对象Page[APIKeyResponse]。默认hydratefalse即不包含 metadata 扩展字段。服务端逻辑见 service_accounts_endpoints.py先校验调用方对服务账户的READ权限再调用zen_store().list_api_keys()返回结果。示例curl -X GET https://ZENML_SERVER/api/v1/service_accounts/SA_ID/api_keys \ -H Authorization: Bearer ACCESS_TOKEN4.2 创建 API KeyPOST .../api_keys请求体APIKeyRequest即{ name: ..., description: ... }。响应APIKeyResponse且本次响应中的key字段包含完整的明文密钥串必须立即保存。服务端逻辑见 service_accounts_endpoints.py创建前会检查服务账户是否由外部认证external_user_id创建若是则抛出IllegalOperationError禁止为其关联 API Key同时要求调用方具备管理员权限无 RBAC 模式或相应 RBAC 权限。示例curl -X POST https://ZENML_SERVER/api/v1/service_accounts/SA_ID/api_keys \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {name: ci-runner-key, description: Key used by CI pipeline}4.3 获取单个 API KeyGET .../api_keys/{api_key_name_or_id}参数api_key_name_or_id支持名称或 UUIDhydrate查询参数控制是否返回 metadata 扩展字段默认true。注意该端点返回的key字段为null明文只在创建/轮换时可见。服务端逻辑见 service_accounts_endpoints.py先校验服务账户的READ权限再通过zen_store().get_api_key()获取。4.4 更新 API KeyPUT .../api_keys/{api_key_name_or_id}请求体APIKeyUpdate可组合更新name、description、active。典型用途将active设为false立即吊销某个泄露的 Key或为 Key 重新命名以反映其用途。服务端逻辑见 service_accounts_endpoints.py与创建一样会拦截外部认证创建的服务账户并校验服务账户的UPDATE权限。示例吊销 Keycurl -X PUT https://ZENML_SERVER/api/v1/service_accounts/SA_ID/api_keys/my-key \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {active: false}4.5 删除 API KeyDELETE .../api_keys/{api_key_name_or_id}参数api_key_name_or_id无请求体成功返回204。服务端逻辑见 service_accounts_endpoints.py校验调用方为管理员无 RBAC 模式或具备服务账户UPDATE权限随后从 ZenStore 删除。删除操作立即生效使用该 Key 的客户端将立刻认证失败。4.6 轮换 API KeyPUT .../api_keys/{api_key_name_or_id}/rotate轮换是 API Key 管理的核心安全操作配套文档 rotate.md 单独记录了该端点。请求体APIKeyRotateRequest仅一个字段retain_period_minutes默认0表示轮换后旧 Key 继续有效的分钟数见 api_key.py。设为0表示立即作废旧 Key。响应APIKeyResponsekey字段为新生成的明文密钥需立即保存。服务端逻辑见 service_accounts_endpoints.py同样拦截外部认证服务账户并校验UPDATE权限后调用zen_store().rotate_api_key()。轮换的底层语义见 api_key.py内部模型维护key_generation当前代次与previous_key上一代密钥哈希。轮换后新密钥成为当前代key_generation 1旧密钥在retain_period_minutes窗口内仍可认证实现零停机轮换先轮换、再分批更新各客户端、最后等窗口过期is_previous_key_retained()判断旧代是否仍在保留窗口内verify_key()会同时校验当前代与保留期内的上一代。轮换示例保留 30 分钟旧 Keycurl -X PUT https://ZENML_SERVER/api/v1/service_accounts/SA_ID/api_keys/my-key/rotate \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d {retain_period_minutes: 30}五、权限与合规约束调用上述端点时需注意两类约束见 service_accounts_endpoints.py外部认证限制当 ZenML Server 配置为外部认证AuthScheme.EXTERNAL时工作区级服务账户的变更操作创建/更新/删除 API Key、轮换会被_ensure_workspace_service_account_mutation_allowed()直接拦截提示改用组织级服务账户外部认证创建的服务账户external_user_id非空也不能挂载 API Key。权限要求无 RBAC 模式下创建、更新、删除、轮换均要求调用方为管理员is_adminRBAC 模式下则由verify_permissions_and_create_entity、verify_permission_for_model等工具按资源类型ResourceType.SERVICE_ACCOUNT与动作READ/UPDATE/DELETE细粒度校验见 service_accounts_endpoints.py。六、CLI 实战更便捷的管理方式REST API 之外ZenML CLI 在 service_accounts.py 中提供了等价的命令组适合日常运维。命令统一以zenml service-account api-key为前缀服务账户名称或 ID 作为位置参数传入。操作命令关键选项创建zenml service-account api-key create SA NAME-d/--description--set-key将新 Key 直接配置到本地客户端--output-file写入文件查看zenml service-account api-key describe SA NAME_OR_ID输出会排除key字段避免泄露明文列表zenml service-account api-key list SA支持--columns与多种输出格式table/json/yaml/csv/tsv更新zenml service-account api-key update SA NAME_OR_ID--name、--description、--active轮换zenml service-account api-key rotate SA NAME_OR_ID--retain 分钟--set-key--output-file删除zenml service-account api-key delete SA NAME_OR_ID-y/--yes跳过确认轮换并立即配置本地客户端见 service_accounts.pyzenml service-account api-key rotate my-sa my-key --retain 30 --set-key执行后 CLI 会调用client.set_api_key()将新 Key 写入本地配置仅当当前客户端连接的是 ZenML Server 的 REST Store 时可用未使用--set-key/--output-file时会在终端打印新 Key 值并提示使用zenml login URL --api-key完成登录见 service_accounts.py。七、最佳实践小结一次性保存明文key明文只在创建与轮换响应中出现务必通过--output-file写入安全存储或立即配置到密钥管理器零停机轮换轮换时设置合理的retain_period_minutes过渡窗口先轮换再依次更新各消费方最后等待旧 Key 自然过期快速吊销怀疑泄露时优先PUT将active置为false保留审计记录确认后彻底DELETE身份隔离为不同 CI 任务、不同环境各建独立服务账户与 Key配合APIKeyFilter的last_login字段审计使用情况。以上全部端点行为均可通过 service_accounts_endpoints.py、api_key.py 与 service_accounts.py 三个源码文件逐一印证API 参考文档本身位于 README.md 与 rotate.md。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考