Pearl Wallet 同步故障排查与修复笔记

本笔记详细记录了解决 Pearl Wallet (PRL) 桌面钱包卡在高度 1、无法连接节点进行同步，并最终成功在本地恢复显示钱包余额的完整折腾过程。

1. 问题背景与故障诊断

症状

现象：Pearl Wallet 桌面钱包 (v1.0.0) 启动后，高度一直卡在 1/1（或 0），提示 Lost peer 或 EOF。无论等待多久，都无法同步区块，导致钱包余额无法显示（处于未同步的假空状态）。
原因排查：
1. GFW 干扰：国内直连节点可能存在丢包。
2. 握手 Bug（核心原因）：官方 v1.0.0 版本的客户端在向主网 DNS 种子节点进行网络握手时，错误地为不支持过滤的主网种子节点请求了紧凑过滤标志 (HasFiltering)，导致主网远程节点在收到握手后瞬间主动断开连接 (Lost peer)。

解决思路

在海外 VPS 上，拉取官方最新的修复源码（已屏蔽 HasFiltering bug），编译最新的运行程序。
用新程序在 VPS 上连接主网节点，快速同步区块头和 Neutrino 过滤器数据库。
从 VPS 导出一份包含“已连通健康节点”的 peers.json 列表。
将同步好的区块头缓存、过滤器数据库和节点列表打包下载到本地钱包目录。
通过 Clash Verge 配置路由直连规则，保障钱包连接节点时不受代理网络波动干扰。
确认本地钱包正常显示余额后，完全清理 VPS 上的临时编译环境。

2. 折腾全过程详细记录

第一阶段：VPS 端编译最新 Oyster 钱包

重置环境：VPS 重置为 Ubuntu 22.04 LTS。

安装编译依赖：

apt-get update
apt-get install -y git build-essential make golang rustc cargo curl

获取源码：拉取最新的 pearl 官方单体仓库，切换至主分支。
本地编译：
- 编译 ZK 零知识证明电路缓存、FFI 动态库以及 XMSS 签名 C 语言绑定。
- 成功构建原生 fixed oyster 钱包命令行程序。
[!NOTE] 编译 Rust ZK 电路时需要较大的内存。1G 物理内存的 VPS 在启用 1G Swap 虚拟内存后顺利完成了编译，未发生 OOM 崩溃。

3. 第二阶段：VPS 挂载同步与状态监控

指定正常节点强制同步：为避免受坏节点干扰，启动新编译的 oyster 并显式添加多个已知可靠的海外主网节点 IP：

nohup ~/pearl-sync/oyster --usespv -u test -P test \
  --addpeer 104.199.167.233:44108 \
  --addpeer 34.40.50.215:44108 \
  --addpeer 35.223.185.30:44108 \
  --addpeer 35.196.37.244:44108 \
  --addpeer 34.83.190.251:44108 \
  > ~/pearl-sync/oyster.log 2>&1 &

编写监控脚本：通过 Python 监控脚本自动计算同步速度 (blocks/s) 和预计剩余时间 (ETA)。同步在约 15~30 blocks/s 的速度下运行，共计约 25 分钟同步完 6.4 万个区块。
自动打包与停止：高度追上主网 Tip 时，脚本自动停止 VPS 上的 oyster 进程，并打包核心数据：
- block_headers.bin (区块头数据)
- neutrino.db (BoltDB 过滤器数据库)
- reg_filter_headers.bin (过滤器头文件)
- peers.json (节点拓扑信息)
- 数据包名称：sync_cache.tar.gz (约 12MB)

4. 第三阶段：本地数据灌入与 Clash Verge 直连配置

数据灌入：数据包从 VPS 下载到本地 PC 路径：C:\Users\<YourUsername>\.pearl-wallet\wallet-data\<YourWalletName>\mainnet 并解压。
- ⚠️ 特别注意：本地 wallet.db（钱包密钥数据库）保持完全不动，安全无损。
- peers.json 替换的作用：本地客户端直接获得了 VPS 筛选出的几千个健康节点 IP，启动时将不再尝试走报错的官方种子寻路，从而在本地绕过了官方握手 Bug，可实现永久增量自同步。

Clash Verge 直连规则优化：为防止代理内核将主网 P2P 流量误判拦截或通过长链节点转发导致握手失败，在 Clash 配置文件 rules: 的最顶部加入以下最高优先级规则：

rules:
    # 1. 进程规则直连（Verge/Meta 内核支持）
    - 'PROCESS-NAME,oyster-windows-x64.exe,DIRECT'
    - 'PROCESS-NAME,Pearl Wallet.exe,DIRECT'

    # 2. 官方 DNS 种子域名直连
    - 'DOMAIN-SUFFIX,pearlresearch.ai,DIRECT'

    # 3. 我们同步使用的多个高质量稳定节点 IP 直连
    - 'IP-CIDR,104.199.167.233/32,DIRECT,no-resolve'
    - 'IP-CIDR,34.40.50.215/32,DIRECT,no-resolve'
    - 'IP-CIDR,35.223.185.30/32,DIRECT,no-resolve'
    - 'IP-CIDR,35.196.37.244/32,DIRECT,no-resolve'
    - 'IP-CIDR,34.83.190.251/32,DIRECT,no-resolve'

5. 成果验证与 VPS 无痕清理

本地成果：打开本地 Pearl Wallet，钱包加载后仅用几秒钟便同步完了最新的新产生区块，并顺利进入区块历史交易扫描，成功在钱包界面读出您的真实总余额：
- 显示余额：<YOUR_BALANCE> PRL 💎
VPS 环境彻底清理：确认本地钱包恢复后，连接 VPS 运行清理脚本：
- 停止任何残留进程。
- 彻底删除整个临时工作区（~/pearl-src、~/pearl-sync、~/.cargo、~/.rustup、~/.oyster、~/.go）。
- 卸载所安装的开发语言环境（go、rust、gcc/g++、make、build-essential）。
- 释放了共计数百兆 of 磁盘空间，并将内存占用恢复至 0，VPS 重回零残留安全状态。

6. 经验与建议

不要删除本地 wallet.db：钱包同步不上去只是区块缓存和网络同步协议的问题，私钥依然安全地存在于本地 wallet.db 中。遇到此类情况切记不要重装或删除数据库。
利用 P2P peers 直连绕过 Bug：当区块链软件客户端源码中写死的主种子发生握手 Bug 时，手动给软件注入一份已知可靠的 peers.json 即可直接跳过主种子检索，是解决 P2P 客户端连不上网的通用解法。
使用 Merge 模板保存 Clash Verge 规则：在 Verge 中使用 Merge 模板注入直连规则，可以避免未来订阅更新时把手动改写的 rules 覆盖掉。

Last modified on 2026-05-30