如何在Heroku上安装SSL证书

本指南将向您展示如何在Heroku上安装SSL证书。它涵盖了Heroku目前终止TLS的两种方式：自动证书管理（ACM），它会为您自动配置和续订免费的Let’s Encrypt证书，以及通过控制面板或Heroku CLI手动上传第三方证书。

在开始之前，有几件事需要了解。Heroku的旧版SSL Endpoint附加组件（每月20美元的付费产品）已于2021年被弃用，无法再在新应用上配置。每个新的HTTPS部署都使用Heroku SSL，它依赖SNI（服务器名称指示）扩展，并且在每个付费dyno套餐中都免费提供。免费dyno已于2022年11月28日退役，因此您需要Eco、Basic、Standard或Performance套餐才能绑定自定义域名并提供HTTPS服务。

生成CSR（用于手动上传的证书）

如果您已经生成了CSR并从证书颁发机构收到了签发的证书，请直接跳到在Heroku上安装SSL证书。

只有在您购买需要手动上传的第三方证书时才需要CSR。如果您计划使用ACM，可以完全跳过本节：ACM会为您签发证书，无需提交CSR。

CSR（证书签名请求）是您在订购时提交给证书颁发机构的一段文本。它包含您的域名和组织信息，以及证书将据以签发的公钥。Heroku本身不在平台上生成CSR，因此您需要在平台外生成该请求。您有两个选择：

• 使用SSL Dragon的CSR生成器，通过简单的表单生成CSR和匹配的私钥。
• 按照我们的教程如何为Heroku生成CSR，使用OpenSSL在本地生成请求。

用任意文本编辑器打开生成的.csr文件，复制整个内容块，包括—–BEGIN CERTIFICATE REQUEST—–和—–END CERTIFICATE REQUEST—–标记，然后在SSL Dragon订购过程中粘贴。等待CA验证并签发证书（DV证书可能只需几分钟，OV/EV证书可能需要几个工作日），然后按照下方内容继续安装。

在Heroku上安装SSL证书

Heroku提供了两种实现HTTPS的方式。请根据您获取证书的方式选择相应的方式：

• ACM（推荐大多数应用使用）。Heroku会为应用上的每个自定义域名签发、安装并自动续订免费的Let’s Encrypt证书。无需上传任何文件，也无需记录续订日期。适用于Eco、Basic、Standard和Performance dyno。
• 手动上传。当您需要特定的第三方证书时（例如组织验证或扩展验证产品，或非Let’s Encrypt颁发机构的通配符证书）使用此方式。您需要通过控制面板或CLI自行上传证书和私钥。

步骤1. 将自定义域名添加到应用

在您的自定义域名注册到应用之前，Heroku不会配置任何证书（ACM或手动方式）。在提升权限的终端中运行：

heroku domains:add www.example.com -a your-app-name

将www.example.com替换为您的域名，将your-app-name替换为您的Heroku应用名称。如果还有其他主机名（例如裸根域名或第二个子域名），请重复此命令。您也可以在控制面板的Settings > Domains and certificates > Add domain中添加域名。

您添加的每个域名都会返回一个唯一的DNS目标，例如quiet-fire-1234.herokudns.com。在步骤3更新DNS时，您需要用到这个值。

步骤2. 配置证书

选项A：ACM（免费，自动续订的Let’s Encrypt）

从CLI为该应用启用ACM：

heroku certs:auto:enable -a your-app-name

Heroku将开始为应用上的每个自定义域名签发Let’s Encrypt证书。要查看进度并确认状态，运行：

heroku certs:auto -a your-app-name

您也可以在控制面板中启用ACM：打开应用，前往Settings > Domains and certificates，点击Configure SSL，选择Automated Certificate Management，然后点击Continue。一旦DNS配置到位（步骤3），ACM将完成域名验证，证书随即生效。证书将在到期前大约一个月自动续订。

选项B：手动上传第三方证书

CA会通过邮件发送三个文件：

• 终端实体证书，通常带有.crt扩展名（PEM格式）。
• CA证书包（中间证书），通常带有.ca-bundle扩展名。
• 与CSR一起生成的私钥（.key文件）。

Heroku要求提供一个包含终端实体证书及后续中间证书（完整证书链）的单个PEM文件。在Linux或macOS上，使用cat将其合并：

cat yourcertificate.crt bundle.ca-bundle > server.crt

在Windows上，用纯文本编辑器（Notepad++或VS Code，不要用Word）打开这两个文件，将.ca-bundle的内容粘贴到.crt内容的下方，按此顺序排列，块之间不要留空行。将合并后的文件保存为server.crt。

使用Heroku CLI上传完整证书链和私钥：

heroku certs:add server.crt server.key -a your-app-name

如果您要替换应用上现有的证书（例如在续订期间），请改用certs:update，这样Heroku会保留相同的DNS目标：

heroku certs:update server.crt server.key -a your-app-name

更喜欢使用控制面板？打开应用，前往Settings > Domains and certificates，点击Configure SSL，选择Manually，然后将合并后的server.crt拖到证书槽位，将.key文件拖到私钥槽位。点击Next并确认。

如果上传时出现Internal server error，很可能是您本地的Heroku CLI版本过旧。使用heroku update更新，然后重试。此外，Heroku要求使用RSA密钥；目前手动上传不支持ECDSA密钥。

步骤3. 将DNS指向Heroku DNS目标

无论采用哪种配置方式，只有当自定义域名的DNS解析指向Heroku后，证书才会生效。列出您的域名并复制Heroku返回的DNS目标：

heroku domains -a your-app-name

您会在每个域名旁看到类似quiet-fire-1234.herokudns.com的值。在您的DNS提供商处，为每个域名创建一条记录：

• 子域名（例如www.example.com）：创建一条CNAME记录指向Heroku DNS目标。
• 顶点/根域名（例如example.com）：根据DNS规范，顶点上不允许使用CNAME，因此请使用ALIAS、ANAME或扁平化CNAME记录（具体名称取决于您的DNS提供商）指向同一个Heroku DNS目标。如果您的DNS提供商不支持以上任何一种，请将DNS托管到支持的提供商（如Cloudflare、DNSimple、Route 53、NS1、easyDNS等）。

不要将DNS指向your-app-name.herokuapp.com或任何*.herokussl.com主机名：ACM无法通过这些进行证书验证，手动绑定也无法正确路由。请始终使用Heroku为每个域名分配的专用DNS目标。

DNS更改可能需要几分钟到几小时才能生效。一旦Heroku检测到更新的记录，ACM会自动完成验证（或者您的手动证书会开始提供服务）。

步骤4. 验证证书是否已生效

从CLI确认安装情况：

heroku certs:info -a your-app-name

输出结果会列出证书、签发的CA、到期日期以及涵盖的域名。然后在浏览器中通过https://打开您的网站，检查是否显示锁形图标，并使用我们的SSL检测工具进行更深入的外部扫描，以确认证书链是否完整以及协议是否配置正确。

常见问题