Help us learn about your current experience with the documentation. Take the survey.

GitLab for Jira Cloud 应用管理故障排除

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

在管理 GitLab for Jira Cloud 应用时，您可能会遇到以下问题。

已登录时仍显示登录提示消息

当您已经登录时，可能会收到以下提示您登录到 GitLab.com 的消息：

You need to sign in or sign up before continuing.

GitLab for Jira Cloud 应用使用 iframe 在设置页面上添加群组。某些浏览器会阻止跨站 Cookie，这可能导致此问题。

要解决此问题，请设置 OAuth 身份验证。

手动安装失败

如果您从官方应用市场列表安装了 GitLab for Jira Cloud 应用，然后将其替换为手动安装，您可能会收到以下错误之一：

The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace

The app host returned HTTP response code 401 when we tried to contact it during installation. Please try again later or contact the app vendor.

要解决此问题，请禁用 Jira Connect Proxy URL 设置。

在 GitLab 15.7 中：
1. 打开 Rails 控制台。
2. 执行 ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)。
在 GitLab 15.8 及更高版本中：
1. 在左侧边栏的底部，选择 管理员。
2. 在左侧边栏中，选择 Settings > General。
3. 展开 GitLab for Jira App。
4. 清除 Jira Connect Proxy URL 文本框。
5. 选择 Save changes。

如果问题仍然存在，请验证您的实例可以连接到 connect-install-keys.atlassian.com 以从 Atlassian 获取公钥。要测试连接性，请运行以下命令：

# 预期会返回 `404 Not Found`，因为您没有传递令牌
curl --head "https://connect-install-keys.atlassian.com"

数据同步失败并显示 `Invalid JWT`

如果 GitLab for Jira Cloud 应用持续无法从您的实例同步数据，则某个密钥令牌可能已过期。Atlassian 可以向 GitLab 发送新的密钥令牌。如果 GitLab 未能处理或存储这些令牌，则会发生 Invalid JWT 错误。

要解决此问题：

确认实例可公开访问：
- GitLab.com（如果您从官方 Atlassian 应用市场列表安装了该应用）。
- Jira Cloud（如果您手动安装了该应用）。
确保安装应用时发送到 /-/jira_connect/events/installed 端点的令牌请求可从 Jira 访问。以下命令应返回 401 Unauthorized：
```
curl --include --request POST "https://gitlab.example.com/-/jira_connect/events/installed"
```
如果您的实例配置了 SSL，请检查您的证书是否有效且受公众信任。

根据您安装应用的方式，您可能需要检查以下内容：

如果您从官方 Atlassian 应用市场列表安装了该应用，请在 GitLab for Jira Cloud 应用中切换 GitLab 版本：
1. 在 Jira 中，在顶部栏上，选择 Apps > Manage your apps。
2. 展开 GitLab for Jira (gitlab.com)。
3. 选择 Get started。
4. 选择 Change GitLab version。
5. 选择 GitLab.com (SaaS)，然后选择 Save。
6. 再次选择 Change GitLab version。
7. 选择 GitLab (self-managed)，然后选择 Next。
8. 选择所有复选框，然后选择 Next。
9. 输入您的 GitLab instance URL，然后选择 Save。
如果此方法不起作用，并且您是 Premium 或 Ultimate 客户，请提交支持工单。提供您的 GitLab 实例 URL 和 Jira URL。GitLab 支持团队可以尝试运行以下脚本来解决问题：
```
# 检查 GitLab.com 是否可以连接到 GitLab Self-Managed 实例
checker = Gitlab::TcpChecker.new("gitlab.example.com", 443)

# 如果成功则返回 `true`
checker.check

# 如果检查失败则返回错误
checker.error
```
```
# 查找 GitLab Self-Managed 实例的安装记录
installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")

# 尝试再次从 GitLab.com 向 GitLab Self-Managed 实例发送令牌
ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
```
如果您手动安装了该应用：
- 请求 Jira Cloud 支持验证 Jira 是否可以连接到您的实例。
- 重新安装该应用。此方法可能会从 Jira 开发面板中删除所有已同步的数据。

错误：`Failed to update the GitLab instance`

当您设置 GitLab for Jira Cloud 应用时，在输入 GitLab Self-Managed 实例 URL 后，可能会收到 Failed to update the GitLab instance 错误。

