GitLab Pages 自定义域名

您可以使用自定义域名：

• 与 GitLab Pages 配合使用。
• 为 SAML 或 SCIM 管理的用户绕过邮箱验证。 使用自定义域名时，您会使用 GitLab Pages 功能，但可以跳过 先决条件。

要使用一个或多个自定义域名：

• 添加 自定义 根域名 或 子域名。
• 添加 SSL/TLS 证书。

设置自定义域名

要使用自定义域名设置 Pages，请阅读以下要求和步骤。

先决条件

• 管理员已为 GitLab Pages 自定义域名 配置了服务器
• 一个正在运行的 GitLab Pages 网站，在默认 Pages 域名下提供服务 （对于 GitLab.com 是 *.gitlab.io）。
• 一个自定义域名 example.com 或子域名 subdomain.example.com。
• 能够访问您的域名服务器控制面板来设置 DNS 记录：
  • 一个 DNS 记录（A、AAAA、ALIAS 或 CNAME），将您的域名指向 GitLab Pages 服务器。如果 该名称上有多个 DNS 记录，您必须使用 ALIAS 记录。
  • 一个 DNS TXT 记录来验证您的域名所有权。

步骤

按照以下步骤将您的自定义域名添加到 Pages。另请参阅 本文档了解 DNS 记录概述。

1. 添加自定义域名

要将您的自定义域名添加到 GitLab Pages：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Deploy > Pages。
3. 在右上角，选择 New Domain。
4. 在 Domain 中，输入域名。
5. 可选。在 Certificate 中，关闭 Automatic certificate management using Let’s Encrypt 开关以添加 SSL/TLS 证书。您也可以稍后添加证书和密钥。
6. 选择 Create New Domain。

2. 获取验证码

将新域名添加到 Pages 后，系统会提示您验证码。从 GitLab 复制这些值，并在下一步中将它们粘贴到您的域名控制面板中作为 TXT 记录。

3. 设置 DNS 记录

阅读本文档了解 Pages 的 DNS 记录概述。 如果您熟悉此主题，请根据您要与 Pages 网站使用的域名类型， 按照以下说明操作：

• 对于根域名，example.com。
• 对于子域名，subdomain.example.com。
• 对于两者。

对于根域名

根域名（example.com）需要：

• 至少以下之一：
  • 一个 DNS A 记录，将您的域名指向 Pages 服务器。
  • 一个 DNS AAAA 记录，将您的域名指向 Pages 服务器。
• 一个 TXT 记录 来验证您的域名所有权。

对于 GitLab.com 上的项目，IPv4 地址是 35.185.44.232，IPv6 地址是 2600:1901:0:7b8a::。 对于在其他 GitLab 实例（CE 或 EE）中运行的项目，请联系 您的系统管理员询问此信息（您的实例上 Pages 服务器运行在哪个 IP 地址）。

对于子域名

子域名（subdomain.example.com）需要：

• 一个 DNS ALIAS 或 CNAME 记录，将您的子域名指向 Pages 服务器。
• 一个 DNS TXT 记录 来验证您的域名所有权。

无论是用户网站还是项目网站，DNS 记录 都应指向您的 Pages 域名（namespace.gitlab.io）， 不带任何路径。

对于根域名和子域名

在某些情况下，您需要将子域名和根域名都指向同一个网站， 例如 example.com 和 www.example.com。

它们需要：

• 一个域名的 DNS A 记录。
• 一个域名的 DNS AAAA 记录。
• 一个子域名的 DNS ALIAS/CNAME 记录。
• 每个域名的 DNS TXT 记录。

如果您使用 Cloudflare，请检查 使用 Cloudflare 将 www.domain.com 重定向到 domain.com。

此外：

• 不要使用 CNAME 记录来指向您的 domain.com 到您的 GitLab Pages 网站。请使用 A 记录。
• 不要在默认 Pages 域名后添加任何特殊字符。 例如，不要将 subdomain.domain.com 指向 或 namespace.gitlab.io/。不过，某些域名托管提供商可能要求使用尾随点（namespace.gitlab.io.）。
• GitLab.com 上的 GitLab Pages IP 在 2017 年发生了变化。
• GitLab.com 上的 GitLab Pages IP 在 2018 年从 52.167.214.135 变为 35.185.44.232。
• IPv6 支持在 2023 年添加 到了 GitLab.com。

4. 验证域名所有权

添加所有 DNS 记录后：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Deploy > Pages。
3. 在域名旁边，选择 Edit（ ）。
4. 在 Verification status 中，选择 Retry verification（ ）。

一旦您的域名激活，您的网站就可以通过您的域名访问。

此外：

• 域名验证对 GitLab.com 用户是必需的。 对于 GitLab Self-Managed，您的 GitLab 管理员可以选择 禁用自定义域名验证。
• DNS 传播可能需要一些时间（最多 24 小时）， 虽然通常几分钟就能完成。在此之前，验证 会失败，尝试访问您的域名会返回 404。
• 一旦您的域名被验证，请保留验证记录。 您的域名会定期重新验证，如果记录被删除， 可能会被禁用。

添加更多域名别名

您可以为同一项目添加多个别名（自定义域名和子域名）。 别名可以理解为通往同一房间的多个门。

您为网站设置的所有别名都列在 Setting > Pages 上。 从该页面，您可以查看、添加和删除它们。

