From 95bf09fca0361ce25517c41c396b447c7f544e14 Mon Sep 17 00:00:00 2001 From: sillyguodong <33891828+sillyguodong@users.noreply.github.com> Date: Wed, 31 May 2023 15:55:01 +0800 Subject: [PATCH] Add chinese documentations for Packages (#24914) (#25016) backport: #24914 --- docs/content/doc/packages/alpine.zh-cn.md | 133 +++++++++++++++ docs/content/doc/packages/cargo.zh-cn.md | 110 ++++++++++++ docs/content/doc/packages/chef.zh-cn.md | 97 +++++++++++ docs/content/doc/packages/composer.zh-cn.md | 123 ++++++++++++++ docs/content/doc/packages/conan.zh-cn.md | 102 +++++++++++ docs/content/doc/packages/conda.zh-cn.md | 86 ++++++++++ docs/content/doc/packages/container.zh-cn.md | 94 +++++++++++ docs/content/doc/packages/cran.zh-cn.md | 93 +++++++++++ docs/content/doc/packages/debian.zh-cn.md | 134 +++++++++++++++ docs/content/doc/packages/generic.zh-cn.md | 148 ++++++++++++++++ docs/content/doc/packages/go.zh-cn.md | 77 +++++++++ docs/content/doc/packages/helm.zh-cn.md | 68 ++++++++ docs/content/doc/packages/maven.zh-cn.md | 167 +++++++++++++++++++ docs/content/doc/packages/npm.zh-cn.md | 145 ++++++++++++++++ docs/content/doc/packages/nuget.zh-cn.md | 118 +++++++++++++ docs/content/doc/packages/overview.zh-cn.md | 109 ++++++++++++ docs/content/doc/packages/pub.zh-cn.md | 84 ++++++++++ docs/content/doc/packages/pypi.zh-cn.md | 88 ++++++++++ docs/content/doc/packages/rpm.zh-cn.md | 117 +++++++++++++ docs/content/doc/packages/rubygems.zh-cn.md | 128 ++++++++++++++ docs/content/doc/packages/storage.en-us.md | 12 +- docs/content/doc/packages/storage.zh-cn.md | 85 ++++++++++ docs/content/doc/packages/swift.zh-cn.md | 94 +++++++++++ docs/content/doc/packages/vagrant.zh-cn.md | 79 +++++++++ 24 files changed, 2485 insertions(+), 6 deletions(-) create mode 100644 docs/content/doc/packages/alpine.zh-cn.md create mode 100644 docs/content/doc/packages/cargo.zh-cn.md create mode 100644 docs/content/doc/packages/chef.zh-cn.md create mode 100644 docs/content/doc/packages/composer.zh-cn.md create mode 100644 docs/content/doc/packages/conan.zh-cn.md create mode 100644 docs/content/doc/packages/conda.zh-cn.md create mode 100644 docs/content/doc/packages/container.zh-cn.md create mode 100644 docs/content/doc/packages/cran.zh-cn.md create mode 100644 docs/content/doc/packages/debian.zh-cn.md create mode 100644 docs/content/doc/packages/generic.zh-cn.md create mode 100644 docs/content/doc/packages/go.zh-cn.md create mode 100644 docs/content/doc/packages/helm.zh-cn.md create mode 100644 docs/content/doc/packages/maven.zh-cn.md create mode 100644 docs/content/doc/packages/npm.zh-cn.md create mode 100644 docs/content/doc/packages/nuget.zh-cn.md create mode 100644 docs/content/doc/packages/overview.zh-cn.md create mode 100644 docs/content/doc/packages/pub.zh-cn.md create mode 100644 docs/content/doc/packages/pypi.zh-cn.md create mode 100644 docs/content/doc/packages/rpm.zh-cn.md create mode 100644 docs/content/doc/packages/rubygems.zh-cn.md create mode 100644 docs/content/doc/packages/storage.zh-cn.md create mode 100644 docs/content/doc/packages/swift.zh-cn.md create mode 100644 docs/content/doc/packages/vagrant.zh-cn.md diff --git a/docs/content/doc/packages/alpine.zh-cn.md b/docs/content/doc/packages/alpine.zh-cn.md new file mode 100644 index 0000000000..8d95546c69 --- /dev/null +++ b/docs/content/doc/packages/alpine.zh-cn.md @@ -0,0 +1,133 @@ +--- +date: "2023-03-25T00:00:00+00:00" +title: "Alpine 软件包注册表" +slug: "alpine" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Alpine" + weight: 4 + identifier: "alpine" +--- + +# Alpine 软件包注册表 + +在您的用户或组织中发布 [Alpine](https://pkgs.alpinelinux.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Alpine 注册表，您需要使用像 curl 这样的 HTTP 客户端来上传包，并使用像 apk 这样的包管理器来消费包。 + +以下示例使用 `apk`。 + +## 配置软件包注册表 + +要注册 Alpine 注册表，请将 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`): + +``` +https://gitea.example.com/api/packages/{owner}/alpine// +``` + +| 占位符 | 描述 | +| ------------ | -------------- | +| `owner` | 软件包所有者 | +| `branch` | 要使用的分支名 | +| `repository` | 要使用的仓库名 | + +如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}): + +``` +https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine// +``` + +Alpine 注册表文件使用 RSA 密钥进行签名，apk 必须知道该密钥。下载公钥并将其存储在 `/etc/apk/keys/` 目录中： + +```shell +curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key +``` + +之后，更新本地软件包索引： + +```shell +apk update +``` + +## 发布软件包 + +要发布一个 Alpine 包（`*.apk`），请执行带有包内容的 HTTP `PUT` 操作，将其放在请求体中。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository} +``` + +| 参数 | 描述 | +| ------------ | --------------------------------------------------------------------------------------------------- | +| `owner` | 包的所有者。 | +| `branch` | 分支可以与操作系统的发行版本匹配，例如：v3.17。 | +| `repository` | 仓库可以用于[分组包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或类似的名称。 | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.apk \ + https://gitea.example.com/api/packages/testuser/alpine/v3.17/main +``` + +如果您使用的是双重身份验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 +您不能将具有相同名称的文件两次发布到一个包中。您必须首先删除现有的包文件。 + +服务器将以以下的 HTTP 状态码响应： + +| HTTP 状态码 | 含义 | +| ----------------- | ------------------------------------------ | +| `201 Created` | 软件包已发布。 | +| `400 Bad Request` | 软件包的名称、版本、分支、仓库或架构无效。 | +| `409 Conflict` | 具有相同参数组合的包文件已存在于软件包中。 | + +## 删除软件包 + +要删除 Alpine 包，执行 HTTP 的 DELETE 操作。如果没有文件，这将同时删除包版本。 + +``` +DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename} +``` + +| 参数 | 描述 | +| -------------- | -------------- | +| `owner` | 软件包的所有者 | +| `branch` | 要使用的分支名 | +| `repository` | 要使用的仓库名 | +| `architecture` | 软件包的架构 | +| `filename` | 要删除的文件名 | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk +``` + +服务器将以以下的 HTTP 状态码响应： + +| HTTP 状态码 | 含义 | +| ---------------- | ------------------ | +| `204 No Content` | 成功 | +| `404 Not Found` | 未找到软件包或文件 | + +## 安装软件包 + +要从 Alpine 注册表安装软件包，请执行以下命令： + +```shell +# use latest version +apk add {package_name} +# use specific version +apk add {package_name}={package_version} +``` diff --git a/docs/content/doc/packages/cargo.zh-cn.md b/docs/content/doc/packages/cargo.zh-cn.md new file mode 100644 index 0000000000..2d451716d1 --- /dev/null +++ b/docs/content/doc/packages/cargo.zh-cn.md @@ -0,0 +1,110 @@ +--- +date: "2022-11-20T00:00:00+00:00" +title: "Cargo 软件包注册表" +slug: "cargo" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Cargo" + weight: 5 + identifier: "cargo" +--- + +# Cargo 软件包注册表 + +为您的用户或组织发布 [Cargo](https://doc.rust-lang.org/stable/cargo/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +若要使用 Cargo 软件包注册表, 您需要安装 [Rust 和 Cargo](https://www.rust-lang.org/tools/install). + +Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。 +这个仓库是与注册表交互所必需的。 +下面的部分将介绍如何创建它。 + +## 索引仓库 + +Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。 +在 Gitea 中，这个仓库有一个特殊的名称叫做 `_cargo-index`。 +在上传软件包之后，它的元数据会自动写入索引中。 +不应手动修改这个注册表的内容。 + +用户或组织软件包设置页面允许创建这个索引仓库以及配置文件。 +如果需要，此操作将重写配置文件。 +例如，如果 Gitea 实例的域名已更改，这将非常有用。 + +如果存储在 Gitea 中的软件包与索引注册表中的信息不同步，设置页面允许重建这个索引注册表。 +这个操作将遍历注册表中的所有软件包，并将它们的信息写入索引中。 +如果有很多软件包，这个过程可能需要一些时间。 + +## 配置软件包注册表 + +要注册这个软件包注册表，必须更新 Cargo 的配置。 +将以下文本添加到位于当前用户主目录中的配置文件中（例如 `~/.cargo/config.toml`）： + +``` +[registry] +default = "gitea" + +[registries.gitea] +index = "https://gitea.example.com/{owner}/_cargo-index.git" + +[net] +git-fetch-with-cli = true +``` + +| 参数 | 描述 | +| ------- | ---------------- | +| `owner` | 软件包的所有者。 | + +如果这个注册表是私有的或者您想要发布新的软件包，您必须配置您的凭据。 +将凭据部分添加到位于当前用户主目录中的凭据文件中（例如 `~/.cargo/credentials.toml`）： + +``` +[registries.gitea] +token = "Bearer {token}" +``` + +| 参数 | 描述 | +| ------- | ------------------------------------------------------------------------------------- | +| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | + +## 发布软件包 + +在项目中运行以下命令来发布软件包： + +```shell +cargo publish +``` + +如果已经存在同名和版本的软件包，您将无法发布新的软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装软件包，请执行以下命令： + +```shell +cargo add {package_name} +``` + +| 参数 | 描述 | +| -------------- | ------------ | +| `package_name` | 软件包名称。 | + +## 支持的命令 + +``` +cargo publish +cargo add +cargo install +cargo yank +cargo unyank +cargo search +``` diff --git a/docs/content/doc/packages/chef.zh-cn.md b/docs/content/doc/packages/chef.zh-cn.md new file mode 100644 index 0000000000..939c94b429 --- /dev/null +++ b/docs/content/doc/packages/chef.zh-cn.md @@ -0,0 +1,97 @@ +--- +date: "2023-01-20T00:00:00+00:00" +title: "Chef 软件包注册表" +slug: "chef" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Chef" + weight: 5 + identifier: "chef" +--- + +# Chef Package Registry + +为您的用户或组织发布 [Chef](https://chef.io/) cookbooks。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Chef 软件包注册表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/). + +## 认证 + +Chef 软件包注册表不使用用户名和密码进行身份验证，而是使用私钥和公钥对请求进行签名。 +请访问软件包所有者设置页面以创建必要的密钥对。 +只有公钥存储在Gitea中。如果您丢失了私钥的访问权限，您必须重新生成密钥对。 +[配置 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下载的私钥，并将 Gitea 用户名设置为 `client_name`。 + +## 配置软件包注册表 + +要将 [`knife` 配置](https://docs.chef.io/workstation/knife_setup/)为使用 Gitea 软件包注册表，请将 URL 添加到 `~/.chef/config.rb` 文件中。 + +``` +knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef' +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +## 发布软件包 + +若要发布 Chef 软件包，请执行以下命令： + +```shell +knife supermarket share {package_name} +``` + +| 参数 | 描述 | +| -------------- | ---------- | +| `package_name` | 软件包名称 | + +如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表中安装软件包，请执行以下命令： + +```shell +knife supermarket install {package_name} +``` + +您可以指定软件包的版本，这是可选的： + +```shell +knife supermarket install {package_name} {package_version} +``` + +| 参数 | 描述 | +| ----------------- | ---------- | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | + +## 删除软件包 + +如果您想要从注册表中删除软件包，请执行以下命令： + +```shell +knife supermarket unshare {package_name} +``` + +可选地，您可以指定软件包的版本： + +```shell +knife supermarket unshare {package_name}/versions/{package_version} +``` + +| 参数 | 描述 | +| ----------------- | ---------- | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | diff --git a/docs/content/doc/packages/composer.zh-cn.md b/docs/content/doc/packages/composer.zh-cn.md new file mode 100644 index 0000000000..de19f71305 --- /dev/null +++ b/docs/content/doc/packages/composer.zh-cn.md @@ -0,0 +1,123 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Composer 软件包注册表" +slug: "composer" +weight: 10 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Composer" + weight: 10 + identifier: "composer" +--- + +# Composer 软件包注册表 + +为您的用户或组织发布 [Composer](https://getcomposer.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Composer 软件包注册表，您可以使用 [Composer](https://getcomposer.org/download/) 消费，并使用类似 `curl` 的 HTTP 上传客户端发布软件包。 + +## 发布软件包 + +要发布 Composer 软件包，请执行 HTTP `PUT` 操作，将软件包内容放入请求体中。 +软件包内容必须是包含 `composer.json` 文件的压缩 PHP 项目。 +如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/composer +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +如果 `composer.json` 文件不包含 `version` 属性，您必须将其作为查询参数提供： + +``` +PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z} +``` + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/project.zip \ + https://gitea.example.com/api/packages/testuser/composer +``` + +或者将软件包版本指定为查询参数： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/project.zip \ + https://gitea.example.com/api/packages/testuser/composer?version=1.0.3 +``` + +如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 + +服务器将以以下 HTTP 状态码响应。 + +| HTTP 状态码 | 含义 | +| ----------------- | ----------------------------------------------------------- | +| `201 Created` | 软件包已发布 | +| `400 Bad Request` | 软件包名称和/或版本无效，或具有相同名称和版本的软件包已存在 | + +## 配置软件包注册表 + +要注册软件包注册表，您需要将其添加到 Composer 的 `config.json` 文件中（通常可以在 `/.composer/config.json` 中找到）： + +```json +{ + "repositories": [{ + "type": "composer", + "url": "https://gitea.example.com/api/packages/{owner}/composer" + } + ] +} +``` + +要使用凭据访问软件包注册表，您必须在 `auth.json` 文件中指定它们，如下所示： + +```json +{ + "http-basic": { + "gitea.example.com": { + "username": "{username}", + "password": "{password}" + } + } +} +``` + +| 参数 | 描述 | +| ---------- | --------------------------- | +| `owner` | 软件包的所有者 | +| `username` | 您的 Gitea 用户名 | +| `password` | 您的Gitea密码或个人访问令牌 | + +## 安装软件包 + +要从软件包注册表中安装软件包，请执行以下命令： + +```shell +composer require {package_name} +``` + +您可以指定软件包的版本，这是可选的： + +```shell +composer require {package_name}:{package_version} +``` + +| 参数 | 描述 | +| ----------------- | ---------- | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | diff --git a/docs/content/doc/packages/conan.zh-cn.md b/docs/content/doc/packages/conan.zh-cn.md new file mode 100644 index 0000000000..3d3aa8a298 --- /dev/null +++ b/docs/content/doc/packages/conan.zh-cn.md @@ -0,0 +1,102 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Conan 软件包注册表" +slug: "conan" +weight: 20 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Conan" + weight: 20 + identifier: "conan" +--- + +# Conan 软件包注册表 + +为您的用户或组织发布 [Conan](https://conan.io/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 [conan](https://conan.io/downloads.html) 软件包注册表，您需要使用 conan 命令行工具来消费和发布软件包。 + +## 配置软件包注册表 + +要注册软件包注册表，您需要配置一个新的 Conan remote： + +```shell +conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan +conan user --remote {remote} --password {password} {username} +``` + +| 参数 | 描述 | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `remote` | 远程名称。 | +| `username` | 您的 Gitea 用户名。 | +| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 | +| `owner` | 软件包的所有者。 | + +例如: + +```shell +conan remote add gitea https://gitea.example.com/api/packages/testuser/conan +conan user --remote gitea --password password123 testuser +``` + +## 发布软件包 + +通过运行以下命令发布 Conan 软件包： + +```shell +conan upload --remote={remote} {recipe} +``` + +| 参数 | 描述 | +| -------- | --------------- | +| `remote` | 远程名称 | +| `recipe` | 要上传的 recipe | + +For example: + +```shell +conan upload --remote=gitea ConanPackage/1.2@gitea/final +``` + +Gitea Conan 软件包注册表支持完整的[版本修订](https://docs.conan.io/en/latest/versioning/revisions.html)。 + +## 安装软件包 + +要从软件包注册表中安装Conan软件包，请执行以下命令： + +```shell +conan install --remote={remote} {recipe} +``` + +| 参数 | 描述 | +| -------- | --------------- | +| `remote` | 远程名称 | +| `recipe` | 要下载的 recipe | + +例如： + +```shell +conan install --remote=gitea ConanPackage/1.2@gitea/final +``` + +## 支持的命令 + +``` +conan install +conan get +conan info +conan search +conan upload +conan user +conan download +conan remove +``` diff --git a/docs/content/doc/packages/conda.zh-cn.md b/docs/content/doc/packages/conda.zh-cn.md new file mode 100644 index 0000000000..721c2761ca --- /dev/null +++ b/docs/content/doc/packages/conda.zh-cn.md @@ -0,0 +1,86 @@ +--- +date: "2022-12-28T00:00:00+00:00" +title: "Conda 软件包注册表" +slug: "conda" +weight: 25 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Conda" + weight: 25 + identifier: "conda" +--- + +# Conda 软件包注册表 + +为您的用户或组织发布 [Conda](https://docs.conda.io/en/latest/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Conda 软件包注册表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。 + +## 配置软件包注册表 + +要注册软件包注册表并提供凭据，请编辑您的 `.condarc` 文件： + +```yaml +channel_alias: https://gitea.example.com/api/packages/{owner}/conda +channels: + - https://gitea.example.com/api/packages/{owner}/conda +default_channels: + - https://gitea.example.com/api/packages/{owner}/conda +``` + +| 占位符 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +有关各个设置的解释，请参阅[官方文档](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。 + +如果需要提供凭据，可以将它们作为通道 URL 的一部分嵌入（`https://user:password@gitea.example.com/...`）。 + +## 发布软件包 + +要发布一个软件包，请执行一个HTTP `PUT`操作，请求正文中包含软件包内容。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename} +``` + +| 占位符 | 描述 | +| ---------- | --------------------------------------------------------------------------------------------------- | +| `owner` | 软件包的所有者 | +| `channel` | 软件包的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可选） | +| `filename` | 文件名 | + +使用HTTP基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/package-1.0.conda \ + https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda +``` + +如果已经存在同名和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表中安装软件包，请执行以下命令之一： + +```shell +conda install {package_name} +conda install {package_name}={package_version} +conda install -c {channel} {package_name} +``` + +| 参数 | 描述 | +| ----------------- | -------------------- | +| `package_name` | 软件包的名称 | +| `package_version` | 软件包的版本 | +| `channel` | 软件包的通道（可选） | diff --git a/docs/content/doc/packages/container.zh-cn.md b/docs/content/doc/packages/container.zh-cn.md new file mode 100644 index 0000000000..d441a81078 --- /dev/null +++ b/docs/content/doc/packages/container.zh-cn.md @@ -0,0 +1,94 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "容器注册表" +slug: "container" +weight: 30 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "容器" + weight: 30 + identifier: "container" +--- + +# 容器注册表 + +为您的用户或组织发布符合 [Open Container Initiative(OCI)](https://opencontainers.org/) 规范的镜像。 +该容器注册表遵循 OCI 规范，并支持所有兼容的镜像类型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。 + +**目录** + +{{< toc >}} + +## 目录 + +要使用容器注册表，您可以使用适用于特定镜像类型的工具。 +以下示例使用 `docker` 客户端。 + +## 登录容器注册表 + +要推送镜像或者如果镜像位于私有注册表中，您需要进行身份验证： + +```shell +docker login gitea.example.com +``` + +如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 + +## 镜像命名约定 + +镜像必须遵循以下命名约定： + +`{registry}/{owner}/{image}` + +例如，以下是所有者为 `testuser` 的有效镜像名称示例： + +`gitea.example.com/testuser/myimage` + +`gitea.example.com/testuser/my-image` + +`gitea.example.com/testuser/my/image` + +**注意:** 该注册表仅支持大小写不敏感的标签名称。因此，`image:tag` 和 `image:Tag` 将被视为相同的镜像和标签。 + +## 推送镜像 + +通过执行以下命令来推送镜像： + +```shell +docker push gitea.example.com/{owner}/{image}:{tag} +``` + +| 参数 | 描述 | +| ------- | ------------ | +| `owner` | 镜像的所有者 | +| `image` | 镜像的名称 | +| `tag` | 镜像的标签 | + +例如： + +```shell +docker push gitea.example.com/testuser/myimage:latest +``` + +## 拉取镜像 + +通过执行以下命令来拉取镜像： + +```shell +docker pull gitea.example.com/{owner}/{image}:{tag} +``` + +| Parameter | Description | +| --------- | ------------ | +| `owner` | 镜像的所有者 | +| `image` | 镜像的名称 | +| `tag` | 镜像的标签 | + +例如： + +```shell +docker pull gitea.example.com/testuser/myimage:latest +``` diff --git a/docs/content/doc/packages/cran.zh-cn.md b/docs/content/doc/packages/cran.zh-cn.md new file mode 100644 index 0000000000..2823c948ca --- /dev/null +++ b/docs/content/doc/packages/cran.zh-cn.md @@ -0,0 +1,93 @@ +--- +date: "2023-01-01T00:00:00+00:00" +title: "CRAN 软件包注册表" +slug: "cran" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "CRAN" + weight: 35 + identifier: "cran" +--- + +# CRAN 软件包注册表 + +将 [R](https://www.r-project.org/) 软件包发布到您的用户或组织的类似 [CRAN](https://cran.r-project.org/) 的注册表。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用CRAN软件包注册表，您需要安装 [R](https://cran.r-project.org/)。 + +## 配置软件包注册表 + +要注册软件包注册表，您需要将其添加到 `Rprofile.site` 文件中，可以是系统级别、用户级别 `~/.Rprofile` 或项目级别： + +``` +options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran"))) +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +如果需要提供凭据，可以将它们嵌入到URL(`https://user:password@gitea.example.com/...`)中。 + +## 发布软件包 + +要发布 R 软件包，请执行带有软件包内容的 HTTP `PUT` 操作。 + +源代码软件包： + +``` +PUT https://gitea.example.com/api/packages/{owner}/cran/src +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +二进制软件包： + +``` +PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion} +``` + +| 参数 | 描述 | +| ---------- | -------------- | +| `owner` | 软件包的所有者 | +| `platform` | 平台的名称 | +| `rversion` | 二进制的R版本 | + +例如： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/package.zip \ + https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2 +``` + +如果同名和版本的软件包已存在，则无法发布软件包。您必须首先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表中安装R软件包，请执行以下命令： + +```shell +install.packages("{package_name}") +``` + +| 参数 | 描述 | +| -------------- | ----------------- | +| `package_name` | The package name. | + +例如： + +```shell +install.packages("testpackage") +``` \ No newline at end of file diff --git a/docs/content/doc/packages/debian.zh-cn.md b/docs/content/doc/packages/debian.zh-cn.md new file mode 100644 index 0000000000..57b8a9e4ae --- /dev/null +++ b/docs/content/doc/packages/debian.zh-cn.md @@ -0,0 +1,134 @@ +--- +date: "2023-01-07T00:00:00+00:00" +title: "Debian 软件包注册表" +slug: "debian" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Debian" + weight: 35 + identifier: "debian" +--- + +# Debian 软件包注册表 + +为您的用户或组织发布 [Debian](https://www.debian.org/distrib/packages) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Debian 注册表，您需要使用类似于 `curl` 的 HTTP 客户端进行上传，并使用类似于 `apt` 的软件包管理器消费软件包。 + +以下示例使用 `apt`。 + +## 配置软件包注册表 + +要注册 Debian 注册表，请将 URL 添加到已知 `apt` 源列表中： + +```shell +echo "deb https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list +``` + +| 占位符 | 描述 | +| -------------- | -------------- | +| `owner` | 软件包的所有者 | +| `distribution` | 要使用的发行版 | +| `component` | 要使用的组件 | + +如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： + +```shell +echo "deb https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list +``` + +Debian 注册表文件使用 PGP 密钥进行签名，`apt` 必须知道该密钥： + +```shell +sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/gitea-{owner}.asc +``` + +然后更新本地软件包索引： + +```shell +apt update +``` + +## 发布软件包 + +要发布一个 Debian 软件包（`*.deb`），执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload +``` + +| 参数 | 描述 | +| -------------- | ----------------------------------------------------- | +| `owner` | 软件包的所有者 | +| `distribution` | 发行版，可能与操作系统的发行版名称匹配，例如 `bionic` | +| `component` | 组件，可用于分组软件包，或仅为 `main` 或类似的组件。 | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.deb \ + https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload +``` + +如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 +您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。 + +服务器将使用以下 HTTP 状态代码进行响应。 + +| HTTP 状态码 | 意义 | +| ----------------- | ---------------------------------------- | +| `201 Created` | 软件包已发布 | +| `400 Bad Request` | 软件包名称、版本、发行版、组件或架构无效 | +| `409 Conflict` | 具有相同参数组合的软件包文件已经存在 | + +## 删除软件包 + +要删除 Debian 软件包，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。 + +``` +DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | +| `distribution` | 软件包发行版 | +| `component` | 软件包组件 | +| `architecture` | 软件包架构 | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64 +``` + +服务器将使用以下 HTTP 状态代码进行响应。 + +| HTTP 状态码 | 含义 | +| ---------------- | ------------------ | +| `204 No Content` | 成功 | +| `404 Not Found` | 找不到软件包或文件 | + +## 安装软件包 + +要从 Debian 注册表安装软件包，请执行以下命令: + +```shell +# use latest version +apt install {package_name} +# use specific version +apt install {package_name}={package_version} +``` diff --git a/docs/content/doc/packages/generic.zh-cn.md b/docs/content/doc/packages/generic.zh-cn.md new file mode 100644 index 0000000000..ce5cdcb7ae --- /dev/null +++ b/docs/content/doc/packages/generic.zh-cn.md @@ -0,0 +1,148 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "通用软件包注册表" +slug: "generic" +weight: 40 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "通用" + weight: 40 + identifier: "generic" +--- + +# 通用软件包注册表 + +发布通用文件，如发布二进制文件或其他输出，供您的用户或组织使用。 + +**目录** + +{{< toc >}} + +## 身份验证软件包注册表 + +要身份验证软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 + +## 发布软件包 + +要发布通用软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 +您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} +``` + +| 参数 | 描述 | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `owner` | 软件包的所有者。 | +| `package_name` | 软件包名称。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) | +| `package_version` | 软件包版本，一个非空字符串，不包含前导或尾随空格 | +| `file_name` | 文件名。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.bin \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 + +服务器将使用以下 HTTP 状态代码进行响应。 + +| HTTP 状态码 | 意义 | +| ----------------- | ---------------------------------- | +| `201 Created` | 软件包已发布 | +| `400 Bad Request` | 软件包名称和/或版本和/或文件名无效 | +| `409 Conflict` | 具有相同名称的文件已存在于软件包中 | + +## 下载软件包 + +要下载通用软件包，请执行 HTTP `GET` 操作。 + +``` +GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | +| `file_name` | 文件名 | + +文件内容将在响应主体中返回。响应的内容类型为 `application/octet-stream`。 + +服务器将使用以下 HTTP 状态代码进行响应。 + +```shell +curl --user your_username:your_token_or_password \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +服务器会以以下 HTTP 状态码进行响应： + +| HTTP 状态码 | 含义 | +| --------------- | -------------------- | +| `200 OK` | 成功 | +| `404 Not Found` | 找不到软件包或者文件 | + +## 删除软件包 + +要删除通用软件包，请执行 HTTP DELETE 操作。这将同时删除该版本的所有文件。 + +``` +DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | + +服务器将使用以下 HTTP 状态代码进行响应。 + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0 +``` + +The server responds with the following HTTP Status codes. + +| HTTP 状态码 | 意义 | +| ---------------- | ------------ | +| `204 No Content` | 成功 | +| `404 Not Found` | 找不到软件包 | + +## 删除软件包文件 + +要删除通用软件包的文件，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。 + +``` +DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | +| `filename` | 文件名 | + +使用 HTTP 基本身份验证的示例请求： + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +服务器将使用以下 HTTP 状态代码进行响应： + +| HTTP 状态码 | 含义 | +| ---------------- | ------------------ | +| `204 No Content` | 成功 | +| `404 Not Found` | 找不到软件包或文件 | diff --git a/docs/content/doc/packages/go.zh-cn.md b/docs/content/doc/packages/go.zh-cn.md new file mode 100644 index 0000000000..069a6991fb --- /dev/null +++ b/docs/content/doc/packages/go.zh-cn.md @@ -0,0 +1,77 @@ +--- +date: "2023-05-10T00:00:00+00:00" +title: "Go 软件包注册表" +slug: "go" +weight: 45 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Go" + weight: 45 + identifier: "go" +--- + +# Go 软件包注册表 + +为您的用户或组织发布 Go 软件包。 + +**目录** + +{{< toc >}} + +## 发布软件包 + +要发布 Go 软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 +如果已经存在相同名称和版本的软件包，您无法发布软件包。您必须首先删除现有的软件包。 +该软件包必须遵循[文档中的结构](https://go.dev/ref/mod#zip-files)。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/go/upload +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +要身份验证到软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.zip \ + https://gitea.example.com/api/packages/testuser/go/upload +``` + +如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 + +服务器将使用以下 HTTP 状态代码进行响应。 + +| HTTP 状态码 | 含义 | +| ----------------- | -------------------------- | +| `201 Created` | 软件包已发布 | +| `400 Bad Request` | 软件包无效 | +| `409 Conflict` | 具有相同名称的软件包已存在 | + +## 安装软件包 + +要安装Go软件包，请指示Go使用软件包注册表作为代理： + +```shell +# 使用最新版本 +GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name} +# 或者 +GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest +# 使用特定版本 +GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | + +如果软件包的所有者是私有的，则需要[提供凭据](https://go.dev/ref/mod#private-module-proxy-auth)。 + +有关 `GOPROXY` 环境变量的更多信息以及如何防止数据泄漏的信息，请[参阅文档](https://go.dev/ref/mod#private-modules)。 diff --git a/docs/content/doc/packages/helm.zh-cn.md b/docs/content/doc/packages/helm.zh-cn.md new file mode 100644 index 0000000000..337170bc26 --- /dev/null +++ b/docs/content/doc/packages/helm.zh-cn.md @@ -0,0 +1,68 @@ +--- +date: "2022-04-14T00:00:00+00:00" +title: "Helm Chart 注册表" +slug: "helm" +weight: 50 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Helm" + weight: 50 + identifier: "helm" +--- + +# Helm Chart 注册表 + +为您的用户或组织发布 [Helm](https://helm.sh/) charts。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Helm Chart 注册表，可以使用诸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 插件之类的简单HTTP客户端。 + +## 发布软件包 + +通过运行以下命令来发布软件包： + +```shell +curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts +``` + +或者使用 `helm cm-push` 插件： + +```shell +helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm +helm cm-push ./{chart_file}.tgz {repo} +``` + +| 参数 | 描述 | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `username` | 您的Gitea用户名 | +| `password` | 您的Gitea密码。如果您使用的是2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 | +| `repo` | 仓库名称 | +| `chart_file` | Helm Chart 归档文件 | +| `owner` | 软件包的所有者 | + +## 安装软件包 + +要从注册表中安装Helm Chart，请执行以下命令： + +```shell +helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm +helm repo update +helm install {name} {repo}/{chart} +``` + +| 参数 | 描述 | +| ---------- | --------------------------- | +| `username` | 您的Gitea用户名 | +| `password` | 您的Gitea密码或个人访问令牌 | +| `repo` | 存储库的名称 | +| `owner` | 软件包的所有者 | +| `name` | 本地名称 | +| `chart` | Helm Chart的名称 | diff --git a/docs/content/doc/packages/maven.zh-cn.md b/docs/content/doc/packages/maven.zh-cn.md new file mode 100644 index 0000000000..833bb81507 --- /dev/null +++ b/docs/content/doc/packages/maven.zh-cn.md @@ -0,0 +1,167 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Maven 软件包注册表" +slug: "maven" +weight: 60 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Maven" + weight: 60 + identifier: "maven" +--- + +# Maven 软件包注册表 + +为您的用户或组织发布 [Maven](https://maven.apache.org) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Maven 软件包注册表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。 +以下示例使用 `Maven` 和 `Gradle Groovy`。 + +## 配置软件包注册表 + +要注册软件包注册表，首先需要将访问令牌添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中： + +```xml + + + + gitea + + + + Authorization + token {access_token} + + + + + + +``` + +然后在项目的 `pom.xml` 文件中添加以下部分： + +```xml + + + gitea + https://gitea.example.com/api/packages/{owner}/maven + + + + + gitea + https://gitea.example.com/api/packages/{owner}/maven + + + gitea + https://gitea.example.com/api/packages/{owner}/maven + + +``` + +| 参数 | 描述 | +| -------------- | ------------------------------------------------------------------------------------- | +| `access_token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | +| `owner` | 软件包的所有者 | + +### Gradle variant + +如果您计划在项目中添加来自 Gitea 实例的一些软件包，请将其添加到 repositories 部分中： + +```groovy +repositories { + // other repositories + maven { url "https://gitea.example.com/api/packages/{owner}/maven" } +} +``` + +在 Groovy gradle 中，您可以在发布部分中包含以下脚本： + +```groovy +publishing { + // 其他发布设置 + repositories { + maven { + name = "Gitea" + url = uri("https://gitea.example.com/api/packages/{owner}/maven") + + credentials(HttpHeaderCredentials) { + name = "Authorization" + value = "token {access_token}" + } + + authentication { + header(HttpHeaderAuthentication) + } + } + } +} +``` + +## 发布软件包 + +要发布软件包，只需运行以下命令： + +```shell +mvn deploy +``` + +或者，如果您使用的是 Gradle，请使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任务： + +```groovy +./gradlew publishAllPublicationsToGiteaRepository +``` + +如果您想要将预构建的软件包发布到注册表中，可以使用 [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html) 命令： + +```shell +mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +如果存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表中安装 Maven 软件包，请在项目的 `pom.xml` 文件中添加新的依赖项： + +```xml + + com.test.package + test_project + 1.0.0 + +``` + +在 `Gradle Groovy` 中类似的操作如下： + +```groovy +implementation "com.test.package:test_project:1.0.0" +``` + +然后运行： + +```shell +mvn install +``` + +## 支持的命令 + +``` +mvn install +mvn deploy +mvn dependency:get: +``` diff --git a/docs/content/doc/packages/npm.zh-cn.md b/docs/content/doc/packages/npm.zh-cn.md new file mode 100644 index 0000000000..4863b2582b --- /dev/null +++ b/docs/content/doc/packages/npm.zh-cn.md @@ -0,0 +1,145 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "npm 软件包注册表" +slug: "npm" +weight: 70 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "npm" + weight: 70 + identifier: "npm" +--- + +# npm Package Registry + +为您的用户或组织发布 [npm](https://www.npmjs.com/) 包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 npm 包注册表，您需要安装 [Node.js](https://nodejs.org/en/download/) 以及与之配套的软件包管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。 + +该注册表支持[作用域](https://docs.npmjs.com/misc/scope/)和非作用域软件包。 + +以下示例使用具有作用域 `@test` 的 `npm` 工具。 + +## 配置软件包注册表 + +要注册软件包注册表，您需要配置一个新的软件包源。 + +```shell +npm config set {scope}:registry https://gitea.example.com/api/packages/{owner}/npm/ +npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}" +``` + +| 参数 | 描述 | +| ------- | --------------------------------------------------------------------------------------- | +| `scope` | 软件包的作用域 | +| `owner` | 软件包的所有者 | +| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 | + +例如： + +```shell +npm config set @test:registry https://gitea.example.com/api/packages/testuser/npm/ +npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" +``` + +或者，不使用作用域： + +```shell +npm config set registry https://gitea.example.com/api/packages/testuser/npm/ +npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" +``` + +## 发布软件包 + +在项目中运行以下命令发布软件包： + +```shell +npm publish +``` + +如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 + +## 删除软件包 + +通过运行以下命令删除软件包： + +```shell +npm unpublish {package_name}[@{package_version}] +``` + +| 参数 | 描述 | +| ----------------- | ---------- | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | + +例如 + +```shell +npm unpublish @test/test_package +npm unpublish @test/test_package@1.0.0 +``` + +## 安装软件包 + +要从软件包注册表中安装软件包，请执行以下命令： + +```shell +npm install {package_name} +``` + +| 参数 | 描述 | +| -------------- | ---------- | +| `package_name` | 软件包名称 | + +例如： + +```shell +npm install @test/test_package +``` + +## 给软件包打标签 + +该注册表支持[版本标签](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以通过 `npm dist-tag` 管理： + +```shell +npm dist-tag add {package_name}@{version} {tag} +``` + +| 参数 | 描述 | +| -------------- | ---------- | +| `package_name` | 软件包名称 | +| `version` | 软件包版本 | +| `tag` | 软件包标签 | + +例如： + +```shell +npm dist-tag add test_package@1.0.2 release +``` + +标签名称不能是有效的版本。所有可解析为版本的标签名称都将被拒绝。 + +## 搜索软件包 + +该注册表支持[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支持像 `author:gitea` 这样的特殊搜索限定符。 + +## 支持的命令 + +``` +npm install +npm ci +npm publish +npm unpublish +npm dist-tag +npm view +npm search +``` diff --git a/docs/content/doc/packages/nuget.zh-cn.md b/docs/content/doc/packages/nuget.zh-cn.md new file mode 100644 index 0000000000..14205545b5 --- /dev/null +++ b/docs/content/doc/packages/nuget.zh-cn.md @@ -0,0 +1,118 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "NuGet 软件包注册表" +slug: "nuget" +weight: 80 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "NuGet" + weight: 80 + identifier: "nuget" +--- + +# NuGet 软件包注册表 + +发布适用于您的用户或组织的 [NuGet](https://www.nuget.org/) 软件包。软件包注册表支持 V2 和 V3 API 协议，并且您还可以使用 [NuGet 符号软件包](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg)。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 NuGet 软件包注册表，您可以使用命令行界面工具，以及各种集成开发环境（IDE）中的 NuGet 功能，如 Visual Studio。有关 NuGet 客户端的更多信息，请参[阅官方文档](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)。 +以下示例使用 `dotnet nuget` 工具。 + +## 配置软件包注册表 + +要注册软件包注册表，您需要配置一个新的NuGet源： + +```shell +dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json +``` + +| 参数 | 描述 | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `source_name` | 所需源名称 | +| `username` | 您的Gitea用户名 | +| `password` | 您的Gitea密码。如果您使用2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | +| `owner` | 软件包的所有者 | + +例如： + +```shell +dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json +``` + +您可以在不提供凭据的情况下添加源，并在发布软件包时使用--api-key参数。在这种情况下，您需要提供[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 + +## 发布软件包 + +通过运行以下命令发布软件包： + +```shell +dotnet nuget push --source {source_name} {package_file} +``` + +| 参数 | 描述 | +| -------------- | ---------------------------- | +| `source_name` | 所需源名称 | +| `package_file` | 软件包 `.nupkg` 文件的路径。 | + +例如： + +```shell +dotnet nuget push --source gitea test_package.1.0.0.nupkg +``` + +如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 + +### 符号软件包 + +NuGet 软件包注册表支持构建用于符号服务器的符号软件包。客户端可以请求嵌入在符号软件包（`.snupkg`）中的 PDB 文件。 +为此，请将 NuGet 软件包注册表注册为符号源： + +``` +https://gitea.example.com/api/packages/{owner}/nuget/symbols +``` + +| 参数 | 描述 | +| ------- | -------------------- | +| `owner` | 软件包注册表的所有者 | + +例如： + +``` +https://gitea.example.com/api/packages/testuser/nuget/symbols +``` + +## 安装软件包 + +要从软件包注册表安装 NuGet 软件包，请执行以下命令： + +```shell +dotnet add package --source {source_name} --version {package_version} {package_name} +``` + +| 参数 | 描述 | +| ----------------- | ------------ | +| `source_name` | 所需源名称 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本。 | + +例如： + +```shell +dotnet add package --source gitea --version 1.0.0 test_package +``` + +## 支持的命令 + +``` +dotnet add +dotnet nuget push +dotnet nuget delete +``` diff --git a/docs/content/doc/packages/overview.zh-cn.md b/docs/content/doc/packages/overview.zh-cn.md new file mode 100644 index 0000000000..8d01d63cbe --- /dev/null +++ b/docs/content/doc/packages/overview.zh-cn.md @@ -0,0 +1,109 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "软件包注册表" +slug: "overview" +weight: 1 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Overview" + weight: 1 + identifier: "packages-overview" +--- + +# 软件包注册表 + +从Gitea **1.17**版本开始，软件包注册表可以用作常见软件包管理器的公共或私有注册表。 + +**目录** + +{{< toc >}} + +## 支持的软件包管理器 + +目前支持以下软件包管理器： + +| Name | Language | Package client | +| ------------------------------------------------------------- | ---------- | ------------------------- | +| [Alpine]({{< relref "doc/packages/alpine.zh-cn.md" >}}) | - | `apk` | +| [Cargo]({{< relref "doc/packages/cargo.zh-cn.md" >}}) | Rust | `cargo` | +| [Chef]({{< relref "doc/packages/chef.zh-cn.md" >}}) | - | `knife` | +| [Composer]({{< relref "doc/packages/composer.zh-cn.md" >}}) | PHP | `composer` | +| [Conan]({{< relref "doc/packages/conan.zh-cn.md" >}}) | C++ | `conan` | +| [Conda]({{< relref "doc/packages/conda.zh-cn.md" >}}) | - | `conda` | +| [Container]({{< relref "doc/packages/container.zh-cn.md" >}}) | - | 任何符合OCI规范的客户端 | +| [CRAN]({{< relref "doc/packages/cran.zh-cn.md" >}}) | R | - | +| [Debian]({{< relref "doc/packages/debian.zh-cn.md" >}}) | - | `apt` | +| [Generic]({{< relref "doc/packages/generic.zh-cn.md" >}}) | - | 任何HTTP客户端 | +| [Go]({{< relref "doc/packages/go.zh-cn.md" >}}) | Go | `go` | +| [Helm]({{< relref "doc/packages/helm.zh-cn.md" >}}) | - | 任何HTTP客户端, `cm-push` | +| [Maven]({{< relref "doc/packages/maven.zh-cn.md" >}}) | Java | `mvn`, `gradle` | +| [npm]({{< relref "doc/packages/npm.zh-cn.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` | +| [NuGet]({{< relref "doc/packages/nuget.zh-cn.md" >}}) | .NET | `nuget` | +| [Pub]({{< relref "doc/packages/pub.zh-cn.md" >}}) | Dart | `dart`, `flutter` | +| [PyPI]({{< relref "doc/packages/pypi.zh-cn.md" >}}) | Python | `pip`, `twine` | +| [RPM]({{< relref "doc/packages/rpm.zh-cn.md" >}}) | - | `yum`, `dnf` | +| [RubyGems]({{< relref "doc/packages/rubygems.zh-cn.md" >}}) | Ruby | `gem`, `Bundler` | +| [Swift]({{< relref "doc/packages/rubygems.zh-cn.md" >}}) | Swift | `swift` | +| [Vagrant]({{< relref "doc/packages/vagrant.zh-cn.md" >}}) | - | `vagrant` | + +**以下段落仅适用于未全局禁用软件包的情况！** + +## 仓库 x 软件包 + +软件包始终属于所有者（用户或组织），而不是仓库。 +要将（已上传的）软件包链接到仓库，请打开该软件包的设置页面，并选择要将此软件包链接到的仓库。 +将链接到整个软件包，而不仅是单个版本。 + +链接软件包将导致在仓库的软件包列表中显示该软件包，并在软件包页面上显示到仓库的链接（以及到仓库工单的链接）。 + +## 访问限制 + +| 软件包所有者类型 | 用户 | 组织 | +| ---------------- | ---------------------------------------- | ------------------------------------------ | +| **读取** 访问 | 公开，如果用户也是公开的；否则仅限此用户 | 公开，如果组织是公开的，否则仅限组织成员 | +| **写入** 访问 | 仅软件包所有者 | 具有组织中的管理员或写入访问权限的组织成员 | + +注意：这些访问限制可能会[变化](https://github.com/go-gitea/gitea/issues/19270)，将通过专门的组织团队权限添加更细粒度的控制。 + +## 创建或上传软件包 + +根据软件包类型，使用相应的软件包管理器。请查看特定软件包管理器的子页面以获取说明。 + +## 查看软件包 + +您可以在仓库页面上查看仓库的软件包。 + +1. 转到仓库主页。 +2. 在导航栏中选择**软件包** + +要查看有关软件包的更多详细信息，请选择软件包的名称。 + +## 下载软件包 + +要从仓库下载软件包： + +1. 在导航栏中选择**软件包** +2. 选择软件包的名称以查看详细信息。 +3. 在 **Assets** 部分，选择要下载的软件包文件的名称。 + +## 删除软件包 + +在将软件包发布到软件包注册表后，您无法编辑软件包。相反，您必须删除并重新创建它。 + +要从仓库中删除软件包： + +1. 在导航栏中选择**软件包** +2. 选择软件包的名称以查看详细信息。 +3. 单击**删除软件包**以永久删除软件包。 + +## 禁用软件包注册表 + +包注册表已自动启用。要在单个存储库中禁用它： + +1. 在导航栏中选择**设置**。 +2. 禁用**启用仓库软件包注册表**. + +禁用软件包注册表不会删除先前发布的软件包。 diff --git a/docs/content/doc/packages/pub.zh-cn.md b/docs/content/doc/packages/pub.zh-cn.md new file mode 100644 index 0000000000..9941a57089 --- /dev/null +++ b/docs/content/doc/packages/pub.zh-cn.md @@ -0,0 +1,84 @@ +--- +date: "2022-07-31T00:00:00+00:00" +title: "Pub 软件包注册表" +slug: "pub" +weight: 90 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Pub" + weight: 90 + identifier: "pub" +--- + +# Pub 软件包注册表 + +为您的用户或组织发布 [Pub](https://dart.dev/guides/packages) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用Pub软件包注册表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。 + +以下示例使用 `dart`。 + +## 配置软件包注册表 + +要注册软件包注册表并提供凭据，请执行以下操作： + +```shell +dart pub token add https://gitea.example.com/api/packages/{owner}/pub +``` + +| 占位符 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +您需要提供您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 + +## 发布软件包 + +要发布软件包，请编辑 `pubspec.yaml` 文件，并添加以下行： + +```yaml +publish_to: https://gitea.example.com/api/packages/{owner}/pub +``` + +| 占位符 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +现在，您可以通过运行以下命令来发布软件包： + +```shell +dart pub publish +``` + +如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装Pub软件包，请执行以下命令： + +```shell +dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/ +``` + +| 参数 | 描述 | +| -------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | + +例如： + +```shell +# use latest version +dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ +# specify version +dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ +``` diff --git a/docs/content/doc/packages/pypi.zh-cn.md b/docs/content/doc/packages/pypi.zh-cn.md new file mode 100644 index 0000000000..555fc4db43 --- /dev/null +++ b/docs/content/doc/packages/pypi.zh-cn.md @@ -0,0 +1,88 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "PyPI 软件包注册表" +slug: "pypi" +weight: 100 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "PyPI" + weight: 100 + identifier: "pypi" +--- + +# PyPI 软件包注册表 + +为您的用户或组织发布 [PyPI](https://pypi.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 PyPI 软件包注册表，您需要使用 [pip](https://pypi.org/project/pip/) 工具来消费和使用 [twine](https://pypi.org/project/twine/) 工具来发布软件包。 + +## 配置软件包注册表 + +要注册软件包注册表，您需要编辑本地的 `~/.pypirc` 文件。添加以下内容： + +```ini +[distutils] +index-servers = gitea + +[gitea] +repository = https://gitea.example.com/api/packages/{owner}/pypi +username = {username} +password = {password} +``` + +| 占位符 | 描述 | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `owner` | 软件包的所有者 | +| `username` | 您的 Gitea 用户名 | +| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码 | + +## 发布软件包 + +通过运行以下命令来发布软件包： + +```shell +python3 -m twine upload --repository gitea /path/to/files/* +``` + +软件包文件的扩展名为 `.tar.gz` 和 `.whl`。 + +如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装 PyPI 软件包，请执行以下命令： + +```shell +pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name} +``` + +| 参数 | 描述 | +| -------------- | ----------------------------- | +| `username` | 您的 Gitea 用户名 | +| `password` | 您的 Gitea 密码或个人访问令牌 | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | + +例如： + +```shell +pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package +``` + +您可以使用 `--extra-index-url` 替代 `--index-url`，但这样会使您容易受到依赖混淆攻击，因为 `pip` 会先检查官方 PyPi 仓库中的软件包，然后再检查指定的自定义仓库。请阅读 `pip` 文档以获取更多信息。 + +## 支持的命令 + +``` +pip install +twine upload +``` diff --git a/docs/content/doc/packages/rpm.zh-cn.md b/docs/content/doc/packages/rpm.zh-cn.md new file mode 100644 index 0000000000..405e141afd --- /dev/null +++ b/docs/content/doc/packages/rpm.zh-cn.md @@ -0,0 +1,117 @@ +--- +date: "2023-03-08T00:00:00+00:00" +title: "RPM 软件包注册表" +slug: "packages/rpm" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "RPM" + weight: 105 + identifier: "rpm" +--- + +# RPM 软件包注册表 + +为您的用户或组织发布 [RPM](https://rpm.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用RPM注册表，您需要使用像 `yum` 或 `dnf` 这样的软件包管理器来消费软件包。 + +以下示例使用 `dnf`。 + +## 配置软件包注册表 + +要注册RPM注册表，请将 URL 添加到已知 `apt` 源列表中： + +```shell +dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm.repo +``` + +| 占位符 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +如果注册表是私有的，请在URL中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： + +```shell +dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm.repo +``` + +您还必须将凭据添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。 + +## 发布软件包 + +要发布RPM软件包（`*.rpm`），请执行带有软件包内容的 HTTP `PUT` 操作。 + +``` +PUT https://gitea.example.com/api/packages/{owner}/rpm/upload +``` + +| 参数 | 描述 | +| ------- | -------------- | +| `owner` | 软件包的所有者 | + +使用HTTP基本身份验证的示例请求： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.rpm \ + https://gitea.example.com/api/packages/testuser/rpm/upload +``` + +如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。您无法将具有相同名称的文件两次发布到软件包中。您必须先删除现有的软件包版本。 + +服务器将以以下HTTP状态码响应。 + +| HTTP 状态码 | 含义 | +| ----------------- | ------------------------------------------------ | +| `201 Created` | 软件包已发布 | +| `400 Bad Request` | 软件包无效 | +| `409 Conflict` | 具有相同参数组合的软件包文件已经存在于该软件包中 | + +## 删除软件包 + +要删除 RPM 软件包，请执行 HTTP `DELETE` 操作。如果没有文件剩余，这也将删除软件包版本。 + +``` +DELETE https://gitea.example.com/api/packages/{owner}/rpm/{package_name}/{package_version}/{architecture} +``` + +| 参数 | 描述 | +| ----------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | +| `package_version` | 软件包版本 | +| `architecture` | 软件包架构 | + +使用HTTP基本身份验证的示例请求： + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64 +``` + +服务器将以以下HTTP状态码响应： + +| HTTP 状态码 | 含义 | +| ---------------- | ------------------ | +| `204 No Content` | 成功 | +| `404 Not Found` | 未找到软件包或文件 | + +## 安装软件包 + +要从RPM注册表安装软件包，请执行以下命令： + +```shell +# use latest version +dnf install {package_name} +# use specific version +dnf install {package_name}-{package_version}.{architecture} +``` diff --git a/docs/content/doc/packages/rubygems.zh-cn.md b/docs/content/doc/packages/rubygems.zh-cn.md new file mode 100644 index 0000000000..f3416c239e --- /dev/null +++ b/docs/content/doc/packages/rubygems.zh-cn.md @@ -0,0 +1,128 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "RubyGems 软件包注册表" +slug: "rubygems" +weight: 110 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "RubyGems" + weight: 110 + identifier: "rubygems" +--- + +# RubyGems 软件包注册表 + +为您的用户或组织发布 [RubyGems](https://guides.rubygems.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用RubyGems软件包注册表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具来消费和发布软件包。 + +## 配置软件包注册表 + +要注册软件包注册表，请编辑 `~/.gem/credentials` 文件并添加： + +```ini +--- +https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token} +``` + +| 参数 | 描述 | +| ------- | ------------------------------------------------------------------------------------- | +| `owner` | 软件包的所有者 | +| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | + +例如： + +``` +--- +https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4 +``` + +## 发布软件包 + +通过运行以下命令来发布软件包： + +```shell +gem push --host {host} {package_file} +``` + +| 参数 | 描述 | +| -------------- | ------------------------ | +| `host` | 软件包注册表的URL | +| `package_file` | 软件包 `.gem` 文件的路径 | + +例如： + +```shell +gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem +``` + +如果已经存在相同名称和版本的软件包，您将无法发布软件包。您必须先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装软件包，您可以使用 [Bundler](https://bundler.io) 或 `gem`。 + +### Bundler + +在您的 `Gemfile` 中添加一个新的 `source` 块： + +``` +source "https://gitea.example.com/api/packages/{owner}/rubygems" do + gem "{package_name}" +end +``` + +| 参数 | 描述 | +| -------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | + +例如： + +``` +source "https://gitea.example.com/api/packages/testuser/rubygems" do + gem "test_package" +end +``` + +之后运行以下命令： + +```shell +bundle install +``` + +### gem + +执行以下命令： + +```shell +gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name} +``` + +| 参数 | 描述 | +| -------------- | -------------- | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包名称 | + +例如： + +```shell +gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package +``` + +## 支持的命令 + +``` +gem install +bundle install +gem push +``` diff --git a/docs/content/doc/packages/storage.en-us.md b/docs/content/doc/packages/storage.en-us.md index cd5952eb24..655dc3d08a 100644 --- a/docs/content/doc/packages/storage.en-us.md +++ b/docs/content/doc/packages/storage.en-us.md @@ -77,9 +77,9 @@ The cleanup rules are part of the [clean up job]({{< relref "doc/administration/ The cleanup rule: 1. Collects all packages of the package type for the owners registry. -1. For every package it collects all versions. -1. Excludes from the list the # versions based on the *Keep the most recent* value. -1. Excludes from the list any versions matching the *Keep versions matching* value. -1. Excludes from the list the versions more recent than the *Remove versions older than* value. -1. Excludes from the list any versions not matching the *Remove versions matching* value. -1. Deletes the remaining versions. +2. For every package it collects all versions. +3. Excludes from the list the # versions based on the *Keep the most recent* value. +4. Excludes from the list any versions matching the *Keep versions matching* value. +5. Excludes from the list the versions more recent than the *Remove versions older than* value. +6. Excludes from the list any versions not matching the *Remove versions matching* value. +7. Deletes the remaining versions. diff --git a/docs/content/doc/packages/storage.zh-cn.md b/docs/content/doc/packages/storage.zh-cn.md new file mode 100644 index 0000000000..7845f40cf8 --- /dev/null +++ b/docs/content/doc/packages/storage.zh-cn.md @@ -0,0 +1,85 @@ +--- +date: "2022-11-01T00:00:00+00:00" +title: "存储" +slug: "storage" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Storage" + weight: 2 + identifier: "storage" +--- + +# 存储 + +本文档描述了软件包注册表的存储方式以及如何管理存储。 + +**目录** + +{{< toc >}} + +## 去重 + +软件包注册表具有内置的去重功能，可以对上传的 Blob 进行去重处理。 +如果上传了两个相同的文件，只会在文件系统上保存一个 Blob。 +这样可以确保不会浪费空间用于重复的文件。 + +如果上传了两个具有相同文件的软件包，这两个软件包将显示相同的大小，但在文件系统上，它们只需要一半的大小。 +每当删除一个软件包时，只会删除对底层 Blob 的引用。 +此时，Blob 不会被删除，因此它们仍然占用文件系统上的空间。 +当上传新的软件包时，现有的 Blob 可能会再次被引用。 + +这些无引用的 Blob 会在一个清理任务中被删除。 +配置设置 `OLDER_THAN` 可以配置无引用的 Blob 在被删除之前保留的时间。 + +## 清理规则 + +软件包注册表可能会随着时间的推移而变得很大，如果不进行清理的话。 +建议删除不必要的软件包并设置清理规则以自动管理软件包注册表的使用情况。 +每个软件包所有者（用户或组织）都可以管理应用于其软件包的清理规则。 + +| 设置 | 描述 | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| 启用 | 打开或关闭清理规则。 | +| 类型 | 每个规则管理特定的软件包类型。 | +| 将模式应用于完整的软件包名称 | 如果启用，则应用以下模式到完整的软件包名称（`package/version`），否则只使用版本号（`version`）。 | +| 保留最近的版本数 | 对于每个软件包要始终保留的版本数量。 | +| 保留与以下模式匹配的版本 | 确定要保留哪些版本的正则表达式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未配置，容器注册表也始终保留 `latest` 版本。 | +| 删除早于多少天的版本 | 仅删除早于所选天数的版本。 | +| 删除与以下模式匹配的版本 | 确定要删除哪些版本的正则表达式模式。空模式或 `.+` 表示如果没有其他设置指定，则删除所有软件包。 | + +每个清理规则都可以显示受影响的软件包的预览。 +这可以用来检查清理规则是否正确配置。 + +### 正则表达式示例 + +正则表达式模式会自动使用 `\A` 和 `\z` 锚点进行包围。 +不要在正则表达式模式中包含任何 `\A`、`\z`、`^` 或 `$` 标记，因为它们不是必要的。 +模式是不区分大小写的，与 Gitea 中的软件包注册表的行为相匹配。 + +| Pattern | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `.*` | 匹配任何可能的版本。 | +| `v.+` | 匹配以 `v` 开头的版本。 | +| `release` | 仅匹配版本号为 `release`。 | +| `release.*` | 匹配以 `release` 命名或以 `release` 开头的版本。 | +| `.+-temp-.+` | 匹配包含 `-temp-` 的版本。 | +| `v.+\|release` | 匹配以 `v` 开头的版本或版本号为 `release`。 | +| `package/v.+\|other/release` | 匹配以 `v` 开头的 package 的版本或 `other` 的版本号为 `release`。需要启用*将模式应用于完整的软件包名称*设置。 | + +### 清理规则的工作原理 + +清理规则是清理任务的一部分，定期运行。 + +清理规则： + +1. 收集所有属于所有者注册表的特定软件包类型的软件包。 +2. 对于每个软件包，收集所有版本。 +3. 根据 *保留最近的版本数* 的值，从列表中排除版本。 +4. 根据 *保留与以下模式匹配的版本* 的值，从列表中排除任何版本。 +5. 根据 *删除早于多少天的版本* 的值，从列表中排除比这个值更近的版本。 +6. 根据 *删除与以下模式匹配的版本* 的值，从列表中排除任何不匹配的版本。 +7. 删除剩余的版本。 diff --git a/docs/content/doc/packages/swift.zh-cn.md b/docs/content/doc/packages/swift.zh-cn.md new file mode 100644 index 0000000000..9c627416ad --- /dev/null +++ b/docs/content/doc/packages/swift.zh-cn.md @@ -0,0 +1,94 @@ +--- +date: "2023-01-10T00:00:00+00:00" +title: "Swift 软件包注册表" +slug: "swift" +weight: 95 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Swift" + weight: 95 + identifier: "swift" +--- + +# Swift 软件包注册表 + +为您的用户或组织发布 [Swift](https://www.swift.org/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Swift 软件包注册表，您需要使用 [swift](https://www.swift.org/getting-started/) 消费软件包，并使用 HTTP 客户端（如 `curl`）发布软件包。 + +## 配置软件包注册表 + +要注册软件包注册表并提供凭据，请执行以下命令： + +```shell +swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password} +``` + +| 占位符 | 描述 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `owner` | 软件包的所有者。 | +| `username` | 您的 Gitea 用户名。 | +| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | + +登录是可选的，只有在软件包注册表是私有的情况下才需要。 + +## 发布软件包 + +首先，您需要打包软件包的内容： + +```shell +swift package archive-source +``` + +要发布软件包，请执行一个带有软件包内容的 HTTP `PUT` 请求，将内容放在请求正文中。 + +```shell --user your_username:your_password_or_token \ +curl -X PUT --user {username}:{password} \ + -H "Accept: application/vnd.swift.registry.v1+json" \ + -F source-archive=@/path/to/package.zip \ + -F metadata={metadata} \ + https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version} +``` + +| 占位符 | 描述 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `username` | 您的 Gitea 用户名。 | +| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | +| `owner` | 软件包的所有者。 | +| `scope` | 软件包的作用域。 | +| `name` | 软件包的名称。 | +| `version` | 软件包的版本。 | +| `metadata` | （可选）软件包的元数据。以 JSON 编码的子集，格式参考 https://schema.org/SoftwareSourceCode | + +如果已经存在相同名称和版本的软件包，则无法发布软件包。您必须首先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装 Swift 软件包，请将其添加到 `Package.swift` 文件的依赖项列表中： + +``` +dependencies: [ + .package(id: "{scope}.{name}", from:"{version}") +] +``` + +| 参数 | 描述 | +| --------- | -------------- | +| `scope` | 软件包的作用域 | +| `name` | 软件包的名称 | +| `version` | 软件包的版本 | + +之后，执行以下命令来安装它： + +```shell +swift package resolve +``` diff --git a/docs/content/doc/packages/vagrant.zh-cn.md b/docs/content/doc/packages/vagrant.zh-cn.md new file mode 100644 index 0000000000..ddcec9e4c9 --- /dev/null +++ b/docs/content/doc/packages/vagrant.zh-cn.md @@ -0,0 +1,79 @@ +--- +date: "2022-08-23T00:00:00+00:00" +title: "Vagrant 软件包注册表" +slug: "vagrant" +weight: 120 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Vagrant" + weight: 120 + identifier: "vagrant" +--- + +# Vagrant 软件包注册表 + +为您的用户或组织发布 [Vagrant](https://www.vagrantup.com/) 软件包。 + +**目录** + +{{< toc >}} + +## 要求 + +要使用 Vagrant 软件包注册表，您需要安装 [Vagrant](https://www.vagrantup.com/downloads) 并使用类似于 `curl` 的工具进行 HTTP 请求。 + +## 发布软件包 + +通过执行 HTTP PUT 请求将 Vagrant box 发布到注册表： + +``` +PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box +``` + +| 参数 | 描述 | +| ----------------- | ------------------------------------------------------------------ | +| `owner` | 软件包的所有者 | +| `package_name` | 软件包的名称 | +| `package_version` | 软件包的版本，兼容 semver 格式 | +| `provider` | [支持的提供程序名称](https://www.vagrantup.com/docs/providers)之一 | + +上传 Hyper-V box 的示例： + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/your/vagrant.box \ + https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box +``` + +如果已经存在相同名称、版本和提供程序的软件包，则无法发布软件包。您必须首先删除现有的软件包。 + +## 安装软件包 + +要从软件包注册表安装软件包，请执行以下命令： + +```shell +vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}" +``` + +| 参数 | 描述 | +| -------------- | --------------- | +| `owner` | 软件包的所有者. | +| `package_name` | 软件包的名称 | + +例如： + +```shell +vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system" +``` + +这将安装软件包的最新版本。要添加特定版本，请使用` --box-version` 参数。 +如果注册表是私有的，您可以将您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})传递给 `VAGRANT_CLOUD_TOKEN` 环境变量。 + +## 支持的命令 + +``` +vagrant box add +```