GitLab Pages 管理 (FREE SELF)

GitLab Pages 允许托管静态站点，它必须由管理员配置。

NOTE: 本文适用于 Omnibus GitLab 安装实例。

概览

GitLab Pages 利用 GitLab Pages daemon，它是一个用 Go 编写的简易 HTTP 服务器，可以侦听外部 IP 地址，并提供对自定义域名和自定义证书的支持。 它可以通过 SNI 支持动态证书并默认使用 HTTP2 对外暴露 GitLab Pages。

对于自定义域名（不包括通配符域名)，GitLab Pages daemon 需要监听端口 80 和/或 443。因此，您对齐进行设置时，可以使用一些灵活的方法：

• 在运行 GitLab 实例的服务器上，同时运行 Pages daemon，监听 secondary IP。
• 在单独的服务器中运行 Pages daemon。在这种情况下，Pages 路径也必须存在于安装了 Pages daemon 的服务器中，这样您必须在网络中进行共享。
• 在运行 GitLab 实例的服务器上，同时运行 Pages daemon，侦听相同 IP 的不同端口。在这种情况下，您必须使用负载均衡器代理流量。如果您选择路由，请注意您应该针对 HTTPS 使用 TCP 负载均衡。如果您使用 TLS 终止（HTTPS 负载均衡），Pages 无法使用用户提供的证书对外提供服务。对于 HTTP，使用 HTTP 或 TCP 负载均衡皆可。

在本文中，我们假定使用第一种方法。如果您不支持自定义域名，则不需要 secondary IP。

前提条件

在继续 Pages 配置之前，您必须：

1. 准备 Pages 域名，不可以是极狐GitLab 实例域名的子域名。

   GitLab 实例域名	Pages 域名	是否生效？
   example.com	example.io	{check-circle} Yes
   example.com	pages.example.com	{dotted-circle} No
   gitlab.example.com	pages.example.com	{check-circle} Yes

2. 配置一个 通配符 DNS 记录.

3. （可选）如果您决定在 HTTPS 下提供 Pages 服务，为 Pages 域名准备一个 通配符证书。

4. （可选但推荐）启用 Shared runners，这样用户不必准备自己的 runner。

5. （仅适用于自定义域名）准备一个 secondary IP。

NOTE: 如果您的 GitLab 实例和 Pages daemon 部署在专用网络中或在防火墙之后，则您的 GitLab Pages 网站只能由有权访问专用网络的设备/用户访问。

添加域名到公共后缀列表

浏览器使用公共后缀列表来决定如何处理子域名。如果您的 GitLab 实例允许公众成员创建 GitLab Pages 站点，那么它还允许这些用户在 Pages 域名（example.io）上创建子域名。此外，添加 Pages 域名到公共后缀列表可防止浏览器接受 supercookies。

按照这些说明提交您的 GitLab Pages 子域名。例如，如果您的域名是 example.io，您应该请求将 example.io 添加到公共后缀列表中。

DNS 配置

GitLab Pages 期望在它们自己的虚拟主机上运行。在您的 DNS 服务器/提供商中，您需要添加一个通配符 DNS A 记录指向极狐GitLab 运行的主机。示例如下：

*.example.io. 1800 IN A    192.0.2.1
*.example.io. 1800 IN AAAA 2001:db8::1

其中 example.io 是 GitLab Pages 提供服务的域名，192.0.2.1 是 GitLab 实例的 IPv4 地址，2001:db8::1 是 IPv6 地址。如果您没有 IPv6，则可以省略 AAAA 记录。

自定义域名

如果需要支持自定义域名，则 Pages 根域名的所有子域名都应指向 secondary IP（专用于 Pages daemon）。如果没有此配置，用户将无法使用 CNAME 记录，将他们的自定义域名指向他们的极狐GitLab Pages。

示例如下：

example.com   1800 IN A    192.0.2.1
*.example.io. 1800 IN A    192.0.2.2

示例参数说明：

• example.com：GitLab 域名
• example.io：GitLab Pages 提供服务的域名。
• 192.0.2.1：GitLab 实例的主 IP。
• 192.0.2.2：secondary IP，专用于 GitLab Pages，必须和主 IP 不同。

NOTE: 您不应使用 GitLab 域名来为用户提供 Pages 服务。有关更多信息请查看安全部分。

配置

根据您的需要，您可以通过 4 种不同的方式设置 GitLab pages。

以下示例按从最简单到最高级的顺序列出。绝对最低要求是设置通配符 DNS，因为这在所有配置中都是必需的。

通配符域名

要求：

• 通配符 DNS 设置
• TLS 证书。可以是通配符，也可以是任何其他满足要求的类型。

URL scheme：http://<namespace>.example.io/<project_slug>

