Help us learn about your current experience with the documentation. Take the survey.

GitLab Pages 管理

层级（Tier）: Free, Premium, Ultimate
提供方式（Offering）: GitLab 自托管（Self-Managed）

GitLab Pages 为 GitLab 项目和群组提供静态网站托管服务。
服务器管理员必须先配置 Pages，用户才能访问此功能。
借助 GitLab Pages，管理员可以：

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

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

本指南适用于 Linux 软件包安装。如果您使用自编译的 GitLab 安装，请参阅自编译安装的 GitLab Pages 管理。

GitLab Pages 守护进程

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

对于自定义域名（但不包括通配符域名），Pages 守护进程需要监听端口 80 和/或 443。因此，您可以灵活选择以下配置方式：

在与 GitLab 相同的服务器上运行 Pages 守护进程，监听 辅助 IP。
在独立服务器上运行 Pages 守护进程。此时，Pages 路径也必须存在于安装 Pages 守护进程的服务器中，因此需通过网络共享该路径。
在与 GitLab 相同的服务器上运行 Pages 守护进程，监听相同 IP 但不同端口。此时，您必须使用负载均衡器代理流量。若选择此方案，HTTPS 应使用 TCP 负载均衡；若使用 TLS 终止（HTTPS 负载均衡），则无法使用用户提供的证书提供服务；HTTP 可使用 HTTP 或 TCP 负载均衡。

本文档假设采用第一种方案。若不支持自定义域名，则无需辅助 IP。

前提条件

本节介绍配置 GitLab Pages 的前提要求。

通配符域名

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

拥有一个不属于 GitLab 实例域名的子域名的域名用于 Pages。

GitLab 域名	Pages 域名	是否有效？
`example.com`	`example.io`	是
`example.com`	`pages.example.com`	否
`gitlab.example.com`	`pages.example.com`	是

配置 通配符 DNS 记录。
可选。若决定通过 HTTPS 提供 Pages 服务，需拥有该域名的 通配符证书。
可选但推荐。启用实例 runner，这样用户无需自带 runner。
对于自定义域名，需准备 辅助 IP。

单域名站点

在配置单域名站点的 Pages 前，你必须：

拥有一个不属于 GitLab 实例域名子域名的 Pages 域名。

GitLab 域名	Pages 域名	支持情况
`example.com`	`example.io`	是
`example.com`	`pages.example.com`	否
`gitlab.example.com`	`pages.example.com`	是

配置一个 DNS 记录。
可选。如果你决定通过 HTTPS 提供 Pages 服务，请为该域名准备一个 TLS 证书。
可选但推荐。启用实例 runner，这样你的用户就不必自带。
对于自定义域名，需要一个 二级 IP。

如果你的 GitLab 实例和 Pages 守护进程部署在私有网络或防火墙之后，你的 GitLab Pages 网站仅对有权访问私有网络的设备/用户可用。

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

公共后缀列表由浏览器用于决定如何处理子域名。如果你的 GitLab 实例允许公众成员创建 GitLab Pages 网站，它也允许这些用户在 pages 域名（例如 example.io）上创建子域名。将该域名添加到公共后缀列表可防止浏览器接受超级 Cookie 等内容。

若要提交你的 GitLab Pages 子域名，请遵循提交公共后缀列表修正。例如，如果你的域名是 example.io，你应该请求将 example.io 添加到公共后缀列表。GitLab.com 在 2016 年添加了 gitlab.io。

DNS 配置

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

*.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：

通过在 /etc/gitlab/gitlab.rb 中添加 gitlab_pages['namespace_in_path'] = true 来启用此功能的 GitLab Pages 标志。
在你的 DNS 提供商中，为 example.io 添加条目。将 example.io 替换为你的域名，将 192.0.0.0 替换为你的 IP 地址的 IPv4 版本。条目如下所示：
```
example.io          1800 IN A    192.0.0.0
```
可选。如果你的 GitLab 实例有 IPv6 地址，为其添加条目。将 example.io 替换为你的域名，将 2001:db8::1 替换为你的 IP 地址的 IPv6 版本。条目如下所示：
```
example.io          1800 IN AAAA 2001:db8::1
```

此示例包含以下内容：

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

自定义域名的 DNS 配置

