企业官网建设流程全解析

Aptos 遥测服务全解：节点遥测的 Noise 认证、自定义合约信任链与配置实战

【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core

Aptos 遥测服务（aptos-telemetry-service）是 Aptos 网络中集中收集节点指标、日志与自定义事件的独立 Rust 服务。本文以官方规格文档 SPEC.md 为骨架，结合 lib.rs、auth.rs、custom_contract_auth.rs 等源码及端到端测试配置逐项展开。读完后你应能理解：标准节点如何通过 Noise IK 握手换发 JWT、第三方应用如何用链上白名单实现"自定义合约认证"、以及一套可直接落地的 YAML 配置、限流与缓存机制。

1. 服务定位与总体架构

遥测服务支持两类认证模式：

1. 标准节点认证（Standard Node Authentication）：面向验证者（Validator）、验证者全节点（VFN）与公共全节点（PFN）等 Aptos 网络内节点，认证依据是 Noise 协议握手 + 验证者集校验；
2. 自定义合约认证（Custom Contract Authentication）：面向维护自己链上白名单的第三方应用（例如存储节点、RPC 提供商），认证依据是 Ed25519 挑战-应答 + 链上白名单查询。

两类模式的数据最终都汇入相同的后端存储（Backend Sinks）：

┌─────────────────────────────────────────────────────────────────────────────┐ │ Aptos Telemetry Service │ ├─────────────────────────────────────────────────────────────────────────────┤ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Standard │ │ Custom │ │ Standard │ │ Custom │ │ │ │ Auth │ │ Contract │ │ Ingest │ │ Contract │ │ │ │ (/auth) │ │ Auth │ │ Endpoints │ │ Ingest │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ └─────────────────┴──────────────────┴─────────────────┘ │ │ │ │ │ JWT Service │ │ │ │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Backend Sinks │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Victoria │ │ Humio │ │ Loki │ │ BigQuery │ │ │ │ Metrics │ │ (Logs) │ │ (Logs) │ │ (Events) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘

所有路由统一挂载在/api/v1前缀下，由 index.rs 中的routes()组装：index、health、chain-access、auth、标准三类 ingest、telemetry_log_env，以及自定义合约的auth-challenge/auth/ 三类 ingest 端点，并统一挂上 GCP Cloud Trace 上下文（X-Cloud-Trace-Context）的 tracing span。

从源码结构看，服务还启动了若干后台任务（见 lib.rs）：

• PeerSetCacheUpdater：仅在配置了trusted_full_node_addresses时启动，周期拉取验证者/VFN 集合；
• AllowlistCacheUpdater：仅在配置了custom_contract_configs时启动，周期刷新链上白名单缓存，周期即allowlist_cache_ttl_secs；
• PeerLocationUpdater：依赖 BigQuery 客户端，不可用时自动禁用；
• PrometheusExporter：向自身监控端点导出服务自监控指标。

2. 标准节点认证：Noise 握手 + 验证者集校验

2.1 节点类型

类型判定逻辑在 auth.rs：握手解出的公钥若命中验证者/VFN 集合则按集合角色归类；未命中时，若role_type为 FullNode 且 peer_id 在pfn_allowlist中则判为PublicFullNode，否则判为UnknownFullNode/UnknownValidator。未知节点不被拒绝，而是获得带"未知"身份的 JWT，其数据被路由到 untrusted 汇聚端点（并受全局限流约束）。

2.2 三步认证流程

1. 节点GET /api/v1/获取服务端的 X25519 公钥（IndexResponse { public_key }，见 index.rs）；
2. 节点POST /api/v1/auth，请求体为 AuthRequest：chain_id、peer_id、role_type（默认Validator）、server_public_key、handshake_msg（Noise IK 客户端初始化消息）、run_uuid（缺省为零值 UUID）；服务端校验服务端公钥一致后完成握手，并把 JWT 作为载荷加密在 Noise 响应消息中返回（AuthResponse { handshake_msg }）；
3. 节点携带Authorization: Bearer <JWT>调用各 ingest 端点。

