环境

极狐GitLab 环境代表应用程序的特定部署目标，例如开发、预发布或生产环境。您可以使用它来管理不同的配置，并在软件生命周期的各个阶段部署代码。

借助环境，您可以：

• 保持部署流程一致且可重复
• 跟踪哪些代码部署在何处
• 出现问题时回滚到之前的版本
• 保护敏感环境免遭未经授权的更改
• 按环境控制部署变量，以维护安全边界
• 监控环境运行状况，并在出现问题时收到警报

查看环境和部署#

先决条件：

• 在私有项目中，您必须具有报告者、开发者、维护者或所有者角色。请参阅环境权限。

您可以通过以下几种方式查看给定项目的环境列表：

• 在项目的概览页面上，如果至少有一个环境可用（即未停止）。

  

• 在左侧边栏中，选择运维 > 环境。此时会显示环境。

  

• 要查看某个环境的部署列表，请选择环境名称， 例如 staging。只有在部署作业创建部署后，部署才会显示在此列表中。

  

• 要查看部署流水线中所有手动作业的列表，请选择运行 () 下拉列表。

  

环境 URL#

环境 URL 会显示在极狐GitLab 中的几个位置：

• 在合并请求中作为链接：

  

• 在环境视图中作为按钮：

  

• 在部署视图中作为按钮：

  

在以下情况下，您可以在合并请求中看到此信息：

• 该合并请求最终合并到默认分支（通常为 main）。
• 该分支也部署到某个环境（例如 staging 或 production）。

例如：

从源文件跳转到公开页面#

借助极狐GitLab 路由映射，您可以直接从源文件跳转到为评审应用设置的环境中的公开页面。

环境类型#

环境可以是静态的或动态的。

静态环境：

• 通常由后续部署重复使用。
• 具有静态名称。例如 staging 或 production。
• 手动创建，或作为 CI/CD 流水线的一部分创建。

动态环境：

• 通常在 CI/CD 流水线中创建，仅用于单次部署，随后停止或删除。
• 具有动态名称，通常基于某个 CI/CD 变量的值。
• 是评审应用的一项功能。

环境有三种状态之一，具体取决于其停止作业是否已运行：

• available：环境存在。可能存在部署。
• stopping：on stop 作业 已启动。如果未定义 on stop 作业，则此状态不适用。
• stopped：on stop 作业 已运行，或用户手动停止了该作业。

创建静态环境#

您可以在 UI 中或 .gitlab-ci.yml 文件中创建静态环境。

在 UI 中#

先决条件：

• 您必须具有开发者、维护者或所有者角色。

要在 UI 中创建静态环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 选择创建环境。
4. 填写各字段。
5. 选择保存。

在 .gitlab-ci.yml 文件中#

先决条件：

• 您必须具有开发者、维护者或所有者角色。

要创建静态环境，请在 .gitlab-ci.yml 文件中：

1. 在任意阶段中定义一个作业。 以下示例按惯例使用 deploy。
2. 在该作业中，定义环境 name 和 url。如果该名称的环境在流水线运行时不存在，则会创建该环境。

例如，要创建一个名为 staging、URL 为 https://staging.example.com的环境：

yaml
1deploy_staging:
2  stage: deploy
3  script:
4    - echo "Deploy to staging server"
5  environment:
6    name: staging
7    url: https://staging.example.com

创建动态环境#

要创建动态环境，您需要使用每个流水线独有的 CI/CD 变量。

先决条件：

• 您必须具有开发者、维护者或所有者角色。

要创建动态环境，请在 .gitlab-ci.yml 文件中：

1. 在任意阶段中定义一个作业。 以下示例按惯例使用 deploy。
2. 在该作业中，定义以下环境属性：
   • name：使用相关的 CI/CD 变量，例如 $CI_COMMIT_REF_SLUG。可选地，为环境名称添加静态 前缀，UI 中的分组会将所有 具有相同前缀的环境归为一组。
   • url：可选。为主机名添加相关 CI/CD 变量作为前缀，例如 $CI_ENVIRONMENT_SLUG。

