GitLab Pages administration

极狐GitLab Pages 为极狐GitLab 项目和群组提供静态站点托管。服务器管理员必须在用户可以访问此功能之前配置 Pages。通过极狐GitLab Pages，管理员可以：

1. 使用自定义域名和 SSL/TLS 证书安全地托管静态网站。
2. 启用身份验证，通过极狐GitLab 权限控制对 Pages 站点的访问。
3. 在多节点环境中使用对象存储或网络存储扩展部署。
4. 通过速率限制和自定义标头监控和管理流量。
5. 支持所有 Pages 站点的 IPv4 和 IPv6 地址。

极狐GitLab Pages 守护进程作为一个单独的进程运行，可以配置在与极狐GitLab 相同的服务器上或其自己的专用基础设施上。有关用户文档，请参阅 GitLab Pages。

极狐GitLab Pages 守护进程#

极狐GitLab Pages 使用 GitLab Pages 守护进程，这是一个用 Go 编写的基本 HTTP 服务器，可以监听外部 IP 地址并提供对自定义域和自定义证书的支持。它通过服务器名称指示 (SNI) 支持动态证书，并默认使用 HTTP2 公开页面。建议您阅读其 README 以全面了解其工作原理。

在 自定义域（但不是 通配符域）的情况下，Pages 守护进程需要监听端口 80 和/或 443。因此，您可以灵活地设置它：

1. 在与极狐GitLab 相同的服务器上运行 Pages 守护进程，监听 辅助 IP。
2. 在 单独的服务器 上运行 Pages 守护进程。在这种情况下，Pages 路径 也必须存在于安装了 Pages 守护进程的服务器上，因此您必须通过网络共享它。
3. 在与极狐GitLab 相同的服务器上运行 Pages 守护进程，监听相同的 IP 但在不同的端口上。在这种情况下，您必须通过负载均衡器代理流量。如果选择该路线，您应该使用 TCP 负载平衡进行 HTTPS。如果使用 TLS 终止（HTTPS 负载平衡），则无法使用用户提供的证书提供页面。对于 HTTP，使用 HTTP 或 TCP 负载平衡是可以的。

在本文档中，我们假设第一种选择。如果您不支持自定义域，则不需要辅助 IP。

先决条件#

本节描述了配置极狐GitLab Pages 的先决条件。

通配符域#

在为通配符域配置 Pages 之前，您必须：

1. 拥有一个用于 Pages 的域，该域不是您的极狐GitLab 实例域的子域。

   极狐GitLab 域	Pages 域	是否可行？
   example.com	example.io	是
   example.com	pages.example.com	否
   gitlab.example.com	pages.example.com	是

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

3. 可选。如果您决定在 HTTPS 下提供 Pages，则为该域获取一个 通配符证书。

4. 可选但推荐。启用 实例 runners，以便您的用户不必自带。

5. 对于自定义域，拥有一个 辅助 IP。

单域站点#

在为单域站点配置 Pages 之前，您必须：

1. 拥有一个用于 Pages 的域，该域不是您的极狐GitLab 实例域的子域。

   极狐GitLab 域	Pages 域	是否支持
   example.com	example.io	是
   example.com	pages.example.com	否
   gitlab.example.com	pages.example.com	是

2. 配置一个 DNS 记录。

3. 可选。如果您决定在 HTTPS 下提供 Pages，则为该域获取一个 TLS 证书。

4. 可选但推荐。启用 实例 runners，以便您的用户不必自带。

5. 对于自定义域，拥有一个 辅助 IP。

将域添加到公共后缀列表#

公共后缀列表 由浏览器用于决定如何处理子域。如果您的极狐GitLab 实例允许公众成员创建极狐GitLab Pages 站点，它也允许这些用户在页面域 (example.io) 上创建子域。将域添加到公共后缀列表可防止浏览器接受 超级 Cookie，以及其他内容。

要提交您的极狐GitLab Pages 子域，请按照 提交对公共后缀列表的修订。例如，如果您的域是 example.io，您应该请求将 example.io 添加到公共后缀列表中。JihuLab.com 在 2016 年 添加了 gitlab.io。

