极狐GitLab 通用软件包仓库

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com, 私有化部署

使用通用软件包仓库在项目的软件包仓库中发布和管理通用文件，例如发布二进制文件。此功能特别适用于存储和分发不符合特定软件包格式（如 npm 或 Maven）的产物。

通用软件包仓库提供：

存储任何文件类型作为软件包的地方。
软件包的版本控制。
与极狐GitLab CI/CD 集成。
API 访问自动化。

验证软件包仓库#

要与软件包仓库交互，您必须使用以下方法之一进行验证：

具有 api 范围设置的个人访问令牌。
具有 api 范围设置并至少具有开发者角色的项目访问令牌。
CI/CD 作业令牌。
具有 read_package_registry、write_package_registry 或两者范围设置的部署令牌。

不要使用这里未记录的方法进行身份验证。未来可能会移除未记录的身份验证方法。

当您使用软件包仓库进行身份验证时，应遵循以下最佳实践：

要访问与开发者角色相关的权限，请使用个人访问令牌。
使用 CI/CD 作业令牌进行自动流水线。
使用部署令牌进行外部系统集成。
始终通过 HTTPS 发送身份验证信息。

HTTP 基本身份验证#

如果您使用的工具不支持标准身份验证方法，可以使用 HTTP 基本身份验证：

shell
curl --user "<username>:<token>" <other options> <GitLab API endpoint>

虽然它被忽略，但您必须提供用户名。令牌是您的个人访问令牌、CI/CD 作业令牌或部署令牌。

发布软件包#

您可以使用 API 发布软件包。

发布单个文件#

要发布单个文件，请使用以下 API 端点：

shell
PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name

用您的具体值替换 URL 中的占位符：

:id: 您的项目 ID 或 URL 编码路径
:package_name: 您的软件包名称
:package_version: 您的软件包版本
:file_name: 您上传的文件名称

例如：

使用 HTTP 头：

shell
curl --location --header "PRIVATE-TOKEN: <personal_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

使用 HTTP 基本身份验证：

shell
curl --location --user "<username>:<personal_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

使用 HTTP 头：

shell
curl --location --header  "PRIVATE-TOKEN: <project_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

使用 HTTP 基本身份验证：

shell
curl --location --user "<project_access_token_username>:project_access_token" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

使用 HTTP 头：

shell
curl --location --header  "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

使用 HTTP 基本身份验证：

shell
curl --location --user "<deploy_token_username>:<deploy_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

用您的部署令牌用户名替换 <deploy_token_username>，用您的实际部署令牌替换 <deploy_token>。

这些示例适用于 .gitlab-ci.yml 文件。极狐GitLab CI/CD 自动提供 CI_JOB_TOKEN。

使用 HTTP 头：

yaml
1publish:
2  stage: deploy
3  script:
4    - |
5      curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
6           --upload-file path/to/file.txt \
7           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

使用 HTTP 基本身份验证：

yaml
1publish:
2  stage: deploy
3  script:
4    - |
5      curl --location --user "gitlab-ci-token:${CI_JOB_TOKEN}" \
6           --upload-file path/to/file.txt \
7           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

每个请求都会返回一个表示成功或失败的响应。如果上传成功，响应状态为 201 Created。

发布多个文件#

要发布多个文件或整个目录，您必须为每个文件进行一次 API 调用。

发布多个文件到仓库时应遵循以下最佳实践：

版本控制：为您的软件包使用一致的版本控制方案。这可以基于项目的版本、构建号或日期。
文件组织：考虑您希望如何在软件包中组织文件。您可能希望包含一个清单文件，列出所有包含的文件及其用途。
自动化：尽可能通过 CI/CD 流水线自动化发布过程。这确保了一致性并减少了人工错误。
错误处理：在脚本中实施错误检查。例如，检查 cURL 的 HTTP 响应代码以确保每个文件已成功上传。
日志记录：维护上传文件的日志、时间和上传者。这对于故障排除和审计至关重要。
压缩：对于大型目录，考虑在上传前将内容压缩为单个文件。这可以简化上传过程并减少 API 调用次数。
校验和：生成并存储文件的校验和（MD5、SHA256）。这允许用户验证下载文件的完整性。

例如：

创建一个 Bash 脚本来迭代文件并上传：