在以下示例中，每次运行 deploy_review_app 作业时，环境的名称和 URL 都使用唯一值定义。

yaml
1deploy_review_app:
2  stage: deploy
3  script: make deploy
4  environment:
5    name: review/$CI_COMMIT_REF_SLUG
6    url: https://$CI_ENVIRONMENT_SLUG.example.com
7  rules:
8    - if: $CI_COMMIT_BRANCH == "main"
9      when: never
10    - if: $CI_COMMIT_BRANCH

设置动态环境 URL#

某些外部托管平台会为每次部署生成随机 URL，例如 https://94dd65b.amazonaws.com/qa-lambda-1234567。这使得在 .gitlab-ci.yml 文件中引用该 URL 变得困难。

您可以配置部署作业，将生成的 URL 捕获为 dotenv 变量，并将其传递给 environment:url。在作业中指定 artifacts:reports:dotenv。当作业完成时，极狐GitLab 会解析 dotenv 报告，并使用该变量值展开 environment:url。随后分配的 URL 会在 UI 中可见。

您还可以将静态前缀与变量组合使用，例如 https://$DYNAMIC_ENVIRONMENT_URL。如果 DYNAMIC_ENVIRONMENT_URL 为 example.com，则结果为 https://example.com。

在以下示例中，评审应用会为每个合并请求创建一个新环境：

• 每次推送都会触发 review 作业，并创建或更新名为 review/your-branch-name的环境。环境 URL 设置为 $DYNAMIC_ENVIRONMENT_URL。
• 当 review 作业完成时，极狐GitLab 会更新 review/your-branch-name 环境的 URL。 它会解析 deploy.env 报告，提取变量，并使用它们展开和设置 environment:url。

yaml
1review:
2  script:
3    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
4    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
5  artifacts:
6    reports:
7      dotenv: deploy.env                                                       # Report back dotenv file to rails.
8  environment:
9    name: review/$CI_COMMIT_REF_SLUG
10    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
11    on_stop: stop_review
12
13stop_review:
14  script:
15    - ./teardown-environment
16  when: manual
17  environment:
18    name: review/$CI_COMMIT_REF_SLUG
19    action: stop

请注意以下事项：

• stop_review 不会生成 dotenv 报告产物，因此它无法识别 DYNAMIC_ENVIRONMENT_URL 环境变量。因此，您不应在 stop_review 作业中设置 environment:url。
• 如果环境 URL 无效（例如 URL 格式错误），系统不会更新 环境 URL。
• 如果在 stop_review中运行的脚本仅存在于您的代码仓库中，因此无法使用 GIT_STRATEGY: none 或 GIT_STRATEGY: empty，请为这些作业配置 合并请求流水线。 这可确保即使功能分支被删除，Runner 也能获取代码仓库。有关更多信息，请参阅 Runner 的 Ref Specs。

powershell
Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"

环境的部署层级#

同一群组中的项目可以为同一部署层级使用不同的环境名称。例如，一个项目可能使用 production，而另一个项目为同一层级使用 custom-portal。群组受保护环境使用部署层级来处理这些差异。

可用的部署层级如下：

• development
• testing
• staging
• production
• other

极狐GitLab 根据以下模式从环境名称推测部署层级：

不匹配任何模式的环境名称会被推测为 other。

要避免自动推测，请使用 deployment_tier 关键字。

您无法在 UI 中设置部署层级。

重命名环境#

您无法重命名环境。

要达到与重命名环境相同的效果：

1. 停止现有环境。
2. 删除现有环境。
3. 使用所需名称创建新环境。

CI/CD 变量#

要自定义您的环境和部署，您可以使用任何预定义 CI/CD 变量，并定义自定义 CI/CD 变量。

限制 CI/CD 变量的环境范围#

默认情况下，所有 CI/CD 变量都可供流水线中的所有作业使用。如果作业中的某个测试工具被攻破，该工具可能会尝试获取该作业可用的所有 CI/CD 变量。为帮助缓解此类供应链攻击，您应将敏感变量的环境范围限制为仅需要它们的作业。

通过定义 CI/CD 变量可用于哪些环境来限制其环境范围。默认环境范围是 * 通配符，因此任何作业都可以访问该变量。

