fhEVM Preview Environment 实战指南：用标签或 workflow_dispatch 在 zws-dev 集群上拉起一次性 e2e 全栈环境

fhEVM Preview Environment 实战指南：用标签或 workflow_dispatch 在 zws-dev 集群上拉起一次性 e2e 全栈环境

【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm

本文聚焦 fhevm 仓库的preview env（预览环境）机制：它是一套部署在zws-devTailscale 集群独立命名空间中的"即用即弃"式完整 fhEVM 技术栈（Anvil host+gateway 链、真实阈值+enclave KMS、合约、coprocessor、kms-connector、relayer 与 e2e test-suite）。读完本文，你将掌握两种启动方式（PR 打标签自动部署、workflow_dispatch手动部署）、全套控制/拓扑/版本参数的含义、CLI 辅助脚本的用法，以及连接、观测、查看测试结果和销毁环境的完整操作流程。

Preview env 的核心价值在于：用真实的 Helm Charts 与真实的 KMS 把 PR 端到端跑一遍，而不必在本地搭一套完整资源密集的堆栈（仓库 README 明确指出，4-party enclave KMS + coprocessor + kms-connector + relayer + test-suite 的完整组合已不适合本地 Kind/笔记本方案，远程zws-dev集群是唯一受支持的运行路径，本地迭代请继续使用test-suite/fhevm的 docker-compose 方案，详见 ci/preview-env/README.md）。本文是使用层面的指南；部署了什么、为什么这样部署，见 ci/preview-env/README.md。

一、什么是 preview env：一次性部署、端到端验证

一个 preview env 会在zws-dev集群上自己的命名空间内，部署一套完整且隔离的 fhEVM 堆栈：

• 链：默认是一对 per-namespace 的 Anvil（host 链 + gateway 链）；也可切换为共享的blockchain-devGeth + Nitro。
• KMS：真实的阈值签名 + enclave（Nitro Enclave）KMS，由zama-ai/kms自己的deploy.sh直接复用部署，不经过本仓库。
• 应用层：host/gateway 合约、coprocessor（含 tfhe/zkproof/sns workers、gw-listener、host-listener 消费端等）、kms-connector、listener、relayer，以及 e2e test-suite。

部署入口是 .github/workflows/preview-env-deploy.yml，销毁入口是 .github/workflows/preview-env-destroy.yml。在 ci/preview-env 目录下，101-preview-env.md（本文主题文档）负责"怎么用"，README.md负责"里面有什么、为什么"。

启动有两种方式：

前置条件

在开始之前，需要具备两项权限：

• 属于coprocessor-dev-access或kms-dev-access群组（任一即可获得命名空间管理员权限），并且有到zws-dev集群的Tailscale访问权——这是部署后连接环境所必需的。
• 对 PR 有写权限（才能添加标签），或对 workflow 有运行权限（才能手动触发）。

二、方式 A：从 PR 打标签启动（最常用的开发路径）

给 PR 添加下列标签之一，环境即自动部署。每次新的 push 都会从头重新部署（正在运行中的部署会被取消）。

关于 PR 路径有几个固定行为（源码层面可在 preview-env-deploy.yml 的 check-labels job 中验证）：

• PR 上镜像总是从分支新鲜构建，不存在"只用 pin 值"的 PR 路径；想完全用 base commit 的镜像，请用workflow_dispatch且build_images=false。
• 命名空间：fhevm-ci-<pr-author>-<pr-number>。命名空间以PR 作者而非 push/打标签的人为 key——这样部署与销毁永远能对应上（destroy 工作流注释中对此有专门说明：closed/unlabeled事件里的github.actor可能与作者不同，因此两个工作流都统一用pull_request.user.login推导，见 preview-env-destroy.yml）。
• 结果反馈：成功后 PR 上会收到一个:rocket:评论；使用preview-env-e2e-tests时，会追加一份按测试 SDK 矩阵整理的逐用例 pass/fail 报告评论。
• 自动销毁：PR被关闭时，或移除preview 标签时自动触发。注意：只移除-tests而保留preview-env-e2e时环境保持存活——销毁逻辑判定"不存在任何以preview-env-e2e开头的 preview 标签"才销毁，见 preview-env-destroy.yml。