2.3 Noise IK 协议细节

协议：Noise IK，Ed25519/X25519 密钥。Prologue布局为chain_id (1 字节) | peer_id (32 字节) | server_public_key (32 字节)，构建代码见 auth.rs。

服务端的校验步骤（同样在 auth.rs 中实现）：

1. 请求中的server_public_key必须与当前 Noise 配置的公钥一致，否则 400（帮助客户端发现用错服务端公钥）；
2. 用 prologue 解析客户端初始化消息，取出客户端 X25519 公钥；解析失败返回 400；
3. 按role_type选择验证者集或 VFN 集，查询该chain_id下的缓存；若该链的集合尚未拉取到，返回 401（ValidatorSetUnavailable）；
4. peer_id 命中集合时，握手解出的公钥必须在该 peer 注册的公钥列表中，否则 403（PeerPublicKeyNotFound）；
5. peer_id 未命中时，用握手公钥派生 peer_id（from_identity_public_key）与请求声明的 peer_id 比对，不一致返回 403（PublicKeyMismatch），一致则按 Unknown 节点处理；
6. 依据角色生成对应NodeType，签发 JWT 并随 Noise 响应加密返回。

2.4 JWT Claims

JWT 载荷结构见 Claims：

{ "chain_id": 1, "peer_id": "0x...", "node_type": "Validator", "epoch": 123, "run_uuid": "uuid-v4", "iat": 1234567890, "exp": 1234571490 }

其中node_type携带节点类型（对自定义合约客户端则携带合约名，见第 3.5 节），epoch为认证时所在 epoch，run_uuid用于标识一次节点运行会话。

2.5 标准 API 端点

2.6 三类 Ingest 细节

指标（POST /api/v1/ingest/metrics）：请求头需Authorization: Bearer <jwt>，可选Content-Encoding: gzip；Body 为 Prometheus exposition 格式（文本或 protobuf）。服务会附加如下标签：role（节点类型）、chain_name、namespace=telemetry-service、kubernetes_pod_name（peer_id:{identity}//{peer_id_hex}或peer_id:{peer_id_hex}）、run_uuid、metrics_source=telemetry-service。路由上，已知节点（Validator/VFN/PFN）写入ingest_metrics客户端，未知节点写入untrusted_ingest_metrics客户端（对应 MetricsEndpointsConfig 的三个端点分组，外加服务自监控端点telemetry_service_metrics）。

日志（POST /api/v1/ingest/logs）：Body 为日志消息字符串的 JSON 数组。附加标签：chain_id、peer_role、run_uuid；附加字段：peer_id、epoch。路由上已知节点 →known_logs_endpoint，未知节点 →unknown_logs_endpoint（见 LogIngestConfig，支持可选的blacklist_peers黑名单）。

自定义事件（POST /api/v1/ingest/custom-event）：

{ "client_id": "string", "user_id": "peer_id_hex", "timestamp_micros": "1234567890000", "events": [ { "name": "event_name", "params": { "key": "value" } } ] }

目标为 Google BigQuery 表（由custom_event_config指定project_id/dataset_id/table_id）。BigQuery 为可选项：启动时若未设置GOOGLE_APPLICATION_CREDENTIALS或其无效，服务会记录警告并禁用相关功能，而不是启动失败（见 lib.rs）。

3. 自定义合约认证：链上白名单与挑战-应答

自定义合约让第三方应用以"自己的链上白名单"接入遥测服务，每个合约一份独立配置（custom_contract_configs数组）。

3.1 节点类型

另有Open Telemetry 模式：当on_chain_auth与static_allowlist均未配置时，allow_unknown_nodes必须为true，否则服务启动时直接 panic（校验逻辑见 CustomContractConfig::validate）。此模式下所有节点按 unknown 处理，但签名验证依然强制要求——节点必须证明自己控制所声明的地址。

3.2 信任判定流程