要解决此问题，请确保已满足您安装方法的所有先决条件：

如果您配置了 Jira Connect Proxy URL，并且在检查先决条件后问题仍然存在，请查看调试 Jira Connect Proxy 问题。

如果您使用的是 GitLab 15.8 及更早版本，并且之前同时启用了 jira_connect_oauth_self_managed 和 jira_connect_oauth 功能标志，则由于一个已知问题，您必须禁用 jira_connect_oauth_self_managed 标志。要检查这些标志：

打开 Rails 控制台。

执行以下代码：

# 检查两个功能标志是否都已启用。
# 如果标志已启用，这些命令将返回 `true`。
Feature.enabled?(:jira_connect_oauth)
Feature.enabled?(:jira_connect_oauth_self_managed)

# 如果两个标志都已启用，请禁用 `jira_connect_oauth_self_managed` 标志。
Feature.disable(:jira_connect_oauth_self_managed)

错误：`Invalid audience`

如果您使用的是反向代理， exceptions_json.log 中可能包含如下消息：

Invalid audience. Expected https://proxy.example.com/-/jira_connect, received https://gitlab.example.com/-/jira_connect

要解决此问题，请将反向代理 FQDN 设置为额外的 JWT 受众。

调试 Jira Connect Proxy 问题

如果您在设置实例时将 Jira Connect Proxy URL 设置为 https://gitlab.com，您可以：

在浏览器的开发工具中检查网络流量。
重现 Failed to update the GitLab instance 错误以获取更多信息。

您应该会看到一个对 https://gitlab.com/-/jira_connect/installations 的 GET 请求。

此请求应返回 200 OK，但如果出现问题，可能会返回 422 Unprocessable Entity。您可以检查响应正文以获取错误信息。

如果您无法解决问题并且您是 GitLab 客户，请联系 GitLab 支持寻求帮助。向 GitLab 支持团队提供：

您的 GitLab Self-Managed 实例 URL。
您的 GitLab.com 用户名。
可选。失败的 GET 请求到 https://gitlab.com/-/jira_connect/installations 的 X-Request-Id 响应头。
可选。您已使用 harcleaner 处理过的、捕获该问题的 HAR 文件。

然后，GitLab 支持团队可以在 GitLab.com 服务器日志中调查该问题。

GitLab 支持

这些步骤只能由 GitLab 支持团队完成。

每次向 Jira Connect Proxy URL https://gitlab.com/-/jira_connect/installations 发出的 GET 请求都会生成两个日志条目。

要在 Kibana 中定位相关的日志条目，请执行以下任一操作：

如果您拥有对 https://gitlab.com/-/jira_connect/installations 的 GET 请求的 X-Request-Id 值或关联 ID，则 Kibana 日志应按 json.meta.caller_id: JiraConnect::InstallationsController#update、NOT json.status: 200 和 json.correlation_id: <X-Request-Id> 进行过滤。这应该会返回两个日志条目。
如果您拥有客户的 Self-Managed URL：
1. Kibana 日志应按 json.meta.caller_id: JiraConnect::InstallationsController#update、NOT json.status: 200 和 json.params.value: {"instance_url"=>"https://gitlab.example.com"} 进行过滤。Self-Managed URL 不能有前导斜杠。这应该会返回其中一个日志条目。
2. 将 json.correlation_id 添加到筛选器中。
3. 移除 json.params.value 筛选器。这应该会返回另一个日志条目。

对于第一个日志：

json.status 是 422 Unprocessable Entity。
json.params.value 应与 GitLab Self-Managed URL [[FILTERED], {"instance_url"=>"https://gitlab.example.com"}] 匹配。

对于第二个日志，您可能会遇到以下情况之一：