使用 Cloudflare 将 www.domain.com 重定向到 domain.com

如果您使用 Cloudflare，您可以重定向 www 到 domain.com 而无需将 www.domain.com 和 domain.com 都添加到 GitLab。

为此，您可以使用 Cloudflare 与 CNAME 记录关联的页面规则 将 www.domain.com 重定向到 domain.com。您 可以使用以下设置：

1. 在 Cloudflare 中，创建至少一个：
   • 一个 DNS A 记录，将 domain.com 指向 35.185.44.232。
   • 一个 DNS AAAA 记录，将 domain.com 指向 2600:1901:0:7b8a::。
2. 在 GitLab 中，将域名添加到 GitLab Pages 并获取验证码。
3. 在 Cloudflare 中，创建一个 DNS TXT 记录来验证您的域名。
4. 在 GitLab 中，验证您的域名。
5. 在 Cloudflare 中，创建一个 DNS CNAME 记录，将 www 指向 domain.com。
6. 在 Cloudflare 中，添加一个页面规则，将 www.domain.com 指向 domain.com：
   • 转到您的域名仪表板，然后在顶部导航栏选择 Page Rules。
   • 选择 Create Page Rule。
   • 输入域名 www.domain.com 并选择 + Add a Setting。
   • 从下拉列表中选择 Forwarding URL，然后选择 状态代码 301 - Permanent Redirect。
   • 输入目标 URL https://domain.com。

向 Pages 添加 SSL/TLS 证书

阅读本文档了解 SSL/TLS 证书概述。

要使用 GitLab Pages 保护您的自定义域名，您可以选择：

• 使用 Let’s Encrypt 与 GitLab Pages 的集成， 它会自动获取和续订您的 Pages 域名的 SSL 证书。
• 通过以下步骤手动将 SSL/TLS 证书添加到 GitLab Pages 网站。

手动添加 SSL/TLS 证书

您可以使用任何满足以下要求的证书：

• 一个正在运行的 GitLab Pages 网站，可在自定义域名上访问。
• PEM 证书：这是由 CA 生成的证书， 需要添加到 Certificate (PEM) 字段中。
• 中间证书：（又称"根证书"），它是 加密密钥链的一部分，用于标识 CA。 通常它与 PEM 证书组合在一起，但在某些情况下， 您需要手动添加它们。 Cloudflare 证书 就是其中之一。
• 私钥，这是一个加密密钥，用于验证 您的 PEM 与您的域名。

例如，Cloudflare 证书 满足这些要求。

步骤

• 在添加新域名时添加证书：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 在左侧边栏，选择 Deploy > Pages。
  3. 在右上角，选择 New Domain。
  4. 在 Domain 中，输入域名。
  5. 在 Certificate 中，关闭 Automatic certificate management using Let’s Encrypt 开关以添加 SSL/TLS 证书。
  6. 选择 Create New Domain。

• 为之前添加的域名添加证书：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 在左侧边栏，选择 Deploy > Pages。
  3. 在域名旁边，选择 Edit（ ）。
  4. 在 Certificate 中，关闭 Automatic certificate management using Let’s Encrypt 开关以添加 SSL/TLS 证书。
  5. 选择 Save changes。

1. 将 PEM 证书添加到相应字段。
2. 如果您的证书缺少中间证书，请复制 并粘贴根证书（通常可以从您的 CA 网站获取） 并将其粘贴在 与您的 PEM 证书相同的字段中， 只在它们之间跳一行。
3. 复制您的私钥并将其粘贴到最后一个字段。

不要在 常规文本编辑器中打开证书或加密密钥。始终使用代码编辑器（如 Sublime Text、Dreamweaver、Brackets 等）。

强制 GitLab Pages 网站使用 HTTPS

为了使您的网站访问者更加安全，您可以选择 强制 GitLab Pages 使用 HTTPS。这样做后，所有通过 HTTP 访问您网站的尝试都会自动通过 301 重定向到 HTTPS。

它适用于 GitLab 默认域名和您的自定义域名 （只要您为它设置了有效证书）。

要启用此设置：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Deploy > Pages。
3. 选择 Force HTTPS (requires valid certificates) 复选框。
4. 选择 Save changes。

如果您在 GitLab Pages 前使用 Cloudflare CDN，请确保将 SSL 连接设置设置为 full 而不是 flexible。更多详细信息，请参阅 Cloudflare CDN 说明。

编辑自定义域名

您可以编辑自定义域名来：

• 查看自定义域名。
• 查看要添加的 DNS 记录。
• 查看 TXT 验证条目。
• 重试验证。
• 编辑证书设置。

要编辑自定义域名：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Deploy > Pages。
3. 在域名旁边，选择 Edit（ ）。

删除自定义域名

删除自定义域名后，该域名不再在 GitLab 中验证，也不能与 GitLab Pages 一起使用。

要删除和移除自定义域名：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Deploy > Pages。
3. 在域名旁边，选择 Remove domain（ )
4. 当提示时，选择 Remove domain。

故障排除

域名验证

要手动验证您是否正确配置了域名验证 TXT DNS 条目，您可以在终端中运行以下命令：

dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT

预期输出：

;; ANSWER SECTION:
_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>"

在某些情况下，添加与您尝试注册的域名相同的验证码可能会有所帮助。

对于根域名：

对于子域名：