DNS 配置#

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

plaintext
*.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 记录。

单域站点的 DNS 配置#

要配置极狐GitLab Pages DNS 以用于没有通配符 DNS 的单域站点：

1. 通过将 gitlab_pages['namespace_in_path'] = true 添加到 /etc/gitlab/gitlab.rb 来为此功能启用极狐GitLab Pages 标志。

2. 在您的 DNS 提供商中，为 example.io 添加条目。将 example.io 替换为您的域名，将 192.0.0.0 替换为您的 IP 地址的 IPv4 版本。条目如下所示：

   plaintext
   example.io          1800 IN A    192.0.0.0

3. 可选。如果您的极狐GitLab 实例有一个 IPv6 地址，请为其添加条目。将 example.io 替换为您的域名，将 2001:db8::1 替换为您的 IP 地址的 IPv6 版本。条目如下所示：

   plaintext
   example.io          1800 IN AAAA 2001:db8::1

此示例包含以下内容：

• example.io: 极狐GitLab Pages 提供服务的域。

自定义域的 DNS 配置#

如果需要支持自定义域，Pages 根域的所有子域都应该指向辅助 IP（专用于 Pages 守护进程）。如果没有这种配置，用户无法使用 CNAME 记录将他们的自定义域指向他们的极狐GitLab Pages。

例如，一个条目可以如下所示：

plaintext
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: 专用于极狐GitLab Pages 的辅助 IP。它必须与主 IP 不同。

配置#

根据您的需求，您可以以 4 种不同的方式设置极狐GitLab Pages。

以下示例按从最简单设置到最先进的设置列出。

通配符域#

以下配置是使用极狐GitLab Pages 的最低设置。它是此处描述的所有其他设置的基础。在此配置中：

1. NGINX 将所有请求代理到极狐GitLab Pages 守护进程。
2. 极狐GitLab Pages 守护进程不直接监听公共互联网。

先决条件：

• 通配符 DNS 设置

要配置极狐GitLab Pages 以使用通配符域：

1. 在 /etc/gitlab/gitlab.rb 中设置极狐GitLab Pages 的外部 URL：

   ruby
   external_url "http://example.com" # 此处的 external_url 仅供参考
   pages_external_url 'http://example.io' # 重要：不是 external_url 的子域，因此不能是 http://pages.example.com

2. 重新配置极狐GitLab。

生成的 URL 方案为 http://<namespace>.example.io/<project_slug>。

有关概述，请参阅 如何为极狐GitLab CE 和 EE 启用极狐GitLab Pages。

单域站点#

以下配置是使用极狐GitLab Pages 的最低设置。它是此处描述的所有其他设置的基础。在此配置中：

1. NGINX 将所有请求代理到极狐GitLab Pages 守护进程。
2. 极狐GitLab Pages 守护进程不直接监听公共互联网。

先决条件：

• 您已为 单域站点 配置 DNS。

要配置极狐GitLab Pages 以使用单域站点：

1. 在 /etc/gitlab/gitlab.rb 中设置极狐GitLab Pages 的外部 URL，并启用该功能：

   ruby
   external_url "http://example.com" # 用您自己的 URL 替换此 URL
   pages_external_url 'http://example.io' # 重要：不是 external_url 的子域，因此不能是 http://pages.example.com
   
   # 设置此标志以启用此功能
   gitlab_pages['namespace_in_path'] = true

2. 重新配置极狐GitLab。

生成的 URL 方案为 http://example.io/<namespace>/<project_slug>。

支持 TLS 的通配符域#

先决条件：

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

NGINX 将所有请求代理到守护进程。Pages 守护进程不监听公共互联网。

1. 将 *.example.io 的通配符 TLS 证书和密钥放置在 /etc/gitlab/ssl 中。

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

   ruby
   external_url "https://example.com" # 此处的 external_url 仅供参考
   pages_external_url 'https://example.io' # 重要：不是 external_url 的子域，因此不能是 https://pages.example.com
   
   pages_nginx['redirect_http_to_https'] = true

