Rescan Blockchain

rescanblockchain 命令重新掃描區塊鏈以查找與錢包相關的交易。當導入密鑰、 恢復錢包或錢包數據損壞時，這個命令非常有用。

基本用法

# 掃描整個區塊鏈（從創世區塊開始）
bitcoin-cli rescanblockchain

# 從指定高度開始掃描
bitcoin-cli rescanblockchain 800000

# 指定掃描範圍
bitcoin-cli rescanblockchain 800000 840000

# 返回結果
{
  "start_height": 800000,
  "stop_height": 840000
}

何時需要 rescan？

導入密鑰時的 rescan

# importprivkey 默認會 rescan（很慢）
bitcoin-cli importprivkey "KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU73sVHnoWn"

# 跳過 rescan（導入多個密鑰時）
bitcoin-cli importprivkey "KwDiBf..." "" false

# 導入完成後手動 rescan
bitcoin-cli rescanblockchain 0

# 使用描述符時
bitcoin-cli importdescriptors '[{
  "desc": "wpkh([...]/84h/0h/0h/0/*)#xxxxx",
  "timestamp": 1609459200,
  "range": [0, 999]
}]'

# timestamp 告訴錢包從何時開始掃描

掃描時間估算

// 掃描速度取決於:
// - 硬體性能（SSD vs HDD）
// - 區塊鏈大小
// - 錢包中的地址數量

典型時間（2024 年，SSD）:
- 全量掃描: 30-60 分鐘
- 最近 10,000 區塊: 1-2 分鐘
- 最近 100,000 區塊: 5-10 分鐘

// 如果知道密鑰創建時間，可以大幅縮短
// 例如：密鑰在 2023 年創建
// 只需從 2023 年初的區塊開始掃描

優化 rescan

使用時間戳

# 計算起始區塊高度
# 如果知道密鑰創建於 2023-01-01

# 查找該日期附近的區塊
bitcoin-cli getblockchaininfo
# 使用區塊瀏覽器找到對應高度

# 從該高度開始掃描
bitcoin-cli rescanblockchain 770000

# 使用描述符時直接指定時間戳
bitcoin-cli importdescriptors '[{
  "desc": "wpkh(...)#xxx",
  "timestamp": 1672531200,  # 2023-01-01
  "range": [0, 999]
}]'

批量導入

# 錯誤做法：每個密鑰都 rescan
for key in keys:
    bitcoin-cli importprivkey "$key"  # 每次都掃描！

# 正確做法：先導入，最後掃描一次
for key in keys:
    bitcoin-cli importprivkey "$key" "" false  # 跳過 rescan

# 最後一次性掃描
bitcoin-cli rescanblockchain $start_height

進度監控

# 方法 1: 查看日誌
tail -f ~/.bitcoin/debug.log | grep -i rescan

# 方法 2: 使用 getwalletinfo
bitcoin-cli getwalletinfo
{
  ...
  "scanning": {
    "duration": 30,
    "progress": 0.45
  },
  ...
}

# 方法 3: GUI
# 狀態欄會顯示掃描進度

abortrescan

如果需要中斷正在進行的掃描：

# 停止掃描
bitcoin-cli abortrescan

# 注意:
# - 已掃描的部分會保留
# - 稍後可以從中斷處繼續
# - 部分錢包功能在掃描期間可能不可用

常見問題

餘額不正確

# 症狀: 導入密鑰後餘額為 0

# 原因 1: 沒有 rescan
bitcoin-cli rescanblockchain

# 原因 2: 起始高度太晚
# 使用更早的高度或 0
bitcoin-cli rescanblockchain 0

# 原因 3: 使用了錯誤的地址類型
# 檢查描述符是否正確（wpkh vs pkh vs tr）

掃描太慢

# 解決方案:

# 1. 使用 SSD
# HDD 會慢很多

# 2. 增加 dbcache
# 在 bitcoin.conf 中:
dbcache=4000  # 4GB

# 3. 縮小掃描範圍
# 只掃描必要的區塊

# 4. 使用 blocksonly 模式
# 減少 mempool 相關開銷
blocksonly=1

與 reindex 的區別

最佳實踐