XHGit · 产品文档

各语言软件包接入

不同包管理器和容器仓库的使用方式与配置要点。

01

阅读导览

本页说明当前软件包接口的客户端接入方法。全部域名、拥有者、包名、版本和身份均为测试占位值;把 git.example.test、team、demo 和 0.1.0 替换成包详情页显示的真实值。站点若部署在子路径下,复制详情页地址,不能自行省略子路径。

02

接入前的共同准备

  1. 先在软件包中确认类型、名称、版本与读取权限。
  2. 私有包准备具有 read:package 的测试令牌;上传准备 write:package 及拥有者写入权限。范围名称以令牌页面实际选项为准。
  3. 支持 HTTP Basic 的客户端使用 TEST_USER 为用户名、测试令牌为密码;支持专用 Token 或签名的客户端按对应方式配置。
  4. 把凭据保存在客户端私有配置、系统凭据库或构建 Secrets;不要提交包含真实凭据的配置文件。

下面未带认证的安装命令适合公开包。私有包需要先完成对应客户端认证。使用浏览器登录并不会让本机所有包管理器同时登录。

03

npm:JavaScript 与 Node.js

在项目 .npmrc 配置专用作用域,避免无意改变全部 npm 依赖来源:

@team:registry=https://git.example.test/api/packages/team/npm/
//git.example.test/api/packages/team/npm/:_authToken=${XHGIT_TOKEN}

由本地环境或构建 Secrets 提供 XHGIT_TOKEN,再运行 npm install @team/demo@0.1.0。发布前核对 package.json 中的名称、版本和发布目标,再用 npm 的发布流程。客户端配置里的作用域必须与实际包名一致,保存配置时不能把环境变量替换成真实令牌后提交。

04

PyPI:Python

pip install --index-url https://git.example.test/api/packages/team/pypi/simple/ demo==0.1.0

私有包通过客户端支持的凭据库或受保护的 .netrc 提供测试身份。发布使用构建工具生成的 Python 分发包,并将 Twine 的目标设为 https://git.example.test/api/packages/team/pypi,通过受保护的认证配置提交。此源不保证包含所有公共依赖,按项目策略配置可信来源并核对解析结果,不能靠同名包猜测来源。

05

Maven:Java 与兼容 JVM 项目

在 pom.xml 中增加仓库,并在 distributionManagement 中配置同一目标用于部署:

<repository>
  <id>xhgit</id>
  <url>https://git.example.test/api/packages/team/maven</url>
</repository>

认证放在本机 settings.xml 的 servers 中,id 与 xhgit 一致,用户名用测试账号,密码由环境或加密凭据提供。配置依赖坐标后运行 mvn install;发布前核对 groupId、artifactId、版本及 release/snapshot 目标。Gradle 等客户端使用同一 Maven 仓库地址和自己的凭据配置。

06

NuGet:.NET

dotnet nuget add source https://git.example.test/api/packages/team/nuget/index.json --name xhgit
dotnet add package Demo --version 0.1.0 --source xhgit

需要认证时用客户端凭据提供器,或为这个源配置测试用户名和令牌。具体加密保存能力由运行系统与客户端决定。发布 .nupkg 使用该源对应的 NuGet 推送方式,令牌通过受保护配置提供。源名称 xhgit 仅是本机别名,不能代替服务器上的拥有者名。

07

Cargo:Rust

在 .cargo/config.toml 中配置命名注册表:

[registries.xhgit]
index = "sparse+https://git.example.test/api/packages/team/cargo/"

运行 cargo login --registry xhgit,交互输入测试令牌;按当前 Cargo 版本配置其需要的凭据提供器。再用 cargo add demo@0.1.0 --registry xhgit 或 cargo publish --registry xhgit。Sparse 地址需要尾部斜杠。使用 Git 索引模式时,拥有者可在软件包设置初始化或重建索引,不需要为了 Sparse 模式盲目重建全部数据。

08

Go:模块代理

GOPROXY=https://git.example.test/api/packages/team/go go install example.test/team/demo@v0.1.0

模块路径和版本必须与上传包内的 Go 模块元数据一致。私有源使用当前 Go 客户端支持的认证文件或认证设置,按项目要求配置私有模块和校验策略,不要全局关闭完整性检查。仓库有 Git 标签不等于已经向这个拥有者的软件包代理上传了 Go 模块。

09

Composer:PHP

composer config repositories.xhgit composer https://git.example.test/api/packages/team/composer
composer require team/demo:0.1.0

