使用 ktra 搭建私人 Cargo registry
最新文章只发在：https://zjp-cn.github.io/posts/ktra-cargo-registry/
使用工具：
- ktra：纯 Rust 编写的，用于搭建 Cargo registry 的命令行工具
安装它：
cargo install ktra
注意：
- 这开启了
secure-auth和db-sled，数据库是内置的 sled - 如果你需要 redis 或者 mongo 作为后端数据库，自行添加 features，见 https://book.ktra.dev/installation/cargo.html
- 如果你不想通过命令行运行，而是通过 docker 部署，见 https://book.ktra.dev/installation/docker.html
步骤一：创建 Git Index 仓库
由于 Cargo 使用 git 或者 sparse 协议，后者是最近才稳定的（2023 年），而 ktra
出现得比较早，所以目前只基于 git 协议。
在 gitee 上创建新仓库，比如 ktra-cargo-registry，然后在本地新建这个仓库（主分支为 main），创建仓库配置文件，并提交和推送：
mkdir ktra-cargo-registry
cd ktra-cargo-registry
git remote add origin [email protected]:xxx/ktra-cargo-registry.git
echo '{"dl":"http://localhost:8000/dl","api":"http://localhost:8000"}' > config.json
git add config.json
git commit -am "initial commit"
git push origin main
注意：
- 本文描述的是私有 registry 部署（Index 仓库是私有的，发布的 crate 存于自己的私有服务器）
- 如果你想基于私有 registry 进行更大范围的公开使用，那么可能会对 ktra 的 OpenId 感兴趣（它更复杂）
步骤二：增加本地 Cargo registry
在 Cargo 的配置文件中，比如全局配置文件 ~/.cargo/config
[registries]
ktra = { index = "[email protected]:xxx/ktra-cargo-registry.git" }
注意：
- 全局配置文件可以是
~/.cargo/config或者~/.cargo/config.toml，见 https://doc.rust-lang.org/cargo/reference/config.html - 你可以填 HTTPS 地址，git 验证会简单些（因为 SSH 的方式需要设置 Cargo 的
git-fetch-with-cli，以及 gitee 设置 SSH 公钥）-
具体来说，在 HTTPS 情况下，登陆或者获取 registry 需要手动输入账号和密码
$ cargo b Updating `ktra` index Username for 'https://gitee.com': xxx Password for 'https://[email protected]': xxx -
所以，你可能还需要设置
git config --global credential.helper store或者git config --global credential.helper cache
来减少手动登录的次数。嗯，这就是 git 最基本的登录设置
-
步骤三：创建 ktra 配置文件并部署服务
一个 TOML 文件，传递给 ktra 命令行，里面配置了 ktra 的内置数据库。我把它存放到 ~/.config/ktra/ktra.toml：
[index_config]
branch = "main"
remote_url = "https://gitee.com/xxx/ktra-cargo-registry.git"
https_username = "xxx"
https_password = "xxx"
# 这两个设置似乎没有用
git_email = ""
git_name = "ktra"
# ssh 总是出现 git error: username not defined
# remote_url = "ssh://[email protected]/xxx/ktra-cargo-registry.git"
# ssh_username = "xxx"
# ssh_privkey_path = "~/.ssh/id_ed25519"
# ssh_pubkey_path = "~/.ssh/id_ed25519.pub"
cd ~/.config/ktra/
ktra # 或者 ktra -c ./ktra.toml，此命令部署服务到本地 8000 端口
步骤四：准备账户
由于服务需要一直运行，所以打开新的终端运行以下命令：
# 创建账户 admin 和密码，获得 {"token":"xxx"}
curl -X POST -H 'Content-Type: application/json' -d '{"password":"PASSWORD"}' http://localhost:8000/ktra/api/v1/new_user/admin
# cargo 登录 ktra：发布包，比如 cargo publish/yank 等
CARGO_NET_GIT_FETCH_WITH_CLI=true cargo login --registry ktra
#please paste the token found on http://localhost:8000/me below
# 对话过程中，粘贴 token，看到以下这行就登陆成功
# Login token for `ktra` saved
注意，这里的环境变量表示使用 git 命令行进行验证，如果你不这样做，需要自行参考
https://doc.rust-lang.org/cargo/appendix/git-authentication.html#ssh-authentication。
自行验证看起来很复杂，而且并不支持完整的 SSH 验证（我没试过），建议使用 git cli 的方式验证。
（如果你的 git 不想折腾 SSH，就在 Cargo registry 中使用 HTTPS 地址，步骤二已经描述了。）
注意：由于 registry 写的是 SSH 地址，这意味着从 ktra 拉取库都需要 SSH 验证，建议不要像上面那样采用命令行的局部环境变量。
我那样做是为了快速验证，你最好设置成全局环境变量或者在全局或者局部 .cargo/config.toml 配置文件中写
[net]
git-fetch-with-cli = true
步骤五：试试自己的 registry
发布库
cargo new ktra-test --lib
cd ktra-test
cargo publish --allow-dirty --registry=ktra
# cargo publish 的输出
Packaging ktra-test v0.1.0 (/rust/tmp/ktra-test)
Verifying ktra-test v0.1.0 (/rust/tmp/ktra-test)
Compiling ktra-test v0.1.0 (/rust/tmp/ktra-test/target/package/ktra-test-0.1.0)
Finished dev [unoptimized + debuginfo] target(s) in 1.13s
Packaged 3 files, 941.0B (731.0B compressed)
Uploading ktra-test v0.1.0 (/rust/tmp/ktra-test)
Updating `ktra` index
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (5/5), 486 bytes | 486.00 KiB/s, done.
From ssh://gitee.com/xxx/ktra-cargo-registry
7c6b370..90c97e3 -> origin/HEAD
根据我的观察，发布库到 ktra 做了以下事情：
-
在本地打包库，然后编译，成功之后
-
推送这个库的信息到 INDEX 仓库（仅仅是一个 json 文件）
{"name":"ktra-test","vers":"0.1.0","deps":[],"cksum":"89c08ea6c8ea00f06a7f0dd2ec468cf1116458aa38cd6aa5caf1cde05b7e0849","features":{},"yanked":false,"links":null}- 把打包的库数据上传到运行 ktra 的服务器
- 如果你按照我的上面步骤操作，那么你是在
~/.config/ktra/运行 ktra 的，那么库在crates/下
- 如果你按照我的上面步骤操作，那么你是在
$ ll ~/.config/ktra/ total 28K drwxr-xr-x 3 root root 4.0K Mar 24 18:44 crates/ drwxr-xr-x 2 root root 4.0K Mar 24 16:09 crates_io_caches/ drwxr-xr-x 3 root root 4.0K Mar 24 21:33 db/ drwxr-xr-x 4 root root 4.0K Mar 24 18:44 index/ -rw-r--r-- 1 root root 348 Mar 24 22:57 ktra.toml $ ll ~/.config/ktra/crates/ktra-test/0.1.0/download -rw-r--r-- 1 root root 731 Mar 24 18:44 /root/.config/ktra/crates/ktra-test/0.1.0/download -
拉取库
cargo new use-ktra
cargo add serde # 来自 crates.io 的库
cargo add ktra-test --registry ktr
cargo check # bingo!
# cat Cargo.toml
[dependencies]
serde = "1.0.158"
ktra-test = { version = "0.1.0", registry = "ktra" }
回答一些基本问题
我为什么需要私有 registry？
如果你的代码是公开的、给别人使用的，当然不需要一个私有 registry。
如果不是，那么你可能想弄一个私人控制的、小范围的东西。
除了 ktra，还有别的选择吗？
其他选择见 https://github.com/rust-lang/cargo/wiki/Third-party-registries。
ktra 是 Rust 编写的，而且功能简单小巧，特别适合个人使用或者小团体使用。
Index 仓库与 ktra 的关系？
我没有仔细研究过，但我认为：
- Index 仓库只存有 crate 的基本信息（名称、版本、其依赖信息等等，不含代码），步骤五有一个真实示例，或者去
https://github.com/rust-lang/crates.io-index 看看。 - ktra 可视为一个服务端，管理 crate 和 Index，把 crate 存于 ktra 所运行的本地目录下。（cargo publish 打包的数据就是项目源代码）
有没有比 ktra 更轻量的选择？
Cargo 支持从 HTTPS/SSH 拉取私人仓库，所以这是最简单的做法，比如：
[dependencies.my-private-crate]
git = "ssh://xxx"
tag = "xxx"
但 git 标签没有 semver。你可以 follow 这个讨论。
在项目中混用不同的 registries？
当然可以！
Cargo 把 crates.io 作为默认的 registry，如果需要指定成 ktra，只需要相关的命令行参数或者配置参数。
步骤五就是示例。但这么做会导致你的项目无法发布到 crates.io 上，因为那上面不支持别的 registries 的库。而 ktra
也不支持从 crates.io 拉过来 —— 不过你自己需要什么，完全可以自定义。