企业官网建设流程全解析

fhEVM Coprocessor SQL Exporter：用 Helm + sql_exporter 把 Postgres 指标接入 Prometheus 的完整指南

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

导读

fhEVM 的 Coprocessor 是一个独立于链下运行的计算与中继引擎，其状态（已发送的交易、未完成的同态计算、待验证的 ZK Proof 等）全部持久化在 Postgres 数据库中。charts/coprocessor-sql-exporter是仓库中专门用于观测这套数据库的 Helm Chart：它打包了开源项目sql_exporter，预置了面向 Coprocessor 核心业务表的 SQL 查询，把“数据库里还有多少积压工作”这类关键信号转成 Prometheus 指标。读完本文，你将掌握该 Chart 的配置结构、config/queries.yml中每个指标背后的 SQL 逻辑，以及如何在 Kubernetes 和本地上快速部署、校验与抓取这些指标。

Chart 概览：职责与组成

charts/coprocessor-sql-exporter本身是一个薄封装 Chart（version 2.0.0），核心依赖来自外部仓库的sql-exporter（0.17.6）：

apiVersion: v2 name: fhevm-sql-exporter description: A Helm chart for Kubernetes type: application version: 2.0.0 dependencies: - name: sql-exporter repository: https://burningalchemist.github.io/sql_exporter/ version: 0.17.6

它共由三个核心文件构成，各自职责清晰：

其中的关键设计是“配置与部署分离”：所有 SQL 采集逻辑都集中在config/queries.yml，由模板 templates/configmap.yaml 原样读取并渲染为 ConfigMap：

apiVersion: v1 kind: ConfigMap metadata: name: coprocessor-sql-exporter-config data: sql_exporter.yml: |- {{ .Files.Get "config/queries.yml" | indent 4 }}

也就是说，当你在本机修改config/queries.yml并验证通过后，重新helm upgrade即可把新查询带到集群里——这正是 README 中“本地迭代 queries.yml”工作流的最终落点。

配置结构详解：config/queries.yml

全局（global）与目标（target）段

global: scrape_timeout: 10s scrape_timeout_offset: 500ms min_interval: 0s max_connections: 3 max_idle_connections: 3 target: data_source_name: '$DATA_SOURCE_NAME' collectors: - coprocessor-database

• scrape_timeout/scrape_timeout_offset：单次抓取的超时上限为 10s，并预留 500ms 偏移量，确保在 Prometheus 侧抓取超时前完成查询并返回。
• max_connections/max_idle_connections：对目标 Postgres 的连接池上限与空闲连接数上限均限制为 3。Coprocssor 主服务（gw-listener、sns-worker、tx-sender 等）本身就重度依赖数据库，这里刻意压低连接数，避免监控本身抢占业务连接配额。
• target.data_source_name：DSN 没有硬编码，而是引用环境变量$DATA_SOURCE_NAME，由 Secret 注入（见下文 values.yaml 分析），保证密码不落盘在 Chart 中。
• collectors：挂载名为coprocessor-database的采集器。

采集器 coprocessor-database：六组核心业务指标

采集器coprocessor-database设置了min_interval: 30s，即每条 SQL 至少每 30 秒才执行一次（且受全局scrape_timeout约束），对数据库的查询压力可控。六组指标全部为gauge类型，围绕 Coprocessor 数据模型中的关键业务表展开：

1. allowed_handles_txn_sent —— ACL 授权交易积压

- metric_name: allowed_handles_txn_sent type: gauge help: 'Number of allowed handles transactions sent' key_labels: - status values: [count] query: | SELECT 'txn_sent' AS status, count(*)::float AS count FROM allowed_handles WHERE txn_is_sent = true UNION ALL SELECT 'txn_unsent' AS status, count(*)::float AS count FROM allowed_handles WHERE txn_is_sent = false;