这种方法是您可以使用的最简单设置方法。它是所有其它设置的基础，如下所述。NGINX 将所有请求代理到 daemon。Pages daemon 不监听外界。

1. 在 /etc/gitlab/gitlab.rb中，为 GitLab Pages 设置外部 URL：

   external_url "http://gitlab.example.com" # external_url here is only for reference
   pages_external_url "http://pages.example.com" # not a subdomain of external_url

2. 重新配置极狐GitLab。

支持 TLS 的通配符域名

要求：

• 通配符 DNS 设置
• 通配符 TLS 证书

URL scheme：https://<namespace>.example.io/<project_slug>

NGINX 将所有请求代理到 daemon。Pages daemon 不监听外界。

1. 将 example.io 证书和密钥放在 /etc/gitlab/ssl 中。

2. 在 /etc/gitlab/gitlab.rb 中指定如下配置：

   external_url "https://gitlab.example.com" # external_url here is only for reference
   pages_external_url "https://pages.example.com" # not a subdomain of external_url
   
   pages_nginx['redirect_http_to_https'] = true

3. 如果您还没有命名您的证书和密钥 example.io.crt 和 example.io.key，您需要添加如下所示的完整路径：

   pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
   pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"

4. 重新配置极狐GitLab。

5. 如果您使用 Pages 访问控制，更新 GitLab Pages System OAuth application 中的重定向 URI，去使用 HTTPS 协议。

WARNING: 一个实例不支持多个通配符。每个实例只能分配一个通配符。

WARNING: 如果对重定向 URI 进行了更改，极狐GitLab Pages 不会更新 OAuth 应用程序。在重新配置之前，从 /etc/gitlab/gitlab-secrets.json 中删除 gitlab_pages 部分，然后运行 gitlab-ctl reconfigure。

全局设置

下表列出了 Omnibus GitLab 中 Pages 已知的所有配置设置，以及它们的作用。这些选项可以在/etc/gitlab/gitlab.rb中进行调整，并在您重新配置极狐GitLab 后生效。大多数设置不需要手动配置，除非您需要更精细地控制 Pages daemon 如何在您的环境中运行和提供服务。

高级配置

除了通配符域名之外，您还可以选择配置 GitLab Pages 以使用自定义域名。 同样，这里有两个选项：支持带有和不带有 TLS 证书的自定义域名。最简单的设置是没有 TLS 证书。在任何一种情况下，您都需要一个 secondary IP。 如果您有 IPv6 和 IPv4 地址，则可以同时使用它们。

自定义域名

要求：

• 通配符 DNS 设置
• Secondary IP

URL scheme：http://<namespace>.example.io/<project_slug> and http://custom-domain.com

在这种情况下，Pages daemon 正在运行，NGINX 仍然代理对 daemon 的请求，但守护进程也能够接收来自外部的请求。支持自定义域名，但不支持 TLS。

1. 在 /etc/gitlab/gitlab.rb 中指定以下配置：

   external_url "http://gitlab.example.com" # external_url here is only for reference
   pages_external_url "http://pages.example.com" # not a subdomain of external_url
   nginx['listen_addresses'] = ['192.0.2.1'] # The primary IP of the GitLab instance
   pages_nginx['enable'] = false
   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon

   如果您没有 IPv6，您可以忽略 IPv6 地址。

2. 重新配置极狐GitLab。

支持 TLS 的自定义域名

Requirements:

• 通配符 DNS 设置
• Wildcard TLS certificate
• Secondary IP

URL scheme：https://<namespace>.example.io/<project_slug> 和 https://custom-domain.com

在这种情况下，Pages daemon 正在运行，NGINX 仍然代理对 daemon 的请求，但 daemon 也能够接收来自外部的请求。支持自定义域和 TLS。

1. 将 example.io 证书和密钥放在 /etc/gitlab/ssl 中。

2. 在 /etc/gitlab/gitlab.rb 中指定以下配置：

   external_url "https://gitlab.example.com" # external_url here is only for reference
   pages_external_url "https://pages.example.com" # not a subdomain of external_url
   nginx['listen_addresses'] = ['192.0.2.1'] # The primary IP of the GitLab instance
   pages_nginx['enable'] = false
   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon
   gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon
   # Redirect pages from HTTP to HTTPS
   gitlab_pages['redirect_http'] = true

   如果您没有 IPv6，您可以忽略 IPv6 地址。

3. 如果您还没有分别命名您的证书和密钥 example.io.crt 和 example.io.key，然后您还需要添加完整路径，如下所示：

   gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
   gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"

4. 重新配置极狐GitLab。

5. 如果您使用Pages 访问控制, 更新 GitLab Pages System OAuth application 中的重定向 URI，去使用 HTTPS 协议。