三、方式 B：手动运行（workflow_dispatch）

路径：GitHub →Actions→preview-env-deploy→Run workflow，在 "Use workflow from" 中选择分支，设置输入参数后运行。适用于：更换版本或拓扑、在无 PR 的情况下部署。

preview-env-deploy.yml声明了完整的输入参数（工作流定义），全部有合理默认值，日常通常只需设置少数几个。

3.1 控制类输入

3.2 拓扑类输入

关于共享链的几个关键实现事实（见 ci/preview-env/README.md）：Geth 没有evm_*cheats，因此自动化测试走 Hardhat 网络zwsDev（live 路径，HCU 确定性用例跳过）；钱包不是 Anvil 的固定 mnemonic，而是按同一套 HD 索引映射派生（#0gateway 部署者、#3relayer、#9host/ACL owner、#10+KMS/coprocessor tx-senders），并存储为 secretpreview-wallets-mnemonic。

3.3 版本控制：overridesJSON

手动部署可选传一个overridesJSON 对象（空 /{}= 全部按"今天"解析）。允许的 key 在 ci/preview-env/scripts/parse-overrides.cjs 中硬编码，未知 key 会使运行直接失败；每个 value 必须是字符串。三类 override 的解析规则不同：

解析逻辑的核心在 parse-overrides.cjs：它读取OVERRIDES_RAW与EVENT_NAME，先做 JSON 合法性校验、未知 key 校验、value 类型校验，再对每个允许的 key 按"用户值 →ALWAYS_DEFAULTS→ dispatch 的relayer_sdk_version兜底 0.4.4 → 空串"的顺序填充，最后写入GITHUB_OUTPUT。任何校验失败都会以::error::输出并process.exit(1)——这就是"未知 key 直接让运行失败"的机制来源。

当前默认值（ALWAYS_DEFAULTS）：kms_core_version=d27c3b5、kms_repo_ref=35edfa2f0656ee266e3299a004a83ac7d4fe2418。

3.4 专用 KMS（zama-ai/kms）：两个 key、一套 release

preview env从不构建 kms-core。party 数量由nb_kms_core（4或13）决定（这是拓扑输入，不在overrides中）。版本由两个 override key 控制，且必须保持对齐到同一个 kms release：

一个很容易混淆的点：kms-connector 不是 kms-core。kms_connector_version/kms_connector_chart_version是 fhevm 自有的（与 coprocessor 相同的解析/构建规则）。修改 KMS 版本不会改变 kms-connector，除非你同时 override 这两个 key。

PR 标签无法覆盖 KMS 版本：pull_request事件下overrides为空，所以所有打标签的 preview 都用ALWAYS_DEFAULTS那对默认值。要测试某个 kms 构建，请使用workflow_dispatch或 CLI 的--set，或直接为所有人 bumpparse-overrides.cjs中的默认值。

还有两个隐含前提需要牢记：

• enclave tag 必须真实存在于 GHCR 且带zama.kms.eif_pcr{0,1,2}标签；
• 旧的kms_repo_ref可能缺少 workflow 期望的特性（例如observability=true时需要的--tracing-endpoint）。

3.5 dispatch 示例

命令行语义下的示例（详见 3.6 的 CLI 用法）：

# 测试某个 kms enclave + 配套 deploy 脚本 ci/preview-env/preview-env launch --ref <branch> --tests \ --set kms_core_version=<tag> \ --set kms_repo_ref=<kms-commit-sha> # 13-party 阈值 KMS ci/preview-env/preview-env launch --ref <branch> --kms-parties 13 --tests

