Electric 项目 durable-streams-rust 发布流程全解Changesets 驱动的 crates.io / npm / Docker 三通道发布【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric本文是围绕 packages/durable-streams-rust/RELEASING.md 展开的发布操作指南面向需要在 Electric monorepo 中为durable-streams-rustRust 编写的 Durable Streams 服务端切新版本的维护者、CI 工程师以及想理解一个版本如何同时抵达 crates.io、npm 与 Docker Hub的读者。读完你将掌握版本锚点放在哪里、Changesets 如何驱动版本号提升、三个发布通道各自的产物与认证方式以及当前 npm 通道被禁用时的发布边界。一、版本锚点package.json是唯一事实来源durable-streams-rust的发布与传统 Rust 项目不同——它属于 Electric monorepo因此遵循整个仓库统一的 Changesets 版本管理机制。版本号不存放在Cargo.toml而是存放在包自己的package.json// packages/durable-streams-rust/package.json节选 { name: electric-ax/durable-streams-server-rust, version: 0.1.5, description: High-performance Durable Streams server (Rust) — native binary distributed via npm., private: true, scripts: { test:conformance: vitest run --config conformance/vitest.config.ts, sync-version: node scripts/sync-cargo-version.mjs } }要点解析private: true该包本身不会被发布到 npm。Changesets 只负责提升这里的版本号而真正的二进制包见第三节的四个平台包由 CI 发布。它在这里的角色是版本锚点anchor。electric-ax/durable-streams-server-rust是锚点包名所有下游产物crates.io 的 crate、四个 npm 平台包、Docker 镜像都对齐这一个版本号。sync-version脚本即 scripts/sync-cargo-version.mjs负责在发布前把package.json中的版本同步到Cargo.toml保证 npm、crates.io、Docker 三个通道发布的是同一个版本。从源码看版本同步的细节脚本读取包根目录的package.json拿到version然后用行锚定正则^version [^]*替换Cargo.toml中[package]段的版本号。它特意只用行锚定因为依赖项写法是foo { version ... }不是行首version 所以只有 crate 自身的版本会被命中如果替换后没有变化且目标版本字符串本就不存在脚本会直接抛错防止发布了一个版本未同步的 crate这种事故。运行方式见 scripts/sync-cargo-version.mjs在包根目录执行node scripts/sync-cargo-version.mjs或通过 pnpm 的pnpm sync-version。二、发布总览一次版本提升三个通道并行分发RELEASING.md 明确给出发布模型通过 Changesets 发布与 monorepo 其他包一致。流程是为durable-streams-rust添加一个 changeset记录变更说明合并 Changesets 自动生成的 Version Packages PR版本提升后changesets_release.yml工作流**扇出fan out**到三个通道以同一版本发布通道发布产物关键工作流crates.iodurable-streamscrate可通过cargo install durable-streams安装server_rust_publish.ymlnpmelectric-ax/durable-streams-server-rust锚点包 四个平台二进制包server_rust_publish.ymlDocker Hubelectricax/durable-streams-server-rustmulti-arch 镜像server_rust_dockerhub_image.yml当前发布边界务必先读npm 发布目前处于禁用状态。一次发布只发布 cratecrates.io和 Docker 镜像不会发布 npm 包——server_rust_publish.yml中的npm-publish任务被门控关闭在文件中搜索DISABLED:标记。准备好后再重新启用 npm 包发布。另外合并时的 canary Docker 构建也是关闭的但发布镜像仍然照常推送。也就是说即使 CI 全绿electric-ax/durable-streams-server-rust及其平台包当前也不会出现在 npm 上这一点在验收发布结果时要格外注意。三、crates.io 通道durable-streamscratecrates.io 上发布的是名为durable-streams的 crate。从 Cargo.toml 可以看清命名与产物细节[package] name durable-streams version 0.1.0 # 仓库内当前值发布时由 sync-cargo-version.mjs 从 package.json 同步 edition 2021 description High-performance Durable Streams server (Rust) license Apache-2.0 rust-version 1.75 # CI 在 stable 上构建这里记录支持的最低版本 # crate 名为 durable-streams裸名 durable-streams-server 在 crates.io 上已被占用 # 但产出的二进制保留历史名称保证 conformance 测试、发布工作流和文档不受影响。 [[bin]] name durable-streams-server path src/main.rs值得注意的两点crate 名与二进制名解耦crates.io 上的包名是durable-streams裸名durable-streams-server已被占用但cargo install durable-streams安装下来后你得到的可执行文件仍然叫durable-streams-server。这样 conformance 测试、发布工作流与既有文档都不必改名。版本在发布时同步仓库中的Cargo.toml保持 0.1.0真正发布到 crates.io 的版本由server_rust_publish.yml在发布前调用同步脚本写入。这也解释了为什么 CHANGELOG.md 与 package.json 的版本0.1.5会高于仓库内Cargo.toml的版本。crates.io 发布走server_rust_publish.yml认证方式见第六节OIDC Trusted PublishingCI 不存注册表 token。四、npm 通道锚点包 四个平台包npm 通道的产物结构是一个主包 四个平台二进制包全部由 npm/assemble.mjs 在发布前组装生成主包electric-ax/durable-streams-server-rust不携带任何二进制只包含bin/launcher.cjs启动器、targets.json平台清单和 README通过optionalDependencies按需拉取对应的平台包见 npm/templates/main.package.json。四个平台包每个包含一个预编译好的原生二进制bin/durable-streams-server并在package.json中声明os、cpu和可选的libc约束确保 npm 只在你当前平台安装正确的包。平台矩阵定义在 npm/targets.jsonnpm 平台包Rust targetoscpulibcelectric-ax/durable-streams-server-rust-linux-x64x86_64-unknown-linux-gnulinuxx64glibcelectric-ax/durable-streams-server-rust-linux-arm64aarch64-unknown-linux-gnulinuxarm64glibcelectric-ax/durable-streams-server-rust-darwin-x64x86_64-apple-darwindarwinx64—electric-ax/durable-streams-server-rust-darwin-arm64aarch64-apple-darwindarwinarm64—从 npm/assemble.mjs 可以看到组装逻辑的关键点读取targets.json为每个目标在binsDir/rustTarget/durable-streams-server找编译产物找不到就抛错防止带着缺失平台二进制发布把二进制复制进平台包的bin/目录并chmod 0o755保证可执行位用模板 npm/templates/platform.package.json 生成平台包package.json注入os/cpu/libc与同一版本号主包optionalDependencies中的每个平台包都被钉死在该版本optionalDependencies[t.pkg] version保证npm install拿到的是配套二进制最后输出顺序是平台包在前、主包在后——这正是发布顺序先发平台包再发主包避免主包发布时引用的平台包尚不存在。由于当前 npm 发布被门控关闭见第二节这部分逻辑由 CI 触发但不会真正推送同时 RELEASING.md 指出npm 侧的 trusted publishers 尚未配置这也是 npm 发布重新启用前必须补齐的前置条件之一。五、Docker Hub 通道multi-arch 镜像Docker Hub 上发布electricax/durable-streams-server-rustmulti-arch多架构镜像由server_rust_dockerhub_image.yml负责。镜像构建细节可以对照 Dockerfile 理解多阶段构建第一阶段基于rust:1-bookworm用cargo build --release --locked编译--locked保证按Cargo.lock精确构建第二阶段基于gcr.io/distroless/cc-debian12只拷贝二进制无 shell、无包管理器镜像体积最小化。构建上下文控制Dockerfile 只拷贝Cargo.toml、Cargo.lock和src/不拷贝target/与npm/因此不依赖仓库根目录的.dockerignore。默认特性构建使用默认 features不带tier/telemetry镜像最小且与 conformance 测试矩阵一致。Dockerfile 注释明确提示要发布 S3 分层存储能力需要在构建命令中加--features tier并且在 runtime 阶段额外安装ca-certificates。运行默认值EXPOSE 4437协议默认端口ENTRYPOINT为服务端二进制CMD [--host, 0.0.0.0]——因为二进制默认只绑定127.0.0.1容器外无法访问所以镜像默认绑定所有接口持久化需要挂载卷并追加--data-dir默认是临时目录。六、认证与安全OIDC Trusted Publishing两个注册表crates.io 与 npm都通过OIDC Trusted Publishing进行身份认证因此CI 中不存储任何注册表 token。这是现代发布管线的安全最佳实践认证凭证由 CI 平台如 GitHub Actions与注册表之间直接协商密钥从不落盘到仓库或 secrets 中。当前状态RELEASING.md 原文事实durable-streamscrate 已在 crates.io保留名称其 Trusted Publishing 已配置完成npm 侧的 trusted publishers仍待配置在完成配置之前 npm 发布不应被重新启用。七、发布操作步骤速查综合 RELEASING.md 与上述源码细节一个完整的发布周期是写 changeset在仓库中为durable-streams-rust添加一个 changeset按 semver 声明是 patch / minor / major并附上变更描述仓库历史可参考 CHANGELOG.md例如 0.1.5 记录的是 memory-mode CPU 修复与恢复硬化0.1.4 记录的是写路径性能重构与崩溃恢复修复。合并 Version Packages PRChangesets 机器人会提交一个 PR把锚点包 package.json 的version提升到新版本。合并该 PR 即触发版本提升。CI 扇出发布changesets_release.yml在版本提升后触发三个通道server_rust_publish.yml先跑 scripts/sync-cargo-version.mjs 把package.json版本同步进Cargo.toml再发布durable-streamscrate同时组装并发布 npm 包当前npm-publish任务被DISABLED:门控关闭。server_rust_dockerhub_image.yml按 arch 构建 multi-arch 镜像并推送electricax/durable-streams-server-rust。验证用cargo install durable-streams验证 crates.io 版本docker pull electricax/durable-streams-server-rust并核对多架构清单同时确认 npm 上没有意外出现新版本当前预期行为。八、发布相关注意事项小结版本必须始终一致crates.io、npm 平台包、Docker 镜像共用package.json中的同一个版本号依赖sync-cargo-version.mjs与assemble.mjs在发布时注入改动发布流水线时不要绕过这两处。平台包钉死版本主包的optionalDependencies用精确版本引用平台包发布顺序必须是平台包先、主包后否则会出现安装时找不到对应版本的问题。Cargo.toml 同步失败即中止同步脚本在找不到[package]版本可替换时会抛错防止静默发布错误版本。镜像默认特性最小化当前 Docker 镜像不包含tier/telemetryfeature若未来要发布 S3 分层能力需同时改 Dockerfile 的构建参数与 runtime 依赖ca-certificates。重新启用 npm 的前置条件解除server_rust_publish.yml中的DISABLED:门控并完成 npm 侧的 OIDC trusted publishers 配置在此之前crates.io 与 Docker Hub 是唯一生效的发布通道。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考