3. 如果您没有将证书和密钥命名为 example.io.crt 和 example.io.key，则还必须添加完整路径，如下所示：

   ruby
   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 系统 OAuth 应用程序 中的重定向 URI，以使用 HTTPS 协议。

生成的 URL 方案为 https://<namespace>.example.io/<project_slug>。

支持 TLS 的单域站点#

先决条件：

• 您已为 单域站点 配置 DNS。
• 您拥有涵盖您的域的 TLS 证书（例如 example.io）。

在此配置中，NGINX 将所有请求代理到守护进程。极狐GitLab Pages 守护进程不监听公共互联网：

1. 按照先决条件中提到的方式将您的 TLS 证书和密钥添加到 /etc/gitlab/ssl。

2. 在 /etc/gitlab/gitlab.rb 中设置极狐GitLab Pages 的外部 URL，并启用该功能：

   ruby
   1external_url "https://example.com" # 用您自己的 URL 替换此 URL
   2pages_external_url 'https://example.io' # 重要：不是 external_url 的子域，因此不能是 https://pages.example.com
   3
   4pages_nginx['redirect_http_to_https'] = true
   5
   6# 设置此标志以启用此功能
   7gitlab_pages['namespace_in_path'] = true

3. 如果您的 TLS 证书和密钥名称与您的域名不匹配，例如 example.io.crt 和 example.io.key，请将证书和密钥文件的完整路径添加到 /etc/gitlab/gitlab.rb：

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

4. 如果您使用 Pages 访问控制，请更新极狐GitLab Pages 系统 OAuth 应用程序 中的重定向 URI，以使用 HTTPS 协议。

极狐GitLab Pages 不会更新 OAuth 应用程序，默认的 auth_redirect_uri 更新为 https://example.io/projects/auth。在重新配置之前，请从 /etc/gitlab/gitlab-secrets.json 中删除 gitlab_pages 部分，然后运行 gitlab-ctl reconfigure。有关更多信息，请参阅 GitLab Pages does not regenerate OAuth。

1. 重新配置极狐GitLab。

生成的 URL 方案为 https://example.io/<namespace>/<project_slug>。

使用 TLS 终止负载均衡器的通配符域#

先决条件：

• 通配符 DNS 设置
• TLS 终止负载均衡器

此设置主要用于在 亚马逊网络服务上安装极狐GitLab POC。这包括一个 TLS 终止的 经典负载均衡器，监听 HTTPS 连接，管理 TLS 证书，并将 HTTP 流量转发到实例。

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

   ruby
   1external_url "https://example.com" # 此处的 external_url 仅供参考
   2pages_external_url 'https://example.io' # 重要：不是 external_url 的子域，因此不能是 https://pages.example.com
   3
   4pages_nginx['enable'] = true
   5pages_nginx['listen_port'] = 80
   6pages_nginx['listen_https'] = false
   7pages_nginx['redirect_http_to_https'] = true

2. 重新配置极狐GitLab。

生成的 URL 方案为 https://<namespace>.example.io/<project_slug>。

全局设置#

以下是 Linux 软件包安装中已知的 Pages 配置设置及其功能的表格。这些选项可以在 /etc/gitlab/gitlab.rb 中进行调整，并在您 重新配置极狐GitLab 后生效。这些设置中的大多数不需要手动配置，除非您需要更细粒度地控制 Pages 守护进程在您的环境中如何运行和提供内容。

高级配置#

除了通配符域，您还可以选择配置极狐GitLab Pages 以使用自定义域。再次有两种选择：支持带有和不带有 TLS 证书的自定义域。最简单的设置是不带 TLS 证书的设置。在任何一种情况下，您都需要一个 辅助 IP。如果您有 IPv6 和 IPv4 地址，可以同时使用它们。

自定义域#

先决条件：

• 通配符 DNS 设置
• 辅助 IP

在这种情况下，Pages 守护进程正在运行，NGINX 仍然将请求代理到守护进程，但守护进程可以接收来自外界的请求。支持自定义域，但不支持 TLS。

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

   ruby
   external_url "http://example.com" # 此处的 external_url 仅供参考
   pages_external_url 'http://example.io' # 重要：不是 external_url 的子域，因此不能是 http://pages.example.com
   nginx['listen_addresses'] = ['192.0.2.1'] # 极狐GitLab 实例的主 IP
   pages_nginx['enable'] = false
   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # 极狐GitLab Pages 守护进程的辅助 IP

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

