---
url: /zh/artifact/intro.md
---
本文将介绍 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            |

## 管理制品库

各制品类型与`组织`、`代码仓库`在 UI 界面展示的层级关系如下:

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

如上图所示，Composer/Maven 等制品库归属于某个`组织`下, 而 Docker/Helm/Docker Model 制品库则归属于`组织`下的`代码仓库`。

所以它们的使用步骤也会有所区别。

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

Docker/Helm/Docker Model 制品库归属于`代码仓库`, 所以无需手动创建。

登陆 cnb 后，您可以点击右上角「+」创建新的代码仓库
![](/images/artifact/create-git-repo.png)

也可以点击右上角「头像」，选择「我的仓库」，使用已有的代码仓库
![](/images/artifact/my-git-repo.png)

进入任意代码仓库后, 点击「制品」可以看到 Docker/Helm/Docker Model 制品库, 点击「使用指引」将会展示操作引导
![](/images/artifact/open-docker-helm-artifact.png)

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

#### 创建制品库

您可以点击右上角「+」创建新的制品库
![](/images/artifact/create-artifact.png)

也可以点击右上角「头像」，选择「我的制品库」，使用已有的制品库
![](/images/artifact/my-artifact-repo.png)

进入制品库后，点击「使用指引」将会展示操作引导
![](/images/artifact/use-artifact-intro.png)

### 删除制品

以 Composer 制品库举例 (其他类型制品库操作也类似，包括 Docker/Helm/Docker Model):

推送制品到制品库以后，点击制品库名字，进入该制品。
![](/images/artifact/artifact-list.png)

点击「删除制品」将删除整个制品。点击「删除」图标，将删除指定版本。
![](/images/artifact/delete-artifact.png)

### 删除制品库

Docker/Helm/Docker Model 制品库无需手动创建，所以也无需手动删除。

其他类型的制品库可以在「制品库设置」中删除
![](/images/artifact/delete-artifact-repo.png)

### 获取制品库的地址

您可以在「制品库设置」>「基础设置」中，查看制品库地址
![](/images/artifact/artifact-repo-addr.png)

## 权限管控

### 角色

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://cnb.build/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在 云原生构建(ci 流水线)，云原生开发 中为用户内置了`访问令牌`，若无特殊需求，可以直接使用该环境变量即可，无需再手动额外创建`访问令牌`。关于该`访问令牌`的权限范围，请参考 [CNB\_TOKEN](../build/build-in-env.md#cnb_token)

## 容量统计

我们将基于您托管在 CNB 的制品所占存储空间进行计费

* 对于 Docker/Helm/Docker Model，您可以在「代码仓库」>「设置」>「用量统计」 中查看每个制品所占用的容量
* 对于其他制品库，您可以在「制品库」>「制品库设置」>「用量统计」 中查看每个制品占用的容量

PS：针对 Docker/Docker Model 制品，重复的基础镜像会去重后计算容量。

## 制品迁移

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