如果需要支持自定义域名，Pages 根域名的所有子域名应指向二级 IP（专用于 Pages 守护进程）。若无此配置，用户无法使用 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：专用于 GitLab Pages 的二级 IP。必须与主 IP 不同。

你不应该使用 GitLab 域名来提供用户页面。更多信息请参见安全章节。

配置

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

以下示例按从最简单的设置到最复杂的顺序列出。

通配符域名

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

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

先决条件：

通配符 DNS 设置

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

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

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

重新配置 GitLab。

生成的 URL 方案是 http://<命名空间>.example.io/<项目标识符>。

概览请参见如何为 GitLab CE 和 EE 启用 GitLab Pages。

单域站点

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

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

先决条件：

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

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

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

external_url "http://example.com" # 替换此 URL 为您自己的
pages_external_url 'http://example.io' # 重要：不是 external_url 的子域，因此不能是 http://pages.example.com

# 设置此标志以启用此功能
gitlab_pages['namespace_in_path'] = true

重新配置 GitLab。

生成的 URL 方案是 http://example.io/<命名空间>/<项目标识符>。

GitLab Pages 同一时间只支持一种 URL 方案：通配符域名或单域站点。如果您启用了 namespace_in_path，现有的 GitLab Pages 网站只能在单域站点上访问。

支持TLS的通配符域名

前提条件：

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

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

将 *.example.io 的通配符TLS证书及其密钥放置在 /etc/gitlab/ssl 目录下。

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

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

如果你的证书和密钥未命名为 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"

重新配置GitLab。
如果你正在使用Pages访问控制，请在GitLab Pages的System OAuth应用中更新重定向URI以使用HTTPS协议。

生成的URL方案为 https://<命名空间>.example.io/<项目标识>。

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

如果对重定向URI进行修改，GitLab Pages不会更新OAuth应用。在重新配置前，请从 /etc/gitlab/gitlab-secrets.json 中删除 gitlab_pages 部分，然后运行 gitlab-ctl reconfigure。更多信息，请阅读GitLab Pages不会重新生成OAuth。

支持TLS的单域名站点

先决条件：

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

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

按照先决条件所述，将您的 TLS 证书和密钥添加到 /etc/gitlab/ssl。

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

external_url "https://example.com" # 用您自己的 URL 替换此 URL
pages_external_url 'https://example.io' # 重要：不是 external_url 的子域，因此不能是 https://pages.example.com

pages_nginx['redirect_http_to_https'] = true

# 设置此标志以启用此功能
gitlab_pages['namespace_in_path'] = true

如果您的 TLS 证书和密钥与您的域名名称不匹配（例如 example.io.crt 和 example.io.key），请在 /etc/gitlab/gitlab.rb 中添加证书和密钥文件的完整路径：
```
pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
```
如果您使用 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 不会重新生成 OAuth。
重新配置 GitLab。

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

GitLab Pages 仅支持一种 URL 方案：通配符域名或单域名站点。如果您启用了 namespace_in_path，现有的 GitLab Pages 网站只能通过单域名站点访问。

带有 TLS 终止负载均衡器的通配符域名

先决条件：

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

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

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

pages_nginx['enable'] = true
pages_nginx['listen_port'] = 80
pages_nginx['listen_https'] = false
pages_nginx['redirect_http_to_https'] = true

重新配置 GitLab。

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

全局设置

以下是Linux包安装中Pages已知所有配置设置的表格及其作用。这些选项可以在 /etc/gitlab/gitlab.rb 中调整，并在你重新配置GitLab后生效。除非你需要更精细地控制Pages守护进程在你的环境中如何运行及提供服务，否则大多数设置无需手动配置。