情况 1：
- 存在 json.message、json.jira_status_code 和 json.jira_body。
- json.message 是 Proxy lifecycle event received error response 或类似信息。
- json.jira_status_code 和 json.jira_body 可能包含从 GitLab Self-Managed 实例或实例前端的代理收到的响应。
- 如果 json.jira_status_code 是 401 Unauthorized 且 json.jira_body 是 (empty)：
  - Jira Connect Proxy URL 可能未设置为 https://gitlab.com。
  - GitLab Self-Managed 实例可能正在阻止传出连接。确保您的 GitLab Self-Managed 实例可以连接到 connect-install-keys.atlassian.com 和 gitlab.com。
  - GitLab Self-Managed 实例无法解密来自 Jira 的 JWT 令牌。从 GitLab 16.11 开始， exceptions_json.log 包含有关错误的更多信息。
  - 如果反向代理位于您的 GitLab Self-Managed 实例前面，则发送到 GitLab Self-Managed 实例的 Host 头可能与反向代理 FQDN 不匹配。检查 GitLab Self-Managed 实例上的 Workhorse 日志：
    grep /-/jira_connect/events/installed /var/log/gitlab/gitlab-workhorse/current
    输出可能包含以下内容：
    { "host":"gitlab.mycompany.com:443", // 主机应与输入到 GitLab for Jira Cloud 应用中的反向代理 FQDN 匹配 "remote_ip":"34.74.226.3", // 此 IP 应在 GitLab.com IP 范围内 https://docs.gitlab.com/ee/user/gitlab_com/#ip-range "status":401, "uri":"/-/jira_connect/events/installed" }
情况 2：
- 存在 json.exception.class 和 json.exception.message。
- json.exception.class 和 json.exception.message 包含联系 GitLab Self-Managed 实例时是否发生问题。

错误：`Failed to link group`

当您链接群组时，可能会收到以下错误：

Failed to link group. Please try again.

此错误可能由多种原因返回。

如果由于权限不足而无法从 Jira 获取用户信息，则可能返回 403 Forbidden。要解决此问题，请确保安装和配置该应用的 Jira 用户满足某些要求。
如果您将重写或子过滤器与反向代理一起使用，也可能发生此错误。请求中使用的应用密钥包含服务器主机名的一部分，某些反向代理过滤器可能会捕获它。 Atlassian 和 GitLab 中的应用密钥必须匹配才能使身份验证正常工作。
如果在首次安装 GitLab for Jira Cloud 应用时 GitLab 实例最初配置错误，则可能发生此错误。在这种情况下，jira_connect_installation 表中的数据可能需要删除。仅当您确定不需要保留任何现有的 GitLab for Jira 应用安装时，才删除此数据。
1. 从任何 Jira 项目中卸载 GitLab for Jira Cloud 应用。
2. 要删除记录，请在 GitLab Rails 控制台中运行此命令：
```
JiraConnectInstallation.delete_all
```

错误：`Failed to load Jira Connect Application ID`

当您将应用指向您的 GitLab Self-Managed 实例后登录 GitLab for Jira Cloud 应用时，可能会收到以下错误：

Failed to load Jira Connect Application ID. Please try again.

当您检查浏览器控制台时，可能还会看到以下消息：

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403.

要解决此问题：

确保 /-/jira_connect/oauth_application_id 可公开访问并返回 JSON 响应：
```
curl --include "https://gitlab.example.com/-/jira_connect/oauth_application_id"
```
如果您从官方 Atlassian 应用市场列表安装了该应用，请确保 Jira Connect Proxy URL 设置为 https://gitlab.com，且没有尾部斜杠。

错误：`Missing required parameter: client_id`

当您将应用指向您的 GitLab Self-Managed 实例后登录 GitLab for Jira Cloud 应用时，可能会收到以下错误：

Missing required parameter: client_id

要解决此问题，请确保已满足您安装方法的所有先决条件：

错误：`Failed to sign in to GitLab`

当您将应用指向您的 GitLab Self-Managed 实例后登录 GitLab for Jira Cloud 应用时，可能会收到以下错误：

Failed to sign in to GitLab

要解决此问题，请确保为该应用创建的 OAuth 应用中的 Trusted 和 Confidential 复选框已清除。

GitLab for Jira Cloud 应用管理故障排除

已登录时仍显示登录提示消息

手动安装失败

数据同步失败并显示 Invalid JWT

错误：Failed to update the GitLab instance

错误：Invalid audience

调试 Jira Connect Proxy 问题

GitLab 支持

错误：Failed to link group

错误：Failed to load Jira Connect Application ID

错误：Missing required parameter: client_id

错误：Failed to sign in to GitLab

数据同步失败并显示 `Invalid JWT`

错误：`Failed to update the GitLab instance`

错误：`Invalid audience`

错误：`Failed to link group`

错误：`Failed to load Jira Connect Application ID`

错误：`Missing required parameter: client_id`

错误：`Failed to sign in to GitLab`