指标带status标签，拆分txn_sent/txn_unsent两个序列。表结构见 20250317140442_create_allow_handle.sql：allowed_handles记录每条 ACL 授权事件（event_type0 表示 allow account，1 表示 allow public decryption），txn_is_sent标记对应的允许交易是否已上链，txn_retry_count与txn_last_error则用于失败重试追踪。当txn_unsent持续增长时，说明 tx-sender 侧发送 ACL 交易出现积压，是排队/故障排查的关键信号。迁移 20251230155309_improve_sns_and_txsend_select_indexing.sql 中为allowed_handles (txn_is_sent)建立了索引，正是为了让这条计数查询在表变大后依然高效。

2. ciphertext_txn_sent —— 密文摘要上链积压

- metric_name: ciphertext_txn_sent type: gauge help: 'Number of ciphertext transactions sent' key_labels: - status values: [count] query: | SELECT 'txn_sent' AS status, count(*)::float AS count FROM ciphertext_digest WHERE txn_is_sent = true UNION ALL SELECT 'txn_unsent' AS status, count(*)::float AS count FROM ciphertext_digest WHERE txn_is_sent = false;

ciphertext_digest（建表见 20250310120834_create_ciphertext_digest.sql）存放密文摘要（ciphertext64/ciphertext128两个版本字段），txn_is_sent标记摘要交易是否已上链。该指标与allowed_handles_txn_sent结构完全对称，用于监控密文上链环节的健康度。迁移 20251203140023_ciphertext_digest_idx_sent_and_handle.sql 建立了(txn_is_sent, created_at)索引，同样是为这类“按未发送状态计数”的查询服务。

3. computations_completion —— 同态计算完成度

- metric_name: computations_completion type: gauge help: 'Number of computations done' key_labels: - status values: [count] query: | SELECT 'completed' AS status, COUNT(*)::float AS count FROM computations WHERE is_completed = true UNION ALL SELECT 'uncompleted' AS status, COUNT(*)::float AS count FROM computations WHERE is_completed = false;

computations是 Coprocessor 最核心的任务表之一（建表见 20240722111257_coprocessor.sql），记录每次同态运算：output_handle、fhe_operation（操作类型）、dependencies（依赖句柄数组）、is_scalar、is_completed、is_error等字段，主键为(tenant_id, output_handle)。uncompleted数量是判断计算积压的最直接指标——该值长期高企意味着 tfhe-worker / zkproof-worker 处理能力不足或调度出现问题。迁移脚本对该表围绕is_completed、is_error、dependence_chain_id、created_at建立了多组部分索引（见 20260120102002_unused_index_cleaning.sql 中的索引清单），说明“未完成计算”的筛选是生产环境的高频查询路径。

4. pbs_completion —— PBS 计算完成度

- metric_name: pbs_completion type: gauge help: 'Number of PBS done' key_labels: - status values: [count] query: | SELECT 'completed' AS status, COUNT(*)::float AS count FROM pbs_computations WHERE is_completed = true UNION ALL SELECT 'uncompleted' AS status, COUNT(*)::float AS count FROM pbs_computations WHERE is_completed = false;

pbs_computations（建表见 20250205130209_create_pbs_computations_table.sql）与computations结构相似但更精简（handle、created_at、completed_at、is_completed），用于追踪 Programmable Bootstrap（PBS）类操作的状态。uncompleted序列可以单独告警，帮助区分 PBS 密集场景下的负载特征。

5. ciphertexts —— 密文总量

- metric_name: ciphertexts type: gauge help: 'Number of ciphertexts in ciphertexts table' values: [count] query: | SELECT COUNT(*)::float AS count FROM ciphertexts;

直接统计ciphertexts表（建表见 20240722111257_coprocessor.sql）的总行数。该表主键为(tenant_id, handle, ciphertext_version)，保存每个密文句柄对应的实际密文内容。此指标反映数据库的数据规模与增长速度，可用于容量规划；由于是全表计数，在数据量大时其耗时也可能成为 scrape 的瓶颈。

