fix(certd-server): 修复 AWS 中国区 CloudFront 证书部署问题 (#764) @yw-mao

- 修复证书链拆分，保留 END CERTIFICATE 结尾标记，避免 MalformedCertificate - 更新 CloudFront 时构造干净的 IAM ViewerCertificate，强制 sni-only，解决 InvalidViewerCertificate 及中国区不支持 vip 的报错 - 部署完成后清理被替换掉的旧 IAM 证书，避免续期堆积 - IAM/CloudFront 权限不足时抛出可读中文提示，便于运维排查 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 21:17:42 +08:00 · 2026-07-07 16:20:07 +08:00
parent 2a606fdb1d
commit c0be4d702c
2 changed files with 234 additions and 26 deletions
@@ -1,21 +1,107 @@
 // 导入所需的 SDK 模块
 import { AwsCNAccess } from "../access.js";
 import { CertInfo } from "@certd/plugin-cert";
+import { ILogger } from "@certd/basic";

-type AwsIAMClientOptions = { access: AwsCNAccess; region: string };
+type AwsIAMClientOptions = { access: AwsCNAccess; region: string; logger?: ILogger };
+
+// IAM ListServerCertificates 返回的证书元信息（仅保留本插件用到的字段）
+export type ServerCertificateMetadata = {
+  ServerCertificateName?: string;
+  ServerCertificateId?: string;
+  Expiration?: Date | string;
+};
+
+/**
+ * 拆分完整 PEM，得到叶子证书和证书链。
+ * 使用 lookbehind 分割，保留每段结尾的 -----END CERTIFICATE-----，
+ * 避免证书链丢失结尾标记而变成非法 PEM（AWS 会报 MalformedCertificate）。
+ */
+export function splitCertAndChain(crt: string): { cert: string; chain: string } {
+  const pemBlocks = crt.split(/(?<=-----END CERTIFICATE-----)/);
+  const cert = pemBlocks[0].trim();
+  const chain = pemBlocks.slice(1).join("").trim();
+  return { cert, chain };
+}
+
+/**
+ * 从 IAM 证书元信息列表中，挑出"本次被替换掉"的旧证书名称。
+ * distribution 已改用新证书，旧证书不再被其引用，因此无论是否过期都应清理，
+ * 否则提前续期/手动重部署产生的旧证书会在 IAM 中不断堆积。
+ * 过滤规则：
+ * - ServerCertificateId 必须命中 targetCertIds（即本次部署前 CloudFront 引用的旧证书）
+ * - 不能等于 excludeCertId（本次新上传的证书，避免误删）
+ * 返回去重后的 ServerCertificateName 列表。
+ */
+export function pickReplacedCertNames(params: { metadataList: ServerCertificateMetadata[]; targetCertIds: Set<string> | string[]; excludeCertId?: string }): string[] {
+  const { metadataList, targetCertIds, excludeCertId } = params;
+  const targetIdSet = targetCertIds instanceof Set ? targetCertIds : new Set(targetCertIds);
+
+  const names = new Set<string>();
+  for (const metadata of metadataList) {
+    const certId = metadata.ServerCertificateId;
+    const certName = metadata.ServerCertificateName;
+    if (!certId || !certName) {
+      continue;
+    }
+    if (!targetIdSet.has(certId)) {
+      continue;
+    }
+    if (excludeCertId && certId === excludeCertId) {
+      continue;
+    }
+    names.add(certName);
+  }
+  return [...names];
+}
+
+// CloudFront ViewerCertificate 字段（仅保留本插件用到的字段）
+export type ViewerCertificate = {
+  CloudFrontDefaultCertificate?: boolean;
+  ACMCertificateArn?: string;
+  IAMCertificateId?: string;
+  Certificate?: string;
+  CertificateSource?: string;
+  SSLSupportMethod?: string;
+  MinimumProtocolVersion?: string;
+};
+
+/**
+ * 基于旧 ViewerCertificate 构造使用 IAM 证书的新配置。
+ * - CloudFront 要求 ACMCertificateArn、IAMCertificateId、CloudFrontDefaultCertificate 三者只能存在其一，
+ *   因此这里只保留 IAM 证书，并显式将 CloudFrontDefaultCertificate 置为 false、不携带 ACMCertificateArn。
+ * - Certificate/CertificateSource 为 AWS 已废弃字段，更新时不再携带，避免旧的 ACM 值残留导致校验冲突。
+ * - SSLSupportMethod 强制为 sni-only：AWS 中国区 CloudFront 只支持 SNI，不支持 vip（专用IP），
+ *   若沿用旧的 vip 值会报 "The parameter ViewerCertificate with the specified SSL support method isn't available in this region"。
+ * - MinimumProtocolVersion 沿用旧值，缺失时给出安全默认值。
+ */
+export function buildIamViewerCertificate(params: { oldViewerCertificate?: ViewerCertificate; certId: string }): ViewerCertificate {
+  const { oldViewerCertificate, certId } = params;
+  const old = oldViewerCertificate || {};
+  return {
+    CloudFrontDefaultCertificate: false,
+    IAMCertificateId: certId,
+    SSLSupportMethod: "sni-only",
+    MinimumProtocolVersion: old.MinimumProtocolVersion || "TLSv1.2_2021",
+  };
+}

 export class AwsIAMClient {
  options: AwsIAMClientOptions;
  access: AwsCNAccess;
  region: string;
+  logger?: ILogger;
  constructor(options: AwsIAMClientOptions) {
    this.options = options;
    this.access = options.access;
    this.region = options.region;
+    this.logger = options.logger;
  }
-  async importCertificate(certInfo: CertInfo, certName: string) {
-    // 创建 IAM 客户端
-    const { IAMClient, UploadServerCertificateCommand } = await this.access.importRuntime("@aws-sdk/client-iam");
+
+  // 统一创建 IAM 客户端，供上传/查询/删除复用
+  private async createIamClient() {
+    const iamModule = await this.access.importRuntime("@aws-sdk/client-iam");
+    const { IAMClient } = iamModule;
    const iamClient = new IAMClient({
      region: this.region, // 替换为您的 AWS 区域
      credentials: {
@@ -23,20 +109,99 @@ export class AwsIAMClient {
        secretAccessKey: this.access.secretAccessKey,
      },
    });
+    return { iamClient, iamModule };
+  }

-    const cert = certInfo.crt.split("-----END CERTIFICATE-----")[0] + "-----END CERTIFICATE-----";
-    const chain = certInfo.crt.split("-----END CERTIFICATE-----\n")[1];
+  async importCertificate(certInfo: CertInfo, certName: string) {
+    const { iamClient, iamModule } = await this.createIamClient();
+    const { UploadServerCertificateCommand } = iamModule;
+
+    const { cert, chain } = splitCertAndChain(certInfo.crt);
    // 构建上传参数
    const command = new UploadServerCertificateCommand({
      Path: "/cloudfront/",
      ServerCertificateName: certName,
      CertificateBody: cert,
      PrivateKey: certInfo.key,
-      CertificateChain: chain,
+      CertificateChain: chain || undefined,
    });
-    const data = await iamClient.send(command);
-    console.log("Upload successful:", data);
-    // 返回证书 ID
-    return data.ServerCertificateMetadata.ServerCertificateId;
+
+    try {
+      const data = await iamClient.send(command);
+      // 返回证书 ID
+      return data.ServerCertificateMetadata.ServerCertificateId;
+    } catch (err) {
+      const message = err.message || String(err);
+      const requestId = err.$metadata?.requestId || err.requestId;
+      console.error(`IAM 调用失败: ${message}, requestId: ${requestId}`);
+      throw err;
+    }
+  }
+
+  // 拉取 /cloudfront/ path 下的全部 server certificate 元信息（处理分页）
+  async listCloudFrontServerCertificates(): Promise<ServerCertificateMetadata[]> {
+    const { iamClient, iamModule } = await this.createIamClient();
+    const { ListServerCertificatesCommand } = iamModule;
+
+    const metadataList: ServerCertificateMetadata[] = [];
+    let marker: string | undefined = undefined;
+    do {
+      const command = new ListServerCertificatesCommand({
+        PathPrefix: "/cloudfront/",
+        Marker: marker,
+      });
+      const data: any = await iamClient.send(command);
+      const pageList: ServerCertificateMetadata[] = data.ServerCertificateMetadataList || [];
+      metadataList.push(...pageList);
+      marker = data.IsTruncated ? data.Marker : undefined;
+    } while (marker);
+
+    return metadataList;
+  }
+
+  // 按名称删除 IAM server certificate
+  async deleteServerCertificate(serverCertificateName: string) {
+    const { iamClient, iamModule } = await this.createIamClient();
+    const { DeleteServerCertificateCommand } = iamModule;
+    const command = new DeleteServerCertificateCommand({
+      ServerCertificateName: serverCertificateName,
+    });
+    await iamClient.send(command);
+  }
+
+  /**
+   * 清理本次被替换掉的旧证书（无论是否过期）。
+   * distribution 已改用新证书，旧证书不再被其引用，直接删除以避免 IAM 堆积。
+   * 必须在更新完 CloudFront 引用之后调用，否则旧证书仍被引用会报 DeleteConflict。
+   * 删除失败（如仍被其他分配引用）时只告警，不阻断部署流程。
+   */
+  async deleteReplacedCerts(params: { oldCertIds: Set<string> | string[]; newCertId?: string }) {
+    const { oldCertIds, newCertId } = params;
+    const targetIdSet = oldCertIds instanceof Set ? oldCertIds : new Set(oldCertIds);
+    if (targetIdSet.size === 0) {
+      return;
+    }
+
+    const metadataList = await this.listCloudFrontServerCertificates();
+    const replacedCertNames = pickReplacedCertNames({
+      metadataList,
+      targetCertIds: targetIdSet,
+      excludeCertId: newCertId,
+    });
+
+    if (replacedCertNames.length === 0) {
+      this.logger?.info("没有需要清理的旧证书");
+      return;
+    }
+
+    for (const certName of replacedCertNames) {
+      try {
+        await this.deleteServerCertificate(certName);
+        this.logger?.info(`已删除被替换的旧证书: ${certName}`);
+      } catch (err: any) {
+        const message = err?.message || String(err);
+        this.logger?.warn(`删除旧证书失败(可能仍被其他分配引用)，已跳过: ${certName}, 原因: ${message}`);
+      }
+    }
  }
 }
@@ -1,7 +1,7 @@
 import { AbstractTaskPlugin, IsTaskPlugin, pluginGroups, RunStrategy, TaskInput } from "@certd/pipeline";
 import { CertApplyPluginNames, CertInfo } from "@certd/plugin-cert";
 import { AwsCNAccess } from "../access.js";
-import { AwsIAMClient } from "../libs/aws-iam-client.js";
+import { AwsIAMClient, buildIamViewerCertificate } from "../libs/aws-iam-client.js";
 import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from "@certd/plugin-lib";
 import { AwsCNRegions } from "../constants.js";

@@ -77,10 +77,19 @@ export class AwsCNDeployToCloudFront extends AbstractTaskPlugin {
  async execute(): Promise<void> {
    const access = await this.getAccess<AwsCNAccess>(this.accessId);

+    const iamClient = new AwsIAMClient({
+      access,
+      region: this.region,
+      logger: this.logger,
+    });
+
+    // 本次是否真正上传了新证书（cert 为字符串时表示直接使用已有证书ID，不涉及替换过期旧证书）
+    const uploadedNewCert = typeof this.cert !== "string";
+
    let certId = this.cert as string;
-    if (typeof this.cert !== "string") {
+    if (uploadedNewCert) {
      //先上传
-      certId = await this.uploadToIAM(access, this.cert);
+      certId = await this.uploadToIAM(iamClient, this.cert as CertInfo);
    }
    //部署到CloudFront

@@ -93,6 +102,9 @@ export class AwsCNDeployToCloudFront extends AbstractTaskPlugin {
      },
    });

+    // 记录每个分配部署前引用的旧 IAM 证书ID，部署完成后清理其中已过期的
+    const oldCertIds = new Set<string>();
+
    // update-distribution
    for (const distributionId of this.distributionIds) {
      // get-distribution-config
@@ -100,30 +112,61 @@ export class AwsCNDeployToCloudFront extends AbstractTaskPlugin {
        Id: distributionId,
      });

-      const configData = await cloudFrontClient.send(getDistributionConfigCommand);
+      const configData: any = await this.sendCloudFrontCommand(() => cloudFrontClient.send(getDistributionConfigCommand), `获取CloudFront配置(${distributionId})`);
+
+      const oldViewerCertificate = configData.DistributionConfig?.ViewerCertificate;
+      const oldCertId = oldViewerCertificate?.IAMCertificateId;
+      if (oldCertId) {
+        oldCertIds.add(oldCertId);
+      }
+
+      // 使用干净的 IAM ViewerCertificate，避免与旧的 ACM/默认证书字段冲突导致 InvalidViewerCertificate
+      const viewerCertificate = buildIamViewerCertificate({ oldViewerCertificate, certId });
+
      const updateDistributionCommand = new UpdateDistributionCommand({
        DistributionConfig: {
          ...configData.DistributionConfig,
-          ViewerCertificate: {
-            ...configData.DistributionConfig.ViewerCertificate,
-            IAMCertificateId: certId,
-          },
+          ViewerCertificate: viewerCertificate,
        },
        Id: distributionId,
        IfMatch: configData.ETag,
      });
-      await cloudFrontClient.send(updateDistributionCommand);
+      await this.sendCloudFrontCommand(() => cloudFrontClient.send(updateDistributionCommand), `更新CloudFront证书(${distributionId})`);
      this.logger.info(`部署${distributionId}完成:`);
    }
    this.logger.info("部署完成");
+
+    // 仅当本次上传了新证书时，清理被替换掉的旧证书（无论是否过期）；清理失败不影响部署结果
+    if (uploadedNewCert) {
+      try {
+        await iamClient.deleteReplacedCerts({ oldCertIds, newCertId: certId });
+      } catch (err: any) {
+        this.logger.warn(`清理旧证书失败，已忽略: ${err?.message || err}`);
+      }
+    }
  }

-  private async uploadToIAM(access: AwsCNAccess, cert: CertInfo) {
-    const acmClient = new AwsIAMClient({
-      access,
-      region: this.region,
-    });
-    const awsCertID = await acmClient.importCertificate(cert, this.appendTimeSuffix(this.certName));
+  /**
+   * 统一包装 CloudFront 调用错误。
+   * 命中 AWS 权限不足（AccessDenied / not authorized）时，抛出可读的中文提示，
+   * 指明该 IAM 用户需要补充的 CloudFront 与 IAM 权限，方便运维在 AWS 控制台排查。
+   */
+  private async sendCloudFrontCommand<T>(action: () => Promise<T>, actionDesc: string): Promise<T> {
+    try {
+      return await action();
+    } catch (err: any) {
+      const message = err?.message || String(err);
+      const isAuthError = err?.name === "AccessDenied" || /not authorized to perform|no identity-based policy/i.test(message);
+      if (isAuthError) {
+        const requiredPermissions = ["cloudfront:ListDistributions", "cloudfront:GetDistributionConfig", "cloudfront:UpdateDistribution", "iam:UploadServerCertificate"].join("、");
+        throw new Error(`${actionDesc}失败：AWS 账号权限不足，请为该 IAM 用户附加 CloudFront 部署所需权限（${requiredPermissions}）。原始错误：${message}`);
+      }
+      throw err;
+    }
+  }
+
+  private async uploadToIAM(iamClient: AwsIAMClient, cert: CertInfo) {
+    const awsCertID = await iamClient.importCertificate(cert, this.appendTimeSuffix(this.certName));
    this.logger.info("证书上传成功,id=", awsCertID);
    return awsCertID;
  }