shell
1#!/bin/bash
2
3TOKEN="<access_token>"
4PROJECT_ID="24"
5PACKAGE_NAME="my_package"
6PACKAGE_VERSION="1.0.0"
7DIRECTORY_PATH="./files_to_upload"
8
9for file in "$DIRECTORY_PATH"/*; do
10    if [ -f "$file" ]; then
11        filename=$(basename "$file")
12        curl --location --header  "PRIVATE-TOKEN: $TOKEN" \
13             --upload-file "$file" \
14             "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$filename"
15        echo "Uploaded: $filename"
16    fi
17done

在您的 CI/CD 流水线中自动上传，您可以迭代文件并上传：

yaml
1upload_package:
2  stage: publish
3  script:
4    - |
5      for file in ./build/*; do
6        if [ -f "$file" ]; then
7          filename=$(basename "$file")
8          curl --header "JOB-TOKEN: $CI_JOB_TOKEN" \
9               --upload-file "$file" \
10               "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/$filename"
11          echo "Uploaded: $filename"
12        fi
13      done

维护目录结构#

要保持已发布目录的结构，请在文件名中包含相对路径：

shell
1#!/bin/bash
2
3TOKEN="<access_token>"
4PROJECT_ID="24"
5PACKAGE_NAME="my_package"
6PACKAGE_VERSION="1.0.0"
7DIRECTORY_PATH="./files_to_upload"
8
9find "$DIRECTORY_PATH" -type f | while read -r file; do
10    relative_path=${file#"$DIRECTORY_PATH/"}
11    curl --location --header  "PRIVATE-TOKEN: $TOKEN" \
12         --upload-file "$file" \
13         "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$relative_path"
14    echo "Uploaded: $relative_path"
15done

下载软件包#

您可以使用 API 下载软件包。

下载单个文件#

要下载单个软件包文件，请使用以下 API 端点：

shell
GET /projects/:id/packages/generic/:package_name/:package_version/:file_name

用您的具体值替换 URL 中的占位符：

:id: 您的项目 ID 或 URL 编码路径
:package_name: 您的软件包名称
:package_version: 您的软件包版本
:file_name: 您上传的文件名称

例如：

使用 HTTP 头：

shell
curl --header "PRIVATE-TOKEN: <access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

使用 HTTP 基本身份验证：

shell
curl --user "<username>:<access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

使用 HTTP 头：

shell
curl --header "PRIVATE-TOKEN: <project_access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

使用 HTTP 基本身份验证：

shell
curl --user "<project_access_token_username>:<project_access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

使用 HTTP 头：

shell
curl --header "DEPLOY-TOKEN: <deploy_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

使用 HTTP 基本身份验证：

shell
curl --user "<deploy_token_username>:<deploy_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

这些示例适用于 .gitlab-ci.yml 文件。极狐GitLab CI/CD 自动提供 CI_JOB_TOKEN。

使用 HTTP 头：

yaml
1download:
2  stage: test
3  script:
4    - |
5      curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
6           --location \
7           --output file.txt \
8           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

使用 HTTP 基本身份验证：

yaml
1download:
2  stage: test
3  script:
4    - |
5      curl --user "gitlab-ci-token:${CI_JOB_TOKEN}" \
6           --location \
7           --output file.txt \
8           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

每个请求都会返回一个表示成功或失败的响应。如果上传成功，响应状态为 201 Created。

下载多个文件#

要下载多个文件或整个目录，您必须为每个文件进行一次 API 调用，或使用其他工具。

下载多个文件时应遵循以下最佳实践：

版本控制：始终指定要下载的软件包的确切版本以确保一致性。
目录结构：下载时保持软件包的原始目录结构以保留文件组织。
自动化：将软件包下载集成到 CI/CD 流水线或构建脚本中以实现自动化工作流。
错误处理：实施检查以确保所有文件成功下载。您可以验证 HTTP 状态码或在下载后检查文件是否存在。
缓存：对于经常使用的软件包，考虑实施缓存机制以减少网络使用并提高构建速度。
并行下载：对于包含许多文件的大型软件包，您可能需要实施并行下载以加快速度。
校验和：如果可用，请使用软件包发布者提供的校验和验证下载文件的完整性。
增量下载：对于频繁更改的大型软件包，考虑实施机制以仅下载自上次下载以来更改的文件。

例如：

创建一个 Bash 脚本来下载多个文件：

shell
1#!/bin/bash
2
3TOKEN="<access_token>"
4PROJECT_ID="24"
5PACKAGE_NAME="my_package"
6PACKAGE_VERSION="1.0.0"
7OUTPUT_DIR="./downloaded_files"
8
9# Create output directory if it doesn't exist
10mkdir -p "$OUTPUT_DIR"
11
12# Array of files to download
13files=("file1.txt" "file2.txt" "subdirectory/file3.txt")
14
15for file in "${files[@]}"; do
16    curl --location --header  "PRIVATE-TOKEN: $TOKEN" \
17         --output "$OUTPUT_DIR/$file" \
18         --create-dirs \
19         "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$file"
20    echo "Downloaded: $file"
21done

在您的 CI/CD 流水线中自动下载：

yaml
1download_package:
2  stage: build
3  script:
4    - |
5      FILES=("file1.txt" "file2.txt" "subdirectory/file3.txt")
6      for file in "${FILES[@]}"; do
7        curl --location --header  "JOB-TOKEN: $CI_JOB_TOKEN" \
8             --output "$file" \
9             --create-dirs \
10             "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/$file"
11        echo "Downloaded: $file"
12      done

下载整个软件包#

要下载软件包中的所有文件，请使用极狐GitLab API 列出软件包内容，然后下载每个文件：

shell
1TOKEN="<access_token>"
2PROJECT_ID="24"
3PACKAGE_ID="1234"
4PACKAGE_NAME="my_package"
5PACKAGE_VERSION="1.0.0"
6OUTPUT_DIR="./downloaded_package"
7
8# Create output directory
9mkdir -p "$OUTPUT_DIR"
10
11# Get list of files in the package
12files=$(curl --location --header  "PRIVATE-TOKEN: $TOKEN" \
13     "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/$PACKAGE_ID/package_files" \
14     | jq -r '.[].file_name')
15
16# Download each file
17for file in $files; do
18    curl --location --header  "PRIVATE-TOKEN: $TOKEN" \
19         --output "$OUTPUT_DIR/$file" \
20         --create-dirs \
21         "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$file"
22    echo "Downloaded: $file"
23done

禁用发布重复软件包名称#

History

在极狐GitLab 15.0 中，所需角色从开发者更改为维护者。
在极狐GitLab 17.0 中，所需角色从维护者更改为所有者。

默认情况下，当您发布与现有软件包同名同版本的软件包时，新文件会添加到现有软件包中。您可以在设置中禁用发布重复文件名。

前提条件：

您必须拥有所有者角色。

禁用发布重复文件名的方法：

在左侧边栏，选择 搜索或前往 并找到您的群组。
选择 设置 > 软件包和仓库。
在 重复软件包 表的通用行中，关闭 允许重复 切换。
可选。在例外文本框中，输入一个匹配要允许的包名称和版本的正则表达式。

如果 **允许重复** 被打开，您可以在 **例外** 文本框中指定不应有重复的软件包名称和版本。

添加软件包保留策略#

实施软件包保留策略以管理存储和维护相关版本。

为此：

使用内置的极狐GitLab 清理策略。

您还可以使用 API 实现自定义清理脚本。

故障排除#

HTTP 403 错误#

您可能会收到 HTTP 403 Forbidden 错误。此错误发生在以下情况：

您没有访问资源的权限。
项目没有启用软件包仓库。

要解决此问题，请确保软件包仓库已启用，并且您有权限访问它。

上传大文件到 S3 时的内部服务器错误#

S3 兼容对象存储限制单个 PUT 请求的大小为 5 GB。如果在对象存储连接设置中将 aws_signature_version 设置为 2，尝试发布超过 5 GB 限制的软件包文件可能会导致 HTTP 500: Internal Server Error 响应。

如果您在将大文件发布到 S3 时收到 HTTP 500: Internal Server Error 响应，请将 aws_signature_version 设置为 4：

ruby
1# Consolidated Object Storage settings
2gitlab_rails['object_store']['connection'] = {
3  # Other connection settings
4  'aws_signature_version' => '4'
5}
6# OR
7# Storage-specific form settings
8gitlab_rails['packages_object_store_connection'] = {
9  # Other connection settings
10  'aws_signature_version' => '4'
11}