2. 重新配置极狐GitLab。

生成的 URL 方案为 http://<namespace>.example.io/<project_slug> 和 http://custom-domain.com。

支持 TLS 的自定义域#

先决条件：

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

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

1. 将 *.example.io 的通配符 TLS 证书和密钥放置在 /etc/gitlab/ssl 中。

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

   ruby
   1external_url "https://example.com" # 此处的 external_url 仅供参考
   2pages_external_url 'https://example.io' # 重要：不是 external_url 的子域，因此不能是 https://pages.example.com
   3nginx['listen_addresses'] = ['192.0.2.1'] # 极狐GitLab 实例的主 IP
   4pages_nginx['enable'] = false
   5gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # 极狐GitLab Pages 守护进程的辅助 IP
   6gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # 极狐GitLab Pages 守护进程的辅助 IP
   7# 将页面从 HTTP 重定向到 HTTPS
   8gitlab_pages['redirect_http'] = true

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

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

   ruby
   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 系统 OAuth 应用程序 中的重定向 URI，以使用 HTTPS 协议。

生成的 URL 方案为 https://<namespace>.example.io/<project_slug> 和 https://custom-domain.com。

自定义域验证#

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

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

1. 在左侧边栏的底部，选择 管理员。
2. 选择 设置 > 首选项。
3. 展开 Pages。
4. 清除 要求用户证明自定义域的所有权 复选框。此设置默认启用。

Let's Encrypt 集成#

极狐GitLab Pages 的 Let's Encrypt 集成 允许用户为极狐GitLab Pages 在自定义域下提供的站点上添加 Let's Encrypt SSL 证书。

要启用它：

1. 选择一个用于接收域名过期通知的电子邮件地址。
2. 在左侧边栏的底部，选择 管理员。
3. 选择 设置 > 首选项。
4. 展开 Pages。
5. 输入接收通知的电子邮件地址，并接受 Let's Encrypt 的服务条款。
6. 选择 保存更改。

访问控制#

极狐GitLab Pages 访问控制可以按项目配置，并允许根据用户对项目的成员资格来控制对 Pages 站点的访问。

访问控制通过将 Pages 守护进程注册为极狐GitLab 的 OAuth 应用程序来工作。每当未认证用户访问私有 Pages 站点时，Pages 守护进程会将用户重定向到极狐GitLab。如果认证成功，用户将被重定向回 Pages，并携带一个令牌，该令牌存储在一个 cookie 中。cookie 使用一个密钥签名，因此可以检测到篡改行为。

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

Pages 访问控制默认情况下是禁用的。要启用它：

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

   ruby
   gitlab_pages['access_control'] = true

2. 重新配置极狐GitLab。

3. 用户现在可以在他们的项目设置中配置它。

使用 Pages 进行简化认证范围#

默认情况下，Pages 守护进程使用 api 范围进行认证。您可以配置此项。例如，在 /etc/gitlab/gitlab.rb 中将范围减小到 read_api：

ruby
gitlab_pages['auth_scope'] = 'read_api'

认证使用的范围必须与极狐GitLab Pages OAuth 应用程序设置相匹配。现有应用程序的用户必须修改极狐GitLab Pages OAuth 应用程序。按照以下步骤进行操作：

1. 启用访问控制。
2. 在左侧侧边栏底部，选择 管理员。
3. 选择 Applications。
4. 展开 极狐GitLab Pages。
5. 清除 api 范围的复选框并选择所需范围的复选框（例如，read_api）。
6. 选择 Save changes。

禁止所有 Pages 站点的公共访问#

先决条件：

• 您必须拥有实例的管理员权限。
• 您必须首先启用访问控制，以便设置在 管理员 区域中显示。

您可以强制执行访问控制，以便只有经过认证的用户才能访问托管在极狐GitLab 实例上的所有极狐GitLab Pages 网站。此设置覆盖用户在单个项目中设置的访问控制。

