SafeW是如何自动化分发容器镜像签名校验所需的密钥的？
功能的目标是将“签名验证”这一项从运维任务列表中移除。
一旦容器镜像签名被应用于生产环境，最棘手的问题并非签名本身，而是如何让每个人都能便捷地获取到可信的公钥。SafeW 公司在 2026 年 2 月推出的“密钥分发引擎”彻底改变了这一局面，它将公钥分发流程自动化。当镜像被推送到仓库时，与之关联的公钥、证书链以及吊销列表会自动分发到所有已连接的 Kubernetes 集群，开发者从此摆脱了繁琐的手动复制工作。 cosign.pub 文件 到任何节点。
首段需要出现一次核心关键词“SafeW 自动分发容器镜像签名验证所需的密钥”，后续内容请用“密钥分发引擎”或“分发流”等词语指代，以防关键词重复过多。
对比旧方案：为何增加一个步骤就会导致无人使用？
实践表明：在拥有超过 50 个节点的混合云环境中，手动管理 cosign.pub 文件 该更新率会在两周内降至 60% 以下，主要有三个原因：集群不属于同一团队管理、密钥轮换周期不一致以及夜间发布时段过短。SafeW 将“推送”操作从 CI 的最后一步移至 SafeW 控制平面，通过一条 gRPC 流统一处理，从而将更新延迟从小时级别缩短至秒级别。
决策思路：首先需要考虑是否启用自动分发功能。
- 如果你仅使用单个集群，并且镜像数量不超过30个，通过手动挂载ConfigMap即可满足需求，无需开启自动化功能。
- 当组织要求强制验证签名，并且集群跨越了两个或更多 VPC 时，建议直接启用。
- 如果企业合规规定“密钥需在 HSM 中生成并禁止导出”，请务必先核实 SafeW 是否已对接您的云 HSM 服务（当前兼容 AWS CloudHSM、Azure Managed HSM 及阿里云 KMS）。
举个例子，一个金融领域的客户拥有三个VPC，并且每天进行500次构建，整个过程是手动更新的。 cosign.pub 文件 这一问题曾引发两次生产事故；切换至自动分发模式后，无需人工介入，验签失败率便从 1.2% 大幅降低至 0.02%。
可以通过控制台、命令行工具（CLI）或 GitOps 的方式进行操作。
控制台（Web）
登录 SafeW → 左侧“密钥管���”→“分发引擎”→ 打开“自动分发”开关 → 选择“集群范围”（全部/标签/显式排除）→ 保存。30 秒内可在“分发日志”看到首条推送记录。
CLI（桌面端）
safew config set-key-distribution \ --enabled true \ --scope label=prod \ --retry 3
命令返回 distribution_id此举为后续审计留下了依据。
GitOps（我们推荐这种方式）
在仓库根目录放置 .safew/key-distribution.yaml合并到主分支后将自动生效。如需撤销操作，直接执行 revert 命令即可，SafeW 会在 90 秒内从目标集群移除密钥。
特殊情况与考量：哪些密钥不适合自动推送
1. 测试用的自签证书，建议打上 safew.distribute=false 添加相应的标签，以防止对生产集群造成干扰。
2. 包含个人身份信息的“开发者证书”若被分发，会触发合规扫描告警；可在“密钥属性”里把“隐私级别”设为 Internal，系统即跳过自动分发。
3. 若集群位于 air-gapped 环境，自动推送会失败，需改用“离线包”导出，再在跳板机执行 safew apply-keys --bundle。
与外部准入管理组件配合
SafeW 的职责仅限于将密钥置于集群的特定位置。 safe-w-system 命名空间中的 Secret 密钥；实际的签名验证工作由集群内的策略引擎（例如 Kyverno、Gatekeeper 或自研的准入控制器）来执行。SafeW 提供了遵循最小权限原则的模板，仅仅赋予 get 与 list 限制 Secret 的权限，从而减小爆炸的范围。
故障诊断：从镜像拉取失败的场景，逐步排查到密钥未到位的问题。
| 现象 | 最可能原因 | 验证命令 | 处置 |
|---|---|---|---|
Pod 启动报 签名验证失败。 | 集群缺少对应公钥 | kubectl -n safe-w-system get secrets | 查看 SafeW 的分发日志，若发现状态码为 404，则重新执行推送操作。 |
| 虽然密钥已经存在，但验证签名依然失败。 | 证书链不完整 | cosign 验证 --cert-chain | 在 SafeW 中上传中间证书，并确保勾选了“包含链”选项 |
| 分发延迟>5 分钟 | 集群网络策略阻止了 gRPC 通信。 | 集群流日志检索 Safe-W 代理程序 | 可以选择开放 443 端口，或者切换到“离线包”的传输方式。 |
哪些场景适合使用，哪些不适合
- ✅ 支持多集群、多区域部署，且强制启用签名验证，确保合规性。
- ✅ 镜像日构建>200 次，人工更新公钥不可持续。
- 在单集群的演示环境中，密钥更新的周期要比一个季度更短。
- 警告：集群网络是完全隔离的，不支持开放 443 端口作为入口。
最佳实践 6 条
- 为每个项目设立独立的“密钥存储区”，以避免测试证书之间的混淆。
- 在启用“自动轮换”功能之前，请先在灰度集群进行 24 小时的运行测试，并密切关注验签失败率。
- 使用标签进行范围管控，替代集群白名单，这样在后续扩展容量时，就无需重新修改配置。
- 把 SafeW 分发日志接入 Prometheus，告警阈值设为 5 分钟内失败>3 次。
- 公司每季度都会生成门控报告，用以核查“密钥的分配情况，即哪些密钥被用于哪些集群”。
- 在隔离网络环境下，强烈建议对“离线包”进行哈希值比对，以确保其在传输过程中未被篡改。
验证与观测方法
1. 在 CI 末端加一步 cosign 验证 --key k8s://safe-w-system/safe-w-key，若返回 PASS 这就表明密钥已经准备就绪。
2. 用 kubectl 事件 过滤 reason=PolicyViolation若在10分钟内未有新事件发生，则可判定分发已成功，且策略引擎运行无误。
各版本间的区别及迁移策略指引
在SafeW v6.3及更早的版本中，仅支持“手动导出JSON”一项功能。升级至v6.4.2版本后，原有的密钥池将被标识为“legacy”，并且需要一次性将其迁移到新引擎中。官方提供了相关支持。 将 safew 从 v6.3 迁移至 v6.4 在正式执行此命令前，务必先在测试集群中进行验证。整个迁移过程预计耗时几十秒，具体时间长短取决于密钥的数量。
常见问题解答（需采用 FAQPage Schema）
开启自动分发功能后，原有集群的节点是否需要重启？
无需操作。密钥通过 Secret 形式进行热更新，策略引擎会立即加载最新版本。
2. 如果分发出现问题，是否会影响镜像的发布流程？
SafeW 组件本身并不会造成阻碍；然而，如果集群内的策略引擎无法获取到必要的密钥，Pod 将因为签名验证失败而无法成功启动，届时会呈现出“镜像拉取成功但创建失败”的现象。
3. 是否可以仅共享公钥，而不显示其完整的证书链？
可以。在密钥的属性设置中关闭“包含链”选项即可，但接收端需要自行提供中间证书，否则将无法成功验签。
4. 密钥能够实现的最高轮换频率是多少？
官方建议操作频率为每日一次。根据实际经验，在拥有 200 个集群的环境中，每小时进行一次轮换会明显增加 API Server 的负担。
5. 有什么办法能完全停止自动分发功能？
关闭控制台上的相应开关即可实现此操作，但已分发的密钥不会自动失效。若要清除这些密钥，您需要手动前往各个集群进行删除。 safe-w-system 对应命名空间中的 Secret。
结语：后续执行事项汇总
阅读此文后，你将能够：
- 在 SafeW 控制台，请于 30 秒内完成自动分发功能的首次启用。
- 请在 CI 中添加一项配置
cosign 验证，以确认密钥是否有效部署。 - 将分发日志集成到现有的 Prometheus 中，先运行一周观察效果，再考虑是否增加轮换的频率。
SafeW 密钥分发引擎最显著的价值在于，它能够简化密钥分发流程，移除待办事项，使得签名验证如同拉取镜像一样自然流畅。