listpayments 的索引语义：排他边界、稳定编号与双向游标

闪电节点的付款历史越攒越厚，导出对账的人很快会撞到一个问题：这笔账没有”块高游标”可用，翻页靠的是一套比时间戳更可靠的索引机制。LND 的 listpayments 走的就是这套索引，而它给”哪条记录排第几”下的定义，直接决定对账脚本是漏单还是重单。

索引绑在记录上，而不是绑在时间上

分页参数有三个主角：index_offset、max_payments 与 reversed。文档对 index_offset 的说明有两层容易漏掉的语义。第一，它是排他的：作为查询边界的那条记录本身不会出现在结果里，想要它就得把偏移量往回让一格。第二，索引与个体付款绑定，不随新付款的写入而漂移——昨天排第 1000 号的付款，今天依然排第 1000 号，不会因为今天又发了五十笔就整体后移。这一点与多数数据库 offset 分页的直觉相反：那边的 offset 含义是”跳过前 N 行”，行序一变就可能漏读；这边更接近自增主键区间，翻页稳定性因此高得多。

文档还交代了零值边界：index_offset 为 0 时，正向翻页从最老的付款开始，反向翻页则止于最近的付款；reversed 置真即”从指定索引往回找”，与 max_payments 合用就能从新到旧滚动读取。响应附带的 first_index_offset 与 last_index_offset 是专为连续翻页准备的续读游标：把上一批的边界值原样填进下一次请求，即可无缝衔接、断点续传。

include_incomplete：失败的付款算不算

默认查询只返回已完成的付款；include_incomplete 置真后，在途与失败的付款也进入结果。这个开关的微妙之处在于文档特意强调它不改变索引含义——同一笔失败的付款，无论你在哪个视图里看，都占着同一个编号。对账脚本如果两次查询一次开标志一次不开，条数会对不上，但索引序列依然咬合，所以检查点应当记索引、不该记条数。

两种视图的用途也不同：回答”钱最终花到哪了”，默认视图足够；排查”这笔单为什么没成”，必须开 include_incomplete，否则那笔卡住又失败的付款根本不在列表里，你会对着空结果怀疑人生。

与发票、转发记录的三本账

容易混淆的是命令族的分工：本命令查本节点主动发起的付款；收款发票的账走发票接口；替人路由的过路费流水在转发历史里。三本账共用索引概念，却没有任何两本能互相代替。月度对账的稳妥顺序是：先用付款历史列出站支出，再用发票列表核入账，最后用转发历史核路由收入——三者相加才构成节点的全部资金流动，缺任何一条腿的报表都一定在某个字段上对不平。

性能上的提醒同样朴素：单次返回量由 max_payments 控制，历史极长的节点一次全量拉取既慢又占内存，分页几乎永远优于裸奔。索引单调、游标显式、方向可逆，这套设计让宕机重启后的导出既不重复也不遗漏，这正是它存在的工程理由。还有一个容易被忽略的细节：响应里可选地携带总数字段，但那要先在请求里显式开启计数开关才会填充——默认不数总数，是因为对十万级历史的节点来说”数一遍”本身就不便宜，接口宁可不给也不让你为它付隐形的代价。

最后提醒数据的敏感性：付款历史里包含收款方身份、金额与时间线，属于节点运营的最高敏感信息，导出文件与求助截图务必脱敏；它也只存在你自己的数据库里，链上没有它的镜像，删库即灭账，备份纪律请把它算进去。

风险提示：本文仅为节点接口机制说明，历史数据的准确性依赖软件版本与数据库完整性，重要对账请以链上事实为准，本文不构成投资建议。