---
url: /zh/artifact/intro.md
description: |
  介绍 CNB 制品库的基本概念，包括支持的制品类型（Docker、Helm、Maven、npm 等）、 页面管理、权限控制、存储容量计费和制品迁移等内容。
---
本文介绍 CNB 制品库的基本概念，包括支持的制品类型、管理方式、权限控制、存储计费和制品迁移。

## 制品类型

CNB 当前支持以下制品类型：

| 制品类型         | 域名                               |
|:-----------------|:-----------------------------------|
| Docker           | \_\_ENV\_\_CNB\_DOCKER\_REGISTRY         |
| Docker Model     | \_\_ENV\_\_CNB\_DOCKER\_MODEL\_REGISTRY   |
| Helm             | \_\_ENV\_\_CNB\_HELM\_REGISTRY           |
| Maven            | maven.\_\_ENV\_\_CNB\_HOST              |
| npm              | npm.\_\_ENV\_\_CNB\_HOST                |
| ohpm             | ohpm.\_\_ENV\_\_CNB\_HOST               |
| Nuget            | nuget.\_\_ENV\_\_CNB\_HOST              |
| Composer         | composer.\_\_ENV\_\_CNB\_HOST           |
| PyPI             | pypi.\_\_ENV\_\_CNB\_HOST               |
| Cargo            | cargo.\_\_ENV\_\_CNB\_HOST              |
| Conan            | conan.\_\_ENV\_\_CNB\_HOST              |

| 制品类型         | 域名                               |
|:-----------------|:-----------------------------------|
| Docker           | \_\_ENV\_\_CNB\_DOCKER\_REGISTRY         |
| Docker Model     | \_\_ENV\_\_CNB\_DOCKER\_MODEL\_REGISTRY   |
| Helm             | \_\_ENV\_\_CNB\_HELM\_REGISTRY           |
| Maven            | maven.\_\_ENV\_\_CNB\_HOST              |
| npm              | npm.\_\_ENV\_\_CNB\_HOST                |
| ohpm             | ohpm.\_\_ENV\_\_CNB\_HOST               |
| Nuget            | nuget.\_\_ENV\_\_CNB\_HOST              |
| Composer         | composer.\_\_ENV\_\_CNB\_HOST           |
| PyPI             | pypi.\_\_ENV\_\_CNB\_HOST               |
| Cargo            | cargo.\_\_ENV\_\_CNB\_HOST              |
| Conan            | conan.\_\_ENV\_\_CNB\_HOST              |
| Generic          | generic.\_\_ENV\_\_CNB\_HOST            |

## 管理制品库

各制品类型与`组织`、`代码仓库`在 UI 中的层级关系如下：

```shell
test-org  # 组织
├── maven
├── npm
├── ohpm
├── nuget
├── composer
├── pypi
├── cargo
├── conan
└── test-git-repo # 代码仓库
    ├── docker
    ├── helm
    └── docker model
```

```shell
test-org  # 组织
├── maven
├── npm
├── ohpm
├── nuget
├── composer
├── pypi
├── cargo
├── conan
├── generic
└── test-git-repo # 代码仓库
    ├── docker
    ├── helm
    └── docker model
```

如上所示，Composer/Maven 等制品库归属于组织，Docker/Helm/Docker Model 制品库归属于代码仓库，两者使用方式不同。

## 制品类型准入限制

Docker、Helm、Docker Model 三类制品库相互隔离，**每个制品库只接受自己类型的制品推送**，推送其它类型的制品会被拒绝并返回错误。

| 制品库 | 允许的制品 |
|:---|:---|
| Docker | 容器镜像（单/多架构）、buildx 注册表缓存、buildx attestation（provenance/SBOM 证明） |
| Helm | Helm Chart（OCI 格式） |
| Docker Model | Docker Model 制品 |

各类型对应的 manifest config mediaType 详见 [附录：OCI 制品库支持的 manifest 类型](./supported-manifest-types.md)。

例如：将 Helm Chart 推送到 Docker 制品库地址，或将容器镜像推送到 Helm 制品库地址，都会被拒绝：

```text
denied: artifact type "CHART" is not allowed to be pushed to a "docker" registry
```

被拒推送已上传的 blob 不会被任何制品引用，将由垃圾回收（GC）自动清理，无需人工处理。

### 使用 Docker/Helm/Docker Model 制品库

Docker/Helm/Docker Model 制品库归属于代码仓库，无需手动创建。登录后进入代码仓库的「制品」页面即可查看。

### 使用 Composer/Maven 等制品库

#### 创建制品库

点击右上角「+」创建新的制品库，或通过「头像」→「我的制品库」使用已有制品库。进入制品库后点击「使用指引」查看操作引导。

### 删除制品

进入制品库后，点击制品名称进入该制品，可删除整个制品或指定版本。

### 删除制品库

Docker/Helm/Docker Model 制品库无需手动删除。其他类型可在「制品库设置」中删除。

### 获取制品库地址

在「制品库设置」>「基础设置」中查看。

## 权限管控

### 角色

Docker/Helm/Docker Model 类型制品的可见性与所托管的 `代码仓库` 可见性一致。
用户对制品的操作权限由其在代码仓库中的角色决定。

