fhevm-relayer 本地开发指南：构建、测试、Lint 与本地协议栈全流程

fhevm-relayer 本地开发指南构建、测试、Lint 与本地协议栈全流程【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本文是 fhevm 仓库中 relayer/docs/DEVELOPMENT.md 的深度展开版面向需要在本地克隆、构建、测试并调试 fhevm-relayer 的开发者。fhevm-relayer 是 fhevm 生态中连接宿主链如 Ethereum与 Gateway 的桥接服务承担公开解密public decryption、输入证明校验input proof verification、用户解密user decryption与密钥材料 URLkeyurl等关键能力。读完本文你将掌握一条命令完成本地开发环境初始化、按测试组精确运行集成测试、在本地拉起完整 Zama 协议栈并注入自建 relayer 镜像、管理本地 PostgreSQL、执行 lint/format 门禁以及构建可发布的 Docker 镜像。面向运维/自托管部署的说明请参见 SELF_HOSTING.md贡献规范参见 CONTRIBUTING.md。目录环境与前置条件首次设置一条命令完成开发环境初始化运行测试nextest 与按组执行Local Stack本地运行完整 Zama 协议Lint 与格式化数据库管理Docker 镜像构建故障排查仓库源码导读环境与前置条件在动手之前请确认本机具备以下工具链见 relayer/README.md依赖用途Rust 工具链 Cargo编译、运行与测试 relayer 本体Docker Docker Compose v2本地 Postgres、本地协议栈、镜像构建Foundrycast仅网络对接类目标需要make preflight-*、make mint-zama-*、make approve-payment-*Node.js npm仅make api-lint需要工具链版本以仓库内 rust-toolchain.toml 为准当前 channel 为1.97.1包含rustfmt与clippy组件。运行make help可随时查看全部可用目标。首次设置一条命令完成开发环境初始化make setup # 启动 Postgres、执行迁移、复制配置模板该命令聚合了本地开发所需的全部初始化工作对应 Makefile 中的setup目标实际依次执行启动本地 PostgreSQL通过 Docker Compose 拉起实例映射到5433 端口刻意避开默认的 5432避免与系统自带 Postgres 冲突。对应make db-start。执行数据库迁移使用独立的relayer-migrate二进制cargo run --manifest-path relayer-migrate/Cargo.toml --bin relayer-migrate应用全部 schema 迁移最多重试 20 次。对应make db-migrate。复制配置模板若config/local.yaml不存在则将config/local.yaml.example复制为config/local.yaml。本地 Postgres 的完整定义在 dev/docker-compose.yaml数据库名relayer_db、用户/密码均为postgres、启用trust认证并配置了pg_isready健康检查、命名卷postgres_data持久化数据。值得注意的是它的启动参数把max_connections抬高到了500并预加载了pg_cron扩展——这是为了给并行的集成测试留出连接余量详见下文测试一节。本地连接串由 Makefile 统一派生DATABASE_URL : postgresql://postgres:postgreslocalhost:5433/relayer_db提示Makefile 中的_db-probe前置检查会同时校验DB_PORT/DB_NAME与dev/docker-compose.yaml的一致性以及 Postgres 是否真正在 5433 端口就绪。如果手工修改了其中一方而未同步另一方make会在运行前直接报错而不是连到错误的地方。运行测试nextest 与按组执行relayer 的测试体系运行在 nextest 之上测试目标会直接检查cargo-nextest是否安装见 Makefile 的_check-nextest因此第一步是安装它cargo install cargo-nextest --locked随后可以运行make test # 完整套件与 CI 完全一致需要 Postgres make test-unit # 仅 src/ 下的单元测试与文档测试不需要 Postgresmake test-unit实际上执行两部分cargo nextest run --lib单元测试与cargo test --workspace --docnextest 不跑 doctest所以交给 cargo 自己。而make test-integration会先单独跑ethereum_rpc_mock测试 crate再以--features integration-tests --test *模式运行 tests/ 下所有测试二进制。按测试组精确执行测试被划分为若干组group一组对应一个测试二进制其语义是一条 API 流程如public-decrypt或流程间共享的横切特性如listener-redundancy。组的定义与成员映射全部集中在 Makefile例如public-decrypt→public_decrypt_v2_testinput-proof→input_proof_v2_testuser-decrypt→user_decrypt_v2_testuser_decrypt_v3_testrestart→shutdown_testhandled_events_testrecovery_test进程存活这一行为被合并为一组listener-redundancy、dispatcher-lock、sweep、epoch-fencing等横切特性各占一组按组执行的方式make test-groups # 列出全部可用组名 make test-group GROUPpublic-decrypt # 跑一个组内的全部用例 make test-group GROUPpublic-decrypt CASEacl # 仅跑名称匹配 acl 子串的用例 make test-group GROUPpublic-decrypt SKIPtimeout # 排除名称匹配 timeout 的慢用例CASE与SKIP会合成为 nextest 的过滤器表达式例如test(acl) and not test(timeout)见 Makefile。并发模型与连接预算测试默认8 个并发与 CI 相同且 nextest 的调度池横跨所有测试二进制而不是一个二进制跑完再跑下一个。每个测试使用独立的 schema大约占用3 条 Postgres 连接因此并发上限由服务端max_connections决定CI 中是 100本地是 500见 dev/docker-compose.yaml 的max_connections500。想加快本地运行可在任意上述命令后追加TEST_THREADS32调试单个用例时可使用TEST_THREADS1串行化。组与测试文件的强一致性校验Makefile 还提供了make test-groups-check它对比组中声明的测试文件与磁盘上实际存在的tests/*.rs任何不在任何组中的测试文件或组中声明却不存在的测试文件都会让构建失败——确保 CI 不会漏跑新写的测试也不存在从未被执行的孤儿测试。CI 会执行该校验。测试用配置见 tests/relayer-test-config.yaml其结构是 config/local.yaml.example 的近亲差异点包括更快的 keyurl 轮询间隔、关闭负载均衡等待时间等专门为测试场景调优。Local Stack本地运行完整 Zama 协议这一模式通过 fhevm 仓库的fhevm-cli在本地跑起整套 Zama 协议然后把你本地构建的 relayer 镜像注入其中非常适合做端到端联调。部署 Zama 协议git clone gitgithub.com:zama-ai/fhevm.git cd fhevm/test-suite/fhevm ./fhevm-cli deploy该步骤需要 Docker 至少分配12 GB 内存。这也是 relayer/README.md 明确记录的硬性要求。构建并注入本地 relayer 镜像fhevm-cli 的 Docker Compose 栈期望镜像名带 registry 前缀因此先用带时间戳的 tag 构建本地镜像LOCAL_RELAYER_TAGlocal-relayer-$(date %Y%m%d%H%M%S) make docker-release TAG${LOCAL_RELAYER_TAG}make docker-releaseMakefile会依次构建relayer与relayer-migrate两个镜像并打上ghcr.io/zama-ai/console/前缀同时校验 TAG 不能是latest。随后在 fhevm 栈目录中升级 relayer# 在 fhevm/test-suite/fhevm 目录下执行 RELAYER_VERSION${LOCAL_RELAYER_TAG} \ RELAYER_MIGRATE_VERSION${LOCAL_RELAYER_TAG} \ ./fhevm-cli upgrade relayer验证运行中的镜像确认升级后容器实际使用的镜像docker inspect fhevm-relayer --format {{.Config.Image}} docker inspect relayer-db-migration --format {{.Config.Image}}两条命令应分别输出你构建的local-relayer-时间戳镜像。通过 fhevm-cli 运行 E2E 测试./fhevm-cli test input-proof停止本地栈./fhevm-cli cleanLint 与格式化make check # fmt clippy推荐的 push 前门禁 make fix # 自动修复 fmt clippy 问题 make clippy # 仅 clippy make fmt # 仅格式检查make check是推荐的pre-push 门禁它同时运行fmt --check与clippy但不启动 Postgres、不跑测试因此非常快。其实际组成Makefile还包括openapi-check——它会重新生成 OpenAPI 规范并git diff校验openapi.yml是否漂移。值得注意的细节make clippy使用cargo clippy --workspace --all-targets --all-features -- -D warnings把任何 clippy 警告都升级为错误防止警告悄悄堆积。make fmt只针对本仓库拥有的包fhevm-relayer与ethereum_rpc_mock刻意排除了通过路径依赖引入的生成代码如gateway-contracts/rust_bindings、host-contracts/rust_bindings因为这些不是 relayer 团队可以格式化的代码。make fix依次执行fmt-fix与clippy-fixclippy 以--fix --allow-dirty --allow-staged自动应用修复。数据库管理生命周期管理make db-start # 启动本地 Postgres5433 端口并等待就绪 make db-stop # 停止 Postgres保留数据 make db-destroy # 停止 Postgres 并清空所有数据-v 删除卷 make db-reset # 清空并从头重新执行迁移 make db-status # 显示容器状态 连接测试 make db-shell # 打开 psql shell make db-logs # 跟踪 Postgres 容器日志其中db-reset是先db-destroy再db-start再db-migrate的组合适合需要从干净 schema 重跑测试的场景。db-migrate依赖relayer-migrate二进制执行迁移带连接重试迁移脚本位于 relayer-migrate/migrations/例如建表、job id 唯一约束、请求类型演进、sweep 索引等回滚脚本位于 relayer-migrate/down/。sqlx-cli 目标这些目标依赖sqlx-cli。安装时必须固定到 0.8.x 系列因为 sqlx-cli 0.9.0 将 MSRV 提升到了 rustc 1.94而rust-toolchain.toml指定的工具链更高当前 1.97.1但仓库注释中明确建议的版本为 0.8.6cargo install sqlx-cli --version 0.8.6 --no-default-features --features postgres,rustls安装后make sqlx-migrate # 通过 sqlx-cli 执行迁移 make sqlx-prepare # 重新生成离线元数据供 CI / Docker 构建使用关键约束Docker 构建依赖预计算的查询元数据.sqlx/仓库根relayer/.sqlx/下是一批query-*.json文件配合SQLX_OFFLINE使用。因此每当你新增或修改 SQL 查询必须先在本地运行make sqlx-prepare再构建 Docker 镜像否则离线构建会基于过期的元数据编译通过却描述错误的数据访问。make sqlx-check可以在 CI 中只校验不写入用于及时发现.sqlx/与迁移的漂移。Docker 镜像构建make docker-build # 构建 relayer 镜像 make docker-build-migrate # 构建 relayer-migrate 镜像 make docker-build-all # 同时构建上述两者 make docker-release TAGv0.9.0-rc.1 # 带 registry 前缀构建TAG 必填构建细节Dockerfile构建阶段使用 golden 基础镜像ghcr.io/zama-ai/fhevm/gci/rust-glibc:${RUST_IMAGE_VERSION}Rust 版本由 rust-toolchain.toml 单一来源派生Makefile 用 awk 读取channel字段保证本地与 CI 一致。Dockerfile 通过 bind mount 引入仓库根级路径依赖gateway-contracts/rust_bindings、host-contracts/rust_bindings、shared/user-decryption-signature、shared/ciphertext-attestation这正是 relayer 作为 monorepo 子项目、跨 crate 依赖多个绑定库的体现。构建以--locked --release进行并挂载 cargo registry 与 target 缓存加速增量构建。运行阶段使用最小化镜像创建非特权用户appuserUID 10001并以该用户运行/bin/server。Git worktree 限制relayer 的 Dockerfile 需要真实的.git/目录而非 worktree用于构建期版本信息嵌入。在 Git worktree 中.git是一个文件而非目录会导致挂载失败。请从主克隆primary clone构建这也是 README 排障章节 记录的已知问题。故障排查完整的排障清单见 relayer/README.md 的 Troubleshooting 章节以下是几个高频问题速查症状原因与解决connection refused本地 Postgres 映射在5433而非 5432。确认连接串使用localhost:5433。Docker 构建失败Git 挂载错误正在 worktree 中构建。改用主克隆构建。构建通过但查询行为与 schema 不符.sqlx/离线元数据过期。运行make sqlx-prepare后重新构建。本地协议栈起不来./fhevm-cli deploy需要 Docker 至少12 GB 内存。配置连到 mock 地址config/local.yaml.example内置localhost:8757RPC 与0.0.0.0:3001keyurl仅适用于本地 mock 栈对接 Testnet/Mainnet 应使用make preflight-testnet/make preflight-mainnet它们会自动复制正确的示例配置。仓库源码导读如果你想进一步深入下面这些路径是继续阅读的起点Makefile本文所有命令的权威定义自文档化make help可读。dev/docker-compose.yaml本地 Postgres 的完整定义端口、连接上限、pg_cron。config/local.yaml.example本地开发配置模板覆盖 keyurl、listener_pool、tx_engine 节流器、readiness_checker、动态 retry-after、cron 超时/过期策略、dispatcher_lock 等全部可调参数。tests/全部集成测试二进制与 Makefile 中的BINS_group一一对应。tests/relayer-test-config.yaml集成测试专用配置。relayer-migrate/独立迁移 crate含迁移脚本与回滚脚本。docker/relayer/Dockerfile 与 docker/relayer-migrate/Dockerfile镜像构建定义。rust-toolchain.toml工具链单一事实来源。SELF_HOSTING.md面向运维的自托管部署指南。README.md服务能力总览、API 端点、超时与数据保留策略、排障。整个 fhevm 仓库是一个 monoreporelayer 与 gateway-contracts、host-contracts、shared 等模块通过路径依赖联动理解这一点有助于把握构建上下文。开发期间一切以make help的输出为最权威的操作清单。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考