这样做可以帮助限制使用 Pages 网站发布的信息仅限于实例用户。
执行步骤：

1. 在左侧侧边栏底部，选择 管理员。
2. 选择 设置 > 偏好设置。
3. 展开 Pages。
4. 选择 禁用 Pages 站点的公共访问 复选框。
5. 选择 保存变更。

在代理后运行#

像极狐GitLab 的其他部分一样，Pages 可以在通过代理限制外部互联网连接的环境中使用。要为极狐GitLab Pages 使用代理：

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

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

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

使用自定义证书颁发机构 (CA)#

使用自定义 CA 签发的证书时，访问控制 和 HTML 作业产物的在线查看会失效，如果自定义 CA 未被识别。

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

对于 Linux 软件包安装，这是通过安装自定义 CA解决的。

对于自编译安装，可以通过在系统证书存储中安装自定义证书颁发机构 (CA) 来解决。

支持调用极狐GitLab API 时的双向 TLS#

先决条件：

• 您的实例必须使用 Linux 软件包安装方法。

如果极狐GitLab 配置为需要双向 TLS，您必须将客户端证书添加到极狐GitLab Pages 配置中。

证书有以下要求：

• 证书必须指定主机名或 IP 地址作为主题备用名称。
• 需要完整证书链，包括最终用户证书、中间证书和根证书，按顺序排列。

证书的通用名称字段被忽略。

要在极狐GitLab Pages 服务器中配置证书：

1. 在极狐GitLab Pages 节点上，创建 /etc/gitlab/ssl 目录并将您的密钥和完整证书链复制到该目录：

   shell
   sudo mkdir -p /etc/gitlab/ssl
   sudo chmod 755 /etc/gitlab/ssl
   sudo cp key.pem cert.pem /etc/gitlab/ssl/
   sudo chmod 644 key.pem cert.pem

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

   ruby
   gitlab_pages['client_cert'] = ['/etc/gitlab/ssl/cert.pem']
   gitlab_pages['client_key'] = ['/etc/gitlab/ssl/key.pem']

3. 如果您使用了自定义证书颁发机构 (CA)，您必须将根 CA 证书复制到 /etc/gitlab/ssl 并编辑 /etc/gitlab/gitlab.rb：

   ruby
   gitlab_pages['client_ca_certs'] = ['/etc/gitlab/ssl/ca.pem']

   多个自定义证书颁发机构 (CA) 的文件路径用逗号分隔。

4. 如果您有多节点极狐GitLab Pages 安装，请在所有节点中重复这些步骤。

5. 在所有极狐GitLab 节点上的 /etc/gitlab/trusted-certs 目录中保存完整证书链文件的副本。

ZIP 服务和缓存配置#

极狐GitLab Pages 可以通过对象存储从 ZIP 存档中提供内容。它使用内存缓存来提高从 ZIP 存档提供内容时的性能。您可以通过更改以下配置标志来修改缓存行为。

ZIP 缓存刷新示例#

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

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

HTTP 严格传输安全 (HSTS) 支持#

可以通过 gitlab_pages['headers'] 配置选项启用 HTTP 严格传输安全 (HSTS)。HSTS 通知浏览器他们正在访问的网站应始终通过 HTTPS 提供内容，以确保攻击者无法迫使后续连接未加密。此外，它可以提高页面的加载速度，因为它可以防止浏览器尝试通过未加密的 HTTP 通道连接，然后再重定向到 HTTPS。

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

Pages 项目重定向限制#

极狐GitLab Pages 具有一组默认限制，用于 _redirects 文件，以最大限度地减少对性能的影响。如果您想增加或减少限制，可以配置这些限制。

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

使用环境变量#

您可以将环境变量传递给 Pages 守护进程（例如，启用或禁用功能标志）。

要禁用可配置目录功能：

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

   ruby
   gitlab_pages['env'] = {
     'FF_CONFIGURABLE_ROOT_DIR' => "false"
   }

2. 保存文件并重新配置极狐GitLab：

   shell
   sudo gitlab-ctl reconfigure

激活守护进程的详细日志记录#

