mirrord CI API Key 使用策略详解：keyless CI、MIRRORD_CI_API_KEY 与三种凭据场景

开发工具云原生CLI【免费下载链接】mirrordRun any process, on your machine or in an AI agents environment, as if it were a pod in your Kubernetes cluster: real env vars, DNS, network, traffic.项目地址https://gitcode.com/gh_mirrors/mi/mirrord点击查看免费下载导读本文以 mirrord 仓库的变更记录 changelog.d/ci-api-key-help.fixed.md 为主线完整梳理mirrord ci start与mirrord ci container在什么情况下必须配置MIRRORD_CI_API_KEY、什么情况下可以免 key 使用自动普通凭据keyless CI并对照 CLI、认证与 Operator 源码解释凭据选择、错误诊断与 CI 集成实战配置。读完本文你将能在 Free Operator、付费/旧版 Operator、无 Operator 三种集群环境下准确判断 CI 会话的凭据要求避免 CI 管道因缺失 API Key 而失败。变更背景修正的是帮助信息反映的是真实的凭据策略该 changelog 片段属于.fixed.md类型记录了一次针对 CI 命令帮助文本的修正Corrected CI command help:mirrord ci startandmirrord ci containeruse automatic ordinary credentials without a CI API key when a supporting Free operator advertises keyless CI; other operator-backed CI sessions require a CI API key. No-operator sessions and localmirrord ci stopdo not require one.翻译过来即修正了 CI 命令的帮助说明——当受支持的 Free Operator 广告advertisekeyless CI 能力时mirrord ci start与mirrord ci container可以不提供 CI API Key自动使用普通凭据automatic ordinary credentials而其他由 Operator 支撑的 CI 会话必须提供 CI API Key无 Operator 的会话以及本地的mirrord ci stop则都不需要。虽然变更表面上是帮助文本但它精确描述了 mirrord 的 CI 凭据分发策略。这份策略同时体现在四个层面命令行定义mirrord/cli/src/config/ci.rs、连接校验mirrord/cli/src/connection.rs、错误诊断mirrord/cli/src/ci/error.rs以及集成测试mirrord/cli/tests/ci_credentials.rs。理解前提mirrord for CI 的会话模型与凭据来源mirrord 的 CI 集成mirrord for CI允许 CI runner 在本机以仿佛运行在集群 Pod 内的方式启动被测服务从而在共享 staging 环境上进行端到端测试而无需为每次 CI 运行临时搭建和销毁整套测试环境。相关命令簇定义在 mirrord/cli/src/config/ci.rsmirrord ci api-key向 Operator 申请一个 CI API KeyCiApiKey要求 Operator 已安装且许可有效mirrord ci start启动一个 CI 会话参数与mirrord exec相同并附加 CI 专用选项mirrord ci container在本地容器运行时如 Docker、podman内启动 CI 会话mirrord ci stop停止该 CI job 的所有 CI 会话只依赖本地保存的进程状态。其中mirrord ci start与mirrord ci container共享的公共参数CiCommonArgs包括参数含义示例--foreground前台运行默认后台任务--foreground--environmentCI 环境名--environment staging--pipelineCI 管道或 job 名--pipeline e2e-tests--triggered-byCI 触发来源--triggered-by pull requestOperator 是集群内负责创建 agent、管理会话与许可的组件。凭据的选择取决于集群里是否有 Operator、Operator 的许可类型以及它对外广告的supported_features。三种凭据场景一张决策表根据变更记录与源码中的诊断文案CI 凭据需求可以归纳为如下三种场景场景是否配置MIRRORD_CI_API_KEY使用的凭据依据受支持的 Free Operator 广告了KeylessCi能力可选不配置也能运行自动普通凭据ordinary credentialsmirrord/cli/src/config/ci.rs其他 Operator 支撑的 CI 会话付费/旧版许可必须取值为mirrord ci api-key的输出CI API KeyCiApiKeymirrord/cli/src/ci/error.rs无 Operator 的会话不需要不涉及 Operator 凭据mirrord/cli/src/config/ci.rs本地mirrord ci stop不需要本地保存的进程状态mirrord/cli/src/config/ci.rs场景一Free Operator 广告 keyless CI —— 免 Key 自动普通凭据当集群中的 Operator 以 Free 许可运行并在MirrordOperator.status.supported_features中广告KeylessCi特性时mirrord ci start/mirrord ci container可以不设置MIRRORD_CI_API_KEYCLI 会走普通用户凭据路径with_client_certificate自动向 Operator 申请一份 ordinary credentials。这一点在CiCommand的帮助注释中写得很直白With a Free operator that advertises keyless CI,MIRRORD_CI_API_KEYis optional; ordinary credentials are automatic.The operator enforces its license policy for CI credentials.场景二其他 Operator 支撑的会话 —— 必须提供 CI API Key对于付费许可或旧版 Operator不广告KeylessCi缺失MIRRORD_CI_API_KEY会导致命令在凭据签发与会话准备之前就失败错误为MissingCiApiKeyMIRRORD_CI_API_KEYis required for operator-backedmirrord ci startandmirrord ci containerwhen the operator does not advertise keyless CI.诊断帮助mirrord/cli/src/ci/error.rs会引导用户Set this environment variable to the value received frommirrord ci api-key. Supporting Free operators advertise keyless CI and use automatic ordinary credentials. Without the operator, no CI API key is required. Localmirrord ci stoprequires no API key.注意KeylessCi是一个Free 许可专属例外。在 mirrord/operator/src/crd.rs 的NewOperatorFeature枚举注释中明确写道[KeylessCi] is a Free-only exception: paid and legacy licenses require CI API keys for explicit CI sessions.也就是说Free 许可允许免 Key 的显式 CI 会话而付费与旧版许可的显式 CI 会话必须携带 CI API Key。场景三无 Operator 会话与本地mirrord ci stop—— 均不需要 Key没有 Operator 时mirrord ci start/mirrord ci container走无 Operator 路径不需要任何 API Key帮助文本Without the operator, no API key is requiredmirrord ci stop读取本地保存的MirrordCiStoreintproxy pid、extproxy pid、sidecar pid、sidecar 容器、用户进程组等默认位于{temp_dir}/mirrord/mirrord-for-ci.json据此终止相关进程完全不接触 Operator因此也不需要任何凭据。这也体现在测试ci_stop_help_does_not_require_a_keymirrord/cli/src/config/ci.rs中mirrord ci stop --help的帮助文本包含 no API key is required且不提及MIRRORD_CI_API_KEY。源码纵深CLI 如何决定使用哪种凭据1. 环境变量的读取与解析MIRRORD_CI_API_KEY常量定义于 mirrord/cli/src/ci.rs读取逻辑ci_api_key_availablemirrord/cli/src/ci.rs将其解码为CiApiKey变量未设置NotPresent→ 返回Ok(None)即未提供 Key变量值不是合法 Unicode → 返回CiError::EnvVar帮助文案同样说明三种场景变量值存在 → 调用CiApiKey::decode解析格式非法时立即报错不会回退到普通凭据。2. 连接阶段的强制检查关键决策点在 mirrord/cli/src/connection.rsif mirrord_for_ci.is_some_and(|ci| ci.api_key().is_none()) api .operator() .spec .supported_features() .contains(NewOperatorFeature::KeylessCi) .not() { return Err(CiError::MissingCiApiKey.into()); }逻辑非常清晰只要这是 CI 会话mirrord_for_ci存在、没有提供 API Key、且 Operator 广告的能力中不含KeylessCi就直接以MissingCiApiKey终止——这是在凭据签发credential issuance或会话准备session preparation之前的 fail-fast 校验避免白跑一轮再报错。3. 凭据的两种获取路径通过校验后mirrord/cli/src/connection.rs 按是否携带 Key 分派提供了 Keyapi.with_ci_api_key(...)直接使用CiApiKey内含的证书未提供 Keykeylessapi.with_client_certificate(...)走普通凭据签发路径。而MirrordCi::api_key()mirrord/cli/src/ci.rs只是把OptionCiApiKey暴露给上层MirrordCiStore本身不持久化 API Key——Key 只以环境变量形式存在于 CI 进程中mirrord/cli/src/ci.rs 的注释明确说明it doesnotstore theCiApiKey, this one lives only as an env var。4.KeylessCi能力如何被广告NewOperatorFeature::KeylessCi定义于 mirrord/operator/src/crd.rs属于新增特性枚举旧客户端无法识别的变体会反序列化为Unknown不会导致失败。它通过MirrordOperator.status.supported_features暴露给客户端而特性广告的过滤由许可层级自动完成Free 许可在允许列表中显式包含KeylessCi付费/旧版许可则不含。生成 CI API Keymirrord ci api-key与 V1 编码格式对于需要 Key 的 Operator 环境先执行mirrord ci api-key生成 Key。其实现位于 mirrord/cli/src/ci.rs解析配置可用--config-file指定默认./.mirrord/mirrord.json通过OperatorApi::try_new发现集群中的 Operator找不到则报OperatorNotInstalledcheck_license_validity校验许可生成 CI 凭据需要 Enterprise 许可调用 Operator 的POST /mirrordclusteroperatorusercredentials接口create_ci_api_key创建 Key将 Key 打印到终端并提示mirrord CI API key: {api_key} Please store this securely! To use it in your CI/CD system, set it as the value of the MIRRORD_CI_API_KEY environment variable.CiApiKey本身是一个版本化容器mirrord/auth/src/credentials.rs当前只有V1(Credentials)变体——V1 携带的数据与普通Credentials本地KeyPair Operator 签发的Certificate完全一致。V1 的编码流程mirrord/auth/src/credentials.rs为用bincodestandard config序列化Credentials用zlib以最高压缩级别9压缩用 URL-safe 且无 padding 的 base64 编码加上前缀mci-v1:常量 V1_PREFIX。解码过程mirrord/auth/src/credentials.rs按前缀识别版本后逆序还原。单元测试v1_ci_api_key_encode_decodemirrord/auth/src/credentials.rs用一段固定样本验证了编解码往返一致其签发者 CN 为 API Key Unit Tests Enterprise License佐证了 CI Key 与 Enterprise 许可绑定的设计。此外mirrord/auth/src/credentials.rs 的注释强调CI 凭据由Credentials::init_ci生成后只存在于用户的 CI 环境中不会写入本地凭据存储credential store而普通用户凭据的refresh永远走regular路径——两者生命周期彻底分离。实战配置三种环境下 CI 管道的正确写法无 Operator开源 mirrord 直接连集群# 无需 MIRRORD_CI_API_KEY mirrord ci start --target deployment/ip-visit-counter go run ip-visit-counter.go # 测试完成后停止本地状态清理同样不需要 Key mirrord ci stopFree Operator 广告 keyless CI# 不设置 MIRRORD_CI_API_KEY自动使用普通凭据 mirrord ci start --target deployment/ip-visit-counter -- go test ./...付费/旧版 Operator必须提供 Key# 1. 生成 Key需要 Enterprise 许可 mirrord ci api-key # 2. 在 CI 平台的 secret 中配置环境变量例如 GitHub Actions # env: # MIRRORD_CI_API_KEY: ${{ secrets.MIRRORD_CI_API_KEY }} # 3. 启动会话 mirrord ci start --target deployment/ip-visit-counter go run ip-visit-counter.gomirrord ci container在容器运行时内使用mirrord/mcp/corpus/docs/use-cases/mirrord-for-ci.mdmirrord ci container -- docker run my-image凭据规则与mirrord ci start完全一致mirrord/cli/src/config/ci.rs。测试验证凭据选择行为被集成测试锁定mirrord/cli/tests/ci_credentials.rs 用模拟 Operatoraxum 假服务验证了三种行为ci_commands_preserve_credentials_and_metadata当supported_features含KeylessCi时未提供 Key 的start/container会提交kind: regular的凭据请求并复用缓存的普通凭据而携带 Key 时则直接使用 Key 内含证书、不创建本地凭据缓存。测试同时断言会话元数据environment、pipeline、triggeredBy在两种路径下都被正确传递。missing_ci_key_requires_advertised_capabilityOperator 不广告KeylessCi能力缺失、旧版features字段或字段完全省略时未提供 Key 的命令输出 MIRRORD_CI_API_KEYis required ... does not advertise keyless CI且不会发起任何凭据请求。malformed_ci_key_does_not_fall_back_to_ordinary_credentials即使 Operator 支持 keylessMIRRORD_CI_API_KEY值非法如malformed-ci-key或空串也会直接报 invalid api key format 失败绝不静默回退到普通凭据——这保证了 CI 管道不会在错误配置下看似成功实则绕过凭据策略。常见错误与排查指引现象原因处理MIRRORD_CI_API_KEY is required ... does not advertise keyless CIOperator 不支持KeylessCi且未提供 Key运行mirrord ci api-key并配置环境变量或确认 Operator 为受支持的 Free 版本The environment variable MIRRORD_CI_API_KEY contains an invalid character!Key 值包含非法字符或格式错误重新生成 Key 并完整复制注意换行与空格invalid api key formatKey 前缀/编码不符合mci-v1:规范用mirrord ci api-key重新生成operator not found生成 Key 时集群中无 Operator先安装并启用 Operator再执行mirrord ci api-keymirrord ci stop报进程相关错误本地状态文件异常非空损坏文件会直接报错而非静默成功见 mirrord/cli/src/ci.rs检查临时目录下的mirrord/mirrord-for-ci.json该命令本身不涉及 API Key小结这份 changelog 片段背后是一套严格的三态凭据策略Free Operator 广告KeylessCi时免 Key 自动走普通凭据其他 Operator 场景必须使用mirrord ci api-key生成的MIRRORD_CI_API_KEY无 Operator 会话与本地mirrord ci stop则完全不需要 Key。从 mirrord/cli/src/connection.rs 的 fail-fast 校验、mirrord/operator/src/crd.rs 的能力广告到 mirrord/cli/tests/ci_credentials.rs 的行为锁定测试源码与测试共同保证了帮助文本、错误诊断与真实凭据路径的一致性——这正是该帮助修正变更的真正价值所在。赞分享开发工具云原生CLI【免费下载链接】mirrordRun any process, on your machine or in an AI agents environment, as if it were a pod in your Kubernetes cluster: real env vars, DNS, network, traffic.项目地址https://gitcode.com/gh_mirrors/mi/mirrord点击查看免费下载相关推荐Agno Environments CI Gating用环境运行证据驱动 CI 发布决策的三种门禁模式Agno Environments CI Gating用环境运行证据驱动 CI 发布决策的三种门禁模式 本文基于 Agno 仓库 cookbook/envir人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆Chromeless等待机制详解wait方法的三种使用场景Chromeless等待机制详解wait方法的三种使用场景 你是否在使用Chromeless进行自动化测试或网页抓取时遇到过元素还未加载就执行操作的问题是否开发工具测试Liquibase 数据库变更管理快速上手指南5 分钟跑通第一次数据库迁移Liquibase 数据库变更管理快速上手指南5 分钟跑通第一次数据库迁移 Liquibase 是一款广泛使用的开源数据库变更管理工具。它让数据库结构改动像代数据库开发工具后端上一篇解决方案如何高效实现B站缓存视频的格式转换与长期保存下一篇FanControl终极指南告别风扇噪音打造智能静音散热系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考