T25 · Blockchain Data Infrastructure

一个现实问题

你的索引器已经按 T17 跑得很稳：不漏块、能回滚、能重跑。业务库里躺着几千万条转账事件。

运营发来第一个问题：「过去 12 个月，我们协议每个月的活跃地址数和手续费收入是多少？」

你写了一条 SQL，点回车。四十分钟后结果出来了，与此同时线上告警响了——那条查询把数据库的 IO 吃满，前端接口开始超时。

你加了索引，第二次跑快了一些。然后第二个问题来了：「把新用户和老用户拆开看。」 又是半小时。

第三个问题：「能不能看 24 个月？」

你打开库一看，只有最近 6 个月的数据。因为磁盘涨得太快，三个月前你写了个定时任务删旧数据。

这三个问题一个比一个普通，普通到运营觉得应该是「点两下就有」。但你的系统一个都答不好。

不是你的索引器写得差——它在自己的岗位上做得很对。问题是：为「查一个地址此刻的余额」优化出来的系统，和为「把十亿行扫一遍求个和」优化出来的系统，从存储格式到重跑策略都不是一个东西。

这一章要建的是后面那个。

思想实验

先看一张纸上的账本。

一本流水账，每一页记一笔：日期、对方、金额、用途、经手人、发票号、部门、项目编号——三十个字段。

问题一：「张三昨天那笔钱是多少？」 你翻到那一页，看一眼，答完。翻一页的代价很小。

问题二：「去年全年按月的总支出。」 你必须把一整年的每一页都翻过去。翻的时候你只关心「日期」和「金额」两列，但纸是按页装订的，你没办法只翻那两列——每一页的三十个字段都得从眼前过一遍。

现在换一种装订方式：把所有页的「日期」抄成一卷，所有页的「金额」抄成另一卷，三十个字段三十卷。 问题二变成只取两卷，工作量掉到十五分之一。而且同一卷里全是同类型的数字，压缩率高得离谱，连搬运的重量都轻了。

代价是问题一变难了：想看张三那一笔的完整信息，你得从三十卷里各抽一条再拼起来。

这就是行存和列存的全部区别。没有谁更好，只有各自适合什么问题。

但真正难的不是这个，是第二个思想实验。

假设这本账不是一次抄完的，而是每天新增一批，并且偶尔要把上个月某一天的内容整天换掉：链发生了重组、你发现某个字段一直解析错了、合约升级后事件的含义变了。

这时候问题就不是「怎么翻得快」，而是：

怎么把「某一天」重做一遍，并且做完之后，和从第一天开始完整重做的结果一模一样？

能做到这件事，你的仓库才敢被人拿去做对账、做报表、做结算。做不到，它就只是一个跑得快一点的缓存。

你来决定

运营那三个问题落到你头上，你要选一条路。

观察结果

把四条路放在一起：

注意第四列。前三行都是「完全可控」，第四行是「不可控」——而这一列在出事时的权重，比其他四列加起来都大。

因为对一份分析数据，人们真正会问的问题只有两个：

这个数字是怎么算出来的？

我重新算一遍，还是这个数字吗？

第一个问题叫口径，第二个问题叫可重放。它们都不是查询问题，是 ETL 问题。

这就是这一章最反直觉的一点：搭一个能跑的分析仓库，难点不在 SQL，SQL 部分一个下午就能学完。难点在于让每一条数据都能说清出处、每一个分区都能被独立重做、每一次重做都得到同样的结果。

而你已经有一半的答案了：T17 那套 checkpoint、幂等、区间表、重组回滚，在仓库里会以另一种形态再出现一次。

建立模型

三层：Raw、Decoded、Curated

不要把「从链上拉数据」和「算出业务指标」写在同一段代码里。中间至少分三层：

分层的全部价值就在最后一列。代价最高的那一步，要做到只做一次。

现实里最常见的返工是「某个字段解析错了」或者「合约升级后事件含义变了」。如果你的流水线是 RPC 直接算到指标，这类返工意味着把全链历史重拉一遍——几天起步，还要看 RPC 服务商的脸色。如果 Raw 层留着原始字节，同样的返工只是重跑一次解码，几十分钟。

Raw 层是你为「将来一定会发现自己解错了」买的保险。 它的存储成本远低于一次全量重拉的代价。

分区：按什么切，决定了一切

分区就是把数据物理切成一块块文件，查询时只读相关的块。这个动作叫分区裁剪。

链上数据天然有两个候选键：区块高度和时间。选哪个？

两个都要，但角色不同：

物理分区键  →  日期（从区块时间推导，UTC）
分区内排序  →  区块高度，其次 log_index

