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

GitLab Pages 管理故障排除

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

本页面列出了您在管理 GitLab Pages 时可能遇到的问题。

如何查看 GitLab Pages 日志

您可以通过运行以下命令查看 Pages 守护进程日志：

sudo gitlab-ctl tail gitlab-pages

您也可以在 /var/log/gitlab/gitlab-pages/current 中找到日志文件。

更多信息，请参阅从日志中获取关联 ID。

调试 GitLab Pages

以下序列图说明了 GitLab Pages 请求是如何被处理的。有关 GitLab Pages 站点如何部署以及如何从对象存储提供静态内容的更多信息，请参阅 GitLab Pages 架构文档。

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: GitLab Pages 请求流程
    accDescr: 序列图显示用户请求如何通过 GitLab Pages 组件流动以提供静态文件。

    actor User
    participant PagesNGINX as Pages NGINX
    participant Pages as GitLab Pages
    participant GitlabNGINX as GitLab NGINX
    participant GitlabAPI as GitLab Rails
    participant ObjectStorage as Object Storage

    User->>PagesNGINX: 请求 Pages
    activate PagesNGINX
    PagesNGINX->>Pages: 转发到 Pages
    activate Pages

    Pages->>GitlabNGINX: 获取域名信息
    activate GitlabNGINX
    GitlabNGINX->>GitlabAPI: 转发到 GitLab API
    activate GitlabAPI
    GitlabAPI->>GitlabNGINX: 200 OK (域名信息)
    deactivate GitlabAPI
    GitlabNGINX->>Pages: 200 OK (域名信息)
    deactivate GitlabNGINX

    Note right of Pages: 域名信息缓存在 Pages 中

    Pages->>ObjectStorage: 获取静态文件
    activate ObjectStorage
    ObjectStorage->>Pages: 200 OK (文件)
    deactivate ObjectStorage

    Pages->>User: 200 OK (提供静态文件)
    deactivate Pages
    deactivate PagesNGINX

识别错误日志

您应该按照前面序列图中显示的顺序检查日志。基于您的域名进行过滤也有助于识别相关日志。

开始跟踪日志：

对于 GitLab Pages NGINX 日志，运行：

# 查看 GitLab Pages NGINX 错误日志
sudo gitlab-ctl tail nginx/gitlab_pages_error.log

# 查看 GitLab Pages NGINX 访问日志
sudo gitlab-ctl tail nginx/gitlab_pages_access.log

对于 GitLab Pages 日志，运行：首先从日志中识别关联 ID。
```
sudo gitlab-ctl tail gitlab-pages
```

对于 GitLab NGINX 日志，运行：

# 查看 GitLab NGINX 错误日志
sudo gitlab-ctl tail nginx/gitlab_error.log

# 查看 GitLab NGINX 访问日志
sudo gitlab-ctl tail nginx/gitlab_access.log

对于 GitLab Rails 日志，运行：您可以根据在 GitLab Pages 日志中识别的 correlation_id 过滤这些日志。
```
sudo gitlab-ctl tail gitlab-rails
```

授权码流程

以下序列图说明了用户、GitLab Pages 和 GitLab Rails 之间用于访问受保护 Pages 站点的 OAuth 认证流程。

更多信息，请参阅 GitLab OAuth 授权码流程。

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
   accTitle: GitLab Pages OAuth 流程
   accDescr: 序列图显示用户、GitLab Pages 和 GitLab Rails 之间用于访问受保护页面的 OAuth 认证流程。

   actor User
   participant PagesService as GitLab Pages
   participant GitlabApp as GitLab Rails

   User->>PagesService: GET 请求站点
   activate PagesService
   PagesService-->>User: 302 重定向到项目子域名 https://projects.gitlab.io/auth?state=state1
   deactivate PagesService
   Note left of User: Cookie state1

   User->>PagesService: GET https://projects.gitlab.io/auth?state=state1
   activate PagesService
   PagesService-->>User: 302 重定向到 gitlab.com/oauth/authorize?state=state1
   deactivate PagesService

   User->>GitlabApp: GET oauth/authorize?state=state1
   activate GitlabApp
   GitlabApp-->>User: 200 OK (授权表单)
   deactivate GitlabApp

   User->>GitlabApp: POST 授权表单
   activate GitlabApp
   GitlabApp-->>User: 302 重定向到 oauth/redirect
   deactivate GitlabApp

   User->>GitlabApp: GET oauth/redirect?state=state1
   activate GitlabApp
   GitlabApp-->>User: 200 OK (包含授权码)
   deactivate GitlabApp

   User->>PagesService: GET https://projects.gitlab.io/auth?code=code1&state=state1
   activate PagesService
   PagesService->>GitlabApp: POST oauth/token with code=code1
   activate GitlabApp
   GitlabApp-->>PagesService: 200 OK (访问令牌)
   deactivate GitlabApp
   PagesService-->>User: 302 重定向到 https://[namespace].gitlab.io/auth?code=code2&state=state1
   deactivate PagesService

   User->>PagesService: GET https://[namespace].gitlab.io/auth?code=code2&state=state1
   activate PagesService
   PagesService-->>User: 302 重定向到站点
   deactivate PagesService

   User->>PagesService: GET 请求站点
   activate PagesService
   PagesService-->>User: 200 OK (站点内容)
   deactivate PagesService

