区块链【免费下载链接】lndLightning Network Daemon ⚡️项目地址https://gitcode.com/gh_mirrors/ln/lnd点击查看免费下载output_article /output_article输出文章LND 接入 PostgreSQL从 kvdb 配置到 KV-over-SQL 存储原理详解LNDLightning Network Daemon通过引入kvdb抽象接口将底层数据库从单一的 Bolt DB 扩展到多种后端PostgreSQL 便是其中官方支持的后端之一。本文以 docs/postgres.md 为核心完整介绍 LND 启用 Postgres 的构建方式、数据库准备、配置项说明与复制注意事项并结合仓库源码深入讲解其KV-over-SQL的存储设计与表结构原理。读完本文你将掌握如何为 LND 正确配置 Postgres 后端、理解各配置项的默认值与影响以及知道每个数据库表中到底存了什么。一、构建支持 Postgres 的 LND自lnd v0.14.1-beta起启用 Postgres 支持所需的构建标签build tags已默认开启。因此无论是官方发布的二进制包还是 Docker 镜像开箱即用即可获得 Postgres 后端能力无需额外编译参数。如果要从源码自行构建直接在仓库根目录执行$ make install从源码看Postgres 后端由构建标签kvdb_postgres控制。该标签生效时kvdb/kvdb_postgres.go 会将PostgresBackend置为true并提供NewPostgresFixture与StartEmbeddedPostgres两个测试辅助函数未启用该标签时则由 kvdb/kvdb_no_postgres.go 提供禁用实现。make install走的是默认构建流程因此产物默认就带上了 Postgres 支持。二、为 LND 准备 Postgres 数据库在启动 LND 之前需要保证以下几点已就绪存在一个空的数据库可通过常规方式创建如psql、pgAdmin 等客户端。存在一个有权限访问该数据库的用户LND 将使用该用户的凭据建立连接。需要特别强调的是表结构schema与数据表的创建完全由 LND 自动完成无需手工执行任何建表 SQL。LND 启动时会自动连接数据库并执行建表语句详见下文表结构如何被创建一节。一个典型的创建命令示例如下具体值需按实际环境调整-- 以超级用户登录后执行 CREATE DATABASE lnd; CREATE USER lnd WITH PASSWORD your_password; GRANT ALL PRIVILEGES ON DATABASE lnd TO lnd;注意LND 需要在publicschema 下创建表并写入数据请确保所用用户对目标数据库及其默认 schema具备完整读写权限。三、配置 LND 使用 Postgres 后端LND 通过db.*前缀的配置项选择数据库后端与 Postgres 相关的核心配置如下配置项说明默认值db.backendpostgres选择 Postgres 作为 kvdb 后端bdbBoltdb.postgres.dsn...数据库连接串包含数据库名、用户名与密码空db.postgres.timeout...数据库连接/查询超时设为 0 表示不超时不设则无超时db.postgres.maxconnections...允许打开的最大连接数0 表示不限50db.postgres.skipmigrationsfalse是否跳过 schema 迁移falsedb.postgres.walletdb-with-global-locktrue对walletdb_kv表启用全局写锁单写者truedb.postgres.channeldb-with-global-lockfalse对channeldb_kv表启用全局写锁单写者false官方文档给出的最小配置示例如下写入lnd.conf[db] db.backendpostgres db.postgres.dsnpostgresql://dbuser:dbpass127.0.0.1:5432/dbname db.postgres.timeout0其中db.postgres.timeout0表示关闭连接超时——这是有意为之用于应对数据库因意外原因变慢的场景避免 LND 因超时频繁中断访问。3.1 更多配置项的权威出处仓库自带的示例配置 sample-lnd.conf 中[postgres]一节给出了全部可选项的完整注释包括DSN 示例db.postgres.dsnpostgres://lnd:lndlocalhost:45432/lnd?sslmodedisableURL 形式与postgresql://前缀等价均可使用。超时db.postgres.timeout合法时间单位包括{s, m, h}设为0即禁用。连接数db.postgres.maxconnections50建议设置为低于服务器连接上限的值否则高负载下 LND 可能报错。迁移开关db.postgres.skipmigrationsfalse。全局锁db.postgres.channeldb-with-global-lockfalse与db.postgres.walletdb-with-global-locktrue。原生 SQL 查询调优db.postgres.query.max-batch-size5000原生 SQL 批量查询IN子句的最大元素数与db.postgres.query.max-page-size10500分页查询单次最大记录数。这些选项在源码中的定义位于 kvdb/postgres/config.go 的Config结构体type Config struct { Dsn string long:dsn Timeout time.Duration long:timeout MaxConnections int long:maxconnections WithGlobalLock bool long:withgloballock }底层实现上kvdb/postgres/db.go 中的newSQLBaseConfig会将上述配置翻译为 sqlbase 层配置使用pgx驱动、固定Schema: public、以传入前缀拼出表名并将WithGlobalLock映射为WithTxLevelLock事务级锁。查询相关调优参数如max-batch-size、max-page-size则在 config_builder.go 中依据db.backend postgres条件加载到查询配置中。3.2 关于全局锁单写者模式针对部分仍以 KV 表形式存储的子系统在它们拥有原生 SQL schema 之前LND 提供了全局锁选项以数据库内的一把全局互斥锁将写操作串行化保证同一时刻只有一个写者从而缓解 LND 在高并发负载下可能出现的资源耗尽问题。官方文档明确说明这是一个临时措施待相关表完成原生 SQL 化后会移除。db.postgres.walletdb-with-global-locktrue对walletdb_kv表启用单写者默认开启db.postgres.channeldb-with-global-lockfalse对channeldb_kv表启用单写者默认关闭保留并发写能力。从 kvdb/sqlbase/db.go 的实现看当WithTxLevelLock为真时数据库对象内部会维护一把sync.RWMutex全局读写锁写事务需要先持有写锁才能执行从而将并发写转换为串行写。四、重要提醒复制架构下的同步模式官方文档特别强调如果计划为 LND 数据库搭建复制架构应避免使用流式复制streaming replication。原因在于流式复制模式下主库并不校验副本是否真正一致只是把写入队列转发给从库由从库自行追赶一旦主备间出现偏差无法及时发现。作为替代应当使用同步模式synchronous mode。虽然同步模式性能更慢但它对 LND 跨副本的数据完整性至关重要——只有从库确认复制成功后写操作才会最终落定finalize。这保证了任一时刻各副本持有的是相同且完整的数据视图是 LND 这类对状态一致性要求极高的系统所必需的。五、数据库里到底存了什么5.1 KV-over-SQL 的总体设计目前LND 的 Postgres 数据库在功能上仍是一个键值存储Key-Value Store与 Bolt DB 的定位一致LND 的kvdb接口对上层提供 Bucket/Key/Value 语义底层由 sqlbase 层翻译成 SQL 表操作。表中部分 value 采用 TLV 编码另一部分则是普通二进制序列化官方文档同时指出随着迭代会有更多原生 schema 逐步引入。每个 KV 表/关系relation的列结构当前固定为列类型含义keyBYTEA键二进制valueBYTEA值二进制可为空parent_idBIGINT父桶bucket的 idNULL表示属于最顶层桶idBIGSERIAL行自增主键sequenceBIGINT桶内自增序号对应 Bolt 的 NextSequence5.2 数据库中的表清单文档给出了一份典型的关系清单\dt输出owner 为lndadminList of relations Schema | Name | Type | Owner ------------------------------------------- public | channeldb_kv | table | lndadmin public | decayedlogdb_kv | table | lndadmin public | macaroondb_kv | table | lndadmin public | towerclientdb_kv | table | lndadmin public | towerserverdb_kv | table | lndadmin public | walletdb_kv | table | lndadmin这些*_kv表分别服务于 LND 的不同子系统channeldb_kv通道数据库Channel DBdecayedlogdb_kv衰减日志Decayed Log用于htlcswitch的失效日志存储macaroondb_kvmacaroon 认证凭据库towerclientdb_kv/towerserverdb_kvWatchtower 客户端与服务端数据库walletdb_kv钱包数据库Wallet DB。值得注意的是Invoice DB发票数据库是独立于上述 KV 表体系维护的——它不与 LND 节点共用这一套 KV 存储而是单独管理。5.3 表结构是如何被创建的建表语句由 kvdb/sqlbase/schema.go 中的newKVSchemaCreationCmd生成核心 SQL 如下CREATE TABLE IF NOT EXISTS schema.table ( key BLOB NOT NULL, value BLOB, parent_id BIGINT, id INTEGER PRIMARY KEY, sequence BIGINT, CONSTRAINT table_parent FOREIGN KEY (parent_id) REFERENCES schema.table (id) ON UPDATE NO ACTION ON DELETE CASCADE ); CREATE INDEX IF NOT EXISTS table_p ON schema.table (parent_id); CREATE UNIQUE INDEX IF NOT EXISTS table_up ON schema.table (parent_id, key) WHERE parent_id IS NOT NULL; CREATE UNIQUE INDEX IF NOT EXISTS table_unp ON schema.table (key) WHERE parent_id IS NULL;设计要点外键自引用parent_id通过外键引用同一张表的id实现桶嵌套桶的树状结构parent_id IS NULL的行属于最顶层桶。唯一性约束通过table_up与table_unp两个部分唯一索引保证同一桶内键不重复Postgres 的单索引无法同时约束NULL parent_id行的唯一性因此拆成两个。级联删除ON DELETE CASCADE使得删除父桶时子行自动清理。在 LND 的 Postgres 适配层kvdb/postgres/db.go中建表语句还会经过一组 SQLite 兼容性替换将BLOB替换为BYTEA、INTEGER PRIMARY KEY替换为BIGSERIAL PRIMARY KEY从而适配 Postgres 类型系统。表名则由newSQLBaseConfig中的TableNamePrefix加_kv拼接而成见 kvdb/sqlbase/db.go 中table : fmt.Sprintf(%s_%s, cfg.TableNamePrefix, kvTableName)这就是channeldb_kv、walletdb_kv等命名的由来。5.4 驱动注册与打开流程Postgres 后端通过标准walletdb驱动机制接入。kvdb/postgres/driver.go 在init()中注册名为postgres的驱动createDBDriver与openDBDriver两个回调最终都调用newPostgresBackendkvdb/postgres/db.go即经由sqlbase.NewSqlBackend建立连接并在首次打开时自动执行建表命令。连接池由全局的dbConnSet管理其容量由db.postgres.maxconnections决定kvdb/sqlbase/db.go 的Init(maxConnections int)。LND 主程序侧config_builder.go在db.backend postgres时会调用lncfg.GetPostgresConfigKVDB组装 Postgres 配置并创建对应 KV 后端同时早期将 neutrino 数据库保留在 Bolt 中的迁移逻辑handleNeutrinoPostgresDBMigration也已将 neutrino 数据一并迁入 Postgres使全部子系统统一收口到 Postgres 后端。六、适用前提与限制总结版本前提Postgres 后端自lnd v0.14.1-beta起默认启用本文配置适用于该版本及之后以当前仓库为准。运维前提需自行维护一个可访问的空数据库与授权用户schema 迁移默认自动执行除非显式设置skipmigrationstrue。一致性前提若做多副本部署请使用同步复制而非流式复制以保障 LND 数据跨副本的完整性。架构现状当前 Postgres 后端整体仍是 KV-over-SQL 形态部分子系统如 wallet、channeldb依赖可选的全局锁来规避高并发下的资源耗尽问题这是过渡期的临时方案后续会被原生 SQL schema 逐步取代。综上LND 的 Postgres 支持是一套完整且可落地的数据库后端方案配置极简一条db.backendpostgres加一条 DSN 即可切换建表全自动底层通过kvdb/sqlbase两层抽象把 Bolt 式的 KV 语义无损映射到关系型表结构上。对于希望摆脱单机 Bolt 文件、引入外部数据库管理与复制能力的部署场景本文所讲的配置与原理即是直接的实践入口。赞分享区块链【免费下载链接】lndLightning Network Daemon ⚡️项目地址https://gitcode.com/gh_mirrors/ln/lnd点击查看免费下载相关推荐Spinnaker Front50 SQL 存储配置指南MySQL / PostgreSQL 接入与元数据迁移Spinnaker Front50 SQL 存储配置指南MySQL / PostgreSQL 接入与元数据迁移 Front50 是 Spinnaker 的元数后端DevOps云原生微服务SkyWalking OAP 动态配置 Apollo 实现详解接入、配置存储与源码原理SkyWalking OAP 动态配置 Apollo 实现详解接入、配置存储与源码原理 SkyWalking OAP 的大部分配置通过 application可观测性APM链路追踪指标监控日志分析微服务Mastra MSSQL 存储适配器实战mastra/mssql 安装配置、连接池与 SQL Server 存储原理解析Mastra MSSQL 存储适配器实战mastra/mssql 安装配置、连接池与 SQL Server 存储原理解析 导读 mastra/mssql人工智能Agent 框架AI AgentRAG后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考