按照以下步骤配置极狐GitLab Pages 守护进程的详细日志记录。

1. 默认情况下，守护进程仅记录 INFO 级别的事件。如果您希望它记录 DEBUG 级别的事件，您必须在 /etc/gitlab/gitlab.rb 中进行配置：

   ruby
   gitlab_pages['log_verbose'] = true

2. 重新配置极狐GitLab。

传播关联 ID#

将 propagate_correlation_id 设置为 true 允许在反向代理后安装时生成并设置关联 ID，以发送到极狐GitLab Pages 的请求。当反向代理设置头值 X-Request-ID 时，值会在请求链中传播。用户可以在日志中找到关联 ID。

要启用关联 ID 的传播：

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

   ruby
   gitlab_pages['propagate_correlation_id'] = true

2. 重新配置极狐GitLab。

更改存储路径#

按照以下步骤更改极狐GitLab Pages 内容的默认存储路径。

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

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

2. 重新配置极狐GitLab。

配置反向代理请求的监听器#

按照以下步骤配置极狐GitLab Pages 的代理监听器。

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

   如果您希望禁用它，您必须在 /etc/gitlab/gitlab.rb 中进行配置：

   ruby
   gitlab_pages['listen_proxy'] = nil

   如果您希望使它监听不同的端口，您也必须在 /etc/gitlab/gitlab.rb 中进行配置：

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

2. 重新配置极狐GitLab。

设置每个极狐GitLab Pages 站点的全局最大大小#

先决条件：

• 您必须拥有实例的管理员权限。

要设置项目的全局最大 Pages 大小：

1. 在左侧侧边栏底部，选择 管理员。
2. 选择 Settings > Preferences。
3. 展开 Pages。
4. 在 Maximum size of pages 中输入一个值。默认值为 100。
5. 选择 Save changes。

设置群组中每个极狐GitLab Pages 站点的最大大小#

先决条件：

• 您必须拥有实例的管理员权限。

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

1. 在左侧侧边栏中，选择 搜索或前往 并找到您的群组。
2. 选择 Settings > General。
3. 展开 Pages。
4. 在 Maximum size 中输入一个值，以 MB 为单位。
5. 选择 Save changes。

设置项目中极狐GitLab Pages 站点的最大大小#

先决条件：

• 您必须拥有实例的管理员权限。

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

1. 在左侧侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 Deploy > Pages。
3. 在 Maximum size of pages 中输入大小，以 MB 为单位。
4. 选择 Save changes。

设置项目中极狐GitLab Pages 自定义域的最大数量#

先决条件：

• 您必须拥有实例的管理员权限。

要设置项目中极狐GitLab Pages 自定义域的最大数量：

1. 在左侧侧边栏底部，选择 管理员。
2. 选择 Settings > Preferences。
3. 展开 Pages。
4. 输入 Maximum number of custom domains per project 的值。使用 0 表示无限制域。
5. 选择 Save changes。

配置并行部署的默认过期时间#

先决条件：

• 您必须拥有实例的管理员权限。

要配置实例的默认持续时间，此后并行部署将被删除：

1. 在左侧侧边栏底部，选择 管理员。
2. 选择 Settings > Preferences。
3. 展开 Pages。
4. 输入 Default expiration for parallel deployments in seconds 的值。使用 0 表示并行部署不应默认过期。
5. 选择 Save changes。

设置每个极狐GitLab Pages 网站的最大文件数量#

极狐GitLab Pages 网站的文件条目（包括目录和符号链接）总数限制为 200,000。

您可以使用极狐GitLab Rails 控制台在极狐GitLab 私有化部署实例中更新限制。

有关详细信息，请参阅 极狐GitLab 应用程序限制。

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

您可以在单独的服务器上运行极狐GitLab Pages 守护进程，以减少主应用服务器的负载。此配置不支持双向 TLS (mTLS)。有关更多信息，请参阅相关功能提案。

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

1. 可选地，为启用访问控制，在 /etc/gitlab/gitlab.rb 中添加以下内容，并重新配置极狐GitLab 服务器：

   ruby
   gitlab_pages['access_control'] = true

