配置 TLS

关于传输层安全

当 GitHub Enterprise Server 首次启动时，会启用 TLS（替代了 SSL）并通过自签名证书进行配置。 由于自签名证书不受 Web 浏览器和 Git 客户端的信任，因此这些客户端将报告证书警告，直至您禁用 TLS 或上传由 Let's Encrypt 等可信颁发机构签名的证书。

GitHub Enterprise Server 设备将在 SSL 启用时发送 HTTP 严格传输安全标头。 禁用 TLS 会导致用户无法访问设备，因为用户的浏览器将不允许协议降级为 HTTP。 有关详细信息，请参阅维基百科上的“HTTP 严格传输安全 (HSTS)”。

若要允许用户使用 FIDO U2F 进行双因素身份验证或使用 GitHub Actions 部署 GitHub Pages 站点，必须为实例启用 TLS。 有关详细信息，请参阅“配置双重身份验证”。

先决条件

要在生产中使用 TLS，您必须具有由可信证书颁发机构签名的未加密 PEM 格式的证书。 若要使用由内部证书颁发机构签名的证书，必须安装根证书和任何中间证书。 有关详细信息，请参阅“排查 TLS 错误”。

证书还需要为“启用子域隔离”中列出的子域配置使用者可选名称，如果证书已由中间证书颁发机构签名，将需要包含完整的证书链。 有关详细信息，请参阅维基百科上的“使用者可选名称”。

可使用 ghe-ssl-generate-csr 命令为实例生成证书签名请求 (CSR)。 有关详细信息，请参阅“命令行实用程序”。

密钥必须是 RSA 密钥，并且不能有密码。 有关详细信息，请参阅“排查 TLS 错误”。

上传自定义 TLS 证书

1. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击 。

2. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

3. 在“ 站点管理”边栏中，单击“管理控制台”。

4. 在“设置”边栏中，按下“隐私”并取消选中“隐私模式”。

5. 选择“仅限 TLS”（推荐）。

6. 在“TLS Protocol support”下，选择您想要允许的协议。

7. 在“证书”下，单击“选择文件”，然后选择要安装的 TLS 证书或证书链（PEM 格式）。 此文件通常采用 .pem、.crt 或 .cer 扩展名 。

8. 在“未加密密钥”下，单击“选择文件”，然后选择要安装的 RSA 密钥（PEM 格式）。 此文件通常采用 .key 扩展名。

9. 在“设置”边栏下，单击“保存设置”。

   Note

   保存 管理控制台 中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。

10. 等待配置运行完毕。

关于 Let's Encrypt 支持

Let's Encrypt 是公共证书颁发机构，他们使用 ACME 协议颁发受浏览器信任的免费、自动化 TLS 证书。 您可以在设备上自动获取并续订 Let's Encrypt 证书，无需手动维护。

要使用“让我们加密”自动化，您的设备必须配置可通过 HTTP 公开访问的主机名。 该设备还必须可以进行出站 HTTPS 连接。

在使用 Let's Encrypt 启用 TLS 证书管理自动化后，你的 GitHub Enterprise Server 实例 将与 Let's Encrypt 服务器通信，以获取证书。 要续订证书，Let's Encrypt 服务器必须通过入站 HTTP 请求验证已配置域名的控制。

还可以在 你的 GitHub Enterprise Server 实例 上使用 ghe-ssl-acme 命令行实用程序自动生成 Let's Encrypt 证书。 有关详细信息，请参阅“命令行实用程序”。

使用 Let's Encrypt 配置 TLS

要使用“让我们加密”自动化，您的设备必须配置可通过 HTTP 公开访问的主机名。 该设备还必须可以进行出站 HTTPS 连接。

1. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击 。

2. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

3. 在“ 站点管理”边栏中，单击“管理控制台”。

4. 在“设置”边栏中，按下“隐私”并取消选中“隐私模式”。

5. 选择“仅限 TLS”（推荐）。

6. 选择“使用 Let's Encrypt 启用 TLS 证书管理自动化”。

7. 在“设置”边栏下，单击“保存设置”。

   Note

   保存 管理控制台 中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。

8. 等待配置运行完毕。

9. 在“设置”边栏中，按下“隐私”并取消选中“隐私模式”。

10. 单击“请求 TLS 证书”。

11. 等待“状态”从“开始”更改为“完成”。

    

12. 单击“保存配置”。

Let's Encrypt 的 TLS 故障排除

可以对 Let's Encrypt 的 TLS 证书问题进行故障排除。

错误：“安全错误阻止加载资源”

在某些情况下，最终用户可能会报告 你的 GitHub Enterprise Server 实例 上的服务页面会在浏览器的开发人员工具中返回以下错误。

Security error prevented the resource from being loaded

若要解决这些错误，必须重新颁发证书来更新 Let's Encrypt 证书中的“使用者可选名称”(SAN)。 更换实例的证书需要停机。

1. 向用户传达停机时间，并考虑启用维护模式。 有关详细信息，请参阅以下文章。

   • “自定义企业的用户消息”
   • “启用和排定维护模式” 1. 通过 SSH 连接到 你的 GitHub Enterprise Server 实例。 如果实例包含多个节点，例如，如果配置了高可用性或异地复制，则通过 SSH 连接到主节点。 如果使用群集，则可以通过 SSH 连接到任何节点。 将 HOSTNAME 替换为实例的主机名，或节点的主机名或 IP 地址。 有关详细信息，请参阅“访问管理 shell (SSH)”。
   Shell

   ssh -p 122 admin@HOSTNAME
   

2. 若要禁用 Let's Encrypt，请运行以下命令。

   Shell

   ghe-ssl-acme -d
   

3. 若要清除 Let's Encrypt 的现有设置，请运行以下命令。

   Shell

   ghe-ssl-acme -x
   

4. 若要从 Let's Encrypt 请求新证书并进行安装，请运行以下命令。

   Shell

   ghe-ssl-acme -e
   

5. 若要应用配置，请运行以下命令。

   Note

   在配置运行过程中，你的 GitHub Enterprise Server 实例 上的服务可能会重启，这可能会导致用户短暂停机。

   Shell

   ghe-config-apply
   

6. 等待配置运行完毕。

7. 如果配置了用户消息或维护模式，请删除该消息并禁用维护模式。