6. zkproof —— ZK Proof 待处理量

- metric_name: zkproof type: gauge help: 'Number of remaining ZK-Proof to process' values: [count] query: | SELECT COUNT(*)::float AS count FROM verify_proofs;

统计verify_proofs表（建表见 20250207092623_verify_proofs.sql）的全部行数。该表记录待验证的 ZK Proof：zk_proof_id、chain_id、contract_address、user_address、input、handles、verified（三态：NULL 未验证 / true / false）、retry_count、last_error等。表上的索引idx_verify_proofs_verified_retry (verified, retry_count, zk_proof_id)表明系统按“验证状态 + 重试次数”的顺序消费任务。该指标的上升意味着 zkproof-worker 存在积压，是链上验证能力是否跟得上的直接证据。

指标背后的数据模型小结

values.yaml：部署参数的逐项说明

values.yaml 覆盖了镜像、凭据注入、监控抓取与配置挂载四个方面：

sql-exporter: replicaCount: 1 image: repository: hub.zama.org/zama-protocol/zama.ai/sql_exporter tag: "0.23.0" imagePullSecrets: - name: registry-credentials serviceMonitor: enabled: true interval: 30s # Disable inline config; we provide /etc/sql_exporter/sql_exporter.yml from # the ConfigMap rendered by templates/configmap.yaml. createConfig: false env: DATA_SOURCE_NAME: from: kind: Secret name: sql-exporter-config key: DATA_SOURCE_NAME extraVolumes: - name: sql-exporter-config volume: configMap: name: coprocessor-sql-exporter-config mount: readOnly: true mountPath: /etc/sql_exporter/sql_exporter.yml subPath: sql_exporter.yml

关键点：

• 镜像与拉取：使用 Zama 内部镜像仓库hub.zama.org/zama-protocol/zama.ai/sql_exporter:0.23.0，并通过imagePullSecrets: registry-credentials完成私有仓库鉴权。若你的集群可直连公共 Docker Hub，可将其替换为burningalchemist/sql_exporter对应版本。
• ServiceMonitor：enabled: true且抓取间隔30s，与采集器min_interval保持一致，说明该 Chart 面向 Prometheus Operator 生态，安装后会自动生成 ServiceMonitor 供 Prometheus 发现。
• createConfig: false：关闭依赖 Chart 自带的内联配置，改用下方 ConfigMap 提供的完整配置，保证配置源唯一（即仓库中的config/queries.yml）。
• env.DATA_SOURCE_NAME：从 Secretsql-exporter-config的DATA_SOURCE_NAME键注入连接串，对应config/queries.yml中的$DATA_SOURCE_NAME占位符。
• extraVolumes：把 ConfigMapcoprocessor-sql-exporter-config以readOnly方式挂载到容器内/etc/sql_exporter/sql_exporter.yml（subPath只挂载其中sql_exporter.yml一个键），即 sql_exporter 默认读取的配置路径。

在 Kubernetes 中安装

第一步：创建数据库连接 Secret

在发布命名空间（示例为coprocessor）中，先创建保存 DSN 的 Secret。README 给出的写法同时使用--dry-run与管道kubectl apply，实现“先本地生成、再幂等应用”，避免密码出现在 shell 历史之外的明文文件里：

kubectl -n coprocessor create secret generic sql-exporter-config \ --from-literal=DATA_SOURCE_NAME='postgres://coprocessor:<password>@<host>:5432/coprocessor' \ --dry-run=client -o yaml | kubectl apply -f -

Secret 名称sql-exporter-config与键名DATA_SOURCE_NAME必须与 values.yaml 中env段的引用完全一致。若数据库凭据后续轮换，只需重新 apply 该 Secret 并重启 Pod（或触发 rollout），无需改动 Chart。

第二步：拉取依赖并安装

helm dependency update helm upgrade --install fhevm-sql-exporter . -n coprocessor