私有认证放在 Composer 的私有 auth.json 或受保护环境配置中,对实际域名使用测试用户名和令牌。发布时按 Composer 包上传接口提交合法的包元数据及文件,不能把任意 ZIP 当成完整的 Composer 包。仓库配置可以进入项目,认证文件应留在仓库之外。

10

RubyGems:Ruby

gem install demo --version 0.1.0 --source https://git.example.test/api/packages/team/rubygems

Bundler 项目可在 Gemfile 中为相关 gem 使用同一专用 source 块。私有下载或推送使用 RubyGems/Bundler 自己的凭据配置保存测试令牌。发布之前先构建 .gem 并核对名称和版本,注意本地默认源是否仍指向另一个注册表,防止发错目标。

11

Pub:Dart 与 Flutter 依赖

dart pub token add https://git.example.test/api/packages/team/pub/
dart pub add demo:0.1.0 --hosted-url=https://git.example.test/api/packages/team/pub/

Token 添加命令按提示输入测试令牌。发布时在包的配置中指定正确的 publish_to,运行 Dart 的发布检查并确认包含文件,再提交。Pub 托管的是依赖包;它不会替 Flutter 项目生成 Android 或 Windows 安装包,构建操作见自动打包。

12

Swift:Swift 包注册表

swift package-registry set https://git.example.test/api/packages/team/swift
swift package resolve

在 Package.swift 中使用实际注册表包标识和版本,例如 .package(id: "team.demo", from: "0.1.0")。私有包按 Swift 客户端的 registry login 流程输入测试身份或令牌,核对包详情提供的标识。注册表支持与某个平台上的完整编译环境是两件事,配置源不会自动安装 SDK。

13

Conan:C 与 C++ 包

conan remote add xhgit https://git.example.test/api/packages/team/conan
conan remote login xhgit TEST_USER

登录时按提示输入测试令牌,旧版客户端使用其对应的认证命令。随后按所用 Conan 版本安装所需的 recipe/reference 并指定该远程;包详情会显示实际名称与版本。编译器、架构、构建类型等 profile 必须匹配可用二进制,找不到匹配包不能只靠重新登录解决。

14

Conda:Python 与科学计算环境

channels:
  - https://git.example.test/api/packages/team/conda

将需要的源加入专用环境配置,再使用 conda install demo=0.1.0。实际包可能属于具体 channel,按详情页添加相应通道。私有访问使用客户端支持的受保护认证配置,不能把含令牌的 URL 写进公开的环境文件。还要检查客户端平台子目录,Linux 包不能直接当作 Windows 包安装。

15

CRAN:R 包

options(repos = c(xhgit = "https://git.example.test/api/packages/team/cran"))
install.packages("demo")

按项目需要保留其他可信的 R 源;上述代码只设置演示源。私有访问通过 R 下载方式实际支持的认证配置提供测试身份。安装包要匹配当前 R 版本和平台,源码包可能需要本机编译器。修改源不会自动把站点当成完整公共 CRAN 镜像。

16

容器镜像:Docker 与 OCI

docker login git.example.test
docker pull git.example.test/team/demo:0.1.0

登录时使用测试用户名和软件包令牌。发布者先把本地镜像标记成同一完整名称,再推送有权限的拥有者路径。容器地址使用注册表主机及路径,不添加 /api/packages;网页包地址则仍用于查看元数据。部署需要可追溯时使用包页显示的 digest,避免可变标签后来指向其他镜像。

17

Helm:Chart 仓库与 OCI

helm repo add xhgit https://git.example.test/api/packages/team/helm
helm repo update
helm install demo xhgit/demo --version 0.1.0

私有 Chart 源通过 Helm 的用户名与密码选项或安全配置提供测试身份。普通 Chart 仓库与 OCI 仓库是不同方式;OCI Chart 使用 oci://git.example.test/team/demo,先完成 registry 登录,再按版本拉取。发布前核对 Chart 包内的名称、版本及所用接口,不能混用两套源地址。

18

Alpine:APK 仓库

把 https://git.example.test/api/packages/team/alpine/TEST_BRANCH/TEST_REPOSITORY 加入测试系统的仓库配置。分支和仓库必须来自实际包详情;客户端会进一步选择架构。仓库公钥可从 /api/packages/team/alpine/key 下载,核对来源后按 APK 的信任密钥方式安装。

