文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载导读当你在~/.cargo/config.toml中通过[source.crates-io] replace-with把 crates.io 替换成镜像或本地 vendor 目录后再执行cargo publish、cargo yank等 API 操作时Cargo 的行为是混乱甚至危险的crates.io 的凭据可能被误发给替换源而报错信息也令人困惑。本篇文章基于 Rust RFC 流程仓库中的 RFC 3289 源文档系统讲解该 RFC 提出的四项核心变更——强制--registry NAME消除歧义、对替换后的 crates-io 明确报错、凭据只发给同源 registry、以及让[source]表可引用[registries]表——并结合 RFC 3139 备选注册表认证 与 RFC 2141 备选注册表 的上下文帮助你理解并安全配置 Cargo 的源码替换与多注册表凭据体系。一、问题背景源码替换在 API 操作上的行为不一致Cargo 的源码替换source replacement是让crates-io这一内置源指向其他位置本地目录、镜像、vendor 目录的机制。它在拉取依赖时被 Cargo 尊重但在执行 API 操作时却只对crates-io生效对备选注册表完全不生效行为并不一致。RFC 3289 在 Motivation 一节 中列出了它要解决的四个问题不一致性Cargo 执行 API 操作时源码替换只对crates-io被尊重对备选注册表不生效。同为 registry行为却分叉。报错令人困惑尝试向被替换的 crates-io 发布 crate 时报错信息难以理解而且除了临时删除源码替换配置外没有别的办法对应 rust-lang/cargo#6722 描述的场景。凭据泄露风险执行publish之外的 API 操作时如果crates-io源被替换crates-io的凭据会被发送给替换 registry 的 API。这是明确的安全风险。凭据归属不清当使用被替换的、需要认证的备选注册表对应 RFC 3139 的场景拉取依赖时应该用哪一份凭据并不明确。这四项问题都指向同一个根因当crates-io被替换后用户意图发给原始 crates.io 还是发给替换源无法被 Cargo 可靠推断而 Cargo 默认行为又过于隐式。二、Guide-level 设计显式指定杜绝隐式推断RFC 3289 的 Guide-level explanation 给出了三条对用户友好的核心规则当crates-io源被替换后执行 API 操作必须携带--registry NAME来明确指明使用哪个 registry否则cargo直接报错。cargo只会把某个 registry 对应的 token 发送给该 registry 本身即使配置了源码替换也绝不会把 token 发给其他 registry。replace-with键可以引用[registries]表中注册的 registry 名称打通源码替换与注册表配置两套体系。场景一本地 vendor源码替换用于离线构建一个仓库在.cargo/config.toml中把 crates.io 的依赖全部 vendor 到本地目录。在此仓库内拉取依赖、构建都使用 vendor 源一切如常# .cargo/config.toml [source.crates-io] replace-with vendored-sources [source.vendored-sources] directory vendor当开发者决定发布这个 crate 时执行cargo publish --registry crates-io--registry crates-io会忽略源码替换直接发布到真正的 crates.io。发布动作与 vendor 配置互不干扰。场景二需要认证的 crates.io 镜像 registry假设部署了一台提供 crates.io 完整镜像的服务器并在~/.cargo/config.toml的[registries]表中配置了该镜像。镜像基于 RFC 3139 要求认证config.json中设置auth-required true。开发者先登录镜像cargo login --registry mirror之后拉取与构建都走镜像源。当需要向 crates.io 发布时cargo login --registry crates-io cargo publish --registry crates-iocargo login --registry crates-io登录到真正的 crates.iotoken 被保存cargo publish --registry crates-io在构建与发布时同样忽略源码替换直达 crates.io。整个过程中镜像的 token 只发给镜像crates.io 的 token 只发给 crates.io。三、Reference-level 设计四项变更详解变更 1--registry优先于源码替换执行 API 操作login、logout、owner、publish、search、yank时Cargo 一律使用--registry NAME指定的 registry绝不使用源码替换。这让显式参数成为唯一的权威来源从机制上消除了该用哪个源的歧义。变更 2替换后的 crates-io 在 API 操作下明确报错当执行上述 API 操作且同时满足以下全部条件时cargo会报错crates-io已被一个远程 registry 源替换replace-with指向 registry 类型源命令行未携带--registry NAME命令行未携带--index URLCargo.toml中的publish NAME清单键未设置该条件只对发布操作生效。报错信息如下error: crates-io is replaced: use --registry replacement or --registry crates-io这条错误直接把解法写出来要么用--registry replacement明确使用替换源要么用--registry crates-io明确绕过替换。它替代了原先令人困惑的发布报错rust-lang/cargo#6722也消除了临时删除配置才能发布的痛苦。变更 3凭据只发给与其关联的同一个 registry若crates-io被替换为另一个远程 registrycrates-io的凭据永远不会被发送给替换 registry。这一规则让crates-io与备选注册表的行为保持一致备选注册表本来就各自持有各自 token确保凭据只发给与其关联的 registry。这也是本 RFC 在安全层面的核心收益即使镜像配置里config.json写明了 API 地址token 也不会跨源流动。结合 RFC 3139 备选注册表认证 可知备选注册表通过 index 中config.json的auth-required: true要求认证token 以Authorization: tokenHTTP 头携带并且跟随重定向时不发送 Authorization 头见该 RFC 的 Security 一节。RFC 3289 的变更 3 正是把这一凭据与源强绑定的安全纪律推广到被替换的 crates-io 上。变更 4[source]表的replace-with可引用[registries]表[source]表中的replace-with键现在可以引用[registries]表中定义的 registry。例如以下配置变得合法[source.crates-io] replace-with my-registry [registries.my-registry] index https://my-registry-index/这是让--registry NAME命令行参数能够与源码替换后的 registry 配合工作的必要前提。同时它还带来一个实用收益可以为替换源指定额外配置例如 token而不必在[registries]与[source]两处重复配置同一份信息。也就是说被替换的 registry 可以复用备选注册表已有的认证与凭据体系对应 RFC 2141 备选注册表 引入的[registries]表及其后续演进让源码替换与多注册表模型在同一套配置框架下自洽。四、缺陷与取舍破坏性在哪里RFC 在 Drawbacks 中坦承了两点行为变更凭据发送位置发生变化可能破坏某些既有工作流。镜像场景受影响如果 crates.io 镜像的config.json中配置了api: https://crates.io那么旧行为把 crates.io token 发给替换源恰好能正常工作而本 RFC 会打破这种配置下的可用性——因为 token 不再发给替换源了。这正是该 RFC 在设计上刻意选择显式优于隐式的代价旧行为在特定镜像配置下碰巧能用但本质上是凭据跨源发送的安全隐患RFC 选择用显式参数换取安全与一致。五、备选方案回顾为什么不用别的解法RFC 在 Rationale and alternatives 中评估了两个主要备选方案方案 AAPI 操作默认忽略源码替换可选的--respect-source-config备选注册表目前就是这么做的API 操作默认忽略替换。可以再加一个--respect-source-config选项让 cargo 在 API 操作时遵循源码替换类似cargo vendor的已有行为。但这样会静默改变行为对用户来说过于隐晦——你可能根本没意识到发布到的是替换源。RFC 认为歧义场景下必须强制用户显式指定。方案 B禁止对替换源执行 API 操作对替换源执行 API 操作一律报错用户必须用--registry crates-io显式绕过替换Error: operation is not supported on replaced source crates-io-mirror; use --registry crates-io for the original source这个方案更严格但把用替换源做 API 操作这条路完全堵死灵活度不如最终方案。最终方案取两者之长既保留显式绕过--registry crates-io又保留使用替换源的可能--registry replacement并把选择权完全交给用户。六、未决问题与后续RFC 在 Unresolved questions 中留下两个开放问题--registry NAME是否也应允许引用[source]表中的 source 名称这样更灵活但会带来不必要的复杂度。Cargo 自身测试依赖替换 crates-io 源并把 crates-io 凭据发给替换源的能力需要为这些测试找到继续工作的方式。此外RFC 在 Prior art 中指出其他包管理器似乎并没有源码替换功能因此缺乏现成的同类设计可参照Future possibilities 则未提出后续扩展。七、实操要点总结操作场景正确命令说明crates-io 被替换后发布cargo publish --registry crates-io显式绕过替换发布到真实 crates.iocrates-io 被替换后使用镜像cargo publish --registry my-mirror显式选择替换源替换源需已在[registries]或[source]中定义登录镜像cargo login --registry mirrortoken 只与该 registry 绑定登录 crates.iocargo login --registry crates-io与镜像 token 互不干扰遗漏--registry的 API 操作直接报错crates-io is replaced: use \--registry replacement or --registry crates-io需要说明的是本 RFC 属于 Cargo 的规范设计文档位于本仓库 text/3289-source_replacement_ambiguity.md配套实现追踪于 rust-lang/cargo 的 #10894文章中的命令行为与报错文案以其设计为准实际使用前建议对照当前 Cargo 版本的行为验证。对于更完整的备选注册表索引格式与认证细节可继续阅读 RFC 2141 与 RFC 3139。赞分享文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载相关推荐Cosign与Git安全集成如何确保容器镜像与源代码的一致性Cosign与Git安全集成如何确保容器镜像与源代码的一致性 在现代软件开发流程中容器镜像的构建与源代码的管理往往是分离的。开发团队使用Git管理代码而运供应链安全云原生应用安全N_m3u8DL-RE 一条命令下载 DASH/HLS/M3U8 流的完整指南从解析到解密的深度拆解N_m3u8DL RE 一条命令下载 DASH/HLS/M3U8 流的完整指南从解析到解密的深度拆解 N_m3u8DL RE 是一款跨平台的 .NET 命令行CLI音视频Cargo 源码替换Source Replacement完全指南Vendoring、Mirroring 与 Git 源替换实战Cargo 源码替换Source Replacement完全指南Vendoring、Mirroring 与 Git 源替换实战 输出文章 Cargo 源开发工具包管理器CLI构建工具上一篇终极指南如何3步彻底卸载Windows顽固Edge浏览器下一篇GoGoGo 安卓虚拟定位免 ROOT 5 分钟完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考