FHEVM Relayer 自托管部署完整指南打造权限无关的 FHE 网络接入节点【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本文是一份面向开发者和节点运营者的 FHEVM Relayer 自托管实战指南覆盖从环境准备、主网/测试网一键式引导、数据库与迁移、私钥安全管理到生产级配置调优与监控的全流程。读完本文你将掌握如何在 fhevm 仓库的relayer/模块下独立部署一个可处理公开解密public decryption、用户解密user decryption、输入证明校验input proof verification与 FHE 密钥材料分发key material distribution的 Relayer 服务并理解其底层实现原理与配置项的源码依据。Relayer 是什么FHEVM 主机链与 Zama Gateway 之间的桥梁FHEVM Relayer 桥接了两类网络FHEVM 主机链host chain例如 Ethereum L1负责托管 FHEVM 智能合约Zama GatewayGateway 链负责执行 FHE 计算、解密与密钥管理。Relayer 对外提供的核心能力包括公开解密Public Decryption转发 HTTP 公开解密请求并返回明文响应用户解密User Decryption将用户解密请求转发在密文句柄访问控制ciphertext-handle access control的前提下将数据用用户提供的公钥重新加密后返回输入证明校验Input Proof Verification转发输入证明校验请求并返回有效性证明密钥材料Key Material对外暴露 FHE 公钥与 CRS 的 URL/v2/keyurl。从事件驱动架构看Relayer 由 Orchestrator 统一协调事件流Gateway 监听器WSS 订阅接收链上事件HTTP Handler 处理 V2 API 请求SQL Repository 持久化请求状态并支持状态轮询Transaction Engine 配合 Throttler 负责可靠的交易发送与背压控制Metrics/Tracing 提供运行时可观测性。详细架构图见 relayer/README.md。权限无关Permissionless任何人只要自托管一个 Relayer即可获得对 FHEVM 网络的独立接入能力无需依赖第三方基础设施。为什么需要自托管运行自己的 Relayer 的核心价值在于获得对 FHEVM 网络的权限无关、独立访问能力不依赖任何第三方的公共节点或服务可用性对请求队列、超时策略、交易节流throttling、数据保留策略拥有完全控制权可自主扩缩容按需调整数据库连接池、监听器数量等资源参数。环境准备自托管前需要准备以下环境依赖说明Rust 工具链 Cargo通过 rustup 安装用于编译并运行fhevm-relayer二进制Docker Docker Compose v2用于启动本地 PostgreSQL端口 5433Foundrycast仅用于网络接入引导流程make preflight-*、make mint-zama-*、make approve-payment-*负责钱包地址推导、余额查询与授权交易已注资的钱包同时持有 ETHGas与 $ZAMA 代币所有部署命令均在仓库的relayer/目录下执行。执行make help可查看全部可用的 Make 目标。主网Mainnet自托管前置条件Gateway 链上的 ETH用于 Gas从 Arbitrum One 通过 Zama Bridge 跨链到 Gateway 主网chain id261131Gateway 链上的 $ZAMA 代币购买 $ZAMA 后通过 Zama Bridge 从 Ethereum L1 跨链到 Gateway 主网一个 Ethereum L1 RPC 端点config/local.mainnet.yaml.example中默认使用公共节点https://ethereum-rpc.publicnode.com可用于测试但有速率限制生产环境建议替换为自有的 L1 RPC。Step 1启动数据库make db-start该命令通过 dev/docker-compose.yaml 启动一个本地 PostgreSQL 实例容器内端口5432映射到宿主机5433避免与常见本地 PostgreSQL 冲突。数据库名为relayer_db默认用户/密码为postgres/postgres。Makefile 中定义的连接串为DATABASE_URL : postgresql://postgres:postgreslocalhost:5433/relayer_db启动后_db-wait会探测容器内的pg_isready最长等待 30 秒直到 PostgreSQL 就绪。Step 2应用数据库迁移make db-migrate该目标运行独立的relayer-migratecrate见 relayer/relayer-migrate/以MAX_ATTEMPTS20在连接失败时自动重试并将 13 个 SQL 迁移文件按序应用到数据库DATABASE_URLpostgresql://postgres:postgreslocalhost:5433/relayer_db MAX_ATTEMPTS20 \ cargo run --manifest-path relayer-migrate/Cargo.toml --bin relayer-migrateStep 3运行预检引导Preflightmake preflight-mainnet这是一个交互式接入向导其内部逻辑实现在 relayer/Makefile 的_preflight目标中具体执行若config/local.mainnet.yaml不存在则从config/local.mainnet.yaml.example模板复制生成通过init-mainnet并交互式提示输入钱包私钥写入gateway.tx_engine.private_key字段使用cast wallet address --private-key $pk推导出钱包地址通过cast balance向主网 RPChttps://rpc.mainnet.zama.org/查询Gateway ETH 余额通过cast call调用 ZAMA 代币合约的balanceOf(address)(uint256)查询$ZAMA 余额主网与测试网代币合约地址均为0xcE762c7FDaac795D31a266B9247F8958c159c6d4通过cast call调用代币合约的allowance(address,address)(uint256)检查钱包是否已授权 ProtocolPayment 合约花费 $ZAMA若余额或授权缺失向导会提示操作指引ETH 不足时提示跨链地址$ZAMA 不足时提示购买与跨链授权缺失时提示运行make approve-payment-mainnet在获得你确认后也可自动执行。ProtocolPayment 合约地址由 Makefile 定义网络ProtocolPayment 地址Mainnet0x7E179E45E5fe0a21015Be25185363B4F2F2F7e89Testnet0xAA1d9D4927A62f842F0DE5AD6b8dFDB074Fa62f2make approve-payment-mainnet会发送一笔approve(address,uint256)交易将MAX_UINT256即115792089237316195423570985008687907853269984665640564039457584007913129639935作为最大授权额度授予 ProtocolPayment 合约并回读确认授权结果。向导还支持通过YES1/NO1环境变量自动接受或拒绝交互提示便于脚本化。Step 4启动 Relayermake run-mainnet以主网配置启动服务实际执行的命令为cargo run --bin fhevm-relayer -- --config-file config/local.mainnet.yaml启动前会校验配置文件存在且private_key非空。运行前必须保证本地 PostgreSQL 已启动make run-mainnet依赖_check-postgres。Step 5验证健康状态make health该目标通过curl依次检查以下端点GET http://localhost:3000/liveness—— 存活探针GET http://localhost:3000/healthz—— 就绪/健康检查GET http://localhost:3000/version—— 构建版本信息GET http://localhost:3000/metrics—— Prometheus 指标打印前 10 行。若服务不可达会提示 Relayer is not reachable at localhost:3000。测试网Testnet自托管测试网的流程与主网完全一致仅代币来源不同ETH通过测试网桥从 Arbitrum Sepolia 跨链到 Gateway 测试网chain id10901$ZAMA测试网不提供自助获取需要向 Relayer 团队申请发放到你的钱包地址。make db-start make db-migrate make preflight-testnet make run-testnet make health其中make run-testnet实际执行为cargo run --bin fhevm-relayer -- --config-file config/local.testnet.yamlRPC 为https://rpc.testnet.zama.org/。注意测试网配置模板中的 KMS 公钥与 CRS URL 指向kms-public.testnet.zama.org主网模板则指向kms-public.mainnet.zama.org二者的data_id与链 ID 也不同。私钥管理与安全最佳实践配置文件将私钥存放在gateway.tx_engine.private_key字段中。安全实践要点切勿将config/local.mainnet.yaml或config/local.testnet.yaml提交到版本控制它们已被加入.gitignore环境变量覆盖设置APP_GATEWAY__TX_ENGINE__PRIVATE_KEY0x...可以完全避免把私钥写入配置文件。这一机制源于 relayer/src/config/settings.rs 中基于configcrate 的加载逻辑配置按YAML 文件 → 环境变量APP_前缀、__表示层级嵌套→ CLI 参数的优先级合并使用专用钱包运行 Relayer避免与主钱包混用降低私钥泄露风险面。此外配置文件还支持 AWS KMS 签名器替代方案gateway.tx_engine.signer.type: aws_kms可在生产环境将私钥托管在云端 KMS 中避免明文私钥落盘。配置参考可调字段详解relayer/docs/SELF_HOSTING.md 给出了运维人员最常调整的字段清单默认值来自代码与配置模板字段说明默认值http.endpointAPI 监听地址0.0.0.0:3000log.format日志格式compact、pretty、jsonprettygateway.tx_engine.tx_throttlers.*.per_seconds每种操作类型的交易节流速率20storage.app_pool.max_connections应用连接池最大数据库连接数10storage.cron.timeout_cron_interval超时 Worker 的运行频率60sstorage.cron.public_decrypt_timeout公开解密请求超时30mstorage.cron.user_decrypt_timeout用户解密请求超时30mstorage.cron.input_proof_timeout输入证明请求超时30mstorage.cron.expiry_enabled是否启用自动数据清理falsestorage.cron.public_decrypt_expiry公开解密记录保留期365dstorage.cron.user_decrypt_expiry用户解密记录保留期7dstorage.cron.input_proof_expiry输入证明记录保留期7dhttp.retry_after.max_secondsRetry-After响应头的最大值300http.enable_admin_endpoint是否启用/admin/config运行时配置见下方安全说明false配置层级YAML → 环境变量 → CLI 参数配置是分层级的先加载 YAML 文件再用带APP_前缀、__嵌套分隔的环境变量覆盖最后 CLI 参数如--config-file优先级最高。示例APP_GATEWAY__BLOCKCHAIN_RPC__HTTP_URLhttps://rpc.example.org等价于修改 YAML 中的gateway.blockchain_rpc.http_url。完整的主网/测试网/本地配置模板分别见relayer/config/local.mainnet.yaml.examplerelayer/config/local.testnet.yaml.examplerelayer/config/local.yaml.example值得注意的实现细节配置在加载后会经过GatewayConfig::validate()校验见 relayer/src/config/settings.rs例如http_url/read_http_url必须以http://或https://开头否则启动失败并返回明确的错误信息。关键底层机制超时 Worker 与数据保留超时 Worker始终启用后台任务周期性地把在receipt_received状态停留超过配置时长的请求标记为timed_out。其实现位于 relayer/src/store/sql/repositories/timeout_repo.rs对user_decrypt_req、public_decrypt_req、input_proof_req三张表分别执行UPDATE ... FOR UPDATE SKIP LOCKED的原子更新错误原因为 Gateway chain did not respond within the expected timeframe并同时记录状态流转指标。数据保留默认关闭清理 Worker 会按保留窗口删除已完结成功或失败的旧记录实现位于 relayer/src/store/sql/repositories/expiry_repo.rs。默认不启用如需启用请设置expiry_enabled: true并确保数据库用户对相关表拥有DELETE权限也可以手动执行等价的DELETESQL 完成清理。Admin 端点安全/admin/configGET/POST主要用于测试与压测场景可在运行时调整节流器 TPS 与Retry-After字段。它默认关闭且刻意不提供应用层认证——启用时必须通过网络层手段限制可达性将http.endpoint绑定到回环地址127.0.0.1:3000或仅内部子网或将端点置于认证层如 API 网关之后。监控与可观测性Prometheus 指标:9898端口GET /metrics应用健康:3000端口/liveness存活、/healthz就绪指标与 Grafana 面板参见 relayer/src/metrics/docs_and_dashboards/http_metrics.md 等文档包含 HTTP 请求量、错误率、延迟分位数等 R.E.D. 指标的完整定义与 PromQL 查询示例。HTTP 层核心指标包括relayer_http_requests_totalCounterVecendpoint、method、versionrelayer_http_responses_totalCounterVec按status分类relayer_http_request_duration_secondsHistogramVec请求延迟桶由http.metrics.histogram_buckets配置。请求超时、交易发送耗时、队列深度等也在relayer/src/metrics/下按模块拆分暴露。完整的 V2 API 语义异步 POST GET 轮询、Retry-After动态计算、统一响应信封、请求去重等可参考 relayer/docs/http-api-design.md。故障排查主 README 的 Troubleshooting 章节 总结了常见问题这里列举与自托管强相关的几条PostgreSQL 使用 5433 而非 5432本地开发库映射到 5433 以避免端口冲突。出现 connection refused 时请确认目标端口是 5433配置模板包含 localhost/mock URLconfig/local.yaml.example内置localhost:8757RPC 与0.0.0.0:3001密钥 URL只适用于本地 mock 栈。接入测试网/主网时必须使用make preflight-testnet/make preflight-mainnet它们会自动复制对应的正确示例配置Docker 内存在本地完整栈上运行./fhevm-cli deploy需要至少 12 GB 的 Docker 内存配额Git worktree 破坏 Docker 构建Relayer 的 Dockerfile 会挂载.git/HEAD、.git/objects、.git/refs用于版本信息嵌入而 worktree 中.git是文件而非目录会导致挂载失败请在主克隆中构建。小结自托管 FHEVM Relayer 是一条完整可控的接入路径通过make db-start、make db-migrate、make preflight-*、make run-*、make health五个命令即可完成从数据库、引导检查到服务运行与健康验证的全流程。在接入之后通过配置表中的节流速率、超时窗口、连接池与保留策略等字段可以针对实际流量对服务进行精细化调优结合:9898的 Prometheus 指标与源码级的超时/保留 Worker 实现运营者可以完全掌握请求生命周期中的每一个状态流转。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考