配置完成后更新索引,再运行 apk add demo=0.1.0。私有源需要客户端支持的受保护认证配置。不要为了通过校验而全局允许未签名软件包,包签名与 HTTP 登录不是同一种验证。

19

Arch:Pacman 仓库

在测试系统的 Pacman 配置中添加对应仓库段,服务器地址形如:

[xhgit-test]
Server = https://git.example.test/api/packages/team/arch/TEST_REPOSITORY/$arch

仓库名与架构要与包页匹配;公钥入口为 /api/packages/team/arch/repository.key。核对密钥后按系统策略配置签名信任,再更新系统与索引并安装包。私有访问通过客户端支持的下载认证配置完成,不能把真实令牌放进要共享的 Pacman 配置。

20

Debian:APT 仓库

从 Debian 包详情复制“仓库配置”区域,里面包含当前拥有者的源地址、发行版与组件信息;基础路径为 /api/packages/team/debian。按详情安装并验证仓库签名密钥,保存源配置,更新 APT 索引后运行 apt install demo=0.1.0。

私有源凭据放在系统的受限 APT 认证配置中,使用测试用户名和令牌,不放在共享的源列表。不同发行版、组件和 CPU 架构必须对应,不能把某个 .deb 的文件名直接当成完整源配置。

21

RPM:DNF 与 Zypper

复制包页显示的分组源地址,例如 https://git.example.test/api/packages/team/rpm/TEST_GROUP.repo。不使用分组的包应按实际地址省略分组部分,不能自己添加一个不存在的名称。

DNF 可用对应版本的 config-manager 添加 .repo 源,再运行 dnf install demo;DNF5 和旧版命令不同。Zypper 使用 addrepo 和 install。私有认证放进权限受限的客户端源配置,保留正确的签名验证,检查架构与发行版兼容性后安装。

22

Chef:Cookbook 与签名认证

Chef 使用单独的请求签名机制。先在个人软件包设置生成 Chef 密钥对,安全保存下载的私钥,配置 Knife 使用对应测试用户名和私钥路径。不要用普通 Git SSH 私钥替代专用 Chef 配置,也不要把生成私钥提交到仓库。

knife[:supermarket_site] = 'https://git.example.test/api/packages/team/chef'

配置后使用 knife supermarket install demo 0.1.0。重新生成密钥对会影响依赖旧密钥的客户端,操作前先确认使用位置;机器时间偏差也可能导致签名请求被拒绝。

23

Vagrant:Box 镜像

vagrant box add --box-version 0.1.0 https://git.example.test/api/packages/team/vagrant/demo

私有 Box 按 Vagrant 客户端支持的认证方式提供测试令牌,并核对认证是否随下载请求发送。选择与本地虚拟化软件匹配的 provider 和架构。站点托管的是 Box 数据,不会为客户端自动安装 VirtualBox、VMware 或其他虚拟化环境。

24

Terraform:HTTP 状态后端

Terraform 状态包含基础设施信息,应使用专门的私有权限与凭据。在测试项目配置 backend "http",address 为 https://git.example.test/api/packages/team/terraform/state/demo,锁定与解锁地址在其后加 /lock,lock_method 为 POST,unlock_method 为 DELETE。

通过 TF_HTTP_USERNAME、TF_HTTP_PASSWORD 等受保护的运行配置提供测试用户名和令牌,运行 terraform init 后验证测试状态与锁。迁移已有状态前先备份和核对后端目标,不能直接对正式状态试验。本接口是状态后端,不能据此认定站点提供任意 Terraform 模块注册表。

25

Generic:通用版本文件

通用文件路径为 /api/packages/team/generic/demo/0.1.0/demo.zip。上传用带认证的 HTTP PUT;下载用 GET,私有包同样要求认证。例如 curl --fail --user TEST_USER -o demo.zip https://git.example.test/api/packages/team/generic/demo/0.1.0/demo.zip 会按提示请求测试令牌。

上传步骤见软件包管理。包名、版本和文件名分别是路径中的独立字段,注意 URL 编码与大小写,不要让同一个版本包含无法区分的平台文件。下载后检查内容和校验值,再交给使用者。

26

验证接入并处理错误

先用公开测试包验证地址,再用私有测试包验证认证,最后验证写入目标。401/403 检查令牌与账号权限,404 检查类型、拥有者、包名、版本和隐私范围;重复版本或格式错误应检查客户端打包产物。不要通过全局关闭 TLS 校验、签名检查或公开私有包来解决接入问题。需要帮助时提供脱敏命令与状态码,参见故障排查。