GitLab Pages 管理

GitLab Pages 为极狐GitLab 项目和群组提供静态站点托管。 服务器管理员必须先配置 Pages，用户才能使用此功能。作为管理员，您可以使用 GitLab Pages 来：

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

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

GitLab Pages 守护进程#

GitLab Pages 使用 GitLab Pages 守护进程，这是一个用 Go 编写的基础 HTTP 服务器， 可以监听外部 IP 地址，并支持自定义域名和自定义证书。它通过服务器名称指示（SNI）支持动态证书，并默认使用 HTTP2 提供页面。

有关更多信息，请参阅 README。

与自定义域名一起使用时，Pages 守护进程必须监听端口 80 或 443。对于通配符域名，则不需要这样做。

您可以这样运行 Pages 守护进程：

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

以下各节假设采用第一种方案。如果您不支持自定义域名，则不需要辅助 IP。

先决条件#

本节介绍配置 GitLab Pages 的先决条件。

通配符域名#

每个站点都有自己的子域名（例如 <namespace>.example.io/<project_slug>）。此子域名需要通配符 DNS 记录（*.example.io），这是大多数实例的推荐设置。

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

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

   极狐GitLab 域名	Pages 域名	是否可用？
   example.com	example.io
   example.com	pages.example.com	1
   gitlab.example.com	pages.example.com

   脚注：

   1. 如果 Pages 域名是极狐GitLab 实例域名的子域名， 则所有已部署的 Pages 站点都可以访问极狐GitLab 会话 cookie。

2. 配置通配符 DNS 记录。

3. 可选。如果您决定在 HTTPS 下提供 Pages，请为该域名准备通配符证书。

4. 可选但推荐。开启实例 Runner， 这样您的用户就不必自带 Runner。

5. 对于自定义域名，请准备辅助 IP。

单域名站点#

所有站点共用一个域名，以命名空间和项目路径作为路径段（例如 example.io/<namespace>/<project_slug>）。此域名只需要一条 DNS A 记录。

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

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

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

   脚注：

   1. 如果 Pages 域名是极狐GitLab 实例域名的子域名， 则所有已部署的 Pages 站点都可以访问极狐GitLab 会话 cookie。

2. 配置 DNS 记录。

3. 可选。如果您决定在 HTTPS 下提供 Pages，请为该域名准备 TLS 证书。

4. 可选但推荐。开启实例 Runner， 这样您的用户就不必自带 Runner。

5. 对于自定义域名，请准备辅助 IP。

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

浏览器使用公共后缀列表来决定如何处理子域名。如果您的极狐GitLab 实例允许公众创建 GitLab Pages 站点，那么它也允许这些用户在 Pages 域名（example.io）上创建子域名。将域名添加到公共后缀列表可以防止浏览器接受 超级 cookie， 以及其他问题。

要提交您的 GitLab Pages 子域名，请参阅向公共后缀列表提交修订。例如，如果您的域名是 example.io，您应该请求将 example.io 添加到公共后缀列表。GitLab.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 配置#

要为不使用通配符 DNS 的单域名站点配置 GitLab Pages DNS：

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

2. 在您的 DNS 提供商中，为 example.io 添加条目。 将 example.io 替换为您的域名，将 192.0.0.0 替换为您实例的 IPv4 地址：

   plaintext
   example.io          1800 IN A    192.0.0.0

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

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

   example.io 是 GitLab Pages 提供服务的域名。

自定义域名的 DNS 配置#

如果您需要自定义域名支持，Pages 根域名的所有子域名都必须指向专用于 Pages 守护进程的辅助 IP。如果没有此配置，用户将无法使用 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 不同。

配置#

您可以通过多种方式设置 GitLab Pages。以下示例从最简单的设置到最复杂的设置依次列出。

通配符域名#

此配置是使用 GitLab Pages 的最低设置，也是所有其他设置的基础。在此配置中：

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

先决条件：

• 您已配置通配符 DNS。

要将 GitLab Pages 配置为使用通配符域名：

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

   ruby
   external_url "http://example.com" # external_url here is only for reference
   pages_external_url 'http://example.io' # Important: not a subdomain of external_url, so cannot be http://pages.example.com

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

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

单域名站点#

