China CloudFront SSL 插件

操作手册

• 第一步 - 方案部署
  

  1. 初始化部署
  

  通过 CloudFormation 服务部署模板，点击链接，随后将跳转至中国区 CloudFormation 控制台创建堆栈。点击右下角【下一步】操作。

  

  2. 输入部署参数信息
  

  为堆栈指定详细信息，请注意以下参数信息。
  

  • 堆栈名称：请为堆栈命名，例如 cloudfront-ssl-plugin-v2，堆栈名需要在当前帐户中的区域内唯一。
  • Access Key：指定 Access Key 作为您 API Gateway 的密钥。API Gateway 密钥可以保证有权限的用户才能通过 API Gateway 调用后端函数。

  

  信息确认完毕后点击，请点击下一步，进入第 3 步 “配置堆栈选项”。

  3. 确认部署信息
  

  在当前页面底部勾选最下方蓝色窗口内的 “我确认”，并点击右下角【下一步】进入第 4 步 “查看并创建”。
  

  

  请在当前页面确认您的部署信息，确认完毕后在页面底部点击右下角【提交】按钮进行提交。

  

  提交完毕后，将在该堆栈事件栏内看到堆栈内资源正在陆续创建。等待约 1 分钟，当堆栈状态转变为 CREATE_COMPLETE 即为创建完毕。

  4. 查看堆栈输出
  

  您可以在堆栈 “输出” 标签页中查看解决方案为您提供的快速链接：
  

  • CloudfrontConsole：访问 Amazon CloudFront 控制台，快速绑定已经颁发的证书
  • ManagementWebURL：访问证书管理前端页面，点开后可以看到无项目数据的前端页面和输入密钥的对话框。

  

  您可以通过点击资源标签页查看创建的资源，其中包含的 Lambda 函数资源的主要功能如下表所示。

  

  Lambda 函数与功能对应关系
  

  Lambda 函数名称	功能	Lambda 函数名称	功能
  AddEmail	输入邮件地添加指定项目的通知邮件地址	DeleteProject	删除证书颁发项目及关联子堆栈
  Authorizer	管理界面及 API 鉴权	Frontend	前端管理页面运行函数
  CheckCertState	根据项目名称查找 DynamoDB，获取最新证书颁发状态	GetCertByPath	根据证书路径获取路径下所有证书的关联信息
  CheckStackState	根据项目名称获取关联堆栈的状态	GetMailByProject	根据项目名称获取关联邮件地址
  DataProvider	获取首页数据，列出列表	Master	根据项目名称、邮件地址等信息创建证书颁发堆栈
  DeleteCert	输入证书名称并删除	TriggerCertbot	触发证书颁发函数，用于手动 renew 证书
  DeleteEmail	输入邮件地址删除指定项目的通知邮件	UpdateProject	更新项目信息，即证书颁发堆栈的相关信息

