Zarf 1.0 上手指南：在离线环境打包部署软件并验证签名与完整性

离线环境交付软件最容易被低估的环节，不是把镜像和安装包拷进去，而是证明“进去的东西确实是我构建、我签名、我没有在传输途中被替换”。Zarf 1.0 的价值正在这里：它把 Kubernetes 和云原生工作负载所需的镜像、清单、依赖与 SBOM 打包成可迁移的制品，并在部署路径上强化签名与校验流程。OpenSSF 在 2026 年 11 月 9 日的 1.0 公告中，把“更强的包签名与验证工作流、更可预测的行为、面向长期兼容的包格式”列为这次发布的核心变化。对运维和安全团队来说，这更像一条可验证交付链的起点，而不是一个“拷进去就能跑”的万能工具。

先判断：Zarf 1.0 适合哪些隔离场景

Zarf 最初由 Defense Unicorns 构建，现在是 OpenSSF 项目。它采用声明式打包方式，把软件交付到离线或半连接环境，主要面向 Kubernetes 与云原生工作负载。典型的适用场景包括：隔离网络中的平台交付、边缘或现场环境的一次性部署、需要重复构建同一套制品并保留 SBOM 与签名证据的受控交付，以及联网侧构建、隔离侧验证的跨域流程。

采用前也要明确它不替代什么。Zarf 负责打包、搬运、校验和部署编排，不等于应用数据备份方案，也不自动解决密钥托管、身份治理和合规审计平台的问题。若目标环境不是 Kubernetes，或依赖大量非容器化的主机级安装脚本，应先确认 Zarf 的组件能力是否覆盖，再决定是否引入。把 Zarf 当作“离线部署流水线中的可验证搬运层”更准确。

采用前的环境与权限检查清单

Zarf 1.0 引入了 v1beta1 包 schema，官方公告明确说明这次重构用 values 取代了过去的 variables，并调整了部分已弃用能力。若团队已有旧包或模板，先做 schema 迁移评估，不要直接把旧定义套到 1.0 上。

环境侧至少核对以下几项：

• Kubernetes 版本、节点架构与操作系统是否与包内组件匹配，因为部署流程会按架构和 OS 过滤组件。
• 是否具备安装 Zarf init 包所需的集群权限，包括创建命名空间、工作负载、CRD 或 registry 相关资源。
• 隔离侧是否有可用的内部镜像仓库、DNS、证书与代理配置；若使用 Zarf 内置 registry，需要预留存储和端口。
• 信任材料是否齐备：签名公钥或 Sigstore TrustedRoot、证书身份与 OIDC issuer 策略、是否使用 RFC3161 时间戳、离线环境下 Rekor 透明日志如何处置。
• 制品证据是否随包归档：包文件、校验和、签名、SBOM、构建记录与发布审批记录。
• 回滚条件是否明确：旧版本包是否保留，应用数据是否有独立备份，集群资源是否有快照或导出。

权限上要避免“为了省事给集群管理员永久权限”。安装 init 包通常需要较高权限，但后续部署应尽量收敛到目标命名空间和必要资源范围。签名验证也不应被当作部署后的补充动作，而应前置为制品准入条件。

安装与初始化：先把信任根带进去

联网侧先获取 Zarf 二进制和对应 init 包，校验下载来源与哈希，再转入隔离侧。二进制和 init 包都应保留版本号、校验和与获取记录。Zarf 2026 路线图中仍将“签名 init 包”和 keyless 签名支持列为推进项，这意味着生产采用时不能默认 init 包已经具备完整的可验证来源；至少应把 init 包的来源、哈希和人工复核记录纳入交付证据。

在隔离侧执行初始化前，确认目标集群的 kubeconfig 指向正确上下文，并记录初始化前的集群状态。初始化完成后，检查 Zarf 所需的工作负载、registry 或 agent 是否正常运行，再进入打包部署阶段。若初始化失败，先清理残留资源并回到已知状态，不要在部分初始化的集群上继续部署。

打包：把依赖、SBOM 和签名一起带走

Zarf 的打包思路是把部署所需内容收敛到一个包中，减少隔离侧临时找依赖的情况。使用 1.0 时，先按 v1beta1 schema 编写 zarf.yaml，明确组件、镜像、清单和值配置。打包应在受控的联网构建环境中完成，构建完成后立即生成校验和并执行签名，避免包在签名前经过多次转手。

最小示例可参考下面的命令形态，实际参数以当前版本文档为准：

# 在联网构建侧创建包，生成的包文件和校验和应一并归档
zarf package create . --confirm

# 隔离侧部署时强制要求签名验证
zarf package deploy zarf-package-demo-amd64-1.0.0.tar.zst --confirm --verify=always

包体积较大时可能产生分片文件。部署分片包时应传入首个分片，例如 .part000，并确保所有分片按顺序完整传输；缺片或顺序错误会在解包或校验阶段暴露，不应通过跳过校验来绕过。