理由很直接。人和业务提的问题永远是按时间的（「上个月」「Q3」），所以分区按日期切，裁剪才有效。而写入、去重、重做的单位是区块高度，所以分区内部按高度排好序，既能让引擎跳过整段数据，也让「这个分区覆盖哪个高度区间」成为一个精确可查的事实。

目录长这样：

warehouse/
  raw_logs/
    dt=2024-03-01/part-0000.parquet
    dt=2024-03-02/part-0000.parquet
  decoded_transfers/
    dt=2024-03-01/part-0000.parquet
  curated_daily_metrics/
    dt=2024-03-01/part-0000.parquet

两个很容易写错的细节：

第一，分区键必须来自区块时间，绝对不能来自 now()。 用写入时间打分区，同一批数据今天跑和明天重跑会落到不同分区，重放立刻失效。这是这条流水线上最隐蔽的一个坑，T16 讲事实表时已经强调过一次：时间戳来自区块头，不是来自你的服务器。

第二，分区粒度不要太细。 一天一个文件、每个文件几十上百兆是舒服的。按小时切会得到几万个小文件，元数据开销会吃掉列存的全部好处——这个现象有个很形象的名字叫小文件问题。

幂等：分区是写入的原子单位

T17 在数据库里靠事务和主键做幂等。文件系统没有事务，但它有一个足够用的替代品：原子重命名。

1. 把这个分区的数据完整写进一个临时目录
   warehouse/decoded_transfers/_tmp_2024-03-01_run42/
2. 写完、校验通过之后，原子地换名到正式路径
   → warehouse/decoded_transfers/dt=2024-03-01/
3. 更新 manifest：这个分区的高度区间、行数、校验和、解码器版本

规则和 T17 是同一条，只是换了个载体：

一个分区要么完整存在，要么完全不存在。绝不允许出现「写了一半」的分区。

任务在第 1 步挂掉，临时目录被下次运行清理掉，正式路径纹丝不动。任务在第 2 步之后挂掉，manifest 没更新，下次重跑会重做这个分区——重做的结果和上次逐字节相同，所以无害。

注意顺序：先换名，后更新 manifest。 反过来会得到「manifest 说有，文件却没有」——这正是 T17 里 checkpoint 排在数据前面的那个错误，换了一身衣服又来一次。

Manifest：这条流水线唯一的真相

没有 manifest，你的仓库就是一堆文件，没人能回答「这个月的数据全不全」。

create table warehouse_manifest (
  dataset        text    not null,      -- raw_logs / decoded_transfers / ...
  chain_id       integer not null,
  dt             date    not null,      -- 分区键
  from_block     bigint  not null,      -- 这个分区实际覆盖的高度区间
  to_block       bigint  not null,
  row_count      bigint  not null,
  checksum       text    not null,      -- 内容指纹，用于比对重跑结果
  decoder_version text   not null,      -- 解码器的代码版本，血缘的关键
  status         text    not null,      -- pending / running / done / failed
  attempts       integer not null default 0,
  built_at       timestamptz not null default now(),
  primary key (dataset, chain_id, dt)
);

它直接回答四个平时没人问、出事时人人都问的问题：

-- 1. 有没有洞？
select dt from generate_series($from::date, $to::date, '1 day') g(dt)
 where not exists (
   select 1 from warehouse_manifest m
    where m.dataset = 'decoded_transfers' and m.chain_id = $chain
      and m.dt = g.dt and m.status = 'done'
 );

-- 2. 高度区间连不连续？相邻两天之间不能断档
select a.dt, a.to_block, b.dt, b.from_block
  from warehouse_manifest a
  join warehouse_manifest b
    on b.dataset = a.dataset and b.chain_id = a.chain_id
   and b.dt = a.dt + 1
 where b.from_block <> a.to_block + 1;

-- 3. 哪些分区是用旧版解码器生成的？改了解码逻辑之后，这就是待重做清单
select dt from warehouse_manifest
 where dataset = 'decoded_transfers' and decoder_version <> $current;

-- 4. 重跑之后内容变了吗？校验和逐分区比对

第 1 条和 T17 的区间表是同一个思想：「完成」必须是一个能被一条 SQL 回答的问题，而不是「进度看起来到了」。 第 3 条则是分层设计真正兑现价值的地方。

重组：仓库的正确姿势是落后

列存文件不可变，怎么处理 T17 那种链头重组？

最简单也最正确的办法：根本不让链头进仓库。

业务库（OLTP）   ← 贴着链头，负责实时，承担重组回滚
        │
        │  只搬运 block_number 不超过 safeHeight 的数据
        ↓