• helm dependency update会把Chart.yaml声明的外部依赖（sql-exporter 0.17.6）下载到charts/目录，首次安装或升级依赖前必须执行；
• helm upgrade --install同时覆盖首次安装与后续升级场景，命名fhevm-sql-exporter，目标命名空间coprocessor。

第三步：验证抓取

安装完成后，通过 ServiceMonitor（interval: 30s）Prometheus 会自动发现并抓取该 exporter。也可以在集群内直接验证指标端点是否存活：

kubectl -n coprocessor port-forward svc/<sql-exporter-service> 9399:9399 curl -s localhost:9399/metrics | grep -E 'allowed_handles_txn_sent|computations_completion|zkproof'

本地运行与配置迭代

config/queries.yml在集群与本地共用同一份，因此可以完全在本地迭代 SQL、验证语法，再通过helm upgrade推送回集群。

校验配置语法（无需数据库）

sql_exporter -config.file config/queries.yml -config.check

该命令会解析 YAML 并解析 collector 引用，但不会连接 Postgres，因此此时不需要设置任何数据库环境变量。它是 CI 或本地改动后最快的第一道防线——能够尽早发现 YAML 缩进错误、metric 定义缺失等低级问题。

连接真实数据库抓取

当需要验证 SQL 本身（表名、字段、类型转换）是否正确时，指向一个可达的 Postgres 实例：

export DATA_SOURCE_NAME='postgres://coprocessor:$DATABASE_PASSWORD@localhost:5432/coprocessor' sql_exporter -config.file config/queries.yml curl -s localhost:9399/metrics

• 默认监听端口为9399，这是 sql_exporter 的默认 metrics 端口；
• 这里连接串使用了$DATABASE_PASSWORD变量（注意 shell 单引号内不会展开，需提前 export），与 Kubernetes 环境通过 Secret 注入的方式对应；
• curl -s localhost:9399/metrics输出中应能看到allowed_handles_txn_sent{status="txn_sent"}、zkproof等以fhevm_之外原始名称暴露的指标（实际名称即config/queries.yml中的metric_name）。

README 特别提示：sql_exporter二进制本身来自开源项目 burningalchemist/sql_exporter 的 release 页面，与 Chart 依赖的镜像版本（0.23.0）配套使用即可。

运维建议：如何用这些指标做告警

综合config/queries.yml的采集逻辑与 db-migration 中对应的表结构，可以给出以下可落地的监控口径（均为基于源码结构的推断建议，阈值需按实际负载标定）：

1. 上链积压告警：对allowed_handles_txn_sent{status="txn_unsent"}与ciphertext_txn_sent{status="txn_unsent"}设置持续增长告警，反映 tx-sender / sns-worker 发送交易滞后。
2. 计算积压告警：对computations_completion{status="uncompleted"}与pbs_completion{status="uncompleted"}设置水位告警，反映 tfhe-worker 处理能力不足。
3. ZK 验证积压告警：对zkproof设置阈值告警，结合verify_proofs表中verified三态与retry_count的索引设计，可在积压时进一步下钻查询具体失败原因。
4. 容量与性能：ciphertexts总量用于容量规划；若 scrape 耗时接近scrape_timeout: 10s，说明全表计数类查询开销过大，需考虑按 tenant 拆分或引入预聚合。

小结

charts/coprocessor-sql-exporter通过“外部 sql-exporter 依赖 + 自管 ConfigMap 配置 + Secret 注入 DSN + ServiceMonitor 接入”的组合，为 fhEVM Coprocessor 的 Postgres 数据库提供了一套开箱即用的 Prometheus 可观测性方案。其价值在于：六组指标精准对应当前仓库数据库迁移中真实存在的computations、pbs_computations、ciphertexts、ciphertext_digest、allowed_handles、verify_proofs表，让“计算积压、上链积压、ZK 积压”这些 Coprocessor 的核心健康信号可以直接进入告警与看板体系，而无需为监控编写额外的业务逻辑。

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