您可以使用特定匹配来选择特定环境。例如，将变量的环境范围设置为 production，以仅允许环境为 production的作业访问该变量。

您还可以使用通配符匹配（*）来选择特定环境组，例如所有使用 review/* 的评审应用。

例如，对于以下四个环境：

• production
• staging
• review/feature-1
• review/feature-2

这些环境范围的匹配情况如下：

您不应将环境范围变量与 rules 或 include 一起使用。当极狐GitLab 在流水线创建时验证流水线配置时，这些变量可能尚未定义。

搜索环境#

要按名称搜索环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 在搜索栏中，输入搜索词。
   • 搜索词的长度应为三个或更多字符。
   • 匹配从环境名称的开头开始。
     • 例如，devel 匹配环境名称 development，但 elop 不匹配。
   • 对于采用文件夹名称格式的环境，匹配在基础文件夹名称之后进行。
     • 例如，当名称为 review/test-app 时，搜索词 test 匹配 review/test-app。
     • 使用带文件夹名称前缀的搜索（如 review/test）也会匹配 review/test-app。

对相似环境进行分组#

您可以在 UI 中将环境分组到可折叠的区块中。

例如，如果您的所有环境都以名称 review 开头，那么在 UI 中，这些环境会分组在该标题下：

以下示例展示了如何让环境名称以 review 开头。$CI_COMMIT_REF_SLUG 变量在运行时用分支名称填充：

yaml
1deploy_review:
2  stage: deploy
3  script:
4    - echo "Deploy a review app"
5  environment:
6    name: review/$CI_COMMIT_REF_SLUG

停止环境#

停止环境意味着其部署在目标服务器上不再可访问。您必须先停止环境，然后才能删除它。

使用 on_stop 操作停止环境时，如果作业未被归档，则该作业会运行。

使用 UI 停止环境#

要在极狐GitLab UI 中停止环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 在要停止的环境旁边，选择停止。
4. 在确认对话框中，选择停止环境。

您也可以在不运行 on_stop 操作的情况下停止环境。

默认停止行为#

当关联的分支被删除或合并时，极狐GitLab 会自动停止环境。即使未定义显式的 on_stop CI/CD 作业，此行为也会持续。

但是，议题 428625 提议更改此行为，以便生产和预发布环境仅在定义了显式 on_stop CI/CD 作业时才停止。

您可以使用环境 API 中的 auto_stop_setting 参数来配置环境的停止行为。

在分支被删除时停止环境#

您可以配置环境在分支被删除时停止。

在以下示例中，deploy_review 作业调用 stop_review 作业来清理并停止环境。

• 两个作业必须具有相同的 rules 或 only/except 配置。否则， stop_review 作业可能不会包含在包含 deploy_review 作业的所有流水线中，您也无法触发 action: stop 来自动停止环境。
• 如果带有 action: stop 的作业位于启动环境的作业之后的阶段，则该作业可能不会运行。
• 如果您无法使用合并请求流水线， 请在 stop_review 作业中将 GIT_STRATEGY 设置为 none 或 empty。 这样，Runner 在分支被删除后 就不会尝试检出代码。

yaml
1deploy_review:
2  stage: deploy
3  script:
4    - echo "Deploy a review app"
5  environment:
6    name: review/$CI_COMMIT_REF_SLUG
7    url: https://$CI_ENVIRONMENT_SLUG.example.com
8    on_stop: stop_review
9
10stop_review:
11  stage: deploy
12  script:
13    - echo "Remove review app"
14  environment:
15    name: review/$CI_COMMIT_REF_SLUG
16    action: stop
17  when: manual

在合并请求被合并或关闭时停止环境#

当您使用合并请求流水线配置时，stop 触发器会自动启用。

在以下示例中，deploy_review 作业调用 stop_review 作业来清理并停止环境。

• 当流水线必须成功设置开启时， 您可以在 stop_review 作业上配置 allow_failure: true 关键字，以防止它阻塞您的流水线和合并请求。

yaml
1deploy_review:
2  stage: deploy
3  script:
4    - echo "Deploy a review app"
5  environment:
6    name: review/$CI_COMMIT_REF_SLUG
7    on_stop: stop_review
8  rules:
9    - if: $CI_MERGE_REQUEST_ID
10
11stop_review:
12  stage: deploy
13  script:
14    - echo "Remove review app"
15  environment:
16    name: review/$CI_COMMIT_REF_SLUG
17    action: stop
18  rules:
19    - if: $CI_MERGE_REQUEST_ID
20      when: manual

在特定时间段后停止环境#

您可以将环境设置为在特定时间段后自动停止。

在 .gitlab-ci.yml 文件中，指定 environment:auto_stop_in 关键字。使用自然语言指定时间段，例如 1 hour and 30 minutes 或 1 day。时间段过后，极狐GitLab 会自动启动作业来停止环境。

在以下示例中：

• 合并请求上的每次提交都会运行 review_app 作业，将最新更改部署到 环境并重置其到期时间。
• 如果环境超过一周处于非活动状态，极狐GitLab 会自动运行 stop_review_app 作业来停止环境。

yaml
1review_app:
2  script: deploy-review-app
3  environment:
4    name: review/$CI_COMMIT_REF_SLUG
5    on_stop: stop_review_app
6    auto_stop_in: 1 week
7  rules:
8    - if: $CI_MERGE_REQUEST_ID
9
10stop_review_app:
11  script: stop-review-app
12  environment:
13    name: review/$CI_COMMIT_REF_SLUG
14    action: stop
15  rules:
16    - if: $CI_MERGE_REQUEST_ID
17      when: manual

environment:action 关键字可用于重置环境计划停止的时间。有关更多信息，请参阅为准备或验证目的访问环境。

查看环境的计划停止日期和时间#

当环境已计划在指定时间段后停止时，您可以查看其到期日期和时间。

要查看环境的到期日期和时间：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 选择环境的名称。

到期日期和时间显示在左上角，紧邻环境名称。

覆盖环境的计划停止日期和时间#

当环境已计划在指定时间段后停止时，您可以覆盖其到期时间。

要在 UI 中覆盖环境的到期时间：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 选择环境名称。
4. 在右上角，选择图钉 ()。

要在 .gitlab-ci.yml中覆盖环境的到期时间：

1. 打开项目的 .gitlab-ci.yml。
2. 将相应部署作业的 auto_stop_in 设置更新为 auto_stop_in: never。

auto_stop_in 设置会被覆盖，环境会保持活动状态，直到手动停止。

清理陈旧环境#

当您想要停止项目中的旧环境时，可以清理陈旧环境。

先决条件：

• 您必须具有维护者或所有者角色。

要清理陈旧环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 选择清理环境。
4. 选择用于确定哪些环境被视为陈旧的日期。
5. 选择清理。

在指定日期之后未更新的活动环境会被停止。受保护环境会被忽略，不会停止。

在环境停止时运行流水线作业#

您可以在环境的部署作业中使用 on_stop 操作为环境定义停止作业。

当环境停止时，最新完成的流水线中已完成部署的停止作业会运行。如果部署或流水线具有成功、已取消或失败状态，则视为已完成。

先决条件：

• 部署作业和停止作业必须具有相同的 rules 或 only/except 配置。
• 停止作业必须定义以下关键字：
  • when，定义在以下任一位置：
    • 作业级别。
    • 在 rules 子句中。如果您使用 rules 和 when: manual，您还应 设置 allow_failure: true，以便即使作业不运行， 流水线也能完成。
  • environment:name
  • environment:action

在以下示例中：

• review_app 作业在第一个作业完成后调用 stop_review_app 作业。
• stop_review_app 根据 when 下定义的内容触发。在此 情况下，它设置为 manual，因此需要 从极狐GitLab UI 执行手动操作 才能运行。
• GIT_STRATEGY 设置为 none。如果 stop_review_app 作业 自动触发， 则 Runner 在分支被删除后不会尝试检出代码。

yaml
1review_app:
2  stage: deploy
3  script: make deploy-app
4  environment:
5    name: review/$CI_COMMIT_REF_SLUG
6    url: https://$CI_ENVIRONMENT_SLUG.example.com
7    on_stop: stop_review_app
8
9stop_review_app:
10  stage: deploy
11  variables:
12    GIT_STRATEGY: none
13  script: make delete-app
14  when: manual
15  environment:
16    name: review/$CI_COMMIT_REF_SLUG
17    action: stop

环境的多个停止操作#

要为环境配置多个并行停止操作，请在同一 environment的多个部署作业中指定 on_stop 关键字，如 .gitlab-ci.yml 文件中所定义。

当环境停止时，仅来自成功部署作业的匹配 on_stop 操作会并行运行，顺序不分先后。

在以下示例中，test 环境有两个部署作业：

• deploy-to-cloud-a
• deploy-to-cloud-b

当环境停止时，系统会并行运行 on_stop 操作 teardown-cloud-a 和 teardown-cloud-b。

yaml
1deploy-to-cloud-a:
2  script: echo "Deploy to cloud a"
3  environment:
4    name: test
5    on_stop: teardown-cloud-a
6
7deploy-to-cloud-b:
8  script: echo "Deploy to cloud b"
9  environment:
10    name: test
11    on_stop: teardown-cloud-b
12
13teardown-cloud-a:
14  script: echo "Delete the resources in cloud a"
15  environment:
16    name: test
17    action: stop
18  when: manual
19
20teardown-cloud-b:
21  script: echo "Delete the resources in cloud b"
22  environment:
23    name: test
24    action: stop
25  when: manual

在不运行 on_stop 操作的情况下停止环境#

您可以强制停止环境，以跳过其 on_stop 操作。使用此选项可以：

• 在不使用计算配额运行停止作业的情况下删除多个环境。
• 恢复卡在 stopping 状态的环境。例如，当 源分支在 auto_stop_in 计时器触发停止作业之前被删除时，可能会发生这种情况。

强制停止环境会立即将其标记为已停止，并将其移动到已停止标签页。极狐GitLab 不会运行或等待 on_stop 作业，因此该作业中的清理步骤不会运行。您必须自行完成此清理。极狐GitLab 仍会删除使用 delete_resources: on_stop的 极狐GitLab 管理的 Kubernetes 资源。

强制停止不会取消已处于待处理或运行状态的 on_stop 作业。如果该作业稍后完成，环境会保持已停止状态。要阻止该作业运行，请手动取消它。

先决条件：

• 要强制停止未受保护的环境，您必须至少具有开发者角色。
• 要强制停止受保护的环境，您必须被允许部署到该环境。

要在极狐GitLab UI 中强制停止环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 如果环境可用且定义了 on_stop 操作：
   1. 在环境旁边，选择停止。
   2. 在确认对话框中，选中强制停止复选框。
   3. 选择强制停止环境。
4. 如果环境卡在 stopping 状态：
   1. 在环境旁边，选择更多操作 () > 强制停止环境。
   2. 在确认对话框中，选择强制停止环境。 或者，在环境详情页面上，选择强制停止。

您也可以使用停止环境 API 并带上参数 force=true 来强制停止环境。

删除环境#

当您想要移除环境及其所有部署时，可以删除环境。

先决条件：

• 您必须具有开发者、维护者或所有者角色。
• 您必须先停止环境，然后才能删除它。

要删除环境：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择运维 > 环境。
3. 选择已停止标签页。
4. 在要删除的环境旁边，选择删除环境。
5. 在确认对话框中，选择删除环境。

为准备或验证目的访问环境#

您可以定义一个作业，出于各种目的（例如验证或准备）访问环境。这实际上绕过了部署创建，因此您可以更准确地调整 CD 工作流。

为此，请将 action: prepare、action: verify 或 action: access 添加到作业的 environment 部分：

yaml
1build:
2  stage: build
3  script:
4    - echo "Building the app"
5  environment:
6    name: staging
7    action: prepare
8    url: https://staging.example.com

这使您可以访问环境范围变量，并可用于保护构建免遭未经授权的访问。此外，它还有助于避免阻止过时的部署作业功能。

如果环境配置为在特定时间段后停止，带有 access 或 prepare 操作的作业会重置计划停止时间。重置计划时间时，会使用最近一次成功部署到该环境的作业中的 environment:auto_stop_in。例如，如果最近一次部署使用了 auto_stop_in: 1 week，之后被带有 action: access的作业访问，则环境会重新计划为在访问作业完成一周后停止。

要在不更改计划停止时间的情况下访问环境，请使用 verify 操作。

环境事件管理#

生产环境可能会意外宕机，包括出于您无法控制的原因。例如，外部依赖项、基础设施或人为错误的问题可能导致环境出现重大问题。例如：

• 依赖的云服务宕机。
• 第三方库更新，与您的应用程序不兼容。
• 有人对您服务器中易受攻击的端点执行 DDoS 攻击。
• 运维人员错误配置基础设施。
• 生产应用程序代码中引入了一个缺陷。

您可以使用事件管理在出现需要立即关注的严重问题时收到警报。

查看环境的最新警报#

如果您设置了警报集成，环境的警报会显示在环境页面上。会显示严重性最高的警报，以便您可以识别哪些环境需要立即关注。

当触发警报的问题解决后，该警报会被移除，不再显示在环境页面上。

如果警报需要回滚，您可以从环境页面选择部署标签页，并选择要回滚到的部署。

自动回滚#

在典型的持续部署工作流中，CI 流水线会在部署到生产环境之前测试每次提交。但是，有问题的代码仍可能进入生产环境。例如，逻辑正确但效率低下的代码即使导致严重的性能下降，也可能通过测试。运维人员和 SRE 会监控系统，以尽快发现这些问题。如果他们发现有问题的部署，可以回滚到之前的稳定版本。

极狐GitLab 自动回滚通过在检测到严重警报时自动触发回滚，简化了此工作流。为了让极狐GitLab 选择合适的环境进行回滚，警报应包含一个 gitlab_environment_name 键，其值为环境名称。极狐GitLab 会选择并重新部署最近一次成功的部署。

极狐GitLab 自动回滚的限制：

• 如果检测到警报时有部署正在运行，则跳过回滚。
• 回滚在三分钟内只能发生一次。如果同时检测到多个警报，只会 执行一次回滚。

极狐GitLab 自动回滚默认关闭。要开启它：

1. 在顶部栏中，选择搜索或跳转到，然后找到您的项目。
2. 在左侧边栏中，选择设置 > CI/CD。
3. 展开自动部署回滚。
4. 选中启用自动回滚复选框。
5. 选择保存更改。

环境权限#

根据您的角色，您可以在公开和私有项目中与环境交互。

查看环境#

• 在公开项目中，任何人都可以查看环境列表，包括非成员。
• 在私有项目中，您必须具有报告者、开发者、维护者或所有者角色才能查看环境列表。

创建和更新环境#

• 您必须具有开发者、维护者或所有者角色才能创建新环境，或更新现有的未受保护环境。
• 对于受保护环境，您必须位于允许部署列表中。

停止和删除环境#

• 您必须具有开发者、维护者或所有者角色才能停止或删除未受保护的环境。
• 如果环境受保护且您无权访问它，则无法停止或删除该环境。

在受保护环境中运行部署作业#

如果您可以推送到或合并到受保护分支：

• 您必须具有报告者、开发者、维护者或所有者角色。

如果您无法推送到受保护分支：

• 您必须是具有报告者角色的群组成员。

请参阅对受保护环境的仅部署访问权限。

Web 终端（已弃用）#

如果您借助部署服务（例如 Kubernetes 集成）部署到环境，极狐GitLab 可以打开 到您环境的终端会话。这样您无需离开 Web 浏览器即可调试问题。

Web 终端是基于容器的部署，通常缺少基本工具（如编辑器），并且可能随时停止或重启。如果发生这种情况，您将丢失所有更改。请将 Web 终端视为调试工具，而不是全面的在线 IDE。

Web 终端：

• 仅对项目维护者和所有者可用。
• 必须启用。

在 UI 中，要查看 Web 终端，可以：

• 从操作菜单中，选择终端：

  

• 在特定环境的页面上，在右侧选择终端 ()。

选择该按钮以建立终端会话。它的工作方式与任何其他终端一样。您位于部署所创建的容器中，因此您可以：

• 运行 shell 命令并实时获取响应。
• 查看日志。
• 尝试配置或代码调整。

您可以为同一环境打开多个终端。它们各自拥有自己的 shell 会话，甚至可以使用 screen 或 tmux 等多路复用器。

故障排除#

带有 action: stop的作业不运行#

在某些情况下，尽管配置了 on_stop 作业，环境也不会停止。当带有 action: stop的作业由于其 stages: 或 needs: 配置而处于不可运行状态时，就会发生这种情况。

例如：

• 环境可能在一个同时有失败作业的阶段中启动。 那么后续阶段中的作业不会启动。如果该环境的带有 action: stop 的作业也位于后续阶段，它就无法启动，环境也不会被删除。
• 带有 action: stop的作业可能依赖于一个尚未完成的作业。

为确保 action: stop 在需要时始终可以运行，您可以：

• 将两个作业放在同一阶段：

  yaml
  1stages:
  2  - build
  3  - test
  4  - deploy
  5
  6...
  7
  8deploy_review:
  9  stage: deploy
  10  environment:
  11    name: review/$CI_COMMIT_REF_SLUG
  12    url: https://$CI_ENVIRONMENT_SLUG.example.com
  13    on_stop: stop_review
  14
  15stop_review:
  16  stage: deploy
  17  environment:
  18    name: review/$CI_COMMIT_REF_SLUG
  19    action: stop
  20  when: manual

• 为 action: stop 作业添加一个 needs 条目，以便 该作业可以脱离阶段顺序启动：

  yaml
  1stages:
  2  - build
  3  - test
  4  - deploy
  5  - cleanup
  6
  7...
  8
  9deploy_review:
  10  stage: deploy
  11  environment:
  12    name: review/$CI_COMMIT_REF_SLUG
  13    url: https://$CI_ENVIRONMENT_SLUG.example.com
  14    on_stop: stop_review
  15
  16stop_review:
  17  stage: cleanup
  18  needs:
  19    - deploy_review
  20  environment:
  21    name: review/$CI_COMMIT_REF_SLUG
  22    action: stop
  23  when: manual

错误：作业 would create an environment with an invalid parameter#

如果您的项目配置为创建动态环境，您可能会在部署作业中遇到此错误，因为动态生成的参数无法用于创建环境：

plaintext
This job could not be executed because it would create an environment with an invalid parameter.

例如，您的项目有以下 .gitlab-ci.yml：

yaml
deploy:
  script: echo
  environment: production/$ENVIRONMENT

由于 $ENVIRONMENT 变量在流水线中不存在，极狐GitLab 会尝试创建一个名为 production/ 的环境，这在环境名称约束中是无效的。

要解决此问题，请使用以下解决方案之一：

• 从部署作业中移除 environment 关键字。极狐GitLab 一直 在忽略该无效关键字，因此即使移除该关键字，您的部署流水线仍保持完好。
• 确保该变量在流水线中存在。请查看 受支持变量的限制。
• 如果您的 .gitlab-ci.yml中有 environment:deployment_tier，请确保该值是 受支持的层级之一：production、staging、testing、development 或 other。

如果您在评审应用上遇到此错误#

例如，如果您的 .gitlab-ci.yml中有以下内容：

yaml
review:
  script: deploy review app
  environment: review/$CI_COMMIT_REF_NAME

当您创建一个分支名称为 bug-fix! 的新合并请求时，review 作业会尝试创建一个环境 review/bug-fix!。但是，! 是环境的无效字符，因此部署作业会失败，因为它将在没有环境的情况下运行。

要解决此问题，请使用以下解决方案之一：

• 重新创建不含无效字符的功能分支， 例如 bug-fix。

• 将 CI_COMMIT_REF_NAME 预定义变量替换为 CI_COMMIT_REF_SLUG，后者会去除任何无效字符：

  yaml
  review:
    script: deploy review app
    environment: review/$CI_COMMIT_REF_SLUG