或 Actions 表单里的overrides：

{ "kms_core_version": "abc1234", "kms_repo_ref": "35edfa2f0656ee266e3299a004a83ac7d4fe2418" }

dispatch 环境的命名空间：fhevm-ci-<actor>-<run-id-base36>（PR 环境则为fhevm-ci-<pr-author>-<pr-number>）。actor 在必要时会被截断，使整个名称保持在28 个字符以内——这个预算计算逻辑在 preview-env 脚本的derive_namespace()中：28 - len('fhevm-ci-') - 1('-') - suffix即为 actor 段可用的长度。

结果：run summary（部署计划；若开了automated_tests还有 e2e 报告）。

销毁：手动。dispatch 环境不与任何 PR 绑定，没有任何东西会自动销毁它。运行preview-env-destroy并传入命名空间（见第六节），或直接重新运行以复用该环境。

3.6 从 CLI 启动

preview-env是一个 bash 脚本，包装gh workflow run/gh run。它不会 helm-install——GitHub Actions 始终是写入路径。--ref对应的分支必须已经 push 到 origin。

ci/preview-env/preview-env launch --ref <your-branch> --tests ci/preview-env/preview-env launch --ref <your-branch> --blockchain-dev ci/preview-env/preview-env launch --ref <your-branch> --blue-green --blockchain-dev --tests ci/preview-env/preview-env launch --ref <your-branch> --set coprocessor_version=abc1234 ci/preview-env/preview-env launch --ref <your-branch> --tests \ --set kms_core_version=d27c3b5 --set kms_repo_ref=35edfa2f0656ee266e3299a004a83ac7d4fe2418

launch的完整选项（脚本 usage 中可见，见 preview-env）：

• --ref <branch>：必填，必须是已 push 的分支；
• --parties 1|2|3|5：coprocessor 身份数，默认1；2只是两方共识，不是 blue-green；
• --blue-green：发送enable_blue_green=true且nb_coprocessor=2（当--parties为 1 时自动抬升为 2）；--parties 2不加--blue-green仅是两方共识；
• --blockchain-dev：用共享 Geth/Nitro 替代 Anvil；
• --tests：automated_tests=true；
• --polygon：第二条 Polygon host 链（与 blue-green 不兼容，脚本会直接die）；
• --observability：命名空间内 Prometheus/Grafana/Jaeger；
• --no-build：build_images=false；
• --test-suite-only：只构建 e2e test-suite 镜像；
• --kms-parties 4|13：默认4；
• --set key=value：可重复，打包进 overrides JSON；key 必须是ALLOWED_OVERRIDES白名单内（脚本与parse-overrides.cjs各自维护了一份白名单，见 preview-env 的ALLOWED_OVERRIDES）；
• --repo owner/repo：默认zama-ai/fhevm；
• --watch：launch 后等待 run id 并流式输出进度。

launch会轮询等待新的 Actions run 出现并打印其 id。可用--watch流式跟进，或稍后查看：

ci/preview-env/preview-env launch --ref <your-branch> --tests --watch ci/preview-env/preview-env status --ref <your-branch> # 该分支上最近一次部署 ci/preview-env/preview-env status <run-id> # 或传 …/actions/runs/<id> URL ci/preview-env/preview-env watch <run-id> ci/preview-env/preview-env namespace --run-id <run-id>

status/watch既可传数字 run id、也可传 GitHub Actions run URL，或配合--ref <branch>自动取该分支上最近一次preview-env-deploy运行（解析逻辑见脚本的normalize_run_id/find_latest_run_id，preview-env）。

四、连接到你的环境

部署完成后，通过 Tailscale 建立 kubeconfig 并查看命名空间内 Pod：

tailscale configure kubeconfig tailscale-operator-zws-dev.diplodocus-boa.ts.net kubectl get pods -n <namespace> # 例如 fhevm-ci-alice-1234