数据仓库（OLAP）  ← 落后若干区块，落地即不可变

safeHeight 就是 T17 里 outbox 用的那个安全高度。仓库天然落后几分钟到几小时，这是设计，不是缺陷。

于是仓库里的重组处理简化成了一句话：仓库里不存在需要回滚的数据。代价是它不适合回答「刚刚那一秒发生了什么」——那个问题本来就该由业务库和 T18 的实时通道回答。

两个系统，两种新鲜度，两种一致性保证。不要试图用一个系统同时满足。

万一真要改写一个已经落地的分区（比如发现三个月前某天解码错了），流程也是现成的：重新生成那个分区、原子换名、更新 manifest、把依赖它的下游分区标成 pending 重跑。这就是为什么 manifest 里要记 decoder_version。

Curated 层：口径写在代码里，不写在脑子里

到这一层，技术问题基本结束了，剩下的全是定义问题。

「月活跃地址」这一个词，至少有六种算法：

- 只算发起交易的地址，还是转账双方都算？
- 失败的交易算不算？
- 合约地址算不算？
- 通过聚合器路由过来的，算聚合器还是算最终用户？
- 一个人用五个地址，算一个还是算五个？
- 时区按 UTC 还是按本地？

六个问题各有两个答案，组合起来是几十种口径，每一种都能理直气壮地叫「月活」。

所以 curated 层的每一张表，都要在代码里带一段口径注释，而且这段注释要和 SQL 放在同一个文件里，不要放在另一个文档里——放另一个文档里的定义，三个月后一定和代码对不上。

-- daily_active_addresses
-- 口径（2024-03 定稿）：
--   1. 只统计成功交易产生的日志
--   2. 转账的 from 与 to 都计入，各算一次去重
--   3. 零地址（铸造与销毁的对手方）排除
--   4. 已知的合约地址不排除，但单独标记
--   5. 按 UTC 自然日
create table curated_daily_active (
  chain_id   integer not null,
  dt         date    not null,
  contract   bytea   not null,
  addresses  bigint  not null,
  tx_count   bigint  not null,
  primary key (chain_id, dt, contract)
);

一条经验：当两个人对同一个指标报出不同的数字时，九成不是谁算错了，而是口径不同。 把口径写进代码，这类争论会从一小时缩短到一分钟。

一个完整的例子

从解码层算出月度指标，跨月份聚合：

-- 跨 12 个月的月度活跃地址与手续费
-- 分区裁剪靠 dt，实际扫描的只有这 12 个月的文件
with e as (
  select dt, from_addr, to_addr, amount, gas_used, gas_price
    from decoded_transfers
   where chain_id = 1
     and contract = $contract
     and dt >= date '2024-01-01'
     and dt <  date '2025-01-01'
),
addrs as (
  select date_trunc('month', dt) as m, from_addr as addr from e
  union all
  select date_trunc('month', dt) as m, to_addr   as addr from e
)
select m,
       count(distinct addr)                      as active_addresses,
       sum(gas_used * gas_price) / 1e18          as fees_native
  from addrs
  join e on date_trunc('month', e.dt) = addrs.m
 group by m
 order by m;

这条查询里唯一值得盯的一行是 where dt >= ... and dt < ...。它决定了引擎读 12 个文件还是读全部文件，而这就是那一到两个数量级的来源。

一个必须知道的反例：把条件写成 where date_trunc('month', dt) = ... 或者对 dt 套任何函数，分区裁剪会失效，引擎老老实实全扫。查询快不快，往往取决于你有没有让分区键保持「裸露」。

它叫什么

动手

验收 1：任意一天的分区重跑，校验和不变
验收 2：manifest 里没有洞，相邻分区的高度区间严格连续
验收 3：聚合结果与从原始日志现算的结果逐行相等

raw_logs/dt=YYYY-MM-DD/part-0000.parquet

三次重跑，三个校验和，必须和原值完全一致

AI Lab

第一步：
这是我的 decoded_transfers 表结构和分区方式（按 dt 分区，分区内按 block_number 排序）。
写一条查询：过去 12 个月，按月给出活跃地址数与手续费总额。
要求利用分区裁剪，并说明你的查询会扫描多少个分区。

第二步：
列出你在这条查询里做了哪些口径假设。
每一条写成「我假设 X，如果实际是 Y，结果会怎么变」。
至少给出 6 条。

第三步：
现在告诉你真实情况：这个合约在去年 6 月做过一次升级，
升级后同一个事件多了一个字段，topic0 也变了。
你上面那条查询在 6 月前后会发生什么？怎么改？

真实案例

改一个变量

带走的问题

本章自测