自定义域名验证

为了防止恶意用户劫持不属于他们的域名，支持自定义域名验证。 添加自定义域名时，用户需要通过将极狐GitLab 控制的验证码添加到该域名的 DNS 记录来证明拥有它。

WARNING: 禁用域名验证是不安全的，并且可能导致各种漏洞。如果您确实要禁用它，请确保 Pages 根域名本身不指向辅助 IP，或者将根域名作为自定义域名添加到项目中；否则，任何用户都可以将此域名作为自定义域名添加到他们的项目中。

如果您的用户群是私有的或受信任的，您可以禁用验证要求：

1. 在顶部栏上，选择 菜单 > 管理员。
2. 在左侧边栏中，选择 设置 > 偏好设置。
3. 展开 Pages。
4. 清除 要求用户证明自定义域名的所有权 复选框。默认情况下启用此设置。

Let's Encrypt 集成

要启用该功能：

1. 选择您希望接收有关域名过期通知的电子邮件地址。
2. 在顶部导航栏，选择 **菜单 > 管理。
3. 在左侧导航栏，选择 设置 > 偏好设置。
4. 展开 Pages。
5. 输入接收通知的电子邮件地址并接受 Let's Encrypt 的服务条款。
6. 选择 保存更改。

访问控制

GitLab Pages 访问控制可以针对每个项目进行配置，并允许根据项目的成员身份来控制对 Pages 站点的访问。

访问控制的工作原理是将 Pages daemon 注册为极狐GitLab 的 OAuth 应用程序。每当未经身份验证的用户发出访问私人 Pages 站点的请求时，Pages daemon 会将用户重定向到 GitLab。如果身份验证成功，用户将被重定向到带有令牌的 Pages，该令牌保存在 cookie 中。cookie 使用密钥签名，因此可以检测到篡改。

每个查看私有站点中资源的请求都由 Pages 使用该令牌进行身份验证。 对于它收到的每个请求，它都会向 GitLab API 发出请求，以检查用户是否有权阅读该站点。

默认情况下禁用页面访问控制。 要启用它：

1. 在 /etc/gitlab/gitlab.rb 中启用：

   gitlab_pages['access_control'] = true

2. 重新配置极狐GitLab。

3. 用户可以在项目设置中进行配置。

NOTE: 要使此设置对多节点设置有效，它必须应用于所有 App 节点和 Sidekiq 节点。

使用 Pages 时缩小身份验证范围

默认情况下，Pages daemon 使用 api 范围进行身份验证。 您可以对此进行配置。 例如，这将范围缩小到 /etc/gitlab/gitlab.rb 中的 read_api：

gitlab_pages['auth_scope'] = 'read_api'

用于身份验证的范围必须与 GitLab Pages OAuth 应用程序设置相匹配。 现有应用程序的用户必须修改 GitLab Pages OAuth 应用程序。 请按照以下步骤执行此操作：

1. 在顶部导航栏，选择 **菜单 > 管理。
2. 在左侧导航栏，选择 设置 > 偏好设置。
3. 展开 Pages。
4. 清除 api 范围的复选框并选择所需范围的复选框（例如，read_api）。
5. 选择 保存更改。

禁止公开访问所有 Pages 网站

您可以对托管在您的 GitLab 实例上的所有 GitLab Pages 网站实施 访问控制。 通过这样做，只有登录用户才能访问它们。此设置会覆盖用户在各个项目中设置的访问控制。

这对于将随 Pages 网站发布的信息仅保留给您实例的用户很有用。要做到这一点：

1. 在顶部导航栏，选择 **菜单 > 管理。
2. 在左侧导航栏，选择 设置 > 偏好设置。
3. 展开 Pages。
4. 选择 Disable public access to Pages sites 复选框。
5. 单击 保存更改。

在代理后运行

与 GitLab 的其余部分一样，Pages 可用于外部 Internet 连接由代理控制的环境。要为 GitLab Pages 使用代理：

1. 在 /etc/gitlab/gitlab.rb 中配置：

   gitlab_pages['env']['http_proxy'] = 'http://example:8080'

2. 重新配置极狐GitLab 使更改生效

使用自定义证书颁发机构（CA）

使用自定义 CA 颁发的证书时，如果无法识别自定义 CA，访问控制和 HTML job artifacts 的在线视图将无法工作。

这通常会导致此错误：Post /oauth/token: x509: certificate signed by unknown authority。

对于源安装实例，通过在系统证书存储中安装自定义 CA 可以解决。

对于 Omnibus 安装实例，通过在 Omnibus GitLab 中安装自定义 CA 可以解决。

调用 GitLab API 时支持双向 TLS

