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

GitLab Pages Let’s Encrypt 证书

  • Tier: 免费版、高级版、旗舰版
  • Offering: GitLab.com、GitLab 自托管

GitLab Pages 与 Let’s Encrypt (LE) 的集成允许你 为使用自定义域名的 Pages 网站使用 LE 证书， 无需自己手动签发和更新； GitLab 会为你自动完成这一切。

Let’s Encrypt 是一个免费的、自动化的、 开源的证书颁发机构。

此功能仅涵盖 自定义域名 的证书，不包括运行 Pages daemon 所需的通配符证书（仅限 GitLab 自托管、免费版、高级版和旗舰版）。通配符 证书签发进度可在 此问题 中跟踪。

前提条件

在为你的域名启用 SSL 证书自动签发之前，请确保你已：

  • 在 GitLab 中创建了一个包含网站源代码的 项目。
  • 获取了一个域名（example.com）并添加了指向你的 Pages 网站的 DNS 记录。 顶级域名（.com）必须是 公共后缀。
  • 将你的域名添加到 Pages 项目中 并验证了你的所有权。
  • 验证了你的网站已正常运行，可以通过你的自定义域名访问。

GitLab 与 Let’s Encrypt 的集成已在 GitLab.com 上启用并可用。 对于 GitLab 自托管 实例，请确保你的管理员已 启用它。

为你的自定义域名启用 Let’s Encrypt 集成

满足要求后，启用 Let’s Encrypt 集成：

  1. 在左侧边栏，选择 搜索或跳转至 并找到你的项目。

  2. 选择 部署 > Pages。

  3. 在域名旁边，选择 编辑（ pencil ）。

  4. 打开 使用 Let’s Encrypt 自动管理证书 开关。

    启用 Let’s Encrypt

  5. 选择 保存更改。

启用后，GitLab 会获取 LE 证书并将其添加到 关联的 Pages 域名。GitLab 还会自动续订该证书。

签发证书和更新 Pages 配置 可能需要长达一小时。 如果你在域名设置中已有 SSL 证书， 它将继续工作，直到被 Let’s Encrypt 证书替换。

故障排除

获取 Let’s Encrypt 证书时出错

如果你收到 获取 Let’s Encrypt 证书时出错 的错误，首先，请确保你的 Pages 网站在项目的 设置 > 常规 > 可见性 中设置为 “所有人”。这允许 Let’s Encrypt 服务器访问你的 Pages 网站。确认这一点后，你可以按照以下步骤尝试重新获取证书：

  1. 在左侧边栏，选择 搜索或跳转至 并找到你的项目。
  2. 选择 部署 > Pages。
  3. 在域名旁边，选择 编辑（ pencil ）。
  4. 在 验证状态 中，选择 重试验证（ retry ）。
  5. 如果你仍然收到相同的错误：
    1. 确保你的域名只正确设置了一个 CNAME 或 A DNS 记录。
    2. 确保你的域名 没有 AAAA DNS 记录。
    3. 如果你的域名或任何更高级别的域名有 CAA DNS 记录，请确保 它包含 letsencrypt.org。
    4. 确保 你的域名已验证。
    5. 返回步骤 1。

获取证书耗时超过一小时

如果你已启用 Let’s Encrypt 集成，但一小时后仍未获得证书，并且看到以下消息：

GitLab 正在为此域名获取 Let's Encrypt SSL 证书。
此过程可能需要一些时间。请稍后再试。

请按照以下步骤重新移除并添加 GitLab Pages 的域名：

  1. 在左侧边栏，选择 搜索或跳转至 并找到你的项目。
  2. 选择 部署 > Pages。
  3. 在域名旁边，选择 移除。
  4. 再次添加域名并验证它。
  5. 为你的域名启用 Let’s Encrypt 集成。
  6. 如果你仍然收到相同的错误：
    1. 确保你的域名只正确设置了一个 CNAME 或 A DNS 记录。
    2. 确保你的域名 没有 AAAA DNS 记录。
    3. 如果你的域名或任何更高级别的域名有 CAA DNS 记录，请确保 它包含 letsencrypt.org。
    4. 返回步骤 1。