如果您计划使用极狐GitLab Pages 进行访问控制，必须在复制 gitlab-secrets.json 之前在第一个极狐GitLab 服务器上启用它。启用访问控制会生成新的 OAuth 应用程序，并将信息传播到 gitlab-secrets.json。如果顺序不正确，您可能会遇到访问控制问题。

1. 在极狐GitLab 服务器上创建秘密文件的备份：

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

2. 在极狐GitLab 服务器上，为启用 Pages，在 /etc/gitlab/gitlab.rb 中添加以下内容：

   ruby
   pages_external_url "http://<pages_server_URL>"

3. 设置对象存储，通过以下方法之一：

   • 配置对象存储并迁移极狐GitLab Pages 数据到其中，或者
   • 配置网络存储。

4. 重新配置极狐GitLab 服务器以使更改生效。gitlab-secrets.json 文件现在已经更新了新的配置。

5. 设置新的服务器。此服务器将成为Pages 服务器。

6. 在Pages 服务器上，通过使用 Linux 软件包安装极狐GitLab 并修改 /etc/gitlab/gitlab.rb 以包含：

   ruby
   1roles ['pages_role']
   2
   3pages_external_url "http://<pages_server_URL>"
   4
   5gitlab_pages['gitlab_server'] = 'http://<gitlab_server_IP_or_URL>'
   6
   7## 如果在步骤 3 启用了访问控制
   8gitlab_pages['access_control'] = true

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

8. 在Pages 服务器上创建秘密文件的备份：

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

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

   shell
   # 在极狐GitLab 服务器上
   cp /etc/gitlab/gitlab-secrets.json /mnt/pages/gitlab-secrets.json
   
   # 在 Pages 服务器上
   mv /var/opt/gitlab/gitlab-rails/shared/pages/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json

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

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

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

12. 重新配置极狐GitLab 服务器以使更改生效。

如果您希望分发负载，可以在多个服务器上运行极狐GitLab Pages。您可以通过标准负载均衡实践来实现，例如配置 DNS 服务器以返回您的 Pages 服务器的多个 IP，或者配置负载均衡器以在 IP 级别工作。如果您希望在多个服务器上设置极狐GitLab Pages，请对每个 Pages 服务器执行上述步骤。

域源配置#

当极狐GitLab Pages 守护进程处理 Pages 请求时，首先需要识别应该使用哪个项目来提供请求的 URL，以及其内容如何存储。

默认情况下，极狐GitLab Pages 每次请求新域时都会使用内部极狐GitLab API。Pages 如果无法连接到 API 则无法启动。域信息也由 Pages 守护进程缓存，以加快后续请求。

有关常见问题，请参阅故障排除。

极狐GitLab API 缓存配置#

基于 API 的配置使用缓存机制来提高 Pages 的服务性能和可靠性。可以通过更改缓存设置来修改缓存行为，不过推荐值已经设置，只有在需要时才应进行修改。这些值的错误配置可能导致间歇性或持续性错误，或 Pages 守护进程提供旧内容。

示例：

• 增加 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 减少在报告错误之前自动尝试解析域配置的次数。

对象存储设置#

以下对象存储设置为：

• 在自编译安装中，嵌套在 pages: 和 object_store: 下。
• 在 Linux 软件包安装中，以 pages_object_store_ 为前缀。

S3 兼容连接设置#

您应使用统一对象存储设置。

请参阅不同提供商的可用连接设置。

将 Pages 部署迁移到对象存储#

现有 Pages 部署对象（ZIP 存档）可以存储在：

• 本地存储
• 对象存储

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

shell
sudo gitlab-rake gitlab:pages:deployments:migrate_to_object_storage

您可以使用 PostgreSQL 控制台 跟踪进度并验证所有 Pages 部署是否成功迁移：

• 对于 Linux 软件包安装，使用 sudo gitlab-rails dbconsole --database main。
• 对于自编译安装，使用 sudo -u git -H psql -d gitlabhq_production。

验证下面的 objectstg（其中 store=2）是否有所有 Pages 部署的计数：

shell
gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM pages_deployments;

total | filesystem | objectstg
------+------------+-----------
   10 |          0 |        10