五、观测你的环境（observability）

将 dispatch 输入observability设为true（默认关闭，目前仅手动运行可开），即可获得命名空间内的Prometheus + Grafana + Jaeger三件套：

• Prometheus自动抓取命名空间内所有暴露了名为metrics或monitoring端口名的 Service（采用 Kubernetes endpoints 服务发现，而非静态目标列表或 ServiceMonitor——因此不依赖集群级 prometheus-operator CRD，并能自动跟随nb_coprocessor/nb_kms_core的每-party 扇出）。指标历史存放在 10Gi PVC（7 天保留期），Pod 中途重调度不会丢数据。其 manifests 以additionalResources原始对象形式交付（endpoints-SD 的 ServiceAccount/Role/RoleBinding 需要这么做），详见 observability/values-prometheus-e2e.yaml。
• Jaeger all-in-one（v2，内存模式）充当 OTLP collector。
• Grafana（匿名 admin——一次性命名空间 + Tailscale 隔离）是两者的 UI，预置了 Prometheus + Jaeger 数据源；暂未预置 dashboard，UI 里创建的会随 Pod 消亡，需要的话请自行导出。

Tailscale 已开启（与连接环境相同的前置条件）时，通过 port-forward 访问：

kubectl port-forward -n <namespace> svc/grafana 3000:3000 # http://localhost:3000 kubectl port-forward -n <namespace> svc/prometheus 9090:9090 # http://localhost:9090 (原始 PromQL) kubectl port-forward -n <namespace> svc/jaeger 16686:16686 # http://localhost:16686 (Jaeger UI)

六、查看测试结果

• 开了自动测试（preview-env-e2e-tests标签或automated_tests=true）：workflow 会为@fhevm/sdk与@zama-fhe/relayer-sdk各跑一遍 e2e DAG，并把逐用例 pass/fail 表格贴到 PR 评论 / run summary。
  • 与preview-env-blue-green组合时，这个 DAG跑两遍：第一遍在DryRunStarted期间（BCS 存活；CI 断言每一方的"gcs-0.15.0".computations非空），第二遍在切换之后（versioning=v0.15，GCS 存活）。
• 没开自动测试：堆栈会部署一个空闲的 test-suite Job——你可以自己对着命名空间跑测试，或重新打上preview-env-e2e-tests标签。

一个值得了解的网络模式细节（见 README 的 Network mode 一节）：e2e 套件根据 Hardhat网络名（而非节点真实能力）通过isLiveNetwork()决定覆盖范围。本 preview 默认把 host 链命名为staging（chainId12345的 Anvil），不在LIVE_NETWORKS集合内，因此走本地/确定性路径——这会跑最强的覆盖：owner-only setter（setHCUPerBlock/setMaxHCUPerTx/setMaxHCUDepthPerTx）、精确 HCU 数值断言、evm_*cheats 打包区块验证 per-block 上限、以及"非 owner 拒绝"的负向用例。而use_blockchain_dev路径用zwsDev（在集合内），确定性 HCU 用例会this.skip()，覆盖反而减少——所以把 preview 切到 live 标记网络并非免费的"增强"。

七、销毁环境

销毁的含义是：helm uninstall命名空间内每个 release（这样 Crossplane claims——coprocessor S3 桶、KMS S3 vaults/enclave nodegroups——才会被释放，底层 AWS 资源才会真正去预配而不会泄漏），然后删除命名空间。全部由 preview-env-destroy.yml 处理。

PR 环境（自动）：无需任何操作。以下两种情况自动销毁：

• 关闭/合并PR；
• 移除preview-env-e2e标签（只移除-tests而保留preview-env-e2e时环境保持存活）。

手动（dispatch）环境：dispatch 环境没有 PR 可依托，需手动销毁。GitHub →Actions→preview-env-destroy→Run workflow，把namespace输入设为 deploy run summary 中的精确命名空间（如fhevm-ci-alice-987654）。它必须以fhevm-ci-开头（有 guard 会拒绝其他任何值，防止误删无关命名空间）。