设置	默认值	描述
`pages_external_url`	N/A	GitLab Pages可访问的URL，包含协议（HTTP/HTTPS）。若使用`https://`，需额外配置。详情请参阅支持通配符域名的TLS和支持自定义域名的TLS。
`gitlab_pages[]`	N/A
`access_control`	N/A	是否启用访问控制。
`api_secret_key`	自动生成	用于与GitLab API认证的秘密密钥文件完整路径。
`artifacts_server`	N/A	在GitLab Pages中启用查看工件。
`artifacts_server_timeout`	N/A	代理请求到工件服务器的超时时间（秒）。
`artifacts_server_url`	GitLab `external URL` + `/api/v4`	代理工件请求的API URL，例如`https://gitlab.com/api/v4`。运行独立的Pages服务器时，此URL必须指向主GitLab服务器的API。
`auth_redirect_uri`	项目子域名 + `/auth`（基于`pages_external_url`）	与GitLab认证的回调URL。URL应为`pages_external_url`子域名 + `/auth`，例如`https://projects.example.io/auth`。启用`namespace_in_path`时，默认为`pages_external_url` + `/projects/auth`，例如`https://example.io/projects/auth`。
`auth_secret`	从GitLab自动拉取	签名认证请求的秘密密钥。留空可在OAuth注册期间从GitLab自动拉取。
`client_cert`	N/A	与GitLab API进行双向TLS的客户端证书。详情请参阅调用GitLab API时支持双向TLS。
`client_key`	N/A	与GitLab API进行双向TLS的客户端密钥。详情请参阅调用GitLab API时支持双向TLS。
`client_ca_certs`	N/A	用于签署与GitLab API双向TLS客户端证书的根CA证书。详情请参阅调用GitLab API时支持双向TLS。
`dir`	N/A	配置和秘密文件的 working 目录。
`enable`	N/A	在当前系统中启用或禁用GitLab Pages。
`external_http`	N/A	配置Pages绑定到一个或多个辅助IP地址，提供HTTP请求服务。可按数组形式传入多个地址（含精确端口），例如`['1.2.3.4', '1.2.3.5:8063']`。设置`listen_http`的值。若在反向代理后运行GitLab Pages并终止TLS，则指定`listen_proxy`而非`external_http`。
`external_https`	N/A	配置Pages绑定到一个或多个辅助IP地址，提供HTTPS请求服务。可按数组形式传入多个地址（含精确端口），例如`['1.2.3.4', '1.2.3.5:8063']`。设置`listen_https`的值。

| enable | N/A | 在NGINX中包含一个用于Pages的虚拟主机server{}块。这是为了让NGINX将流量代理回Pages守护进程。如果Pages守护进程应该直接接收所有请求（例如使用自定义域名时），则设置为false。 | | FF_CONFIGURABLE_ROOT_DIR | N/A | 用于自定义默认文件夹的功能开关（默认启用）。 | | FF_ENABLE_PLACEHOLDERS | N/A | 用于重写的功能开关（默认启用）。更多信息请参见Rewrites。 | | rate_limit_source_ip | N/A | 每个源IP每秒的请求速率限制。设置为0可禁用此功能。 | | rate_limit_source_ip_burst | N/A | 每个源IP每秒允许的最大突发量。 | | rate_limit_domain | N/A | 每个域名的请求速率限制（每秒请求数）。设置为0可禁用此功能。 | | rate_limit_domain_burst | N/A | 每个域名每秒允许的最大突发量。 | | rate_limit_tls_source_ip | N/A | 每个源IP每秒的TLS连接数速率限制。设置为0可禁用此功能。 | | rate_limit_tls_source_ip_burst | N/A | 每个源IP每秒允许的最大TLS连接突发量。 | | rate_limit_tls_domain | N/A | 每个域名的TLS连接数速率限制（每秒连接数）。设置为0可禁用此功能。 | | rate_limit_tls_domain_burst | N/A | 每个域名每秒允许的最大TLS连接突发量。 | | rate_limit_subnets_allow_list | N/A | 应绕过所有速率限制的IP范围（子网）允许列表。例如，['1.2.3.4/24', '2001:db8::1/32']。引入于 GitLab 17.3。 | | server_read_timeout | 5s | 读取请求头和正文的最大时长。若不设置超时，请设为0或负值。 | | server_read_header_timeout | 1s | 读取请求头的最大时长。若不设置超时，请设为0或负值。 | | server_write_timeout | 0 | 写入响应中所有文件的最大时长。较大的文件需要更多时间。若不设置超时，请设为0或负值。 | | server_keep_alive | 15s | 此监听器接受的连接的Keep-Alive周期。若为0，当协议和操作系统支持时会启用Keep-Alive；若为负值，则禁用Keep-Alive。 |

高级配置

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

自定义域名