• 第二步 - 项目创建
  

  1. 进入证书管理页面
  

  在堆栈 “输出” 标签页，找到 ManagementWebURL，点击 URL 链接进入证书管理页面。

  

  输入密钥（即创建堆栈时在参数中指定的 Access Key）即可进入证书管理页面进行操作。

  

  2. 新建项目
  

  点击任意一个新建项目按钮

  

  在 “新建项目” 弹窗中，指定以下参数：
  

  • 项目名称：不能与项目列表中的其他项目同名
  • 域名(,分隔)：项目中涉及的所有域名（用,分隔），我们将为这组域名申请的 SSL 证书。
  • Email：用于接收证书颁发信息的 email，在新建项目阶段只能指定一个 email，后续可以添加更多 email。
  • SSL证书更新时间间隔(天, 1~89天，推荐30天)：指定一个整数作为 SSL证书更新时间间隔，默认值为 30。

  所有参数指定后，点击右下角【新建】开始创建项目。
  

  

  点击新建项目后，证书管理平台会在您的账号中创建一个专属于该项目的堆栈，堆栈中创建的资源包括用于颁发/更新 SSL 证书的 Lambda 函数、EventBridge 规则、用于发送证书颁发状态的 SNS 主题等。

  3. 及时订阅消息通知服务

  在项目创建过程中，您的邮箱中会收到一封来自 <no-reply@sns.amazonaws.com> 的邮件，邀请您订阅 SNS 主题。请您在等待堆栈部署过程请及时查看您的邮箱，并尽快点击订阅确认链接以便及时接收 SNS 消息通知，否则您可能会错过首次证书颁发的信息。

  

  订阅成功后的提示如下。

  

  4. 查看堆栈部署进度

  订阅完毕后，您可以返回证书管理页面，查看项目创建进度。您也可以在 CloudFormation 控制台中查看堆栈状态。当证书管理页面显示 “Succeeded”，或者 CloudFormation 控制台中的 <项目名称>-CertBot 堆栈状态为 CREATE_COMPLETE 时，表示项目创建成功。

  

  

  5. 检查证书颁发状态

  若您在第 3 步中及时订阅了消息通知服务，在项目创建成功后不久，您将会收到一封来自 <no-reply@sns.amazonaws.com> 的邮件。邮件中会显示证书颁发状态和 CloudFront 更新信息。若证书颁发成功，邮件中会显示证书名称和 ID。其中，证书名称由堆栈名称与 SSL 证书过期时间组成。例如：证书名称 WebApp-2025-04-28-1324，其对应的证书过期时间为 2025 年 4 月 28 日 13 点 24 分。

  

  证书颁发成功后，您可以根据证书名称/证书 ID 在 CloudFront 控制台中找到相应的证书。下一步，将CloudFront与成功颁发的 SSL 证书进行绑定。

  6. 在 Amazon CloudFront 控制台中绑定 SSL 证书

  打开 CloudFront 控制台，创建或选择您已有的分配，找到编辑备用域名与 SSL 证书的选项入口。

  

  请在设置菜单的备用域名处填入您申请SSL证书的域名，并在自定义 SSL 证书的下拉菜单中选择对应的 SSL 证书，随后将更改进行保存。

  

  部署完毕后，您可以通过备用域名从浏览器访问由 Amazon CloudFront 加速的站点，并查看由 Let’s Encrypt 颁发的 SSL 证书信息。

  

