📚 课程目录第4章项目级变量

4、项目级变量：在 Project Settings 中配置、覆盖上级变量、项目专属密钥管理

项目级变量是 GitLab CI 变量分层治理中最常用、最灵活的层级。它位于实例级和组级之下，但高于作业级（通过 variables 关键字定义）。所有属于该项目的流水线都会自动继承项目级变量，除非在作业或 MR 中显式覆盖。

4.1 配置入口与作用范围

项目级变量的配置路径为：
Project → Settings → CI/CD → Variables

在此界面中，你可以添加、编辑、删除变量，并控制其可见性与保护级别。下表总结了项目级变量的核心属性：

属性	说明	典型用途
Key	变量名称，大写字母 + 下划线，如 `DEPLOY_`	在 `.gitlab-ci.yml` 中通过 `$DEPLOY_` 引用
Value	变量值，支持明文或掩码显示	、数据库连接串、云服务凭证
Type	`Variable`（默认）或 `File`	File 类型适用于证书、配置文件等二进制或长文本内容
Environment scope	限定变量仅在特定环境（如 `production`、`staging`）的作业中生效	多环境部署时隔离不同环境的密钥
Protect	勾选后，变量仅对受保护分支（如 `main`）和受保护标签可用	生产环境密钥、部署凭证
Mask	勾选后，变量值在作业日志中被 `****` 替换	密码、、私钥

最佳实践：对于敏感信息，始终同时勾选 Protect 和 Mask。Protect 防止非维护者分支读取密钥，Mask 防止密钥在日志中意外泄露。

4.2 覆盖上级变量：项目级 > 组级 > 实例级

当项目级变量与组级或实例级变量同名时，项目级变量会无条件覆盖上级变量。这一机制允许团队在组层面设置通用默认值，然后在项目层面按需定制。

覆盖规则遵循以下优先级（从高到低）：

作业级变量（.gitlab-ci.yml 中 variables 关键字定义）
项目级变量（Project Settings 中配置）
组级变量（Group Settings 中配置）
实例级变量（Admin Area 中配置）
预定义变量（GitLab 内置变量，如 CI_COMMIT_REF_NAME）

  覆盖示例：

  组级变量 DEPLOY_ENV=staging，项目级变量 DEPLOY_ENV=production。

  在该项目的流水线中，$DEPLOY_ENV 的值始终为 production，组级变量被完全覆盖。

4.3 项目专属密钥管理：典型场景与配置

项目级变量最常见的用途是管理项目专属密钥，包括但不限于：

云服务凭证：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY
容器仓库认证：CI_REGISTRY_USER、CI_REGISTRY_PASSWORD
第三方 API ：SLACK_、SONAR_
数据库连接串：DATABASE_URL、REDIS_URL
部署密钥：SSH_PRIVATE_KEY、KUBE_CONFIG

以下是一个典型的项目级变量配置示例，用于自动化部署到 Kubernetes：

# 在 Project Settings → CI/CD → Variables 中配置
Key: KUBE_NAMESPACE
Value: my-app-production
Type: Variable
Protect: ✅
Mask: ❌ (命名空间非敏感)

Key: KUBE_CONFIG_BASE64
Value: <base64 编码的 kubeconfig 内容>
Type: File
Protect: ✅
Mask: ✅

Key: DEPLOY_
Value: <GitLab Deploy >
Type: Variable
Protect: ✅
Mask: ✅

在 .gitlab-ci.yml 中引用这些变量：

deploy:
  stage: deploy
  script:
    - kubectl config use-context $KUBE_NAMESPACE
    - echo "$KUBE_CONFIG_BASE64" | base64 --decode > /tmp/kubeconfig
    - kubectl --kubeconfig /tmp/kubeconfig apply -f k8s/
  only:
    - main

安全警告：不要将密钥硬编码在 .gitlab-ci.yml 中。始终使用项目级变量，并启用 Protect 和 Mask。对于极高敏感度的密钥（如根证书私钥），建议结合 GitLab 的 External Secrets 或 HashiCorp Vault 集成。

4.4 项目级变量覆盖与继承关系图

下图展示了从实例级到项目级的变量继承与覆盖路径，以及项目级变量如何被作业级变量进一步覆盖：

4.5 环境作用域：精细化变量隔离

项目级变量支持环境作用域（Environment Scope），允许你为不同部署环境定义同名但不同值的变量。这在多环境流水线中非常实用，例如：

变量 Key	环境作用域	值	用途
`API_URL`	`*`（所有环境）	`https://api.example.com`	默认 API 地址
`API_URL`	`staging`	`https://staging-api.example.com`	预发布环境专用
`API_URL`	`production`	`https://prod-api.example.com`	生产环境专用

当作业的环境（通过 environment 关键字指定）匹配某个作用域时，该作用域的变量值会生效。如果未匹配到任何特定作用域，则使用 *（所有环境）的默认值。

使用建议：环境作用域与 Protect 结合使用效果最佳。例如，将生产环境作用域的变量设为受保护，确保只有 main 分支的部署作业才能读取生产密钥。

4.6 项目级变量管理清单

在配置项目级变量时，建议遵循以下检查清单：

最小权限原则：只添加当前项目必需的变量，避免将组级或实例级变量复制到项目级。
命名规范：使用大写字母、下划线分隔，如 DEPLOY_SSH_KEY，避免与预定义变量冲突。
定期轮换：为密钥设置过期提醒，定期在 Project Settings 中更新值。
审计日志：通过 GitLab 审计事件追踪变量变更（谁、何时、修改了哪个变量）。
避免重复：如果多个项目使用相同的密钥，优先在组级配置，然后在项目级按需覆盖。

通过合理使用项目级变量，你可以在保持安全性的同时，实现灵活的配置覆盖与密钥隔离，为多环境、多团队的 CI/CD 治理奠定坚实基础。