打包后建议立即做三件事：记录包哈希；确认签名和信任材料可用；把 SBOM 与构建元数据放到与包同级的证据目录。部署流程会将 SBOM 文件保存到当前目录，若在临时目录执行，容易在清理时丢失，最好在部署前固定工作目录并纳入归档。

部署与签名验证：不要接受“能部署就算通过”

官方部署流程包括加载包、处理分片、解压到临时目录、校验包校验和与签名、按架构和 OS 过滤组件、保存 SBOM、处理弃用与破坏性变更，然后继续部署。也就是说，校验发生在部署前，而不是部署后补救。

zarf package deploy 的 --verify 支持三种模式：

默认值是 if-possible。在离线场景中，如果签名材料缺失或信任根未配置，这个默认值可能让部署继续推进，因此生产检查清单应明确要求 --verify=always，并把“验证失败即停止”写成流程规则。

如果使用 keyless 签名，部署侧还需要按文档提供证书身份和 OIDC issuer 条件；使用自带密钥时，则需要正确的公钥或 TrustedRoot。离线环境还要考虑透明日志与时间戳策略：publish 命令提供了 --trusted-root、--use-signed-timestamps 以及气隙场景下与 Rekor 相关的选项。不要把“气隙默认跳过透明日志”理解为签名不重要，它只说明离线验证需要另一套可审计的信任安排。

--insecure-skip-tls-verify 只应在有明确原因且接受降低安全性的情况下临时使用，不能写进常规部署脚本。证书问题应通过修复 CA 和信任链解决。

发布到 OCI 仓库时保留验证证据

若制品需要进入内部 OCI 仓库，zarf package publish 可用于发布包并携带验证相关选项。发布环节应保留 TrustedRoot、时间戳和透明日志策略的记录，确保后续拉取方能复现同样的验证条件。发布不是“上传完就结束”，而是把包、签名、信任根和发布记录绑定在一起。

对隔离网络而言，更稳妥的做法是：联网侧发布并验证，隔离侧通过受控介质带入包与证据，再在隔离侧执行一次强制验证。两侧使用同一套信任策略，避免出现“联网侧验证通过、隔离侧因缺信任根而跳过”的落差。

常见故障与排查顺序

签名验证失败：先确认包是否在签名后被重新打包或修改，分片是否完整；再检查公钥、TrustedRoot、证书身份与 issuer 是否匹配；使用时间戳时检查 TSA 数据是否随包保留。不要第一步就改成 --verify=never。

提示组件缺失或平台不匹配：部署流程会按架构和 OS 过滤组件。核对包的架构、节点操作系统和目标集群是否一致，而不是强行部署不匹配的组件。

SBOM 找不到：检查执行部署时的当前目录和写权限。SBOM 默认保存到当前目录，建议在固定证据目录中执行并立即归档。

init 阶段失败或 registry 不可用：核对集群权限、存储、端口、DNS 和证书；清理部分初始化的资源后重试，避免在残留状态下反复部署。

旧包迁移报错：检查是否仍在使用旧 schema 或 variables 写法。1.0 的 v1beta1 需要按 values 迁移，并复核弃用字段。

OCI 拉取或发布失败：先区分 TLS 信任问题、认证授权问题和网络可达性问题。TLS 问题修复 CA，不要用跳过校验掩盖。

回滚与卸载：把恢复路径也当成交付物

部署前应保留上一版包、校验和、SBOM 与部署记录，并对应用数据做独立备份。Zarf 能编排 Kubernetes 资源，但不应假设它会自动备份持久化数据。回滚时先按官方方式移除或替换本次部署的包，再恢复数据与配置，最后重新执行一次签名验证和业务探针检查。

若验证失败发生在部署前，正确动作是停止并隔离制品，保留失败证据，排查签名链或传输完整性；若失败发生在部署后，应优先回到上一已知良好版本，再分析是包内容、信任材料还是环境差异导致。回滚完成后不要删除失败包和日志，它们是后续审计和改进打包流程的依据。

上线前的一页式检查清单

• 已确认目标环境是 Kubernetes/云原生工作负载，且 Zarf 组件能力覆盖所需资源。
• 已完成 v1beta1 schema 迁移评估，旧 variables 写法已替换为 values。
• 二进制、init 包、业务包均有来源记录、哈希和签名证据。
• 隔离侧信任根、公钥或 keyless 身份条件已配置并测试。
• 部署命令使用 --verify=always，验证失败即中止。
• SBOM 在固定目录生成并归档，未随临时目录清理丢失。
• 分片包完整、顺序正确，传输介质有交接记录。
• 旧版本包、数据备份和卸载步骤已准备，回滚路径经过演练。
• 证书、DNS、registry 和存储容量在隔离侧已提前验证。
• 失败包、日志和验证结果保留，纳入审计与复盘。

Zarf 1.0 让离线交付更接近“可验证的工程流程”，但前提是团队把签名验证、证据归档和回滚能力一起设计进去。工具负责搬运和校验，信任判断仍要由流程和人来完成。

官方资料可参考 OpenSSF 的 1.0 公告、%%XHAI_CODE_0%% 文档和 %%XHAI_CODE_1%% 文档；实际参数与版本行为以对应版本文档为准。