• 第三步 - 项目管理与证书管理

  1. 项目管理
  

  1.1 查看项目基本信息

  在证书管理页面，您会看到您拥有的所有项目及其相关信息。
  

  

  每一列的具体含义如下：
  

  • 域名：该项目涉及域名的集合，也是您申请 SSL 证书的域名。
  • 证书列表：当前域名的所有证书的基本信息，包含证书名称、证书 ID、更新时间（证书颁发时间）和过期时间

  

  • 证书颁发状态：点击可查看上一次的证书颁发状态记录。
  • 更新时间：该域名所拥有的的所有证书中最新的更新时间。
  • 更新时间：该域名所拥有的的所有证书中最新的过期时间。
  • S3 URI：存放该项目所有证书的 S3 目录。进入该目录可以看到以证书颁发时间命名的压缩文件。下载并解压该文件，会得到一个名为 tmp 的文件夹。

  

  访问到解压文件夹中的 /tmp/certbot/config/archive/ssl 路径，即可看到生成的 SSL 证书、证书私钥、证书链等文件。

  

  • 接收通知 Email 列表：已订阅消息通知服务的所有邮箱。

  

  • 堆栈状态：该项目的堆栈的状态，与 CloudFormation 控制台中显示的堆栈状态一致。每个项目对应一个堆栈，堆栈中有负责该项目证书颁发与更新的 Lambda 函数、EventBridge 规则、负责发送证书颁发状态的消息通知服务等。

  1.2 修改项目
  

  选中您想修改的项目，并点击右上角【修改项目】，即可对项目进行修改。

  

  每次修改项目后会重新颁发一次 SSL 证书。支持修改的参数有：
  

  • 域名：注意修改后的域名必须包含修改前的域名，否则修改后新颁发的 SSL 证书不会包含之前的域名，从而导致 SSL 证书与网站域名不匹配的问题。
  • SSL证书更新时间间隔

  

  更新记录成功结果如图所示：

  

  其数据结构意义如下：
  

  • Previous_IAM_SSL_Info： 上一次颁发的 SSL 证书信息。
  • Matched_CloudFront：通过上一次颁发的 SSL 证书信息，匹配到的 Amazon CloudFront 分配 ID。以下图为例，上一次颁发的证书已经绑定了一个 E 开头的 CloudFront 分配，因此 Matched_CloudFront 字段包含该 CloudFront 分配的 ID。
  • Update_CloudFront_Status：Amazon CloudFront 更新状态，请结合匹配的 Amazon CloudFront ID 信息进行比对。以下图为例，E 开头的 CloudFront 分配更新状态为 “Success”，说明该 CloudFront 分配的证书已经替换成了最新的证书。
  • Delete_Previous_IAM_SSL_Cert：若无匹配的 Amazon CloudFront 分配或 Amazon CloudFront 都已更新成功，将自动删除上一次颁发的 SSL 证书。以下图为例，由于新的证书成功颁发，且 Amazon CloudFront 分配成功更新，因此 Delete_Previous_IAM_SSL_Cert 字段中，旧的证书的状态为成功删除。

  1.3 删除项目
  

  删除项目前，需要检查项目中的证书是否已与 CloudFront 分配关联。若存在关联，要先解除关联。确保所有关联解除后，在证书列表中手动删除所有证书，否则将无法删除项目。

  

  项目中的证书删除完毕后，选中要删除的项目，点击右上角删除项目。

  

  输入项目名称后点击右下角【删除】。

  

  点击删除后，该项目的数据和堆栈也会被删除。

  

  正确删除后，您会在证书管理页面看到如下图所示的提示。
  

  

  2. 证书管理
  

  2.1 证书的自动更新

  本解决方案可在 SSL 证书过期前自动更新证书，并根据上一次证书生成的 ID 与证书名称，自动替换已关联在 Amazon CloudFront 的证书。
  注意：每个生成的免费证书有效期为 90 天，首次 SSL 证书生成后，会通过 Amazon Eventbridge 的规则在指定天数后（默认为 30 天）自动生成新证书，并发送一封 SSL 证书颁发成功及 Amazon CloudFront SSL 证书更新记录的通知邮件。
  
  订阅了 SNS 主题的邮箱会收到一封关于证书颁发状态和 CloudFront 更新信息的邮件。
  

  

  邮件中的证书颁发状态其各个字段的意义如下：
  

  • Previous_IAM_SSL_Info: 上一次颁发的 SSL 证书信息。
  • Matched_CloudFront: 通过上一次颁发的 SSL 证书信息，匹配到的 Amazon CloudFront 分配 ID。
  • Update_CloudFront_Status: Amazon CloudFront 更新状态，请结合匹配的 Amazon CloudFront ID 信息进行比对。
  • Delete_Previous_IAM_SSL_Cert: 若无匹配的 Amazon CloudFront 分配或 Amazon CloudFront 都已更新成功，将自动删除上一次颁发的 SSL 证书。

  请您仔细阅读该邮件，并注意以下事项：
  

  • 若证书更新成功，为了节省限额将会自动删除存储在 IAM SSL 存储中的证书，但不会删除 Amazon S3 桶中的备份证书。
  • 若证书颁发失败或 Amazon CloudFront SSL 证书更新失败，请及时手动替换，以免您网站访问中断。
  • 邮件中 CloudFront SSL Certificate Renew Records（CloudFront SSL 证书更新记录）即证书管理页面显示的包含 CloudFront 证书更新的信息 json 对象，其各个字段的意义见上文。

  若自动更新证书时遇到证书颁发失败的情况，请解决关联问题，并建议您按照2.2的操作步骤手动颁发证书。
  

  2.2 重新颁发证书

  在证书列表中，点击右上角【重新颁发】并在弹窗中点击【确认】
  

  

  

  点击确认后，证书管理页面会为您触发 Lambda 函数以进行证书颁发并将 CloudFront 上绑定的证书替换为新颁发的证书。您能在证书管理页面看到该 Lambda 函数的执行进度。

  

  当证书管理页面显示 “Succeeded” 时表示证书已成功颁发，下方的 json 对象记录了 CloudFront 证书更新的信息。

  

  其数据结构意义如下：
  

  • Previous_IAM_SSL_Info: 上一次颁发的 SSL 证书信息。
  • Matched_CloudFront: 通过上一次颁发的 SSL 证书信息，匹配到的 Amazon CloudFront 分配 ID。
  • Update_CloudFront_Status: Amazon CloudFront 更新状态，请结合匹配的 Amazon CloudFront ID 信息进行比对。
  • Delete_Previous_IAM_SSL_Cert: 若无匹配的 Amazon CloudFront 分配或 Amazon CloudFront 都已更新成功，将自动删除上一次颁发的 SSL 证书。

  同样，订阅了 SNS 主题的邮箱会收到一封关于证书颁发状态和 CloudFront 更新信息的邮件。
  

  2.3 删除证书

  在证书列表中，选中您想重新颁发的证书，点击右上角【删除证书】并在弹窗中输入证书名称后点击【删除】。
  

  

  

  注意，删除证书之前请确保没有 CloudFront 分配绑定了该证书，否则删除操作会报如下图所示的 500 错误，删除无法进行。

  

  3. 管理订阅 Email

  在创建项目时，您可以指定一个用于接收证书颁发、更新信息的 Email，后续您可以点击接收通知 Email 列表中的 “ x 个 Email 订阅” 管理订阅消息通知服务的 Email 地址。
  

  

  3.1 添加 Email

  点击 “ x 个 Email 订阅” 后会出现如下图所示的 “接收通知 Email 列表” 弹窗，点击【添加Email】。
  

  

  在方框中想要添加的 Email 地址，如 somebody@example.com，点击【添加】

  

  点击添加后，您会看到 Email 地址 somebody@example.com 的状态为 PendingConfirmation。

  

  稍后，在 somebody@example.com 邮箱中会收到一封来自 <no-reply@sns.amazonaws.com> 的邀请订阅邮件，点击 “Confirm subscription” 以确认订阅。

  

  订阅成功后可以看到如下图所示的页面。

  

  返回证书管理页面，点击右上角刷新按钮，我们可以看到此时订阅状态已变更为 “已确认”。

  

  3.2 重发确认邮件

  如果在确认订阅前，邀请订阅邮件被意外删除，您可以选中该 Email 地址，点击【重发确认邮件】。
  

  

  3.3 删除 Email

  选中要删除的 Email 地址，点击右上角【删除 Email】。
  

  

  在对话框中输入要删除的 Email 地址进行确认，然后点击右下角【删除】。

  