认证请求 │ ▼ 1. 验证 Ed25519 签名（证明地址所有权，任何模式都强制） │ ▼ 2. 查 static_allowlist ──► 命中 ──► TRUSTED（NodeType::Custom） │ 未命中 ▼ 3. 是否配置了 on_chain_auth？ │ 否（Open 模式）──► UNTRUSTED（NodeType::CustomUnknown） │ 是 ▼ 4. 查链上白名单缓存 ├─ 在名单中 ──────────► TRUSTED（NodeType::Custom） ├─ 不在名单 + allow_unknown_nodes=true ──► UNTRUSTED（CustomUnknown） ├─ 不在名单 + allow_unknown_nodes=false ──► 403 REJECTED └─ 缓存未就绪（CacheMiss）────► 403 REJECTED

该流程与 custom_contract_auth.rs 中handle_auth的分支完全一致。信任来源的优先级为：1)static_allowlist（纯配置信任，无链上调用开销，适合"知道运营方地址但不想承担链上查询成本"的 RPC 场景）；2)on_chain_auth（链上白名单动态信任）；3)allow_unknown_nodes（放行但未受信，数据路由到 untrusted 汇聚端点）。

3.3 认证流程与防重放

三步流程（端点均见 custom_contract_auth.rs）：

1. POST /api/v1/custom-contract/{name}/auth-challenge，请求体{ address, chain_id }；合约未配置时直接返回 403。服务端生成随机 UUID 作为 challenge，存入挑战缓存并返回{ challenge, expires_at }（expires_at为 Unix 秒）；
2. POST /api/v1/custom-contract/{name}/auth，请求体{ address, chain_id, challenge, signature, public_key }（32 字节 Ed25519 公钥）；服务端依次校验：合约存在 →挑战存在、未过期且先被消费→ 签名有效且公钥可派生出所声明的地址 → 按 3.2 判定信任级别 → 签发 JWT；
3. 携带 JWT 调用/api/v1/custom-contract/{name}/ingest/{metrics|logs|custom-event}。

安全性要点（均有源码佐证）：

• 挑战先消费后验签：verify_and_consume在签名验证之前执行（custom_contract_auth.rs），挑战一次性，防止重放，也防止客户端自造挑战绕过；
• 签名验证永远执行：即使 Open 模式也必须证明地址所有权（custom_contract_auth.rs 的verify_signature）；
• 挑战缓存隔离：缓存键为(contract_name, chain_id, address)三元组，不同合约、不同地址互不可见（见 challenge_cache.rs 及对应测试）；
• 跨合约 Token 复用防护：JWT 的NodeType中内嵌合约名（Custom(contract_name)/CustomUnknown(contract_name)），每个 ingest 端点校验 JWT 中的合约名与 URL 路径一致，防止用合约 A 的 token 向合约 B 注入数据（custom_contract_auth.rs）；
• 黑名单：每合约可配blacklist_peers，命中即 403，适用于该合约全部 ingest 端点。

自定义客户端的 JWT 中peer_id取客户端地址、epoch固定为 0（对合约客户端不适用），并附带新生成的run_uuid。

3.4 链上白名单验证方式

对应 OnChainAuthConfig，字段与默认值如下：