`unsupported protocol scheme \"\""`

如果您看到以下错误：

{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"}

这意味着您没有在 Pages 服务器设置中设置 HTTP(S) 协议方案。要解决此问题：

编辑 /etc/gitlab/gitlab.rb：

gitlab_pages['gitlab_server'] = "https://<your_gitlab_server_public_host_and_port>"
gitlab_pages['internal_gitlab_server'] = "https://<your_gitlab_server_private_host_and_port>" # 可选，默认使用 gitlab_pages['gitlab_server']

重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

当服务器不监听 IPv6 时连接到 GitLab Pages 代理出现 502 错误

在某些情况下，即使服务器不监听 IPv6，NGINX 也可能默认使用 IPv6 连接到 GitLab Pages 服务。如果您在 gitlab_pages_error.log 中看到类似以下的日志条目，就可以确定何时会发生这种情况：

2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com"

要解决此问题，为 GitLab Pages listen_proxy 设置设置明确的 IP 和端口，以定义 GitLab Pages 守护进程应该监听的明确地址：

gitlab_pages['listen_proxy'] = '127.0.0.1:8090'

间歇性 502 错误或几天后出现

如果您在使用 systemd 和 tmpfiles.d 的系统上运行 Pages，可能会在尝试提供 Pages 时遇到间歇性 502 错误，错误类似：

dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host"

GitLab Pages 在 /tmp/gitlab-pages-* 内部创建一个绑定挂载，其中包括 /etc/hosts 等文件。但是，systemd 可能会定期清理 /tmp/ 目录，因此 DNS 配置可能会丢失。

要阻止 systemd 清理 Pages 相关内容：

告诉 tmpfiles.d 不要删除 Pages /tmp 目录：

echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf

重启 GitLab Pages：
```
sudo gitlab-ctl restart gitlab-pages
```

无法访问 GitLab Pages

如果您无法访问 GitLab Pages（例如收到 502 Bad Gateway 错误，或登录循环），并且在 Pages 日志中显示此错误：

"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"

将以下内容添加到 /etc/gitlab/gitlab.rb：

gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'

重启 GitLab Pages：
```
sudo gitlab-ctl restart gitlab-pages
```

连接到内部 GitLab API 失败

如果您看到以下错误：

ERRO[0010] Failed to connect to the internal GitLab API after 0.50s  error="failed to connect to internal Pages API: HTTP status: 401"

如果您在单独的服务器上运行 GitLab Pages，则必须将 /etc/gitlab/gitlab-secrets.json 文件从 GitLab 服务器 复制到 Pages 服务器。

其他原因可能包括您的 GitLab 服务器 和 Pages 服务器 之间的网络连接问题，例如防火墙配置或关闭的端口。例如，如果存在连接超时：

error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"

Pages 无法与 GitLab API 实例通信

如果您使用 domain_config_source=auto 的默认值并运行多个 GitLab Pages 实例，在提供 Pages 内容时可能会看到间歇性 502 错误响应。您可能还会在 Pages 日志中看到以下警告：

WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized"

如果您的 gitlab-secrets.json 文件在 GitLab Rails 和 GitLab Pages 之间过期，就会发生这种情况。请按照在单独的服务器上运行 GitLab Pages的步骤 8-10，在所有 GitLab Pages 实例中执行。

使用 AWS Network Load Balancer 和 GitLab Pages 时的间歇性 502 错误

当使用启用了客户端 IP 保留的网络负载均衡器并且请求被循环回源服务器时，连接将超时。这可能发生在运行核心 GitLab 应用程序和 GitLab Pages 的多服务器 GitLab 实例中。当单个容器同时运行核心 GitLab 应用程序和 GitLab Pages 时，也可能发生这种情况。

AWS 建议使用 IP 目标类型来解决此问题。

当核心 GitLab 应用程序和 GitLab Pages 在同一主机或容器上运行时，关闭客户端 IP 保留可能会解决此问题。

500 错误，显示 `securecookie: failed to generate random iv` 和 `Failed to save the session`

此问题很可能是由过时的操作系统导致的。 Pages 守护进程使用 securecookie 库通过 Go 中的 crypto/rand 获取随机字符串。这要求主机操作系统上可用 getrandom 系统调用或 /dev/urandom。建议升级到官方支持的操作系统。

请求的 scope 无效、格式错误或未知

此问题来自 GitLab Pages OAuth 应用程序的权限。要解决此问题：

在左侧边栏底部，选择 管理员。
选择 应用程序 > GitLab Pages。
编辑应用程序。
在 Scopes 下，确保选择了 api scope。
保存您的更改。

运行单独的 Pages 服务器时，此设置需要在主 GitLab 服务器上配置。

无法设置通配符 DNS 条目时的解决方法

如果无法满足通配符 DNS 先决条件，您仍然可以有限度地使用 GitLab Pages：

将您需要使用 Pages 的所有项目移动到单个组命名空间中，例如 pages。
配置不带 *. 通配符的 DNS 条目，例如 pages.example.io。
在您的 gitlab.rb 文件中配置 pages_external_url http://example.io/。此处省略组命名空间，因为 GitLab 会自动将其添加到前面。

Pages 守护进程因权限被拒绝错误而失败

如果 /tmp 以 noexec 方式挂载，Pages 守护进程将无法启动，并出现类似错误：

{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"}

在这种情况下，将 TMPDIR 更改为未以 noexec 方式挂载的位置。将以下内容添加到 /etc/gitlab/gitlab.rb：

gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'}

添加后，使用 sudo gitlab-ctl reconfigure 重新配置，并使用 sudo gitlab-ctl restart 重启 GitLab。

使用 Pages 访问控制时出现 `The redirect URI included is not valid.`

如果 pages_external_url 在某个时间点被更新，您可能会看到此错误。验证以下内容：

检查系统 OAuth 应用程序：
1. 在左侧边栏底部，选择 管理员。
2. 选择 应用程序，然后选择 添加新应用程序。
3. 确保 回调 URL/重定向 URI 使用 pages_external_url 配置的协议（HTTP 或 HTTPS）。
Redirect URI 的域名和路径组件是有效的：它们应该类似于 projects.<pages_external_url>/auth。

500 错误 `cannot serve from disk`

如果您从 Pages 收到 500 响应并遇到类似错误：

ERRO[0145] cannot serve from disk                        error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip

这意味着 GitLab Rails 告诉 GitLab Pages 从磁盘上的位置提供内容，但是，GitLab Pages 被配置为禁用磁盘访问。

要启用磁盘访问：

在 /etc/gitlab/gitlab.rb 中为 GitLab Pages 启用磁盘访问：
```
gitlab_pages['enable_disk'] = true
```
重新配置 GitLab。

`httprange: new resource 403`

如果您看到类似错误：

{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"}

并且您在通过 NFS 同步文件的单独服务器上运行 pages，这可能意味着共享的 pages 目录在主 GitLab 服务器和 GitLab Pages 服务器上挂载在不同的路径上。

在这种情况下，强烈建议您配置对象存储并将任何现有的 pages 数据迁移到其中。

或者，您可以将 GitLab Pages 共享目录挂载到两个服务器上的相同路径。

GitLab Pages 部署作业失败，错误为"is not a recognized provider"

如果 pages 作业成功但 deploy 作业给出错误"is not a recognized provider"：

错误消息 is not a recognized provider 可能来自 GitLab 用于连接到云提供商进行对象存储的 fog gem。

要解决此问题：

检查您的 gitlab.rb 文件。如果您启用了 gitlab_rails['pages_object_store_enabled']，但没有配置存储桶详细信息，请执行以下操作之一：
- 按照 S3 兼容连接设置指南为您的 Pages 部署配置对象存储。
- 通过注释掉该行在本地存储您的部署。
保存您对 gitlab.rb 文件所做的更改，然后重新配置 GitLab。

404 错误 `The page you're looking for could not be found`

如果您从 GitLab Pages 收到 404 Page Not Found 响应：

检查 .gitlab-ci.yml 是否包含作业 pages:。
检查当前项目的流水线以确认作业 pages:deploy 正在运行。

没有 pages:deploy 作业，您的 GitLab Pages 站点的更新永远不会发布。

503 错误 `Client authentication failed due to unknown client`

如果 Pages 是已注册的 OAuth 应用程序并且启用了访问控制，此错误表明存储在 /etc/gitlab/gitlab-secrets.json 中的认证令牌已失效：

Client authentication failed due to unknown client, no client authentication included,
or unsupported authentication method.

要解决：

备份您的密钥文件：

sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)

编辑 /etc/gitlab/gitlab-secrets.json 并删除 gitlab_pages 部分。
重新配置 GitLab 并重新生成 OAuth 令牌：
```
sudo gitlab-ctl reconfigure
```