• 设置自定义域名
  • 先决条件
  • 步骤
    • 1. 添加自定义域名
    • 2. 获取验证码
    • 3. 设置 DNS 记录
      • 根域名
      • 子域名
      • 根域名和子域名
    • 4. 验证域名的所有权
  • 添加更多域名别名
• 添加 SSL/TLS 证书到 Pages
  • 手动添加 SSL/TLS 证书
    • 步骤
• 强制 Pages 网站使用 HTTPS
• 编辑自定义域名
• 删除自定义域名
• 故障排除
  • 域名验证

极狐GitLab Pages 自定义域名

• 引入于 15.4 版本，您可以使用经过验证的域名绕过 SAML 或 SCIM 配置用户的用户电子邮件确认。

您可以使用自定义域名：

• 用于极狐GitLab Pages。
• 绕过 SAML 或 SCIM 配置用户的电子邮件确认。以这种方式使用自定义域名时，您可以使用极狐GitLab Pages 功能，但可以跳过先决条件。

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

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

设置自定义域名

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

先决条件

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

步骤

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

1. 添加自定义域名

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

1. 在左侧栏，点击 搜索或转到 并找到您的项目。
2. 选择 部署 > Pages。
3. 在右上角，点击 新的域名。
4. 在 域名 里，输入域名。
5. 可选。在 证书 里，关闭 使用 Let’s Encrypt自动管理证书 切换按钮并添加一个 SSL/TLS 证书，或将其留空（可以稍后添加）。
6. 点击 创建新域名。

2. 获取验证码

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

3. 设置 DNS 记录

请参阅本文档，查看 DNS 记录概述。 如果您熟悉该主题，请根据您希望在 Pages 网站上使用的域名类型按照以下说明进行操作：

• 根域名，example.com。
• 子域名，subdomain.example.com。
• 根域名和子域名。

您可以在私有化部署实例上 配置 IPv6 ， 但是在 GitLab.com 上的 Pages 还没有配置 IPv6。更多细节请查看这个议题 。

根域名

根域名（example.com）需要：

• 一条 DNS A 记录，将您的域名指向 Pages 服务器。
• 一条 TXT 记录，验证您的域名的所有权。

对于 JihuLab.com 上的项目, IP 是 35.185.44.232。对于其他极狐GitLab 实例上的项目，请联系您的系统管理员获取这个信息（您运行 Pages 的实例上使用哪个 IP 地址）。

子域名

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

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

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

根域名和子域名

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

需要：

• 域名的 DNS A 记录。
• 子域名的 DNS ALIAS/CNAME 记录。
• 域名和子域名都有一个 DNS TXT 记录。

如果您使用的是 Cloudflare，请选中使用 Cloudflare 将 www.domain.com 重定向到 domain.com。

注意：

• 如果您想将您的 domain.com 指向您的 Pages 站点，请不要使用 CNAME 记录。请改用 A 记录。
• 不要在默认 Pages 域名之后添加任何特殊字符。例如，不要将 subdomain.domain.com 指向 namespace.gitlab.io/。不过，一些域名托管服务提供商可能会要求一个尾随点（namespace.gitlab.io.）。

4. 验证域名的所有权

添加所有 DNS 记录后：

1. 在左侧栏，点击 搜索或转到 并找到您的项目；
2. 选择 部署 > Pages。
3. 在域名边上，点击 Edit（）。
4. 在 验证状态 里，点击 重试验证（）。

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

注意：

• 对于私有化部署实例，您的极狐GitLab 管理员可以选择禁用自定义域名验证。
• DNS 传播可能需要一些时间（最长 24 小时），虽然通常几分钟就可以完成。在此之前，验证失败，并且尝试访问您的域名会导致 404。
• 验证您的域名后，请保留验证记录。您的域名会定期重新验证，如果记录被删除，您的域名可能会被禁用。

添加更多域名别名

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

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

添加 SSL/TLS 证书到 Pages

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

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

手动添加 SSL/TLS 证书

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

• 一个可通过自定义域名访问的 Pages 网站。
• PEM证书：CA 生成的证书，需要添加到 证书（PEM） 字段。
• 中间证书：（又名根证书），它是标识 CA 的加密钥匙串的一部分。通常它与 PEM 证书结合使用，但在某些情况下您需要手动添加它们。
• 一个私钥，它是一个加密的密钥，可以根据您的域名验证您的 PEM。

步骤

• 要在添加新域名时添加证书：
  1. 在左侧栏，点击 搜索或转到 并找到您的项目。
  2. 在左侧栏，点击 部署 > Pages。
  3. 在右上角，点击 新域名。
  4. 在 域名 里，输入域名
  5. 在 证书 里，关闭 使用 Let’s Encrypt 自动管理证书 切换按钮来添加一个 SSL/TLS 证书
  6. 点击 创建新域名。
• 要将证书添加到之前添加的域名：
  1. 在左侧栏，点击 搜索或转到 并找到您的项目。
  2. 在左侧栏，点击 部署 > Pages。
  3. 在域名旁边，点击 编辑（）
  4. 在 证书 里，关闭 使用 Let’s Encrypt 自动管理证书 切换按钮来添加一个 SSL/TLS 证书
  5. 点击 保存更改。

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

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

强制 Pages 网站使用 HTTPS

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

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

要启用此设置：

1. 在左侧栏，点击 搜索或转到 并找到您的项目。
2. 在左侧栏，点击 部署 > Pages。
3. 勾选复选框 强制 HTTPS（需要有效证书）。
4. 点击 保存更改。

如果您在 Pages 前使用 Cloudflare CDN，请确保将 SSL 连接设置设置为 full 而不是 flexible。

编辑自定义域名

你可以通过编辑自定义域名来：

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

要编辑自定义域名：

1. 在左侧栏，点击 搜索或转到 并找到您的项目。
2. 在左侧栏，点击 部署 > Pages。
3. 在域名旁边，点击 编辑（）

删除自定义域名

自定义域名删除后，在极狐GitLab 里就不会再验证这个域名并且无法和极狐GitLab Pages 一起使用。

要删除或者移除一个自定义域名：

1. 在左侧栏，点击 搜索或转到 并找到您的项目。
2. 在左侧栏，点击 部署 > Pages。
3. 在域名旁边，点击 移除域名（）
4. 提示时，点击 移除域名。

故障排除

域名验证

要手动验证您是否已正确配置域名验证 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>"

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

对于根域名：

对于子域名：