BTCPay Server 项目分析

一、项目定位

BTCPay Server 是一个免费、开源、自托管（self-hosted）的比特币支付处理器 。它在功能上用于替代 BitPay 这类第三方支付网关：商家在自己的服务器上运行它，顾客支付的 BTC 直接进入商家自己的钱包，中间不经过任何托管方。

核心承诺可以用几句话概括：

●    0 手续费 （只付链上网络费）

●    非托管（non-custodial）
：私钥永不上传服务器，收款地址由 xpub 派生，每个账单一个地址，不重复使用

●    无需 KYC、抗审查、可自托管

●    MIT 协议

项目地址：btcpayserver/btcpayserver，官方文档：docs.btcpayserver.org

二、技术栈

开发环境的做法很标准：克隆仓库 → BTCPayServer.Tests 目录下 docker-compose up dev 起 Regtest 网络和依赖 → VS 里 Debug 启动，页面会显示 REGTEST 模式。国内网络下要注意拉取 Docker 镜像和 Bitcoin Core 初始同步（IBD）的耗时，一般会用 Fast Sync 加速。

三、架构与支付流程

浏览器/店铺后端 ──> nginx ──> BTCPay Server (ASP.NET Core)

                                  ├── PostgreSQL（账单、店铺、用户、插件）

                                  ├── NBXplorer（监听地址收款）

                                  │      ├── Bitcoin Core（全节点校验）

                                  │      └── LND / CLN（闪电网络）

                                  └── Webhook ──> 商家后端

典型结账流程（对应官方电商集成指南）：

1.      前端选择 BTC 支付，后端调用 Greenfield API 创建 invoice，并在自己订单表里存下 invoiceId

2.      客户跳转或内嵌弹窗看到二维码并付款

3.      支付进入 mempool 且金额足额时，BTCPay 触发 InvoiceProcessing webhook → 后端标记「待确认」

4.      达到设定确认数（默认 1 个确认）触发 InvoiceSettled webhook → 后端标记「已完成」

5.      闪电网络支付时，上述两个事件几乎同时触发，秒级结算

需要注意：链上支付这两个事件之间通常有约 10 分钟间隔（等下一个区块），所以你的订单状态机必须能处理「已付款但未确认」的中间态。

四、两套 API（做集成时的关键点）

●    Greenfield API（新）
：REST，API Key + storeId 鉴权，是目前推荐的接口，文档齐全，目标是让 BTCPay 可以完全无头运行

●    Legacy API（旧）
：与  BitPay API 完全兼容
，主要是给想从 BitPay 迁移的商家用

对你的电商场景（Shopify 跨境那套），BTCPay 官方提供 Shopify 插件，以及 WooCommerce 等常见电商插件；自研系统直接对接 Greenfield API 即可。

五、内置功能模块

●    账单（Invoice）管理与导出（会计用）

●    支付请求 Payment Requests、退款

●    应用： POS 收银台、众筹、打赏按钮、支付链接

●    内置钱包（支持硬件钱包，如 Ledger/Trezor）+ SegWit

●    多租户 ：一台实例可以共享给朋友或本地社区，成为第三方托管

●    插件体系（Monero、Liquid、ERC-20 等多币种都走插件，核心是 Bitcoin-only 构建）

六、适合谁 / 不适合谁

适合

●    想避开第三方托管和 KYC 的跨境商家（Namecheap 公开过用 BTCPay 处理了超 7300 万美元 BTC 收入）

●    需要接受捐赠、众筹的非营利组织

●    做 Bitcoin 相关产品的开发者：Greenfield API + 插件是很好的二次开发基础

●    想在自己的社区做「支付服务提供方」的技术人

不适合

●    没有运维能力的人（虽然有一键部署，但节点同步、升级、备份都需自己负责）

●    需要法币结算、信用卡收单的业务（BTCPay 不做）

●    需要交易所级别的多币种清算

七、值得警惕的运维风险

6.      备份是真正的命门 ：Lightning 通道状态丢失可能直接导致资金损失，光备份数据库不够，通道状态、seed、Docker volume 都要纳入备份体系

7.      全节点长期运行成本 ：磁盘、带宽、同步时间，国内还得考虑网络可达性，很多部署会选海外 VPS

8.      单点可用性 ：自托管意味着你自己要承担 SLA，宕机时顾客无法付款

9.      升级节奏 ：BTCPay 发布较频繁，插件兼容性需要回归测试

10.   VPS 限制 ：OpenVZ 架构的 VPS 官方明确不支持

八、从代码学习角度值得看的地方

对一个有 .NET 经验、日常用 ASP.NET Core 的开发者来说，这个仓库的参考价值集中在几处：

●    插件化架构 ：可加载插件、独立的插件商店体系，是 ASP.NET Core 应用中比较完整的模块化实践

●    配置与密钥管理 ：大量使用 ASP.NET Core Options + 生成 secrets 的方式，docker-compose 生成器会生成 manifest 声明的 secret 文件

●    Webhook 事件模型
：invoice 状态机 + 幂等重试，是支付网关设计的经典范式

●    双 API 并存策略
：如何在一个应用里同时维护 Greenfield 与 BitPay 兼容层

●    EF Core 迁移 + PostgreSQL 在多租户场景下的应用

九、改造

改造成本很低，建议路径：

1.      Docker 起一个 Regtest 环境（本地不花真钱，几秒出块）

2.      用 Greenfield API 做一个最小的「订单 → 创建 invoice → 接收 webhook 更新状态」闭环

3.      再考虑接入真实 testnet，最后才是 mainnet