• 常见问题及排查
  

  常见问题

  • 可以为一个域名生成几个证书，是否有速率限制？
    根据 Let's Encrypt 文档，每个注册域名每周可签发 50 张证书，重复的域名每周可以签发 5 个证书。详情请查看文档：https://letsencrypt.org/zh-cn/docs/rate-limits/。
  • 可以在 IAM 中存放多少个 SSL 证书？
    根据亚马逊云科技文档，IAM 服务存在证书上限，每个账号默认不能上传超过20个 SSL 证书，该限额可以调整至1000个，请点击链接“Server certificates per account”提交 IAM 证书限额。
  • 如果无法访问证书管理界面怎么办？
    请确保您已经完成 ICP 备案流程。如果您在完成 ICP 备案前部署该方案，可能需要您重新部署该方案。

  证书颁发过程中问题排查

  在新建项目/重新颁发证书/证书自动更新操作中，后台都会为您发出证书颁发请求并更新 CloudFront 分配中所绑定的证书（取消 CloudFront 分配与旧证书的关联并绑上新的证书）。在此过程中可能会遇到以下常见错误。
  

  • 报错信息：“acme.messages.Error: urn:ietf:params:acme:error:rateLimited :: There were too many requests of a given type ::”

  若您在证书管理页面看到如下图所示的报错信息
  

  

  或者在邮件中看到类似的报错

  

  则表示您在短时间内已经为您的域名申请了 5 次证书（超过了 Let's Encrypt 对于重复的域名每周只能签发 5 个证书的限制），因此请求证书颁发失败。
  

  • 邮件中显示证书申请成功，但邮件或证书管理页面中的 CloudFront 更新记录的 Delete_Previous_IAM_SSL_Cert 字段出现 "Delete_IAM_Cert_Error: ..." 或 "Delete_SSL_Res_Error: ..." 信息

  出现此信息说明后端在 IAM Certificate 服务中删除旧证书时失败，失败原因见 "Delete_IAM_Cert_Error:" 或 "Delete_SSL_Res_Error:" 冒号后的具体内容。
  

  • 邮件中显示证书申请成功，但邮件或证书管理页面中的 CloudFront 更新记录的 Matched_CloudFront 字段出现 "Error"

  说明后端在寻找绑定旧证书的 CloudFront 分配过程中遇到错误，失败原因见 "Error" 字段的具体内容。
  

  • 邮件中显示证书申请成功，但邮件或证书管理页面中的 CloudFront 更新记录的 Update_CloudFront_Status 字段出现 "Failed"/"Update_Dist_Error"/"Get_Dist_Error"

  若 Update_CloudFront_Status 字段中，某个 CloudFront 分配 ID 后出现了非 “Success” 字符串的内容（比如 "Failed"/{"Update_Dist_Error": "..."}/{"Get_Dist_Error": "..."}），则表示后端在更新该分配的证书时出现错误。
  

  • 如果邮件中有上述为提及的错误信息该如何排查？
    您可以查看 Certbot Lambda Function 的运行日志。具体方法如下：

  1. 在堆栈的资源标签页中搜索 “Lambda::Function”，选中 CertBot 起始的 Function。
  

  

  2. 点击进入后，在页面下方监控标签页中，点击右侧【查看 CloudWatch Logs】

  

  3. 根据触发时间，在页面下方，日志流标签页中点击查看日志信息，以排查运行日志。

  

