---
url: /zh/repo/secret.md
---
密钥仓库是 `云原生构建` 提供的**高安全等级代码仓库**，专用于存储和管理敏感信息（如密码、API 密钥、证书、令牌等）。
它通过严格的访问控制、操作限制、审计日志与水印等多重安全机制，确保敏感数据在全生命周期内的安全存储与合规使用。

## 创建密钥仓库

1. **进入创建页面**
   登录账号后，[点击此处进入仓库创建页面](https://cnb.cool/new/repos)。

2. **选择仓库类型并填写信息**
   在仓库类型中，务必选择 **`密钥仓库`**，并填写相应的仓库名称与描述。

   ![创建密钥仓库](/images/keystore/create-keystore.zh.png)

3. **完成创建**
   点击创建按钮，即可完成密钥仓库的创建。

## 核心特性

### 1. 操作限制

为确保安全，密钥仓库相比普通仓库存在严格的操作限制：

| 能力               | 普通仓库 | 密钥仓库 | 说明                                     |
| :----------------- | :------- | :------- | :--------------------------------------- |
| Git Clone 到本地   | ✅        | ❌        | **禁止**将敏感数据下载到不受控的本地环境 |
| 本地推送代码       | ✅        | ❌        | **禁止**从本地推送更改，防止引入风险     |
| Web 界面编辑文件   | ✅        | ✅        | 所有更改必须通过受审计的 Web 界面进行    |
| 创建分支/Tag/PR    | ✅        | ✅        | 支持在受控范围内进行代码管理             |
| 被流水线引用       | ✅        | ✅        | 核心功能，支持在流水线中安全使用密钥 |

### 2. 安全增强机制

* **动态水印**: 所有页面自动添加当前用户名的半透明水印，有效防止截图泄露并进行责任追溯。
* **完整的审计日志**: 记录所有对该仓库文件的引用记录（如何时、被哪条流水线引用），支持全链路溯源。
* **强制 Web 端操作**: 仅支持在平台 Web 界面上进行文件编辑，从根本上杜绝本地环境可能带来的泄露风险。
* **严格的权限控制**: 遵循系统统一的[角色权限模型](../guide/role-permissions.md)，精细化管控人员访问权限。
* **声明式访问范围**: 可通过配置精确控制密钥文件的被引用条件，详见流水线文件引用中的[权限检查](../build/file-reference.md#权限检查)规则。

## 在流水线中引用

### 1. 存储密钥文件

在密钥仓库中，通常使用 `YAML` 或 `JSON` 文件来结构化地存储密钥。

```yaml
# env.prod.yml
# 生产环境密钥
DOCKER_USER: "prod_username"
DOCKER_TOKEN: "prod_token_123456"
DOCKER_REGISTRY: "registry.prod.com"
```

```yaml
# env.dev.yml
# 开发测试环境密钥
DOCKER_USER: "dev_username"
DOCKER_TOKEN: "dev_token_123456"
DOCKER_REGISTRY: "registry.dev.com"
```

### 2. 注入为环境变量

在流水线配置 (`.cnb.yml`) 中，通过 `imports` 关键字引用密钥仓库中的文件，将其内容自动注入为流水线任务的环境变量。

```yaml title=".cnb.yml"
main:
  push:
    - services:
        - docker
      imports:
        # 引用密钥仓库中的特定文件
        - https://cnb.share.ralphlauren.cn/<your-repo-slug>/-/blob/main/env.prod.yml
      stages:
        - name: 构建并推送镜像
          script: |
            # 注入的环境变量可直接在脚本中使用
            echo "登录到镜像仓库..."
            docker login -u $DOCKER_USER -p "$DOCKER_TOKEN" $DOCKER_REGISTRY
            echo "构建镜像..."
            docker build -t $DOCKER_REGISTRY/$CNB_REPO_SLUG_LOWERCASE:latest .
            echo "推送镜像..."
            docker push $DOCKER_REGISTRY/$CNB_REPO_SLUG_LOWERCASE:latest
```

### 3. 引用鉴权与范围控制

* **默认权限**: 默认情况下，只有密钥仓库的**管理员**和**负责人**身份成员触发的流水线才有权引用该仓库中的文件。
* **放宽权限与精细控制**: 若需允许更广泛的成员（如普通开发者）触发的流水线引用，必须在密钥文件中声明 `allow_*` 系列字段进行**精细化授权**，例如：
  * `allow_slugs`: 限制只有特定仓库的流水线可以引用。
  * `allow_events`: 限制只有特定事件（如 `tag_push`）触发的流水线可以引用。
  * `allow_branches`: 限制只有特定分支（如 `main`, `prod`）的流水线可以引用。
  * `allow_images`: 限制只有特定镜像的插件任务可以引用。

    **请注意**：一旦配置了 `allow_*` 规则，系统将**忽略触发者的角色权限**，转而完全依据这些规则进行校验。所有规则均需通过，引用才被允许。详情请参阅[权限检查](../build/file-reference.md#权限检查)。

### 4. 防范流水线内泄漏

虽然密钥仓库本身很安全，但密钥一旦被注入到流水线环境中，仍需警惕脚本中的泄漏风险（例如，误将环境变量打印到日志中）。

**防护建议：**

1. **保护流水线配置本身**: 将包含 `imports` 引用的流水线配置存放在一个**独立的、权限受控的仓库**中，其他业务仓库通过 `include` 来引入。从而限制修改流水线配置的人员范围。
2. **使用保护分支**: 结合密钥文件中的 `allow_branches` 规则，将其限制为只能在**保护分支**上使用。对保护分支的修改要求必须通过 Pull Request 并进行**代码评审**，从而增加一道人工审计关卡。
3. **审计与日志监控**: 定期检查流水线日志，关注异常行为。

## 最佳实践

1. **分离与分类**
   * **环境分离**: 为生产环境 (`prod`)、预发布环境 (`staging`)、开发测试环境 (`dev`) 等分别创建不同的密钥仓库或文件。
   * **项目分离**: 不同项目或应用使用独立的密钥仓库，实现权限和影响范围的隔离。
   * **集中管理**: 建议在独立的顶级组织中统一管理所有密钥仓库，严格限制拥有访问权限的成员范围。

2. **最小权限原则**
   * **角色控制**: 审慎分配密钥仓库的“管理员”和“负责人”角色，遵循“按需授权”原则。
   * **范围控制**: 积极使用 `allow_*` 系列配置，为每个密钥文件声明**最小化的允许范围**，避免过度授权。
     * `allow_slugs`: 限定只能被哪些项目引用。
     * `allow_events`: 限定只能由部署事件 (`tag_push`、`tag_deploy.*`) 触发，而非每次代码推送都触发。
     * `allow_branches`: 限定只能在稳定的保护分支上使用。

3. **降低配置泄露风险**
   * 将包含敏感引用的流水线逻辑封装在**受控的公共配置库**中，通过 `include` 方式提供给其他业务项目使用。这将核心风险控制点收敛到少数几个仓库。

4. **定期轮换与审计**
   * **密钥轮换**: 建立定期轮换密钥的机制。只需在密钥仓库的 Web 界面更新文件内容，所有引用此文件的流水线将自动获取新值。
   * **权限审计**: 定期审查审计日志，清理已无效的引用和授权规则，并及时撤销离职或转岗成员的访问权限。