Goldziher/starmetal
GitHub: Goldziher/starmetal
一个高性能的自托管多语言包注册表代理，让团队在不改变原生包管理器使用习惯的前提下集中缓存、验证并管控跨生态的依赖拉取。
Stars: 6 | Forks: 0
**多语言、高性能、自托管的包注册表与注册表代理。**
Starmetal 为团队提供了一条受控的路径，以统一处理跨生态系统的包管理器流量。它使用原生的注册表协议，代理上游读取请求，将制品存储在通用服务层之后，使用 Blake3 验证缓存的字节，并在依赖项到达客户端之前应用策略。
私有 MVP 范围：在全新的实时端到端（E2E）测试后，支持 **PyPI、npm、Cargo 和 Hex 的读取工作流**。Maven、RubyGems、NuGet 和 pub.dev 是可选的 Beta 适配器。原生发布不在 MVP 范围内；本地发布是实验性功能，默认禁用。
PyPI · npm · Cargo · Hex · Maven · RubyGems · NuGet · pub.dev · Blake3 完整性 · OpenDAL 存储 · CLI + MCP 运维
[](https://github.com/Goldziher/starmetal/actions/workflows/ci.yaml)
[](https://www.rust-lang.org/)
[](LICENSE)
[快速开始](#quick-start) · [注册表支持](#registry-support) · [部署](#deployment) · [架构](#architecture) · [ADR](#adrs)
## 为什么需要它
现代团队从多个注册表中拉取依赖项，每个注册表都有不同的协议、元数据格式、身份验证要求和客户端行为。Starmetal 将这些工作流置于一个自托管的服务边界之后，使得运维人员能够集中管理缓存、完整性校验、策略、存储和可观测性，而无需要求开发人员停止使用原生的包管理器客户端。
## 它的功能
Starmetal 位于包管理器客户端和上游注册表之间：
| 功能 | 当前状态 |
|---|---|
| 注册表代理 | 使用原生的包管理器路由，并针对 Starmetal URL 重写上游元数据 |
| 穿透缓存 | 未命中时从上游获取，存储制品，并在命中时提供缓存服务 |
| 完整性 | 存储 Blake3 附属文件，并在提供服务前重新验证已缓存的制品 |
| 策略 | 通过共享的服务检查机制，拦截特定的包、许可证和漏洞严重级别 |
| 协议适配器 | 为 PyPI、npm、Cargo、Hex、Maven、RubyGems、NuGet 和 pub.dev 提供基于 feature flag 的路由器 |
| 存储 | 基于 OpenDAL 的文件系统、S3、GCS 和内存后端 |
| 运维 | 通过相同的本地运维层提供 CLI 以及 stdio MCP 工具 |
Starmetal 专为私有/内部部署而设计。它目前还不是面向公共互联网的注册表产品，且对提供支持声明的功能，需依赖于原生客户端的实时端到端（E2E）测试结果。
## 注册表支持
| 注册表 | 路由 | 默认状态 | 状态 |
|---|---:|---:|---|
| PyPI | `/pypi` | 启用 | 实时 E2E 测试后的私有 MVP 读取候选者 |
| npm | `/npm` | 启用 | 实时 E2E 测试后的私有 MVP 读取候选者 |
| Cargo | `/cargo` | 启用 | 实时 E2E 测试后的私有 MVP 读取候选者 |
| Hex | `/hex` | 启用 | 实时 E2E 测试后的私有 MVP 读取候选者 |
| Maven | `/maven` | 禁用 | 可选的 Beta 读取适配器 |
| RubyGems | `/rubygems` | 禁用 | 可选的 Beta 读取适配器 |
| NuGet | `/nuget` | 禁用 | 可选的 Beta 读取适配器 |
| pub.dev | `/pub` | 禁用 | 可选的 Beta 读取适配器 |
有关支持标准和升级条件，请参阅 [ADR-0011](docs/adr/0011-mvp-support-matrix.md)。
## 快速开始
环境要求：
- Rust edition 2024，Rust 1.85+
- [Task](https://taskfile.dev/)，用于执行文档中提到的工作流命令
- [sccache](https://github.com/mozilla/sccache)，可选，但会被 Taskfile 的 cargo 命令自动使用
```
# 首次设置：hooks、sccache 检查、生成的 AI config
task setup
# 构建并运行测试
task ci
# 安装本地 sm binary
cargo install --path crates/depot-cli --bin sm
# 使用默认配置在 127.0.0.1:8080 上启动 Starmetal
sm serve
# 编写入门 config
sm config init
# 在没有 config 文件的情况下检查 registries
sm --no-config --storage-backend memory registry status
# 通过 cache 路径获取一个 artifact
sm package fetch pypi six 1.16.0 six-1.16.0.tar.gz
```
在将 MVP 读取工作流视为就绪状态之前，请运行原生的实时客户端 E2E 测试：
```
task test:e2e:pypi
task test:e2e:npm
task test:e2e:cargo
task test:e2e:hex
```
`task ci:live-e2e` 会运行相同的 MVP 实时检查关卡，外加实时的 schema 新鲜度检查。
## 配置
Starmetal 默认绑定到回环地址并使用文件系统存储。一个最小的私有部署通常从以下配置开始：
```
[server]
bind = "127.0.0.1:8080"
public_base_url = "https://starmetal.internal.example.com"
cors_allowed_origins = []
max_upload_bytes = 536870912
[storage]
backend = "fs"
path = "/var/lib/starmetal"
[auth]
enabled = true
tokens = ["replace-with-a-secret-token"]
```
上游 URL 必须是 HTTPS 且默认必须是公开的。本地的、私有网络的或不安全的上游需要显式配置 `allow_private_network` 和 `allow_insecure` 设置。有关完整的私有 MVP 配置指南，请参阅 [docs/deployment.md](docs/deployment.md)。
## CLI 和 MCP
CLI 命令是 `sm`。为了兼容性，配置查找仍然支持 `DEPOT_CONFIG` 和 `depot.toml`；CLI 和 MCP 服务器可以在没有配置文件的情况下，使用内置默认值和显式标志运行。
常见的 CLI 操作：
```
sm config show
sm config validate
sm registry status
sm package list pypi
sm package versions npm is-odd
sm package metadata cargo once_cell 1.19.0
sm package fetch npm is-odd 3.0.1 is-odd-3.0.1.tgz --output ./is-odd.tgz
sm cache delete-artifact npm is-odd 3.0.1 is-odd-3.0.1.tgz --yes
```
使用 `--output json` 获取机器可读的输出。MCP 通过 stdio 运行：
```
sm mcp serve
sm mcp serve --allow-writes
```
MCP 的读取工具始终可用。变更工具（包括实验性的本地 publish、yank、unyank 和缓存删除）需要使用 `--allow-writes`。
## 架构
Starmetal 采用六边形架构：协议适配器和存储后端位于共享的服务/核心边界之外。
| Crate | 作用 |
|---|---|
| `depot-core` | 领域类型、配置、策略、端口、lock file、注册表 schema 类型 |
| `depot-service` | 穿透缓存、Blake3 验证、策略检查、实验性本地发布 |
| `depot-storage` | 基于 OpenDAL 的 `StoragePort` 实现 |
| `depot-adapters` | 基于 feature flag 的协议路由器和上游客户端 |
| `depot-server` | Axum 应用程序组装和 Tower 中间件 |
| `depot-ops` | 供 CLI 和 MCP 使用的共享本地运维 API |
| `depot-cli` | Clap CLI 和 stdio MCP 服务器 |
有关图表和组件详细信息，请参阅 [docs/architecture.md](docs/architecture.md)。
## 开发关卡
适用于普通 PR 的常规安全关卡：
```
task fmt:check
task clippy
task test:all
task schema:check
task schema:validate
task conformance
task security
task ci
```
实时 E2E 测试特意与普通的 PR CI 分开，因为它需要网络访问权限和原生的包管理器 CLI。
## Schemas
Schema 来源、获取的上游制品、Starmetal 派生的 JSON Schemas 以及语法测试数据位于 [`schemas/`](schemas/) 目录下：
- [`schemas/registries/`](schemas/registries/) - 当协议类似 JSON 时派生的注册表 schema
- [`schemas/depot/`](schemas/depot/) - 配置和 lockfile schema
- [`schemas/README.md`](schemas/README.md) - 来源链接以及针对各注册表的派生说明
## ADR
- [0001 - 六边形架构](docs/adr/0001-hexagonal-architecture.md)
- [0002 - Tower 中间件](docs/adr/0002-tower-middleware.md)
- [0003 - OpenDAL 存储](docs/adr/0003-opendal-storage.md)
- [0004 - Blake3 和 Lock File](docs/adr/0004-blake3-lockfile.md)
- [0005 - 协议适配器](docs/adr/0005-protocol-adapters.md)
- [0006 - Feature Flags](docs/adr/0006-feature-flags.md)
- [0007 - JSON Schema 验证](docs/adr/0007-json-schema-validation.md)
- [0008 - 注册表扩展，已废弃](docs/adr/0008-registry-expansion.md)
- [0009 - 发布和上传工作流](docs/adr/0009-publishing-upload-workflows.md)
- [0010 - CLI 和 MCP 运维](docs/adr/0010-cli-mcp-operations.md)
- [0011 - 私有 MVP 支持矩阵](docs/adr/0011-mvp-support-matrix.md)
- [0012 - CI 质量关卡](docs/adr/0012-ci-quality-gates.md)
- [0013 - Basemind 和 AI-Rulez 对齐](docs/adr/0013-basemind-ai-rulez-alignment.md)
## 许可证
[BUSL-1.1](LICENSE)
标签：Rust, 依赖管理, 包管理, 注册代理, 漏洞探索, 私有仓库, 网络流量审计, 通知系统