• 其他问题排查

  • 删除堆栈过程中出现错误提示？
    请您先清空对应 Amazon S3 桶中的内容，再进行堆栈删除

  

  • 证书已经颁发，没有收到证书颁发信息该怎么办？
    如果您是创建项目，可能会因为确认订阅的时机较晚而丢失通知信息。如果您未收到证书更新的信息，请确保您收到订阅邮件并点击订阅，您可以在堆栈的资源标签页中搜索 “SNS::Topic”，找到对应的通知服务，检查确认状态。

  

  

  • 如果已经确认订阅状态，依旧没有收到颁发 / 更新的邮件或者该怎么办？
    如果是颁发过程出现错误，您可以查看 Certbot Lambda Function 的运行日志。如果是因为未成功执行自动触发规则，请查看 Amazon EventBridge 监控。
  • 如何查看 Amazon EventBridge 监控？
    在堆栈的资源标签页中搜索 “Events::Rule”，选中 CertScheduledRule 起始的规则，点击进入，查看监控标签页，选择的时间段查看 Invocation 状态。

  

  

  • 您也可以通过“联系我们”来帮助您解决问题。

  参考文档
  

  •  https://letsencrypt.org/zh-cn/how-it-works/
  • https://letsencrypt.org/zh-cn/docs/challenge-types/
  • https://certbot.eff.org/pages/about
  • https://certbot-dns-route53.readthedocs.io/en/stable/
  • https://letsencrypt.org/zh-cn/docs/