极狐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 添加到公共后缀列表。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 16.7 中作为实验功能引入。
• 在极狐GitLab 16.11 中移至 beta。
• 在极狐GitLab 17.2 中，实现从 NGINX 更改为极狐GitLab Pages 代码库。
• 在极狐GitLab 17.4 中正式发布（GA）。

要配置单域站点的极狐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 替换为实例的 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 仅作参考
   pages_external_url 'http://example.io' # 重要：不能是 external_url 的子域，因此不能是 http://pages.example.com

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

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

单域站点#

版本历史

• 在极狐GitLab 16.7 中作为实验功能引入。
• 在极狐GitLab 16.11 中移至 beta。
• 在极狐GitLab 17.2 中实现从 NGINX 更改为极狐GitLab Pages 代码库。
• 在极狐GitLab 17.4 中正式发布（GA）。

该配置是使用单域站点的最小设置，并作为所有其他单域设置的基础。在此配置中：

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

先决条件：

• 你已经为单域站点配置了 DNS。

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

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

   ruby
   external_url "http://example.com" # 将此处 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 支持的通配符域#

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 仅作参考
   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. 如果你使用访问控制，请将极狐GitLab Pages 系统 OAuth 应用程序中的重定向 URI 更新为使用 HTTPS 协议。

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

带 TLS 支持的单域站点#

版本历史

• 在极狐GitLab 16.7 中作为实验功能引入。
• 在极狐GitLab 16.11 中移至 beta。
• 在极狐GitLab 17.2 中实现从 NGINX 更改为极狐GitLab Pages 代码库。
• 在极狐GitLab 17.4 中正式发布（GA）。

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

先决条件：

• 你已经为单域站点配置了 DNS。
• 你有一个涵盖你域名的 TLS 证书（如 example.io）。

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

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

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

   ruby
   1external_url "https://example.com" # 将此处 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，请添加完整路径：

   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。 重新配置前，请将 gitlab_pages 部分从 /etc/gitlab/gitlab-secrets.json 中移除， 然后运行 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 仅作参考
   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 守护进程在你的环境中如何运行和提供内容。

脚注:

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 仅供参考
   2pages_external_url 'http://example.io' # 重要提示：不是 external_url 的子域名，因此不能是 http://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['custom_domain_mode'] = 'http' # 启用自定义域名

   如果您没有 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 仅供参考
   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
   7gitlab_pages['custom_domain_mode'] = 'https' # 启用自定义域名
   8# 将页面从 HTTP 重定向到 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 网站。所有项目都会失去 所有人 可见性级别选项，并根据项目的可见性设置，仅限项目成员或具有访问权限的每个人访问。 使用此设置将 极狐GitLab Pages 发布的信息限制为仅限您实例的用户访问。

前提条件：

• 实例的管理员访问权限。
• 已启用访问控制，以便在管理员区域显示此设置。

要禁用所有 Pages 站点的公共访问：

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

默认禁用唯一域#

版本历史

• [引入] 于极狐GitLab 18.3。

默认情况下，所有新创建的 极狐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: 由未知机构签名的证书

要解决此问题：

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

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

版本历史

• [引入] 于极狐GitLab 17.1。

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

证书需要满足以下要求：

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

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

前提条件：

• 您的实例使用 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 延长至 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. 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. 在左侧边栏中，选择 设置 > 偏好设置。
3. 展开 Pages。
4. 在 Pages 最大大小 中，输入一个值。默认值为 100。
5. 选择 保存更改。

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

前提条件：

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

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

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

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

前提条件：

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

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

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

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

前提条件：

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

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

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

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

版本历史

• [引入] 于极狐GitLab 17.4。

前提条件：

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

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

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

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

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

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

有关更多信息，请参见 极狐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## 如果启用了访问控制
   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
    # 在 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

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。如果无法连接到 API，Pages 将无法启动。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" # 网络存储路径

3. 将 Pages 切换到您的独立服务器。

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

ZIP 存储#

极狐GitLab Pages 的底层存储格式是每个项目一个 ZIP 存档。这些存档可以存储在本地或对象存储中。每次更新 Pages 站点时都会存储一个新的存档。

备份#

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

安全#

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

速率限制#

版本历史

• [变更] 于极狐GitLab 17.3：您可以从 Pages 速率限制中排除子网。

您可以强制执行速率限制，以帮助最大限度地降低拒绝服务 (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 连接数。
• rate_limit_tls_domain：每个托管 Pages 域名每秒的最大 TLS 连接数。设置为 0 以禁用。
• rate_limit_tls_domain_burst：每个托管 Pages 域名在初始突发中允许的最大 TLS 连接数。

要允许某些 IP 范围（子网）绕过所有速率限制，请使用 rate_limit_subnets_allow_list。例如，['1.2.3.4/24', '2001:db8::1/32']。提供了一个极狐GitLab Pages chart 示例。

如果客户端的 IP 地址是 IPv6，则限制应用于长度为 64 的 IPv6 前缀，而不是整个地址。

通过源 IP 启用 HTTP 请求速率限制#

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

1. 添加以下内容：

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

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

通过域名启用 HTTP 请求速率限制#

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

1. 添加：

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

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

通过源 IP 启用 TLS 连接速率限制#

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

1. 添加：

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

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

通过域名启用 TLS 连接速率限制#

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

1. 添加：

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

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

相关主题#

• 极狐GitLab Pages 管理故障排查
• 极狐GitLab Pages 用户文档
• 自定义域名与 SSL/TLS 证书
• Pages 访问控制
• 作业产物
• OAuth 提供程序集成
• 极狐GitLab 应用限制
• 对象存储
• 并行部署
• 自定义默认文件夹
• Pages 重定向