此配置是使用单域名站点的最低设置，也是所有其他单域名设置的基础。在此配置中：

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

先决条件：

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

要将 GitLab Pages 配置为使用单域名站点：

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

   ruby
   external_url "http://example.com" # Swap out this URL for your own
   pages_external_url 'http://example.io' # Important: not a subdomain of external_url, so cannot be http://pages.example.com
   
   # Set this flag to turn on this feature
   gitlab_pages['namespace_in_path'] = true

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

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

支持 TLS 的通配符域名#

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

一个实例只能分配一个通配符。

先决条件：

• 您已配置通配符 DNS。
• 您拥有 TLS 证书。它可以是通配符证书或符合 要求的任何其他类型的证书。

要配置支持 TLS 的通配符域名：

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

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

   ruby
   external_url "https://example.com" # external_url here is only for reference
   pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be 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. 如果您使用访问控制，请更新 GitLab Pages 系统 OAuth 应用程序 中的重定向 URI，以使用 HTTPS 协议。

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

支持 TLS 的单域名站点#

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

先决条件：

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

要配置支持 TLS 的单域名站点：

1. 将您的 TLS 证书和密钥添加到 /etc/gitlab/ssl。

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

   ruby
   1external_url "https://example.com" # Swap out this URL for your own
   2pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be https://pages.example.com
   3
   4pages_nginx['redirect_http_to_https'] = true
   5
   6# Set this flag to turn on this feature
   7gitlab_pages['namespace_in_path'] = true

3. 如果您的 TLS 证书或密钥文件名称与 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 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 不会重新生成 OAuth。

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

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

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

在在 Amazon Web Services 上安装极狐GitLab POC 时使用此设置。 此设置包含一个 TLS 终止的经典负载均衡器，它监听 HTTPS 连接、管理 TLS 证书，并将 HTTP 流量转发到实例。

先决条件：

• 已配置通配符 DNS。
• 一个 TLS 终止负载均衡器。

要配置使用 TLS 终止负载均衡器的通配符域名：

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

   ruby
   1external_url "https://example.com" # external_url here is only for reference
   2pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be 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 速率限制。

脚注：

1. 使用外部 Sidekiq 节点时，您必须将 pages_external_url 添加到您的 配置中。如果没有此设置，外部 Sidekiq 节点将无法处理部署作业。

高级配置#

除了通配符域名，您还可以配置 GitLab Pages 以使用自定义域名，无论是否使用 TLS 证书。无论哪种情况，您都需要一个辅助 IP。如果您同时拥有 IPv6 和 IPv4 地址，可以同时使用它们。

自定义域名#

默认情况下，GitLab Pages 站点在 Pages 根域名的子域名上提供服务，例如 namespace.example.io/project。要为 Pages 站点配置自定义域名，请添加一条 CNAME DNS 记录，将您自己的域名（例如 example-custom-site-here.com）指向 GitLab Pages。

如果您只需要默认的 *.example.io 子域名 URL，则无需配置自定义域名支持。

在此配置中，Pages 守护进程正在运行，NGINX 将请求代理到它，但守护进程也可以接收来自公共互联网的请求。支持不带 TLS 的自定义域名。

先决条件：

• 已配置通配符 DNS。
• 一个辅助 IP。

要配置自定义域名：

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

   ruby
   1external_url "http://example.com" # external_url here is only for reference
   2pages_external_url 'http://example.io' # Important: not a subdomain of external_url, so cannot be http://pages.example.com
   3nginx['listen_addresses'] = ['192.0.2.1'] # The primary IP of the GitLab instance
   4pages_nginx['enable'] = false
   5gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon
   6gitlab_pages['custom_domain_mode'] = 'http' # Enable custom domain

   如果您没有 IPv6，请省略 IPv6 地址。

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

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

支持 TLS 的自定义域名#

在此配置中，Pages 守护进程正在运行，NGINX 将请求代理到它，但守护进程也可以接收来自公共互联网的请求。支持自定义域名和 TLS。

先决条件：

• 已配置通配符 DNS。
• 一个 TLS 证书。它可以是通配符证书或符合 要求的任何其他类型的证书。
• 一个辅助 IP。