引入于 14.8 版本。

如果极狐GitLab 已配置为需要双向 TLS，则需要将客户端证书添加到 Pages：

1. 在 /etc/gitlab/gitlab.rb 中配置：

   gitlab_pages['client_cert_key_pairs'] = ['</path/to/cert>:</path/to/key>']

   其中 </path/to/cert> 和 </path/to/key> 是客户端证书及其各自密钥文件的文件路径。这两个文件都必须以 PEM 格式编码。

2. 要配置 Pages 验证服务器证书，将根 CA 添加到系统信任库。

Zip 服务和缓存配置

WARNING: 以下为高级设置，已在 GitLab Pages 中设置了推荐的默认值。仅在绝对必要时才应更改这些设置。建议谨慎使用。

GitLab Pages 可以通过对象存储，提供来自 zip archives 的内容。使用内存缓存来提高从 zip archives 提供内容时的性能。您可以通过更改以下配置标志来修改缓存。

Zip 缓存刷新示例

如果 archives 在 zip_cache_expiration 之前被访问，并且在过期前的剩余时间小于或等于 zip_cache_refresh，则会在缓存中刷新（延长它们在内存中的时间）。 例如，如果 archive.zip 在时间 0 被访问，它会在 60 秒后过期（zip_cache_expiration 的默认值）。 在下面的示例中，如果 archives 在 15 秒后再次打开，则不刷新，因为到期的剩余时间（45 秒）大于“zip_cache_refresh”（默认为 30 秒）。 但是，如果 archives 在 45 秒后（从第一次打开开始）再次被访问，它会被刷新。 这将 archives 保留在内存中的时间从 45 秒 + zip_cache_expiration (60 秒) 延长，总共 105 秒。

在存档到达 zip_cache_expiration 后，它会被标记为已过期并在下一个 zip_cache_cleanup 时间间隔内被删除。

HTTP Strict Transport Security (HSTS) 支持

HTTP Strict Transport Security (HSTS) 可以通过 gitlab_pages['headers'] 配置选项启用。HSTS 通知浏览器，他们正在访问的网站应始终通过 HTTPS 提供其内容，以确保攻击者无法强制后续连接不加密。它还可以提高页面的加载速度，因为它可以防止浏览器在重定向到 HTTPS 之前尝试通过未加密的 HTTP 通道进行连接。

gitlab_pages['headers'] = ['Strict-Transport-Security: max-age=63072000']

Pages 项目重定向限制

引入于 15.2 版本。

极狐GitLab Pages 为 _redirects 文件提供了一组默认限制，以尽量减少对性能的影响。如果您想增加或减少限制，您可以配置这些限制。

gitlab_pages['redirects_max_config_size'] = 131072
gitlab_pages['redirects_max_path_segments'] = 50
gitlab_pages['redirects_max_rule_count'] = 2000

激活 daemon 详细日志记录

按照以下步骤配置 GitLab Pages daemon 的详细日志记录。

1. 默认情况下，守护进程只记录 INFO 级别。如果你想让它以 DEBUG 级别记录事件，你必须在 /etc/gitlab/gitlab.rb 中配置它：

   gitlab_pages['log_verbose'] = true

2. 重新配置极狐GitLab。

传播关联 ID

将 propagate_correlation_id 设置为 true，允许反向代理后面的实例，为发送到 GitLab Pages 的请求生成和设置相关 ID。当反向代理设置 header 值“X-Request-ID”时，该值在请求链中传播。用户可以在日志中找到相关 ID。

要启用关联 ID 的传播：

1. 在 /etc/gitlab/gitlab.rb 中，将参数设置为 true：

   gitlab_pages['propagate_correlation_id'] = true

2. 重新配置极狐GitLab。

更改存储路径

按照以下步骤更改存储 GitLab 页面内容的默认路径。

1. 页面默认存储在 /var/opt/gitlab/gitlab-rails/shared/pages 中。 如果您希望将它们存储在另一个位置，您必须在 /etc/gitlab/gitlab.rb 中进行设置：

   gitlab_rails['pages_path'] = "/mnt/storage/pages"

2. 重新配置极狐GitLab.

或者，如果您已经部署了 Pages，您可以按照以下步骤，进行无停机时间转移到新的存储位置。

1. 通过在 /etc/gitlab/gitlab.rb 中设置以下内容来暂停 Pages：

   sidekiq['queue_selector'] = true
   sidekiq['queue_groups'] = [
     "feature_category!=pages"
   ]

2. 重新配置极狐GitLab.

3. rsync 内容从当前存储位置到新的存储位置：sudo rsync -avzh --progress /var/opt/gitlab/gitlab-rails/shared/pages/ /mnt/storage/pages。

