密钥仓库

1669 字约 6 分钟

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

创建密钥仓库

进入创建页面 登录账号后，点击此处进入仓库创建页面。
选择仓库类型并填写信息 在仓库类型中，务必选择 密钥仓库，并填写相应的仓库名称与描述。
创建密钥仓库
完成创建 点击创建按钮，即可完成密钥仓库的创建。

核心特性

1. 操作限制

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

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

2. 安全增强机制

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

在流水线中引用

1. 存储密钥文件

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

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

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

2. 注入为环境变量

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

.cnb.yml
main:
  push:
    - services:
        - docker
      imports:
        # 引用密钥仓库中的特定文件
        - https://cnb.cool/<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_* 规则，系统将忽略触发者的角色权限，转而完全依据这些规则进行校验。所有规则均需通过，引用才被允许。详情请参阅权限检查。

4. 防范流水线内泄漏

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

防护建议：

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

最佳实践

分离与分类
- 环境分离: 为生产环境 (prod)、预发布环境 (staging)、开发测试环境 (dev) 等分别创建不同的密钥仓库或文件。
- 项目分离: 不同项目或应用使用独立的密钥仓库，实现权限和影响范围的隔离。
- 集中管理: 建议在独立的顶级组织中统一管理所有密钥仓库，严格限制拥有访问权限的成员范围。
最小权限原则
- 角色控制: 审慎分配密钥仓库的“管理员”和“负责人”角色，遵循“按需授权”原则。
- 范围控制: 积极使用 allow_* 系列配置，为每个密钥文件声明最小化的允许范围，避免过度授权。
  - allow_slugs: 限定只能被哪些项目引用。
  - allow_events: 限定只能由部署事件 (tag_push、tag_deploy.*) 触发，而非每次代码推送都触发。
  - allow_branches: 限定只能在稳定的保护分支上使用。
降低配置泄露风险
- 将包含敏感引用的流水线逻辑封装在受控的公共配置库中，通过 include 方式提供给其他业务项目使用。这将核心风险控制点收敛到少数几个仓库。
定期轮换与审计
- 密钥轮换: 建立定期轮换密钥的机制。只需在密钥仓库的 Web 界面更新文件内容，所有引用此文件的流水线将自动获取新值。
- 权限审计: 定期审查审计日志，清理已无效的引用和授权规则，并及时撤销离职或转岗成员的访问权限。