先决条件：

通配符 DNS 设置
辅助 IP

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

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

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 地址
gitlab_pages['custom_domain_mode'] = 'http' # 启用自定义域名

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

重新配置 GitLab。

生成的 URL 方案为 http://<命名空间>.example.io/<项目标识> 和 http://custom-domain.com。

支持 TLS 的自定义域名

先决条件：

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

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

将 *.example.io 的通配符 TLS 证书及其密钥放置在 /etc/gitlab/ssl 目录下。

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

external_url "https://example.com" # 此处的 external_url 仅作参考
pages_external_url 'https://example.io' # 重要提示：不是 external_url 的子域，因此不能是 https://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 地址
gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # GitLab Pages 守护进程的辅助 IP 地址
gitlab_pages['custom_domain_mode'] = 'https' # 启用自定义域名
# 将页面从 HTTP 重定向到 HTTPS
gitlab_pages['redirect_http'] = true

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

如果您的证书未命名为 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"
```
重新配置 GitLab。
如果您使用了 Pages 访问控制，请在 GitLab Pages 系统 OAuth 应用程序中更新重定向 URI 以使用 HTTPS 协议。

生成的 URL 方案为 https://<命名空间>.example.io/<项目标识> 和 https://custom-domain.com。

自定义域名验证

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

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

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

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

Let’s Encrypt集成

GitLab Pages的Let’s Encrypt集成允许用户为通过自定义域名提供的GitLab Pages站点添加Let’s Encrypt SSL证书。

要启用它：

选择一个用于接收域名过期通知的邮箱地址。
在左侧边栏底部，选择管理。
选择设置 > 首选项。
展开Pages。
输入接收通知的邮箱地址并接受Let’s Encrypt的服务条款。
选择保存更改。

访问控制

GitLab Pages的访问控制可按项目配置，允许基于用户对该项目的成员身份来控制对Pages站点的访问。

访问控制的工作原理是将Pages守护进程注册为GitLab的OAuth应用。每当未认证用户请求访问私有Pages站点时，Pages守护进程会将用户重定向到GitLab。如果认证成功，用户会带着令牌被重定向回Pages，该令牌会被保存在cookie中。cookie使用密钥签名，因此可以检测篡改行为。

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

Pages访问控制默认禁用。要启用它：

在 /etc/gitlab/gitlab.rb 中启用它：
```
gitlab_pages['access_control'] = true
```
重新配置GitLab。
用户现在可以在其项目设置中进行配置。

对于多节点设置，此设置需应用于所有App节点和Sidekiq节点才能生效。

使用减少认证范围的Pages

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

gitlab_pages['auth_scope'] = 'read_api'

用于认证的范围必须与GitLab Pages OAuth应用的设置匹配。现有应用的用户必须修改GitLab Pages OAuth应用。按照以下步骤操作：

启用访问控制。
在左侧边栏底部，选择管理。
选择应用。
展开GitLab Pages。
取消勾选api范围的复选框，并勾选所需范围（例如read_api）。
选择保存更改。

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

先决条件：

你必须有实例的管理员权限。
必须先启用访问控制，设置才会显示在管理区域。

你可以强制执行访问控制，使你GitLab实例上托管的全部GitLab Pages网站仅限认证用户访问。此设置会覆盖用户在单个项目中设置的访问控制。

这有助于限制Pages网站发布的信息仅能被你的实例用户访问。操作如下：

在左侧边栏底部，选择管理。
选择设置 > 首选项。
展开Pages。
勾选禁用Pages站点的公开访问复选框。
选择保存更改。

默认禁用唯一域名

先决条件：

你必须有实例的管理员权限。

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

你可以禁用此默认行为，使新的Pages站点改为使用路径型URL（例如my-namespace.example.com/my-project）。然而，这种方法有风险，即同一命名空间下的不同站点可能会共享cookie。

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

要默认禁用唯一域名：

在左侧边栏底部，选择管理。
选择设置 > 首选项。
展开Pages。
取消勾选默认启用唯一域名复选框。
选择保存更改。

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

在代理后运行

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

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

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

重新配置GitLab，使更改生效。

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

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

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

对于Linux包安装，可通过安装自定义CA 解决此问题。

对于自行编译的安装，可以通过将自定义证书颁发机构（CA）安装在系统证书存储中来修复此问题。

调用GitLab API时支持双向TLS

前提条件：

您的实例必须使用Linux包安装方式。

如果GitLab 被配置为要求双向TLS，则必须在GitLab Pages配置中添加客户端证书。

证书有以下要求：

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

证书的通用名称（Common Name）字段将被忽略。

要在GitLab Pages服务器上配置证书：

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

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

编辑 /etc/gitlab/gitlab.rb：

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

如果使用了自定义证书颁发机构（CA），则必须将根CA证书复制到 /etc/gitlab/ssl 并编辑 /etc/gitlab/gitlab.rb：
```
gitlab_pages['client_ca_certs'] = ['/etc/gitlab/ssl/ca.pem']
```
多个自定义证书颁发机构（CA）的文件路径用逗号分隔。
如果您有多个节点的GitLab Pages安装，请在所有节点重复这些步骤。
在所有GitLab节点上将完整证书链文件的副本保存到 /etc/gitlab/trusted-certs 目录中。

ZIP服务与缓存配置

这些说明涉及您的GitLab实例的一些高级设置。GitLab Pages内部已设置了推荐的默认值。只有在绝对必要时才应更改这些设置。请极端谨慎地使用。

GitLab Pages可以通过对象存储从ZIP归档中提供内容（也支持磁盘存储的问题正在解决中）。它使用内存缓存来提高从ZIP归档提供内容的性能。您可以通过修改以下配置标志来改变缓存行为。

设置	描述
`zip_cache_expiration`	ZIP归档的缓存过期时间间隔。必须大于零以避免提供过期的内容。默认值为 `60s`。
`zip_cache_cleanup`	已过期的归档从内存中清理的时间间隔。默认值为 `30s`。
`zip_cache_refresh`	归档在内存中被延长的访问时间间隔（如果在 `zip_cache_expiration` 前被访问）。这与 `zip_cache_expiration` 共同作用，确定归档是否在内存中延长。有关重要细节，请参见下文的示例。默认值为 `30s`。
`zip_open_timeout`	打开ZIP归档允许的最大时间。对于大归档或慢速网络连接，增加此时间可能会影响Pages服务的延迟。默认值为30秒。
`zip_http_client_timeout`	ZIP HTTP客户端的最大时间。默认值为 `30m`。

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）支持

可以通过 gitlab_pages[\'headers\'] 配置选项启用 HTTP 严格传输安全（HSTS）。HSTS 会告知浏览器，用户正在访问的网站应始终通过 HTTPS 提供其内容，以确保攻击者无法强制后续连接以未加密方式发生。它还可以提高页面加载速度，因为它可以防止浏览器在重定向到 HTTPS 之前尝试通过未加密的 HTTP 通道进行连接。

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

Pages 项目重定向限制

GitLab Pages 为 _redirects 文件提供了一套默认的限制，以最小化对性能的影响。如果您想增加或减少这些限制，可以进行配置。

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

使用环境变量

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

要禁用可配置目录功能：

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

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

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

默认情况下，守护进程仅使用 INFO 级别记录日志。如果希望让它以 DEBUG 级别记录事件，必须在 /etc/gitlab/gitlab.rb 中进行配置：
```
gitlab_pages['log_verbose'] = true
```
重新配置 GitLab。

传播关联 ID

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

要启用关联 ID 的传播：

在 /etc/gitlab/gitlab.rb 中将参数设置为 true：
```
gitlab_pages['propagate_correlation_id'] = true
```
重新配置 GitLab。

更改存储路径

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

Pages 默认存储在 /var/opt/gitlab/gitlab-rails/shared/pages。如果希望将其存储在其他位置，必须在 /etc/gitlab/gitlab.rb 中进行设置：
```
gitlab_rails['pages_path'] = "/mnt/storage/pages"
```
重新配置 GitLab。

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

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

默认情况下，监听器配置为在 localhost:8090 上监听请求。

如果希望禁用它，必须在 /etc/gitlab/gitlab.rb 中进行配置：
```
gitlab_pages['listen_proxy'] = nil
```
如果希望让它监听不同的端口，也必须在 /etc/gitlab/gitlab.rb 中进行配置：
```
gitlab_pages['listen_proxy'] = "localhost:10080"
```
重新配置 GitLab。

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

层级：Free, Premium, Ultimate
提供：GitLab Self-Managed

前提条件：

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

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

在左侧边栏底部，选择 Admin。
选择 设置 > 首选项。
展开 Pages。
在 页面最大大小 中输入一个值。默认值为 100。
选择 保存更改。

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

层级：Premium, Ultimate
提供：GitLab Self-Managed

前提条件：

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

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

在左侧边栏，选择 搜索或前往 并找到您的群组。
选择 设置 > 常规。
展开 Pages。
在 最大大小（MB） 下输入一个值。
选择 保存更改。

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

层级：Premium, Ultimate
提供：GitLab Self-Managed

前提条件：

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

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

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

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

前提条件：

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

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

在左侧边栏底部，选择 Admin。
选择 设置 > 首选项。
展开 Pages。
为 每个项目的自定义域名最大数量 输入一个值。使用 0 表示无限域名。
选择 保存更改。

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

前提条件：

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

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

在左侧边栏底部，选择 Admin。
选择 设置 > 首选项。
展开 Pages。
为 并行部署的默认过期时间（秒） 输入一个值。如果并行部署不应默认过期，请使用 0。
选择 保存更改。

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

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

您可以使用 GitLab Rails 控制台更新 GitLab Self-Managed 实例中的限制。

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

在独立服务器上运行 GitLab Pages

你可以在独立服务器上运行 GitLab Pages 守护进程，以降低主应用服务器的负载。此配置不支持相互 TLS（mTLS）。有关更多信息，请参阅对应的特性提案。

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

以下步骤包括备份和编辑 gitlab-secrets.json 文件的步骤。该文件包含控制数据库加密的秘密信息。请谨慎操作。

可选：若要启用访问控制，请在 /etc/gitlab/gitlab.rb 中添加以下内容，并重新配置 GitLab 服务器：
```
gitlab_pages['access_control'] = true
```
如果计划使用带访问控制的 GitLab Pages，必须在复制 gitlab-secrets.json 之前先在第一个 GitLab 服务器上启用它。启用访问控制会生成新的 OAuth 应用程序，相关信息会传播到 gitlab-secrets.json。如果顺序错误，可能会遇到访问控制问题。

在 GitLab 服务器 上备份密钥文件：

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

在 GitLab 服务器 上，若要启用 Pages，请在 /etc/gitlab/gitlab.rb 中添加以下内容：
```
pages_external_url "http://<pages_server_URL>"
```
通过以下方式设置对象存储：
- 配置对象存储并将 GitLab Pages 数据迁移至其中，或
- 配置网络存储。
重新配置 GitLab 服务器 以使更改生效。此时 gitlab-secrets.json 文件已更新为新配置。
设置新服务器。该服务器将成为 Pages 服务器。

在 Pages 服务器 上，通过 Linux 包安装 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>'

## 若在第 3 步启用了访问控制
gitlab_pages['access_control'] = true

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

在 Pages 服务器 上备份密钥文件：

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

若要为单个 GitLab Pages 站点启用自定义域名，可通过以下方式设置 Pages 服务器：
- 自定义域名
- 支持 TLS 的自定义域名

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

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

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

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

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

若要为单个 GitLab Pages 站点启用自定义域名，在 GitLab 服务器 上对 /etc/gitlab/gitlab.rb 进行以下修改：

自定义域名

   gitlab_pages['custom_domain_mode'] = 'http' # 启用 HTTP 模式的自定义域名

支持 TLS 的自定义域名

   gitlab_pages['custom_domain_mode'] = 'https' # 启用 HTTPS 模式的自定义域名

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

如果希望分发负载，可以在多个服务器上运行 GitLab Pages。可通过标准负载均衡实践实现，例如配置 DNS 服务器返回多个 Pages 服务器的 IP 地址，或在 IP 层面配置负载均衡器。如果希望在多个服务器上设置 GitLab Pages，请对每个 Pages 服务器执行上述过程。

域名源配置

当 GitLab Pages 守护进程响应页面请求时，它首先需要识别应使用哪个项目来服务所请求的 URL 以及其内容如何存储。

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

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

更多详情，请参阅此博客文章。

GitLab API 缓存配置

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

过期时间、间隔和超时标志使用 Go 持续时间格式。持续时间字符串是一个可能带符号的十进制数字序列，每个数字都有可选的小数部分和一个单位后缀，例如 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 会减少自动尝试解析域配置的次数，然后再报告错误。

对象存储设置

以下对象存储设置为：

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

设置	描述	默认值
`enabled`	是否启用对象存储。	`false`
`remote_directory`	存储 Pages 站点内容的桶名称。
`connection`	下面描述的各种连接选项。

如果您想停止使用并断开 NFS 服务器，则需要明确禁用本地存储。

S3 兼容连接设置

您应该使用合并的对象存储设置。

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

将 Pages 部署迁移到对象存储

现有的 Pages 部署对象（zip 归档文件）可以存储在以下位置：

本地存储
对象存储

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

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 部署的数量：

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部署移回本地存储：

sudo gitlab-rake gitlab:pages:deployments:migrate_to_local

禁用Pages本地存储

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

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['pages_local_store_enabled'] = false

重新配置GitLab 以使更改生效。

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

对象存储是大多数环境的优先配置。但是，如果你的需求需要网络存储，并且你想将Pages配置为运行在独立服务器上，你应该：

确保你打算使用的共享存储卷已在主服务器和你指定的Pages服务器上挂载并可用。

更新每个节点的 /etc/gitlab/gitlab.rb 以包含：

gitlab_pages['enable_disk'] = true
gitlab_rails['pages_path'] = "/var/opt/gitlab/gitlab-rails/shared/pages" # 你的网络存储路径

将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：设置每个托管页面域每秒的最大请求数阈值。设为 0 可禁用此功能。
rate_limit_domain_burst：设置每个托管页面域在初始突发请求期间允许的最大请求数阈值。

基于 TLS 连接的速率限制通过以下方式强制执行：

rate_limit_tls_source_ip：设置每个客户端 IP 每秒的最大 TLS 连接数阈值。设为 0 可禁用此功能。
rate_limit_tls_source_ip_burst：设置每个客户端 IP 在初始 TLS 连接突发期间允许的最大 TLS 连接数阈值。例如，当你同时从不同浏览器加载网页时。
rate_limit_tls_domain：设置每个托管页面域每秒的最大 TLS 连接数阈值。设为 0 可禁用此功能。
rate_limit_tls_domain_burst：设置每个托管页面域在初始 TLS 连接突发期间允许的最大 TLS 连接数阈值。

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

rate_limit_subnets_allow_list：设置允许列表，其中包含应绕过所有速率限制的 IP 范围（子网）。例如，['1.2.3.4/24', '2001:db8::1/32']。图表示例可供参考。

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

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

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

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

重新配置 GitLab。

按域名启用 HTTP 请求速率限制

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

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

重新配置 GitLab。

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

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

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

重新配置 GitLab。

按域名启用 TLS 连接速率限制

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

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

重新配置 GitLab。

GitLab Pages 管理

GitLab Pages 守护进程

前提条件

通配符域名

单域名站点

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

DNS 配置

单域名站点的 DNS 配置

自定义域名的 DNS 配置

配置

通配符域名

单域站点

支持TLS的通配符域名

支持TLS的单域名站点

带有 TLS 终止负载均衡器的通配符域名

全局设置

高级配置

自定义域名

支持 TLS 的自定义域名

自定义域名验证

Let’s Encrypt集成

访问控制

使用减少认证范围的Pages

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

默认禁用唯一域名

在代理后运行

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

调用GitLab API时支持双向TLS

ZIP服务与缓存配置

ZIP 缓存刷新示例

HTTP 严格传输安全（HSTS）支持

Pages 项目重定向限制

使用环境变量

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

传播关联 ID

更改存储路径

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

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

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

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

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

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

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

在独立服务器上运行 GitLab Pages

域名源配置

GitLab API 缓存配置

对象存储设置

S3 兼容连接设置

将 Pages 部署迁移到对象存储

将Pages部署回滚到本地存储

禁用Pages本地存储

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

ZIP存储

备份

安全

速率限制

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

按域名启用 HTTP 请求速率限制

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

按域名启用 TLS 连接速率限制

相关主题