4. 在/etc/gitlab/gitlab.rb 中设置新的存储位置：

   gitlab_rails['pages_path'] = "/mnt/storage/pages"

5. 重新配置极狐GitLab。

6. 验证 Pages 仍按预期提供服务。

7. 通过从 /etc/gitlab/gitlab.rb 中删除上面设置的 sidekiq 设置来恢复 Pages 部署。

8. 重新配置极狐GitLab。

9. 触发新的 Pages 部署并验证它是否按预期工作。

10. 删除旧的 Pages 存储位置：sudo rm -rf /var/opt/gitlab/gitlab-rails/shared/pages

11. 验证 Pages 仍按预期提供。

为反向代理请求配置侦听器

请按照以下步骤配置 GitLab Pages 的代理侦听器。

1. 默认情况下，侦听器配置为侦听 localhost:8090 上的请求。

   如果你想禁用它，你必须在 /etc/gitlab/gitlab.rb 中进行如下配置：

   gitlab_pages['listen_proxy'] = nil

   如果你想让它监听不同的端口，你也必须在 /etc/gitlab/gitlab.rb 中配置：

   gitlab_pages['listen_proxy'] = "localhost:10080"

2. 重新配置极狐GitLab.

设置每个极狐GitLab Pages 站点的全局最大大小 (FREE SELF)

先决条件：

• 只有极狐GitLab 管理员可以编辑此设置。

为项目设置全局最大页面大小：

1. 在顶部栏上，选择 菜单 > 管理员。
2. 在左侧边栏中，选择 设置 > 偏好设置。
3. 展开 Pages。
4. 在最大 Pages 大小下输入一个值。
5. 选择 保存更改。

在群组中设置每个极狐GitLab Pages 站点的最大大小 (PREMIUM SELF)

先决条件：

• 您必须至少具有该群组的维护者角色。

要设置群组中每个极狐GitLab Pages 站点的最大大小，覆盖继承的设置：

1. 在顶部栏上，选择 菜单 > 群组 并找到您的群组。
2. 在左侧边栏中，选择 设置 > 通用。
3. 展开 Pages。
4. 在 最大大小 下输入一个值（以 MB 为单位）。
5. 选择 保存更改。

在项目中设置极狐GitLab Pages 站点的最大大小 (PREMIUM SELF)

先决条件：

• 您必须至少具有项目的维护者角色。

要在项目中设置极狐GitLab Pages 站点的最大大小，覆盖继承的设置：

1. 在顶部栏上，选择 菜单 > 项目 并找到您的项目。
2. 在左侧边栏中，选择 设置 > Pages。
3. 在 最大 Pages 大小 下输入一个值，以 MB 为单位。
4. 选择 保存更改。

在单独的服务器上运行 GitLab Pages

您可以在单独的服务器上运行 GitLab Pages daemon 以减少主应用程序服务器上的负载。

在单独的服务器上配置 GitLab Pages：

WARNING: 以下过程包括备份和编辑 gitlab-secrets.json 文件的步骤。此文件包含控制数据库加密的 secrets，建议谨慎操作。

1. 在 GitLab 服务器 上创建 secret 文件的备份：

   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak

2. 在 GitLab 服务器 上，要启用 Pages，添加以下内容到 /etc/gitlab/gitlab.rb：

   pages_external_url "http://<pages_server_URL>"

3. 作为可选项，要启用访问控制，添加以下内容到 /etc/gitlab/gitlab.rb：

   gitlab_pages['access_control'] = true

4. 配置对象存储并迁移 pages 数据到其中。

5. 重新配置 GitLab 服务器使更改生效。gitlab-secrets.json 文件更新了最新的配置。

6. 设置一个新的服务器，作为 Pages 服务器.

7. 在 Pages 服务器上, 安装 Omnibus GitLab 并修改 /etc/gitlab/gitlab.rb 以包含：

   roles ['pages_role']
   
   pages_external_url "http://<pages_server_URL>"
   
   gitlab_pages['gitlab_server'] = 'http://<gitlab_server_IP_or_URL>'
   
   ## If access control was enabled on step 3
   gitlab_pages['access_control'] = true

8. 如果您在 GitLab 服务器 上有自定义 UID/GID 设置，请将它们也添加到 Pages 服务器 /etc/gitlab/gitlab.rb，否则在 GitLab 服务器 上运行 gitlab-ctl reconfigure，可以更改文件所有权并导致 Pages 请求失败。

9. 在 Pages 服务器 上创建 secret 文件的备份：

   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak

10. 将 /etc/gitlab/gitlab-secrets.json 文件从 GitLab 服务器 复制到 Pages 服务器。

    # On the GitLab server
    cp /etc/gitlab/gitlab-secrets.json /mnt/pages/gitlab-secrets.json
    
    # On the Pages server
    mv /var/opt/gitlab/gitlab-rails/shared/pages/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json

