流水线突然无法签名，或者 Apple Distribution 证书进入待处理清单？
本周先盘点证书、私钥、描述文件和依赖它们的发布任务，再用 Fastlane Match 分阶段同步新资产；真实 Mac CI 完成构建、归档与签名验收后，才停用旧资产。证书轮换不等于先撤销旧证书。
企业 IT 负责人：明确资产轮换的审批人、执行人和回退责任。
平台工程师：让 Fastlane Match 在 CI 中按受控方式同步签名材料。
iOS 发布工程师：验证更新后的签名能否完成真实归档与分发。
立项盘点：先确认签名资产，再估算发布影响
把清单按应用、签名用途和发布流程拆开，不要只按证书文件名登记。至少核对开发签名、App Store 分发和内部测试分发，并记录对应的 Bundle ID、描述文件、构建任务、备用 Mac 节点及资产负责人。
- 证书：记录类型、团队归属、有效状态及当前使用的签名身份。Apple 说明，分发证书属于团队，且每个团队对每种分发证书类型通常只能有一个；Developer ID 证书除外。先核查现有证书状态和用途，不要假设所有项目共用同一张证书。可对照 Apple 证书类型与管理说明。
- 私钥：确认 CI 的 Keychain 中是否存在与目标证书匹配的私钥，并核实哪些构建任务、账号和 Mac 主机能访问它。证书文件存在，不代表这台机器具备签名能力。
- 描述文件：逐个对应 App ID、签名类型、证书和相关设备或能力。Apple 指出，证书被撤销后，包含该证书的描述文件会失效；因此撤销前要先列出依赖项并准备更新方案，参见 Apple 关于撤销证书的说明。
- 发布依赖：把构建、归档、测试分发、正式发布和备用节点纳入清单。未进入清单的旧流水线，往往会在新资产切换后才暴露出来。
Apple Distribution 证书可能到期时，先做什么准备？
先从开发者账户、CI 配置和流水线日志核实证书状态与使用范围，再检查私钥、对应的 iOS provisioning profile 和所有发布任务。Apple 的账户权限也要提前确认：组织成员能否创建或撤销资产，取决于角色及相应访问权限；不要把例行操作默认交给拥有过宽权限的账号。具体角色以 Apple Developer Program 角色说明 为准。
切换前基线：把当前可用状态留作对照
在改动签名材料前，先保存当前 Mac CI 的 Xcode 版本信息、构建参数、签名身份、描述文件标识和代表性任务结果。需要对照的是可复现的流水线，不是某位工程师本地成功过一次的记忆。
- 保存一份当前构建日志，并记录归档产物使用的签名身份和嵌入描述文件。
- 在备用或隔离的 Mac 构建环境确认现有签名仍可用，保留已知可工作的配置与恢复步骤。
- 核查 Apple 账户权限、Match 仓库访问权限、解密口令和 CI Secret 的管理范围。签名私钥、Match 解密口令、CI Secret 与主机账号是不同的控制对象，不能因其中一项受控就认为其他项也安全。
⚠️ 不要把已安装的证书文件当成完整签名凭证。Xcode 文档提醒，取得导出的签名身份并知道密码的人，可以签署看起来来自该开发者账户的软件；私钥的导出、存放和访问都应纳入审批与审计。参见 Xcode 团队签名身份同步说明。
新资产准备：创建证书后同步更新描述文件
根据团队现行签名模式，决定由 Xcode、Apple 开发者账户还是既有 Fastlane Match 流程管理新证书和描述文件。创建或管理资产的账号必须有对应权限；若由组织成员执行，先核对其角色，而不是临时共享更高权限账号。
证书更新后，检查相关描述文件是否仍关联有效证书，并确认 App ID、能力和分发方式匹配。若描述文件失效，按 Apple 的说明重新生成或编辑；不要只替换证书就假定打包链路已恢复。可参照 Apple 编辑、下载或重新生成描述文件的步骤。
证书更新后如何确认 Mac CI 已经拿到新资产？
先检查同步日志中的证书身份和目标描述文件，再从归档产物检查实际签名身份及嵌入的描述文件。Apple 的签名排障文档说明，构建日志可用于查看 Xcode 选择的描述文件；因此流水线绿色只能作为一项信号，不能代替产物验收。参见 Apple 关于描述文件与签名日志的说明。
分阶段同步：让 Fastlane Match 在 CI 中只读
先在隔离的 Mac 节点验证目标应用和签名类型的同步结果，再把通过验证的配置推广到正式流水线。Fastlane Match 官方文档支持 readonly 模式，并建议 CI 使用只读模式，避免构建任务自行创建证书或描述文件；可查阅 Fastlane Match 官方文档。
Fastlane Match 怎样只读取已有证书和描述文件？
在 CI 调用中为 Match 设置只读模式，例如在 lane 配置 readonly: true，或按官方文档使用只读命令行选项。上线前确认所选存储、目标应用和签名类型正确，并由有权限的管理流程预先准备新资产。只读模式限制 Match 的资产生成行为，不代表自动完成审批，也不证明构建主机已经隔离。
- 把 Match 存储仓库或对象存储权限限制到需要同步签名材料的任务；解密口令只注入需要它的 CI 作业。
- 只在可信的签名构建流程中注入凭证。对于自托管 Mac 节点，还要检查其他作业能否读取同一用户目录、Keychain 或临时文件。CI 平台的 Secret 机制并不能单独保证主机隔离；可参考 CI 平台关于受控环境与 Secret 的说明 及 受损 runner 的风险说明。
- 若发布任务需要人工审批，把审批门禁与凭证可用范围一起设计。部分 CI 平台支持环境保护规则或审核人门禁，具体能力与仓库、套餐条件有关，部署前应核实 环境与部署保护规则文档。
真实验收：用构建、归档和分发结果决定是否放量
在代表性项目上执行真实 iOS 工作流，分别检查构建、归档，以及团队实际使用的测试或发布分发路径。验收记录要能回答：此次产物由哪张证书签名、使用哪个描述文件、对应哪个应用标识、由哪台 Mac 构建。
- 将新旧流水线日志与归档签名信息逐项对照，检查签名身份和描述文件是否符合预期。
- 在需要设备测试或特定能力的项目上，验证相应描述文件与目标条件匹配；不要用仅能通过编译的模拟器任务代替签名验收。
- 记录每项任务的结果、执行节点、异常和回退依据。任何关键任务失败，就暂停扩大范围，恢复已知可用配置并先定位原因。
旧证书什么时候可以撤销？撤销前要核实什么？
等生产工作流、备用 Mac 节点和相关应用都完成新资产验收后，再按组织审批决定保留、更新或撤销旧证书。撤销会使包含该证书的描述文件失效，Apple 也提供了重新编辑或生成描述文件的处理路径；所以撤销前必须确认依赖面、替代资产和恢复步骤，而不是把撤销当作轮换的默认操作。
退役收尾：留存证据，再关闭旧资产
新资产全面验收后，更新团队的签名资产清单，明确证书、私钥、描述文件、Match 存储、CI Secret 和主机权限各自的责任人。记录变更审批、验收结果、回退条件及旧资产最终处置结论，方便后续排查签名失败或审计资产访问。
撤销或删除前，最后确认没有未迁移的生产任务、备用节点或历史发布流程依赖旧资产；也要确认签名材料仍有经批准的恢复方式。若不能证明依赖已解除，先保留旧资产并继续调查，不要为了清理清单而破坏可恢复性。
如果现有做法是把签名构建都放在团队自有 Mac 上，常见代价是设备采购和维护由团队承担、节点容量固定，以及硬件访问和故障恢复需要自己安排。短期需要额外节点做轮换验收时，可以把远程 Mac 作为补充方案评估；若你的签名任务依赖特定物理接口，或需要长期稳定的专用负载，则应先核对自有设备方案是否更合适。你可以先了解 VMSPIN 的远程 Mac 服务入口，再按实际需要核对 套餐与计费信息。签名资产的审批、凭证保护和产物验收仍由你的团队负责；资源不足时，再考虑通过 VMSPIN 申请远程 Mac 承载隔离测试或轮换验收。