要配置支持 TLS 的自定义域名：

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

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

   ruby
   1external_url "https://example.com" # external_url here is only for reference
   2pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be https://pages.example.com
   3nginx['listen_addresses'] = ['192.0.2.1'] # The primary IP of the GitLab instance
   4pages_nginx['enable'] = false
   5gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon
   6gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon
   7gitlab_pages['custom_domain_mode'] = 'https' # Enable custom domain
   8# Redirect pages from HTTP to HTTPS
   9gitlab_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. 如果您使用访问控制，请编辑 GitLab Pages 系统 OAuth 应用程序中的重定向 URI，以使用 HTTPS 协议。

自定义域名验证#

为防止恶意用户劫持不属于他们的域名，极狐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 使用该令牌进行身份验证。对于它接收的每个请求，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 应用程序。

先决条件：

• 您已开启访问控制。

要更改 Pages 使用的范围：

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择应用程序。
3. 展开 GitLab Pages。
4. 清除 api 范围的复选框，并选中所需范围的复选框（例如 read_api）。
5. 选择保存更改。

禁用对所有 Pages 站点的公开访问#

您可以对托管在您极狐GitLab 实例上的所有 GitLab Pages 网站强制执行访问控制。当您开启此设置时，只有已身份验证的用户才能访问 Pages 网站。所有项目都会失去 所有人 可见性级别选项，并根据项目的可见性设置限制为项目成员或所有有访问权限的人。

使用此设置可将通过 Pages 发布的信息仅限您实例的用户访问。

先决条件：

• 对实例的管理员访问权限。
• 已开启访问控制，该设置才会显示在管理区域中。

要关闭对所有 Pages 站点的公开访问：

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择设置 > 偏好设置。
3. 展开 Pages。
4. 选中 禁用对所有 Pages 站点的公开访问复选框。
5. 选择保存更改。

默认禁用唯一域名#

默认情况下，所有新建的 GitLab Pages 站点都使用唯一域名 URL（例如 my-project-1a2b3c.example.com），这可以防止同一命名空间下不同站点之间 共享 cookie。

您可以关闭此默认行为，使新的 Pages 站点改用基于路径的 URL（例如 my-namespace.example.com/my-project）。但是，此方法存在同一命名空间下不同站点之间共享 cookie 的风险。

此设置仅控制新站点的默认行为。用户仍可为单个项目覆盖此设置。

先决条件：

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

要默认关闭唯一域名：

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择设置 > 偏好设置。
3. 展开 Pages。
4. 清除 默认启用唯一域名 复选框。
5. 选择保存更改。

此设置仅影响新的 Pages 站点。现有站点保持其当前的唯一域名配置。

在代理后面运行#

您可以在外部互联网连接受代理限制的环境中使用 GitLab Pages。

要为 GitLab Pages 使用代理：

1. 在 /etc/gitlab/gitlab.rb中，添加：

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

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

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

使用自定义 CA 颁发的证书时，如果自定义 CA 未被识别，访问控制和在线查看 HTML 作业产物将无法正常工作。

这通常会导致以下错误：

plaintext
Post /oauth/token: x509: certificate signed by unknown authority

要解决此问题：

• 对于 Linux 软件包安装， 安装自定义 CA。
• 对于自行编译安装，请在系统证书存储中安装自定义 CA。

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

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

证书有以下要求：

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

证书的 Common Name 字段会被忽略。

先决条件：

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

要在您的 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']

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

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

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

ZIP 服务和缓存配置#

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

ZIP 缓存刷新示例#

如果在 zip_cache_expiration 之前访问归档，且距离过期剩余的时间小于或等于 zip_cache_refresh，则归档会在缓存中刷新（延长其在内存中保留的时间）。例如，如果在时间 0s 访问 archive.zip，它将在 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）支持#

HTTP 严格传输安全（HSTS）可以通过 gitlab_pages['headers'] 配置选项开启。HSTS 告知浏览器应始终通过 HTTPS 访问网站，防止攻击者强制使用未加密的连接。它还可以通过防止浏览器在被重定向到 HTTPS 之前尝试未加密的 HTTP 连接来提高页面加载速度。

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 以使更改生效。

为守护进程启用详细日志记录#

要配置 GitLab Pages 守护进程的详细日志记录：