Composer/Maven 等类型制品的可见性取决于制品库的可见性，用户对制品的操作权限由其在制品库中的角色决定。

用户在`代码仓库`中的`角色`，可在「代码仓库」>「设置」>「仓库成员」中查看：
![](/images/artifact/git-repo-role.png)

用户在制品库中的`角色`，可在「制品库」>「制品库设置」>「成员管理」中查看：
![](/images/artifact/artifact-repo-role.png)

下表中列出了制品行为及所需`角色`的对应关系：

| 资源           | 行为  | 所需角色                       |
|:---------------|:------|:-------------------------------|
| 公开制品库制品 | 拉取  | 任何人都可以拉取，无需登录鉴权 |
| 公开制品库制品 | 推送  | 开发者及以上                   |
| 公开制品库制品 | 删除  | 管理员及以上                   |
| 私有制品库制品 | 拉取  | 访客及以上，需登录鉴权         |
| 私有制品库制品 | 推送  | 开发者及以上                   |
| 私有制品库制品 | 删除  | 管理员及以上                   |

### 访问令牌

当通过命令行工具读写制品时，操作能否获得授权，由用户的`角色`和请求所携带的`访问令牌`权限共同决定。

访问令牌缺失时，系统视为匿名访问，操作权限会受限。

制品库详细鉴权策略如下：

1. 登录操作，`访问令牌`有效，允许登录，否则拒绝。

2. 匿名操作，仅允许拉取公开制品库制品，其余操作被拒绝。

3. 查询、拉取、推送制品操作，要求用户角色拥有对应权限，
   且访问令牌的 `registry-package` 授权范围包含对应操作，则允许，否则拒绝。删除操作类似。

4. 在策略 3 允许操作的基础上，若 `访问令牌` 指定了使用范围（如指定仓库、指定制品库、仅公开仓库/制品库），
   且此范围与被访问的资源匹配，则返回实际授权范围；否则需要检查被操作资源的可见性：
   * 如果被访问的资源为公开，拉取操作仍然会被允许，其余操作被拒绝；
   * 如果被访问的资源为私有，全部操作均会被拒绝。

5. 用户、令牌、被访问资源任何一项处于非正常状态（如被冻结），全部操作会被拒绝。
   携带错误的访问令牌（令牌登录之后过期也会被视为非正常令牌），即使是拉取公开制品库的制品，也会被拒绝。

上述策略以图形化方式展示如下（其中制品行为以拉取操作作为示例，
Token 指的是 CNB 的 `访问令牌`，Scope 指的是 `访问令牌` 的授权范围）：

```mermaid
%%{init: {"themeVariables": {"fontSize": "10px"}, "themeConfig": {"nodeTextMargin": 2, "spacingFactor": 0.8}}}%%
flowchart LR
    A[用户拉取制品] --> B{是否携带token}
    B -->|否| D{是否为公开制品}
    B -->|是| C{用户在仓库的角色是否有读权限}

    D -->|是| M[拉取成功]
    D -->|否| E[拉取失败]
    
    C -->|否| E[拉取失败]
    C -->|是| F{token是否合法且在有效期内}

    F -->|否| E
    F -->|是| H{token scope是否包含制品的读权限}
    
    H -->|否| E
    H -->|是| I{token是否指定使用范围}
    
    I -->|否| G[拉取成功]
    I -->|是| J{使用范围是否覆盖目标仓库}

    J --> |否| N[拉取失败]
    J --> |是| G
```

#### 创建访问令牌

点击右上角「头像」>「个人设置」>「访问令牌」>
[「添加访问令牌」](https://cnbprod.alpha.qq.com/profile/token) 创建新的 `访问令牌`。

![](/images/artifact/create-token.png)

`访问令牌` 的权限，只需要关注「授权范围」registry 部分即可。

「常见场景」选择「制品库」时，默认只会授权 `registry-package` 的读写权限。

若需要通过命令行工具删除制品（例如：npm unpublish），则需要勾选 `registry-package-delete` 的读写权限。

另外，「使用范围」中「指定制品库」无法选中 Docker、Helm 和 Docker Model 制品库，
需选择「指定仓库」，然后再配置「常见场景」为「制品库」即可。

### 在云原生构建和云原生开发中使用令牌

有三种使用方式：

1. 直接使用环境变量 `${CNB_TOKEN_USER_NAME}` `${CNB_TOKEN}`（推荐）
2. 手动创建访问令牌并直接使用（不推荐）
3. 手动创建访问令牌，写入 [密钥仓库](../repo/secret.md#创建密钥仓库)后 [导入为环境变量](../repo/secret.md#导入为环境变量)

**关于方式 1 的说明：** CNB 在云原生构建和云原生开发中为用户内置了访问令牌，
可直接使用 `${CNB_TOKEN_USER_NAME}` 和 `${CNB_TOKEN}` 环境变量，无需额外创建。

## 容量统计

基于托管在 CNB 的制品所占存储空间计费。可在「用量统计」中查看各制品的容量。

> **注意**：Docker/Docker Model 制品的重复基础镜像会去重后计算容量。

## 制品迁移

如需批量将制品从其他仓库迁移至 CNB，可使用 [CNB 制品迁移工具](https://cnb.cool/cnb/plugins/cnbcool/artifact-migrate)。