在验证一切正常后，禁用 Pages 本地存储。

将 Pages 部署回滚到本地存储#

在执行迁移到对象存储之后，您可以选择将 Pages 部署移回本地存储：

shell
sudo gitlab-rake gitlab:pages:deployments:migrate_to_local

禁用 Pages 本地存储#

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

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

   ruby
   gitlab_rails['pages_local_store_enabled'] = false

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

在多节点环境中启用 Pages 网络存储#

对象存储是大多数环境的首选配置。但是，如果您的需求要求网络存储，并且您希望将 Pages 配置为在单独的服务器上运行，则应：

1. 确保您打算使用的共享存储卷已在主服务器和您计划的 Pages 服务器上挂载并可用。

2. 更新每个节点的 /etc/gitlab/gitlab.rb，以包括：

   ruby
   gitlab_pages['enable_disk'] = true
   gitlab_rails['pages_path'] = "/var/opt/gitlab/gitlab-rails/shared/pages" # Path to your network storage

3. 切换 Pages 到单独的服务器。

在成功配置 Pages 到单独的服务器后，只有该服务器需要访问共享存储卷。考虑保持共享存储卷挂载在主服务器上，以防您必须迁回到单节点环境。

ZIP 存储#

极狐GitLab Pages 的底层存储格式是每个项目单个 ZIP 存档。

这些 ZIP 存档可以在本地磁盘存储或对象存储中存储（如果已配置）。

每次更新 Pages 站点时都会存储 ZIP 存档。

备份#

极狐GitLab Pages 是常规备份的一部分，因此无需配置单独的备份。

安全性#

您应强烈考虑在与极狐GitLab 不同的主机名下运行极狐GitLab Pages，以防止 XSS 攻击。

速率限制#

您可以强制执行速率限制以帮助最小化拒绝服务 (DoS) 攻击的风险。极狐GitLab Pages 使用令牌桶算法来实施速率限制。默认情况下，超过指定限制的请求或 TLS 连接会被报告和拒绝。

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

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

基于 HTTP 请求的速率限制通过以下方式实施：

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

基于 TLS 连接的速率限制通过以下方式实施：

• rate_limit_tls_source_ip：设置每个客户端 IP 每秒 TLS 连接的最大阈值。设置为 0 以禁用此功能。
• rate_limit_tls_source_ip_burst：设置允许每个客户端 IP 在 TLS 连接的初始爆发中 TLS 连接的最大阈值。例如，当您同时从不同的网络浏览器加载网页时。
• rate_limit_tls_domain：设置托管的 Pages 域每秒 TLS 连接的最大阈值。设置为 0 以禁用此功能。
• rate_limit_tls_domain_burst：设置允许托管的 Pages 域在 TLS 连接的初始爆发中 TLS 连接的最大阈值。

要允许某些 IP 范围（子网）绕过所有速率限制：

• rate_limit_subnets_allow_list：设置允许绕过所有速率限制的 IP 范围（子网）的允许列表。例如，['1.2.3.4/24', '2001:db8::1/32']。Charts 示例 可用。

IPv6 地址在 128 位地址空间中接收较大的前缀。前缀通常至少为 /64 大小。由于可能的地址数量众多，如果客户端的 IP 地址是 IPv6，则限制应用于 IPv6 前缀，长度为 64，而不是整个 IPv6 地址。

启用按源 IP 的 HTTP 请求速率限制#

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

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

2. 重新配置极狐GitLab。

启用按域的 HTTP 请求速率限制#

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

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

2. 重新配置极狐GitLab。

启用按源 IP 的 TLS 连接速率限制#

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

   ruby
   gitlab_pages['rate_limit_tls_source_ip'] = 20.0
   gitlab_pages['rate_limit_tls_source_ip_burst'] = 600

2. 重新配置极狐GitLab。

启用按域的 TLS 连接速率限制#

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

   ruby
   gitlab_pages['rate_limit_tls_domain'] = 1000
   gitlab_pages['rate_limit_tls_domain_burst'] = 5000

2. 重新配置极狐GitLab。

相关主题#

• 极狐GitLab Pages 管理故障排除