11. 重新配置 Pages 服务器 使更改生效。

12. 在 GitLab 服务器 上，对 /etc/gitlab/gitlab.rb 进行以下更改：

    pages_external_url "http://<pages_server_URL>"
    gitlab_pages['enable'] = false
    pages_nginx['enable'] = false

13. 重新配置 GitLab 服务器 使更改生效。

如果您希望分布负载，可以在多台服务器上运行 GitLab Pages。 您可以通过标准的负载均衡实践来做到这一点，例如配置您的 DNS 服务器为您的 Pages 服务器返回多个 IP，配置负载均衡器以在 IP 级别工作，等等。 如果您希望在多个服务器上设置 GitLab Pages，请为每个 Pages 服务器执行上述过程。

域名源配置

当 GitLab Pages daemon 为 pages 请求提供服务时，它首先需要确定应该使用哪个项目来为请求的 URL 提供服务以及其内容的存储方式。

这种方法有几个缺点，并且每次请求新域名时都会使用内部 GitLab API 替换为 GitLab Pages。域名信息也由 Pages daemon 缓存，以加快后续请求。

从 14.0 版本开始，GitLab Pages 默认使用 API，如果无法连接则无法启动。

GitLab API 缓存配置

基于 API 的配置使用缓存机制来提高服务 Pages 的性能和可靠性。可以通过更改缓存设置来修改缓存行为，但是，建议值是为您设置的，仅应在需要时进行修改。这些值的不正确配置可能会导致间歇性或持续性错误，或者 Pages daemon 提供旧内容。

NOTE: 到期、间隔和超时标志使用 Golang 的持续时间格式。 持续时间字符串是一个可能有符号的十进制数字序列，每个数字都有可选的小数和单位后缀，例如 300ms、1.5h 或 2h45m。 有效的时间单位是 ns、us（或 µs）、ms、s、m、h。

示例：

• 增加 gitlab_cache_expiry，允许项目在缓存中存在更长时间。 如果 GitLab Pages 和 GitLab Rails 之间的通信不稳定，此设置可能很有用。

• 增加 gitlab_cache_refresh 会降低 GitLab Pages 从 GitLab Rails 请求域配置的频率。 GitLab Pages 向 GitLab API 生成太多请求时，此设置可能很有用，并且内容不会经常更改。

• 减小 gitlab_cache_cleanup 会更频繁地从缓存中删除过期项目，从而减少 Pages 节点的内存使用量。

• 减小 gitlab_retrieval_timeout 可以让您更快地停止对 GitLab Rails 的请求。增加它可以有更多时间从 API 接收响应，这在慢速网络环境中很有用。

• 减小 gitlab_retrieval_interval 会使对 API 的请求更加频繁，仅当 API 有错误响应时，例如连接超时。

• 减小 gitlab_retrieval_retries 会减少在报告错误之前尝试自动解析域配置的次数。

对象存储设置

设置如下：

• 在源安装实例的 object_store: 中，嵌套在 pages: 下。
• 在 Omnibus GitLab 安装实例中，以 pages_object_store_ 为前缀。

S3 兼容的连接设置

在 Omnibus 安装实例中：

1. 将以下内容添加到 /etc/gitlab/gitlab.rb 并将值替换为您想要的值：

   gitlab_rails['pages_object_store_enabled'] = true
   gitlab_rails['pages_object_store_remote_directory'] = "pages"
   gitlab_rails['pages_object_store_connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
   }

   如果您使用 AWS IAM 配置文件，请确保省略 AWS 访问密钥和 secret 访问键值对：

   gitlab_rails['pages_object_store_connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'use_iam_profile' => true
   }

2. 保存文件并重新配置极狐GitLab，使更改生效。

3. 将现有的 Pages 部署迁移到对象存储。

在源安装实例中：

1. 编辑 /home/git/gitlab/config/gitlab.yml 并添加或修改以下内容：

   pages:
     object_store:
       enabled: true
       remote_directory: "pages" # The bucket name
       connection:
         provider: AWS # Only AWS supported at the moment
         aws_access_key_id: AWS_ACCESS_KEY_ID
         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
         region: eu-central-1

2. 保存文件并重启极狐GitLab，使更改生效。

3. 将现有的 Pages 部署迁移到对象存储。

ZIP 存储

在 GitLab 14.0 中，GitLab Pages 的底层存储格式从直接存储在磁盘中的文件更改为每个项目的单个 ZIP archives。

这些 ZIP archives 可以本地存储在磁盘存储上，也可以存储在对象存储上（如果已配置）。