或者用 CLI：

ci/preview-env/preview-env destroy fhevm-ci-<exact-name>

兜底方案：如果某个 run 无法到达集群，可手动执行：

helm list -n <namespace> --short | xargs -r -L1 helm uninstall -n <namespace> kubectl delete namespace <namespace>

注意：命名空间可能停留在Terminating状态几分钟，这是 Crossplane finalizer 正在释放 AWS 资源——属于预期行为，不是删除卡死。

八、易踩坑清单（Gotchas）

以下注意事项全部来自 101-preview-env.md 原文，并结合工作流源码逐条印证：

1. PR 标签总是构建你的分支。preview-env-e2e与preview-env-e2e-tests都会从 PR HEAD 构建新镜像（仅变更组件；其余从 base commit 解析）。只想部署 base commit 的镜像，请用workflow_dispatch且build_images=false（工作流 check-labels 中should_deploy=true时无条件置build_images=true，印证了这一点）。
2. Chart 变更直接部署。仓库内 Charts（charts/*）直接从分支 checkout 安装——无需发布、无需 bump 版本。
3. fhevm 自有镜像没有自动 pin。Charts 来自你的 checkout；镜像除非本次构建，否则解析自 base commit。请查看 run summary 的Images表格中的built、base-sha、dispatch-override标记。blue-green GCS workers 以<sha>-gcs0.15.0形式发布。例外：专用 kms-core 永远是外部 pin（parse-overrides.cjs中的kms_core_version+kms_repo_ref）——PR 标签不改这个文件或走 dispatch 就无法更改它。
4. 解析不到就失败。如果 GHCR 已裁剪掉 base commit 的 tags，且往前的 50 个 commit 内（MAX_IMAGE_COMMIT_COUNT: "50"）都找不到，resolve-tags会失败而不是悄悄部署旧版本。此时应 rebase 到更新的 base commit，或在overridesJSON 里显式传*_versionkey。（resolve-tags对每个组件按"本次构建 SHA → dispatch 输入 → base commit 祖先中最新已发布镜像 SHA"的优先级解析，且存在性必须通过 GHCR manifest 校验，见 resolve-tags.cjs。）
5. Stacked PR 从main解析镜像。只有main/release/*的 commit 会发布镜像，因此基于另一个 feature 分支的 PR 会从它与main的 merge-base 解析镜像，并排除父 PR 的代码变更（带警告）；Charts 不受影响（checkout 包含父分支）。父 PR 合并后请把目标分支改回main。
6. 每次 push 都重新部署PR 环境，并取消进行中的 run（工作流concurrency配置：PR 以 PR 号为 group、cancel-in-progress: true，见 preview-env-deploy.yml）。
7. 命名空间以 PR 作者为 key，不是 push/打标签的人——保证部署与销毁永远一致。
8. nb_coprocessor > 1很贵。每个 party 都是完整堆栈（自己的 workers/Postgres/S3）。除非专门测多 party，否则保持1。
9. 手动（dispatch）环境从不自动销毁——用preview-env-destroy清理。
10. use_blockchain_dev只能通过 dispatch 或preview-env-blue-green启用；普通preview-env-e2e/-tests标签留在 Anvil。faucet 注资的钱包每次运行唯一。销毁命名空间不会从共享 Geth/Nitro 移除合约——它们留在blockchain-dev上（可用host-explorer-blockchain-dev/gateway-explorer-blockchain-dev两个 explorer 查看）。自动化测试使用 Hardhat 网络zwsDev（live 路径：HCU cheat 测试跳过）。

九、深入：overlay 与解析机制的仓库证据

如果想进一步理解 preview env 的落地细节，ci/preview-env/README.md 提供了完整的布局说明。几个关键事实值得在这里一并给出：

• 每个文件都是某个 chart 的 values overlay。anvil-node/contracts/coprocessor/kms-connector/listener直接覆盖仓库根目录 charts 下的生产 Charts（从分支 checkout 安装，PR 的 chart 改动无需等待发布即可生效，且 overlay 永远不会落后于它们所配置的 chart）；relayer/test-suite/三个values-postgres-*-e2e.yaml则走通用的commonchart（与 zama-zws/gitops 的 fhevm-dev 环境相同），Postgres 用官方postgres:17-alpine镜像，刻意不用 Bitnami 的postgresqlchart（Bitnami 在 2025-08-28 重组了免费容器目录，导致该 chart 的新装被破坏）。
• host 链 Anvil 的典型 overlay：chainId12345、blockTime: "1"、120 个账户、slotsInAnEpoch: "1"、经典测试 mnemonictest test test ... junk，见 host-chain/values-anvil-host-e2e.yaml。
• relayer 的配置分层：静态/结构性配置（tuning、retry 策略、日志格式等）放local.yaml，动态配置（合约地址、链 URL、密钥、DB URL）用APP_前缀环境变量注入（env 总是覆盖文件），见 relayer/values-relayer-e2e.yaml。
• N-party 共识 vs RFC-021 blue-green 是两个不同模型：nb_coprocessor > 1是 N-party（1/2/3/5个链上身份，gatewayNUM_COPROCESSORS=N、COPROCESSOR_THRESHOLD=floor(N/2)+1）；blue-green 是同一身份的 two fleets（BCS 存活 v0.14.0-7 + GCS HEAD 编译为 0.15.0，共享 DB/S3/钱包），切换靠ProtocolConfig.proposeCoprocessorUpgrade加链下 N 方 operator 一致同意。blue-green不会注册 2N 个 gateway 槽位，与deploy_polygon及nb_coprocessor=1不兼容。
• 事件流水线采用 producer/broker/consumer 拆分：listener-<i>（charts/listener）作为 producer 读取 host 链并发布到每 party 专属的 iamguarded Redis；coprocessor 的hostListenerConsumer消费并写入 coprocessor DB（coprocessor chart 内置的hostListener在 e2e overlay 中被禁用）；coprocessor-poller-<i>负责在区块 finalize 后从 KMS public-vault S3 下载 ServerKey/PublicKey/CRS 填充keys/crs表——没有它，所有 worker 都会报 "No keys found in database"，且它必须在 keygen 触发之前部署（见 README 的 Multi-coprocessor 一节）。

十、小结

Preview env 是 fhEVM 仓库面向"真实 Charts + 真实 KMS 的端到端 PR 验证"而设计的部署系统，两条启动路径覆盖了从日常开发（PR 打标签）到精确控制（workflow_dispatch+overrides+ CLI--set）的全部诉求。核心心智模型可归纳为三点：

• 隔离性：每个 preview 独占一个fhevm-ci-*命名空间，命名规则（PR 作者/actor + PR 号/base36 run id）保证了部署与销毁永远对齐；
• 保真性：仓库内 Charts 直接从分支 checkout 安装、镜像优先从 PR 分支构建、专用 KMS 从不本地构建而是复用zama-ai/kms的官方 deploy 管道——预览的就是将要发布的；
• 可回收性：PR 关闭/移除标签自动销毁；dispatch 环境手动销毁；兜底命令与fhevm-ci-前缀 guard 双保险，避免 AWS 资源泄漏或误删命名空间。

对开发者而言，日常最常用的组合是：PR 上打preview-env-e2e-tests标签获得"部署 + 自动测试报告"，用preview-env watch <run-id>跟进进度，用preview-env status --ref查看最新部署，结束用preview-env destroy或直接关 PR 完成清理。需要调整拓扑或测试 KMS 构建时，再切换到workflow_dispatch路径。

【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm