{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

本页面包含了您在管理极狐GitLab Pages 时可能遇到的议题列表。

如何查看极狐GitLab Pages 日志

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

sudo gitlab-ctl tail gitlab-pages

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

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

调试极狐GitLab Pages

以下序列图展示了如何处理极狐GitLab Pages 请求。

%%{init: { "fontFamily": "GitLab Sans" }}%% sequenceDiagram accTitle: GitLab Pages Request Flow accDescr: Sequence diagram showing how a user request flows through GitLab Pages components to serve static files. 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: Request to Pages activate PagesNGINX PagesNGINX->>Pages: Forwarded to Pages activate Pages Pages->>GitlabNGINX: Fetch domain info activate GitlabNGINX GitlabNGINX->>GitlabAPI: Forwarded to GitLab API activate GitlabAPI GitlabAPI->>GitlabNGINX: 200 OK (domain info) deactivate GitlabAPI GitlabNGINX->>Pages: 200 OK (domain info) deactivate GitlabNGINX Note right of Pages: Domain information cached in Pages Pages->>ObjectStorage: Fetch static files activate ObjectStorage ObjectStorage->>Pages: 200 OK (files) deactivate ObjectStorage Pages->>User: 200 OK (static files served) deactivate Pages deactivate PagesNGINX

识别错误日志

您应该按照上一个序列图中显示的顺序检查日志。根据您的域进行筛选也可以帮助识别相关日志。

要开始查看日志：

  1. 对于 极狐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

  2. 对于 极狐GitLab Pages 日志，运行：首先通过日志识别 关联 ID。

    sudo gitlab-ctl tail gitlab-pages

  3. 对于 极狐GitLab NGINX 日志，运行：

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

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

  4. 对于 极狐GitLab Rails 日志，运行： 您可以根据在极狐GitLab Pages 日志中识别的 correlation_id 筛选这些日志。

    sudo gitlab-ctl tail gitlab-rails

授权代码流程

以下序列图展示了用户、极狐GitLab Pages 和极狐GitLab Rails 之间的 OAuth 认证流程，以访问受保护的 Pages 站点。

有关更多信息，请参阅 极狐GitLab OAuth 授权代码流程。

%%{init: { "fontFamily": "GitLab Sans" }}%% sequenceDiagram accTitle: GitLab Pages OAuth Flow accDescr: Sequence diagram showing the OAuth authentication flow between User, GitLab Pages, and GitLab Rails for accessing protected pages sites. actor User participant PagesService as GitLab Pages participant GitlabApp as GitLab Rails User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 302 Redirect to project subdomain 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 Redirect to gitlab.com/oauth/authorize?state=state1 deactivate PagesService User->>GitlabApp: GET oauth/authorize?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (authorization form) deactivate GitlabApp User->>GitlabApp: POST authorization form activate GitlabApp GitlabApp-->>User: 302 Redirect to oauth/redirect deactivate GitlabApp User->>GitlabApp: GET oauth/redirect?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (with auth code) 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 (access token) deactivate GitlabApp PagesService-->>User: 302 Redirect to 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 Redirect to site deactivate PagesService User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 200 OK (site content) 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) 协议方案。要解决这个问题：

  1. 编辑 /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>" # optional, gitlab_pages['gitlab_server'] is used as default

  2. 重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

连接到极狐GitLab Pages 代理时的 502 错误，当服务器没有通过 IPv6 监听时

在某些情况下，即使服务器没有通过 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，您可能会遇到间歇性的 502 错误，尝试提供 Pages 时出现类似于以下的错误：

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 相关的内容：

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

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

  2. 重启极狐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"

  1. 在 /etc/gitlab/gitlab.rb 中添加以下内容：

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

  2. 重启极狐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，您必须将 极狐GitLab 服务器上的 /etc/gitlab/gitlab-secrets.json 文件复制到 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 网络负载均衡器和极狐GitLab Pages 时的间歇性 502 错误

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

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

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

500 错误 securecookie: failed to generate random iv 和 Failed to save the session

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

请求的作用域无效、格式错误或未知

此问题源自极狐GitLab Pages OAuth 应用程序的权限。要解决它：

  1. 在左侧边栏的底部，选择 管理员。
  2. 选择 应用程序 > 极狐GitLab Pages。
  3. 编辑应用程序。
  4. 在 作用域 下，确保选中了 api 作用域。
  5. 保存您的更改。

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

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

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

  1. 将所有需要使用 Pages 的项目移动到单个群组命名空间中，例如 pages。
  2. 配置一个没有 *. 通配符的 DNS 条目，例如 pages.example.io。
  3. 在您的 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 在某个时间点被更新，您可能会看到此错误。请验证以下内容：

  1. 检查 系统 OAuth 应用程序：

    1. 在左侧边栏的底部，选择 管理员。
    2. 选择 应用程序，然后选择 添加新应用程序。
    3. 确保 回调 URL/重定向 URI 使用的是 pages_external_url 配置使用的协议（HTTP 或 HTTPS）。

  2. 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 被配置为禁用磁盘访问。

要启用磁盘访问：

  1. 在 /etc/gitlab/gitlab.rb 中为极狐GitLab Pages 启用磁盘访问：

    gitlab_pages['enable_disk'] = true

  2. 重新配置极狐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"}

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

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

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

极狐GitLab Pages 部署作业失败，错误为 “is not a recognized provider”

如果 pages 作业成功，但 deploy 作业出现错误 “is not a recognized provider”：

A GitLab Pages pipeline shows success for the pages job but an error for the deploy job.

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

为了解决这个问题：

  1. 检查您的 gitlab.rb 文件。如果您启用了 gitlab_rails['pages_object_store_enabled']，但没有配置存储桶详细信息，请执行以下操作之一：

    • 按照 S3 兼容连接设置 指南为您的 Pages 部署配置对象存储。
    • 本地存储您的部署，通过注释掉该行。

  2. 保存您对 gitlab.rb 文件所做的更改，然后重新配置极狐GitLab。

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

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

  1. 检查 .gitlab-ci.yml 是否包含作业 pages:。
  2. 检查当前项目的流水线以确认正在运行的作业 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.

要解决：

  1. 备份您的密钥文件：

    sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)
  2. 编辑 /etc/gitlab/gitlab-secrets.json 并删除 gitlab_pages 部分。

  3. 重新配置极狐GitLab 并重新生成 OAuth 令牌：

    sudo gitlab-ctl reconfigure