每次更新 Pages 站点时，都会存储 ZIP archives.

将 legacy 存储迁移到 ZIP 存储

当您升级到 13.11 或更高版本时，系统会尝试自动迁移 legacy 存储格式到新的基于 ZIP 的存储格式。 但是，某些项目可能由于不同原因无法迁移。 要验证所有项目都已成功迁移，您可以手动运行迁移：

sudo gitlab-rake gitlab:pages:migrate_legacy_storage

中断此任务并多次运行它是安全的。

此任务可能报告的两个最常见的问题如下：

• Missing public directory 错误：

  E, [2021-04-09T13:11:52.534768 #911919] ERROR -- : project_id: 1 /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test failed to be migrated in 0.07 seconds: Archive not created. Missing public directory in /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test

  在这种情况下，您应该验证这些项目没有部署页面，并使用附加标志重新运行迁移以将这些项目标记为未使用 GitLab Pages 部署：

  sudo PAGES_MIGRATION_MARK_PROJECTS_AS_NOT_DEPLOYED=true gitlab-rake gitlab:pages:migrate_legacy_storage

• 文件 is invalid 错误：

  E, [2021-04-09T14:43:05.821767 #923322] ERROR -- : project_id: 1 /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test failed to be migrated: /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test/public/link is invalid, input_dir: /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test

此错误表示磁盘存储上的文件无效，最常见的情况时 symlinks 位于 public 目录之外。 您可以手动删除这些文件，或者在迁移过程中忽略它们：

sudo PAGES_MIGRATION_IGNORE_INVALID_ENTRIES=true gitlab-rake gitlab:pages:migrate_legacy_storage

回滚 ZIP 迁移

如果发现迁移的数据无效，可以运行以下命令删除所有迁移的数据：

sudo gitlab-rake gitlab:pages:clean_migrated_zip_storage

这不会从旧磁盘存储中删除任何数据，并且 GitLab Pages daemon 会自动回退到使用它。

将 Pages 部署迁移到对象存储

现有的 Pages 部署对象（存储ZIP archive）可以类似地迁移到对象存储。

将您现有的 Pages 部署从本地存储迁移到对象存储：

sudo gitlab-rake gitlab:pages:deployments:migrate_to_object_storage

回滚 Pages 部署到本地存储

迁移到对象存储后，您可以选择将 Pages 部署移动到本地存储：

sudo gitlab-rake gitlab:pages:deployments:migrate_to_local

禁用 Pages 本地存储

如果您使用对象存储，您可以禁用本地存储来避免不必要的磁盘使用/写入：

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_rails['pages_local_store_enabled'] = false

2. 重新配置极狐GitLab 使更改生效。

从 13.12 版本开始，该设置还禁用了 legacy 存储，因此如果您使用 NFS 来提供页面服务，则可以完全断开与它的连接。

为 14.0 版本准备 GitLab Pages

在 14.0 版本中引入了许多重大更改，可能需要一些用户干预。 以下步骤描述了在不导致 GitLab 实例停机的情况下进行迁移的最佳方式。

如果您在单个服务器上运行 GitLab 实例，那么升级到 14.0 后您很可能不会注意到任何问题，但无论如何按照这些步骤操作可能会更安全。如果您在任何时候遇到问题，请参阅 故障排查部分。

如果当前的版本低于 13.12，那么首先需要升级到13.12。在完成以下步骤之前，直接升级到 14.0 可能会导致托管在 GitLab Pages 上的某些网站停机。要将 GitLab Pages 迁移到 GitLab 14.0：

1. 设置 domain_config_source为gitlab，这是 14.0 开始的默认设置。如果您已经在运行 14.0 或更高版本，请跳过此步骤。
2. 如果要将 Pages 内容存储在对象存储中，请务必进行配置。如果要在本地存储 Pages 内容或继续使用 NFS 服务器，请跳过此步骤。
3. 将 legacy 存储迁移到 ZIP 存储。
4. 如果您已将极狐GitLab 配置为将 pages 内容存储在对象存储中，请将 Pages 部署迁移到对象存储。
5. 升级极狐GitLab 版本到 14.0。

安全

您应该积极考虑在于 GitLab 实例不同的主机名下运行 GitLab Pages，以防止 XSS 攻击。

速率限制

您可以强制执行速率限制，以帮助最大程度地降低拒绝服务 (DoS) 攻击的风险。GitLab Pages 使用令牌桶算法来强制执行速率限制。 默认情况下，超过指定限制的请求会被报告但不会被拒绝。

GitLab Pages 支持以下类型的速率限制：

• 每个 source_ip。限制允许来自单个客户端 IP 地址的请求数量。
• 每个 domain。 限制托管在 GitLab Pages 上的每个域名允许的请求数。它可以是自定义域名，例如 example.com，也可以是组域名，例如 group.gitlab.io。

使用以下参数强制执行速率限制：

• rate_limit_source_ip：设置每个客户端 IP 每秒请求数的最大阈值。设置为 0 禁用此功能。
• rate_limit_source_ip_burst：设置每个客户端 IP 的初始请求突发中允许的最大请求数阈值。 例如，当您加载同时加载多个资源的网页时。
• rate_limit_domain：设置每个 hosted pages 域名每秒请求数的最大阈值。设置为 0 禁用此功能。
• rate_limit_domain_burst：设置每个hosted pages 域名的初始请求突发中允许的最大请求数阈值。

启用源 IP 速率限制

引入于 14.5 版本。

1. 在 /etc/gitlab/gitlab.rb 中设置速率限制：

   gitlab_pages['rate_limit_source_ip'] = 20.0
   gitlab_pages['rate_limit_source_ip_burst'] = 600

2. 要拒绝超过指定限制的请求，请在 /etc/gitlab/gitlab.rb 中启用 FF_ENFORCE_IP_RATE_LIMITS 功能标志：

   gitlab_pages['env'] = {'FF_ENFORCE_IP_RATE_LIMITS' => 'true'}

3. 重新配置极狐GitLab。

启用域名速率限制

引入于 14.7 版本。

1. 在 /etc/gitlab/gitlab.rb 中设置速率限制：

   gitlab_pages['rate_limit_domain'] = 1000
   gitlab_pages['rate_limit_domain_burst'] = 5000

2. 要拒绝超过指定限制的请求，请在 /etc/gitlab/gitlab.rb 中启用 FF_ENFORCE_DOMAIN_RATE_LIMITS 功能标志：

   gitlab_pages['env'] = {'FF_ENFORCE_DOMAIN_RATE_LIMITS' => 'true'}

3. 重新配置极狐GitLab。

故障排查

如何查看 GitLab Pages 日志

运行以下命令查看 Pages daemon 日志：

sudo gitlab-ctl tail gitlab-pages

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

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_pages_domain_name>"
   gitlab_pages['internal_gitlab_server'] = "https://<your_pages_domain_name>"

2. 重新配置极狐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 daemon 应侦听的显式地址：

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

Intermittent 502 errors or after a few days

如果您在使用 systemd 和 tmpfiles.d 的系统上运行 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-* 内创建了一个 bind mount，其中包含像 /etc/hosts 的文件。 然而，systemd 可能会定期清理 /tmp/ 目录，因此 DNS 配置可能会丢失。

要阻止 systemd 清理页面相关内容：

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

将项目转移到不同的组或用户，或更改项目路径后出现 404 错误

如果您在将项目转移到另一个组或用户，或更改项目路径后，在 Pages 站点上遇到 404 Not Found 错误，则必须触发 Pages 的域名配置更新。为此，请在 .update 文件中写入一些内容。Pages daemon 监视此文件的更改，并在发生更改时重新加载配置。

使用此示例修复传输项目或使用 Pages 更改项目路径后的 404 Not Found 错误：

date > /var/opt/gitlab/gitlab-rails/shared/pages/.update

如果您自定义了 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 错误响应。 您可能还会在页面日志中看到以下警告：

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 实例中，按照在单独的服务器上运行 GitLab Pages 的步骤 8-10 j进行操作。

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

此问题可能是由过时的操作系统引起。 Pages daemon 使用 securecookie 库通过 crypto/rand in Go 获取随机字符串。 这需要 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/。 在此处省略组命名空间，因为系统会自动添加它。

Pages daemon 因权限被拒绝错误而失败

如果 /tmp 与 noexec 一起挂载，Pages daemon 将无法启动，并显示如下错误：

{"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. GitLab Pages System OAuth 应用程序中的 Callback URL/Redirect 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"}

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

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

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

升级到 14.0 或以上版本后 GitLab Pages 不工作

14.0 对 GitLab Pages 引入了许多可能需要手动干预的更改。

1. 首先遵循迁移指南。
2. 尝试升级到 14.3 或更高版本，一些问题已在 14.1、14.2 和 14.3 版本中修复
3. 如果无法正常运行，查看 GitLab Pages 日志，如果您看到任何错误，请在此页面上搜索它们。

WARNING: 在 14.0-14.2 版本中，您可以临时启用 legacy 存储和配置机制。

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

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

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

修复方法：

1. 检查你的 gitlab.rb 文件。如果您启用了 gitlab_rails['pages_object_store_enabled']，但未配置存储桶详细信息，则：

   • 为您的 Pages 部署配置对象存储。
   • 通过注释掉该行，将您的部署存储在本地。

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