${ENV_VAR}替换是单趟扫描、不递归展开（防止自引用/循环引用导致死循环），未设置变量或${未闭合都会报错（实现与测试见 lib.rs 及 resolve_env_vars_tests）。

4. 自定义合约完整配置参考

当前代码中每个合约由 CustomContractConfig 描述（deny_unknown_fields，未知字段会直接报错），全量字段如下：

汇聚端点（MetricsSinkConfig / LogSinkConfig）统一支持三种认证：auth_type: bearer（默认，token 从keys_env_var/key_env_var环境变量读取，metrics 端为端点名->token的 JSON 映射）、basic（basic_auth_env_var，username:password）、none。指标端点还支持backend_type（victoria_metrics文本导入 或prometheus_remote_writeprotobuf+snappy，默认前者）；日志端点支持backend_type: humio | loki（默认 humio）。

仓库中的端到端测试配置 e2e-test/telemetry-config.yaml 是一份可运行的完整示例，要点摘录：

address: "0.0.0.0:8082" # 测试用短缓存 TTL（生产默认 300 秒） allowlist_cache_ttl_secs: 10 trusted_full_node_addresses: mainnet: "https://api.mainnet.aptoslabs.com" testnet: "https://api.testnet.aptoslabs.com" devnet: "https://api.devnet.aptoslabs.com" update_interval: 300 custom_contract_configs: - name: "e2e_test_contract" on_chain_auth: chain_id: 4 # 本地测试链 method: viewfunction # ${TEST_CONTRACT_ADDRESS} 由环境变量在启动时注入 resource_path: "${TEST_CONTRACT_ADDRESS}::telemetry_registry::get_all_members" view_function_args: - "${TEST_CONTRACT_ADDRESS}" address_list_field: "[0].address" rest_api_url: "http://127.0.0.1:8080" node_type_name: "TelemetryTestNode" # 允许白名单外节点，数据路由到 untrusted 汇聚端点并带 trust_status 标签 allow_unknown_nodes: true # 同时接入两种指标后端 metrics_sinks: - endpoint_urls: victoria_metrics: "http://127.0.0.1:8428/api/v1/import/prometheus" auth_type: none keys_env_var: "TEST_METRICS_KEYS" - endpoint_urls: prometheus_remote_write: "http://127.0.0.1:9090/api/v1/write" auth_type: none keys_env_var: "TEST_METRICS_KEYS" backend_type: prometheus_remote_write untrusted_metrics_sinks: - endpoint_urls: prometheus_remote_write: "http://127.0.0.1:9090/api/v1/write" auth_type: none keys_env_var: "TEST_METRICS_KEYS" backend_type: prometheus_remote_write logs_sink: endpoint_url: "http://127.0.0.1:3100/loki/api/v1/push" auth_type: none backend_type: loki untrusted_logs_sink: endpoint_url: "http://127.0.0.1:3100/loki/api/v1/push" auth_type: none backend_type: loki

配套的白名单示例合约 telemetry_registry.move 展示了典型的链上白名单形态：一个Registry资源保存members: vector<Member>，admin 通过add_member/remove_member管理成员，成员变动发出MemberAddedEvent/MemberRemovedEvent事件；遥测服务通过get_all_membersview function 读取地址列表，并用address_list_field: "[0].address"从返回的Member结构中提取address字段。自定义合约客户端的 ingest 端点为：

自定义合约 ingest 时附加的指标标签包括：peer_id（客户端地址）、node_type（node_type_name）、contract_name、trust_status（trusted/untrusted）、kubernetes_pod_name（配置了peer_identities时为peer_id:{identity}//{peer_id_hex}）。

5. 限流：全局与每合约两级令牌桶

限流配置结构为 UnknownTelemetryRateLimitConfig，全局默认值：requests_per_second: 100、burst_capacity: 200、enabled: true；requests_per_second设为 0 或enabled: false时等价于关闭限流。

unknown_metrics_rate_limit: requests_per_second: 100 burst_capacity: 200 enabled: true unknown_logs_rate_limit: requests_per_second: 100 burst_capacity: 200 enabled: true

每合约限流的层级为：合约配置了untrusted_*_rate_limit则应用之，否则回退全局限流。实现位于 rate_limiter.rs：

• GlobalRateLimiter用令牌桶：以requests_per_second速率补充令牌，桶容量为burst_capacity，每请求消耗 1 个令牌，令牌以"毫令牌"（token×1000）精度存储，并通过 compare-and-swap 保证并发安全（冲突时有限重试）；无令牌则拒绝，对外表现为 429 Too Many Requests；
• ContractRateLimiters维护合约名 -> 限流器映射，未配置专属限流器的合约默认放行，由上层按全局限流处理（见 lib.rs 中按合约注册限流器的启动逻辑）。

单元测试覆盖了禁用态、零 rps、突发容量耗尽、按速率回填以及每合约隔离等行为（rate_limiter.rs），可直接运行验证：cargo test -p aptos-telemetry-service rate_limiter。

6. 后端 Sinks 一览

客户端实现分别在 clients/victoria_metrics.rs、clients/prometheus_remote_write.rs、clients/humio.rs、clients/loki.rs。

7. 缓存机制

验证者集缓存（标准认证用）：由PeerSetCacheUpdater后台任务维护，按update_interval（默认 60 秒）从可信全节点 REST API 拉取各链的验证者/VFN 集合并写入RwLock保护的映射（lib.rs）；trusted_full_node_addresses为空时该任务不启动。

白名单缓存（自定义合约认证用）：由AllowlistCacheUpdater维护，周期性调用各合约配置的 view function/资源读取，TTL 由allowlist_cache_ttl_secs控制（默认 300 秒，e2e 测试配置为 10 秒以便快速生效）。缓存未就绪（CacheMiss）的认证请求会被 403 拒绝——这是"宁可拒绝、不可误放"的保守设计。

挑战缓存（防重放用）：内存缓存，键为(contract_name, chain_id, address)，challenge 默认 TTL 300 秒，verify_and_consume成功即消费（challenge_cache.rs）。每个地址的并发挑战上限由常量MAX_CHALLENGES_PER_ADDRESS控制，当前源码值为5（challenge_cache.rs；SPEC.md 中写作 10，两处不一致时以实现代码为准）。超限时驱逐最旧挑战并打点evicted指标。挑战缓存自身也暴露了CHALLENGE_CACHE_OPERATIONS（store/verify_success/verify_expired/verify_not_found/evicted）、CHALLENGE_CACHE_SIZE、CHALLENGE_CACHE_KEYS、CHALLENGE_CACHE_LAST_STORE_TIMESTAMP等自监控指标，可按合约维度观测。

8. 错误码与可观测性

错误码约定（统一由 handle_rejection 转换为 JSONErrorResponse）：

服务自监控指标（导出到telemetry_service_metrics端点）：telemetry_service_error_counts（按错误类型计数）、telemetry_service_metrics_ingest_backend_request_duration、telemetry_service_log_ingest_backend_request_duration、telemetry_service_bigquery_backend_request_duration（各 sink 后端延迟）、telemetry_service_custom_contract_errors（自定义合约错误，按合约/端点/错误类型分标签），以及第 7 节所述挑战缓存指标。

日志与链路追踪：结构化 JSON 日志；每个请求经 warp trace 中间件提取X-Cloud-Trace-Context头中的 trace id 并创建 tracing span（index.rs），请求处理关键路径提供 debug 级日志。

9. 部署与运行

启动参数与环境变量：服务二进制通过 clap 定义，唯一参数为配置文件路径-f/--config-path（lib.rs）：

cargo run -p aptos-telemetry-service -- -f /path/to/telemetry-config.yaml

必需环境变量：

• SERVER_PRIVATE_KEY：X25519 编码字符串，用于 Noise 握手；未设置则启动 panic；
• JWT_SIGNING_KEY：Base64 编码的 JWT 签名密钥；未设置则启动 panic。

可选环境变量：GOOGLE_APPLICATION_CREDENTIALS（BigQuery 服务账号，缺失时禁用事件功能）；各类keys_env_var/basic_auth_env_var指向的 sink 凭证变量。

TLS：tls_cert_path与tls_key_path均为可选；设置后服务以 HTTPS 绑定address，否则以明文 HTTP 绑定（lib.rs）。生产部署应启用 TLS。

完整标准节点配置示例（字段布局以当前 TelemetryServiceConfig 为准，SPEC.md 附录 B 的示例对应早期字段命名，注意trusted_full_node_addresses现在以链名（mainnet/testnet/devnet）为键，日志配置别名log_ingest_config）：

address: "0.0.0.0:443" tls_cert_path: "/certs/cert.pem" tls_key_path: "/certs/key.pem" # 以链名键入的可信全节点 REST 地址，用于拉取验证者/VFN 集合 trusted_full_node_addresses: mainnet: "https://api.mainnet.aptoslabs.com/v1" testnet: "https://api.testnet.aptoslabs.com/v1" update_interval: 60 # 验证者集合刷新周期，默认 60 秒 # 公共全节点白名单：chain_id -> peer_id -> x25519 公钥 pfn_allowlist: {} # 服务自监控指标端点 + 受信/未受信指标端点（均可配多种后端与认证） metrics_endpoints_config: telemetry_service_metrics: endpoint_urls: default: "https://vm.example.com/api/v1/import/prometheus" auth_type: bearer keys_env_var: "VM_TOKENS" # JSON: {"default": "<token>"} ingest_metrics: endpoint_urls: default: "https://vm.example.com/api/v1/import/prometheus" auth_type: bearer keys_env_var: "VM_TOKENS" untrusted_ingest_metrics: endpoint_urls: default: "https://vm-untrusted.example.com/api/v1/import/prometheus" auth_type: bearer keys_env_var: "VM_UNTRUSTED_TOKENS" # 日志端点（humio 或 loki；字段名保留 humio_ingest_config，别名 log_ingest_config） log_ingest_config: known_logs_endpoint: endpoint_url: "https://cloud.humio.com/" auth_type: bearer key_env_var: "HUMIO_KNOWN_TOKEN" unknown_logs_endpoint: endpoint_url: "https://cloud.humio.com/" auth_type: bearer key_env_var: "HUMIO_UNKNOWN_TOKEN" # BigQuery 自定义事件（可选） custom_event_config: project_id: "my-project" dataset_id: "telemetry" table_id: "events" unknown_metrics_rate_limit: requests_per_second: 100 burst_capacity: 200 enabled: true unknown_logs_rate_limit: requests_per_second: 100 burst_capacity: 200 enabled: true

仅自定义合约模式（Custom-Contract-Only）：若只需服务第三方应用，可省略全部标准节点字段（trusted_full_node_addresses、pfn_allowlist、metrics_endpoints_config、humio_ingest_config均留空/缺省），服务会记录相应禁用日志并跳过对应后台任务。最小配置形如：

address: "0.0.0.0:8080" custom_contract_configs: - name: "my_provider" allow_unknown_nodes: true node_type_name: "MyProvider" metrics_sinks: - endpoint_urls: vm: "http://metrics:8428/api/v1/import/prometheus"

端到端验证：仓库自带一套 e2e 测试（e2e-test/），包含 docker-compose 环境、Prometheus/VictoriaMetrics/Loki 后端、示例白名单合约与测试客户端，可运行run-test.sh完整走通"部署合约 → 注册成员 → 挑战认证 → 指标/日志落库"链路；单元层面，src/tests/ 提供了auth_test.rs、custom_contract_auth_test.rs、custom_event.rs等针对认证与 ingest 的集成测试，可用cargo test -p aptos-telemetry-service运行。

10. 小结

Aptos 遥测服务用两条互不干扰的认证链——"Noise IK + 验证者集"与"挑战-应答 + 链上白名单"——覆盖了网络内节点与生态应用两类遥测来源：前者以握手公钥与链上身份的强绑定换取免白名单开销，后者以static_allowlist > on_chain_auth > allow_unknown_nodes的信任分级与 trusted/untrusted 双路汇聚端点，让第三方可以在隔离 sink、独立限流与trust_status标签的前提下复用同一套基础设施。配合令牌桶限流、单挑战一消费、JWT 合约名绑定与 BigQuery 可选化等细节，它提供了一个可直接参考的"链上身份驱动"遥测接入范式：先读 SPEC.md 建立整体认知，再以 lib.rs 的配置结构与 e2e-test/telemetry-config.yaml 为落地基准，即可在自己的场景中部署或对接该服务。

【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core