1. 默认情况下，守护进程仅以 INFO 级别记录日志。要以 DEBUG 级别记录事件，请编辑 /etc/gitlab/gitlab.rb：

   ruby
   gitlab_pages['log_verbose'] = true

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

传播关联 ID#

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

要开启关联 ID 的传播：

1. 在 /etc/gitlab/gitlab.rb中，添加：

   ruby
   gitlab_pages['propagate_correlation_id'] = true

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

更改存储路径#

要更改 GitLab Pages 内容存储的默认路径：

1. 页面默认存储在 /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. 在左侧边栏中，选择设置 > 偏好设置。
3. 展开 Pages。
4. 在 页面最大大小中，输入一个值。默认为 100。
5. 选择保存更改。

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

先决条件：

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

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

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

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

先决条件：

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

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

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。
2. 在左侧边栏中，选择部署 > Pages。
3. 在 页面最大大小中，输入以 MB 为单位的大小。
4. 选择保存更改。

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

先决条件：

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

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

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择设置 > 偏好设置。
3. 展开 Pages。
4. 为 每个项目的最大自定义域名数量 输入一个值。使用 0 表示不限域名数。
5. 选择保存更改。

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

先决条件：

• 对实例的管理员访问权限。

要配置并行部署被删除后的默认持续时间：

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择设置 > 偏好设置。
3. 展开 Pages。
4. 为 并行部署的默认过期时间（秒） 输入一个值。 如果并行部署默认不应过期，请使用 0。
5. 选择保存更改。

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

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

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

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

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

您可以在单独的服务器上运行 GitLab Pages 守护进程，以减轻主应用服务器的负载。

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

1. 可选。要开启访问控制，请将以下内容添加到 /etc/gitlab/gitlab.rb 并 重新配置极狐GitLab 服务器：

   如果您计划将 GitLab Pages 与访问控制一起使用，请在复制gitlab-secrets.json 之前在极狐GitLab 服务器上开启访问控制。开启访问控制会生成一个新的 OAuth 应用程序，其相关信息会传播到 gitlab-secrets.json。如果不按 正确的顺序执行此操作，您可能会遇到访问控制问题。

   ruby
   gitlab_pages['access_control'] = true

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

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

3. 在极狐GitLab 服务器上，要开启 Pages，请将以下内容添加到 /etc/gitlab/gitlab.rb：

   ruby
   pages_external_url "http://<pages_server_URL>"

4. 通过以下任一方式设置对象存储：

   • 配置对象存储并将 GitLab Pages 数据迁移到其中。
   • 配置网络存储。

5. 重新配置极狐GitLab 服务器以使 更改生效。gitlab-secrets.json 文件现在会更新为 新配置。

6. 设置一台新服务器。这将成为 Pages 服务器。

7. 在 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## If access control was enabled
   8gitlab_pages['access_control'] = true

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

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

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

10. 要为单个 GitLab Pages 站点开启自定义域名，请使用以下任一方式设置 Pages 服务器：

    • 自定义域名。
    • 支持 TLS 的自定义域名。

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

    shell
    # 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

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

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

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

14. 要为单个 GitLab Pages 站点开启自定义域名，请在极狐GitLab 服务器上， 对 /etc/gitlab/gitlab.rb 进行以下更改：

    • 自定义域名：

      ruby
         gitlab_pages['custom_domain_mode'] = 'http'

    • 支持 TLS 的自定义域名：

      ruby
         gitlab_pages['custom_domain_mode'] = 'https'

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

要分散负载，您可以使用标准负载均衡实践在多台服务器上运行 GitLab Pages，例如配置您的 DNS 服务器返回多个 IP 或使用 IP 级负载均衡器。要在多台服务器上设置 GitLab Pages，请为每台 Pages 服务器重复上述过程。

域名来源配置#

当 GitLab Pages 守护进程处理请求时，它首先确定哪个项目应处理请求的 URL 以及其内容如何存储。

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

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

极狐GitLab API 缓存配置#

基于 API 的配置使用缓存机制来提高性能和可靠性。您可以通过更改以下设置来修改缓存行为，但除非必要，否则应仅更改推荐的默认值。不正确的配置可能导致间歇性或持续性错误，或导致 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 归档。这些归档可以存储在本地或对象存储上。每次更新 Pages 站点时，都会存储一个新的归档。

备份#

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

安全#

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