BTCPay Server Changelog 全解读从 1.0.4 到 2.4.3 的功能演进、安全修复与升级指南【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver本篇文章以开源自托管比特币支付处理器 BTCPay Server 官方仓库的 Changelog.md覆盖 1.0.4.0 至 2.4.3 共 3000 余行为主线系统梳理该项目自 2017 年诞生以来在支付能力、Greenfield API、插件体系、安全加固、数据库与运行时架构上的完整演进路径。读完本文你将掌握各版本的关键特性与破坏性变更、安全修复的来龙去脉、升级前后必须检查的事项并能结合仓库源码如 Build/Version.csproj、BTCPayServer.csproj、docs/db-migration.md验证每个版本声明的真实落地情况。一、Changelog 文档定位与当前仓库版本现状BTCPay Server 是免费、开源、可自托管的比特币支付处理器核心代码集中在 BTCPayServer 目录。仓库根目录的Changelog.md是其唯一的版本发布记录文档按时间倒序记录了从 1.0.4.0 到 2.4.3 的全部 release每个版本条目下通常包含New features/New features:新功能Bug fixes/Fixes缺陷修复Improvements体验与性能改进Breaking changes破坏性变更升级必读Miscellaneous/Deprecations废弃与移除项仓库当前版本与 Changelog 最新条目保持一致Build/Version.csproj 中Version2.4.3/Version且 BTCPayServer/BTCPayServer.csproj 通过Import Project../Build/Version.csproj /统一引入版本号。这意味着 Changelog 不是一份滞后的历史记录而是与当前源码构建产物同步的权威版本说明书。从整体时间线看可以划分出三个阶段阶段版本区间主题1.0.x1.0.4.0 – 1.0.7.2支付核心能力成型Pull Payments、Refunds、Payjoin、Greenfield 起步1.x 后期1.1.0 – 1.13.7插件化、Checkout v2、自定义角色、报告系统、多签与硬件钱包2.x2.0.0 – 2.4.3界面国际化、订阅系统、更细粒度权限、运行时升级.NET 8/.NET 10、安全专项发布二、最新版本 2.4.x安全专项发布与钱包可用性提升Changelog 开头即是当前处于安全发布状态的 2.4.x 系列是整份文档中升级优先级最高的版本。2.4.2 与 2.4.3被积极利用的漏洞必须尽快升级2.4.2 被明确标注为包含一个正在被积极利用的关键漏洞修复需要尽快升级由 Bitcoin Red Team 的 brunoerg 与 benthecarman 报告同时建议集成方将 NBXplorer 同步升级到 2.6.10。2.4.3 则作为补充的安全发布特别建议与许多用户共享服务器的部署立即更新。唯一破坏性变更Breaking changeGreenfield API 默认在账户创建五分钟后禁用 Basic authentication基础认证可通过账户设置与 API 选择开启#7492。Changelog 明确说明目前未发现受此变更影响的用户因为实际使用中普遍采用 API Key 认证——这一判断与仓库中 BTCPayServer.Client 的 API Key 体系、以及 Security/GreenField 目录下的权限实现相互印证。值得重点关注的修复TOTP 双因素绕过修复#7491修复通过 Greenfield Basic authentication 绕过 TOTP 二步验证的问题。这解释了上述 Basic 认证默认关闭的动机——2.4.2 的破坏性变更本质上是该漏洞纵深防御的一部分。多签 PSBT 签名与终结可靠性提升#7484 #7488包括对更新版 HWI 与 Jade 固件的兼容直接服务于 Plugins/Multisig 插件场景。RTL 样式表加载修复#7482配合 2.4.1 引入的阿拉伯语、希伯来语、波斯语等从右到左语言支持。新功能方面2.4.2 为钱包交易表格增加了隐藏、显示与重排列能力#74742.4.1 则带来一批高价值增量包括钱包 BIP-329 标签导入#7457、发票可编辑备注#7444支持 Greenfield API 与报告导出、退款触发的新邮件规则#7374、Greenfield 退款支持payoutMethods数组#7413等。2.4.1RTL 国际化与日期范围选择器重做2.4.1 的亮点是为阿拉伯语、希伯来语、波斯语等 RTL 语言适配整个 UI#7428同时日期范围选择器获得全面升级支持时区配置#7424新增This month、This week、This quarter等更贴合的默认日期范围过滤器#7424修复跨夏令时DST边界的日期范围过滤错误#7424日期时间选择器改用浏览器偏好的小时格式#7424。对 DST 边界的修复细节体现了 BTCPay 对财务数据准确性的要求——报告与发票过滤涉及资金对账时间边界的处理错误会直接导致金额统计偏差。Changelog 还列出了一系列 Lightning 相关修复Boltcard 支付、LNDHub 默认启用、Core Lightning 兼容性、c-lightning 的 MaxFeePercent 单位从 satoshi 修正为 millisatoshi涉及 BTCPayServer/LightningConfigurationProvider.cs 与 Payments/Lightning 目录所代表的闪电网络集成层。三、2.3.x订阅系统、无密码认证与 .NET 10 切换2.3.x 是功能密集的系列其中最关键的三个里程碑值得展开。2.3.7首个基于 .NET 10 的版本2.3.7 是第一个使用 .NET 10 的版本Changelog 明确邀请插件开发者参考官方迁移指南平滑迁移并建议用户在升级到 2.3.7 后更新插件。这对自托管部署是硬性提示运行时大版本切换意味着旧插件可能不兼容务必在升级后检查插件更新。仓库中 Plugins 目录下数量众多的插件源码以及 Plugins/PluginManager 的插件管理实现正是这一提醒的落地支撑。该版本还引入了发送视图事务备注#6687 #7265、订阅手动日期编辑#7231 #7257、支持顶层发票生成无金额 BOLT11#7263、Greenfield 的 UpdateCrowdfundApp 端点#7202等。2.3.0订阅系统Subscriptions元年2.3.0 是整个 2.x 系列中商业能力跃升的版本订阅功能商家可接受客户的周期性重复支付#6922并提供完整 Greenfield Subscriptions API#7022客户端模型集中在 BTCPayServer.Client/Models/Subscriptions 目录。服务器级邮件规则新增 Server Email Rules 概念管理员可自定义密码重置、邮箱确认、邀请、账户批准、审批请求等系统邮件#6979邮件规则引擎与 Plugins/Emails 插件相关代码对应。邮件规则能力扩展增加Condition字段支持复杂触发条件、CC/BCC字段且Subject、To、CC、BCC支持占位符#7016 #6979。语言包后端 UI 可安装语言包#6943语言数据可在 wwwroot/locales 下找到对应 JSON 文件。2.3.5 与 2.3.6可运维性与安全细节BTCPAY_NODEFAULTCHAIN环境变量允许 BTCPay Server 在没有任何链上支付方式的情况下启动#7180对应 Configuration 目录下的选项解析体系全局 UI 控制器 CSRF 防护#7199Greenfield Basic auth 调用限流#7177插件可创建新的权限策略#7215 #7156测试套件从 Selenium 迁移到 Playwright#268 条目下对应 BTCPayServer.Tests/PlaywrightTester.cs 与 BTCPayServer.Tests/PlaywrightTests.cs。2.3.x 其他值得注意的变更2.3.3CoinGecko 汇率源被移除——CoinGecko API 强制要求 API KeyBTCPay 决定停止支持其汇率源依赖 CoinGecko 的发票创建将失败必须改用其他汇率提供商#7096。LTC 默认汇率源从 CoinGecko 切换为 Kraken。2.3.4webhook 交付增加deliveryTime属性#7140某些 HTTP 状态码不再触发 webhook 重试#7139。2.3.1修复插件导致 BTCPay Server 启动循环崩溃的问题并新增启动崩溃时禁用全部插件的保护机制#7046。四、2.0 – 2.2现代化重构、报告系统与 API 大规模扩展2.2.0报告与发票导出重构2.2.0 将Legacy Invoice Export重命名并重排为Invoice Export属于破坏性变更——依赖旧格式的工作流可能受影响需要旧格式者可安装Legacy Invoice Export插件恢复。同时该版本在发票报告中导出全部发票元数据#6835钱包事务列表与报告加入交易手续费、费率信息#6857与汇率跟踪#6841新增Additional rates to track商店设置#6841支持钱包策略/miniscript#6765插件依赖自动安装#6858 #6873。建议同步升级 NBXplorer 到 2.5.28。2.1.x硬件钱包、描述符与费率源2.1.1 引入钱包策略输出描述符子集支持BIP388、BIP389、硬件钱包 Taproot 签名BIP86#6678、支付请求与外部发票如 QuickBooks、Xero通过Reference Id关联及对应 webhook#6642。2.1.2 增加 PoS 税率#6724、InvoiceExpiredPaidPartial与InvoicePaidAfterExpiration两个新 webhook#5936 #6723、RBF 交易加速#6748、phoenixd 支持、Greenfield 发票amountPaid字段#6747。2.1.0 则是大版本断点Monero 与 ZCash 移出核心代码转为插件#6535若使用非 Docker 部署需从配置移除--chains xmr/--chains zec或对应BTCPAY_CHAINS冷钱包创建默认禁用#6626新增 RBF 支持与 CPFP 优化#6581。2.0.0界面国际化的全面铺开2.0.0 是 1.x 到 2.x 的跨越Changelog 特别提示升级前关注三点大型实例可能经历几分钟数据库迁移自定义集成与插件需更新以兼容 2.0 APIGreenfield API 开发者应检查破坏性变更。核心新功能包括界面本地化多语言支持#5662 等系列 PR全新侧边栏导航与引导流程可插拔的汇率提供商#5777用户名称与头像#6008Greenfield 通知管理#6058、文件上传端点#6075。Deprecations一节信息量很大移除实验性托管账户、移除 Checkout V1、移除 MySQL 与 SQLite 依赖#5910、移除 PullPayment 的 period 概念、移除 Altcoins 构建#6177。其中移除 MySQL/SQLite与 docs/db-migration.md 中的迁移指引、BTCPayServer.Data/Migrations 目录下 76 个迁移文件直接对应标志着 2.x 全面转向 PostgreSQL。五、1.0 – 1.13从支付处理器到支付平台的进化1.13.x引入邀请制、BBQr 与商店级管理1.13.0 增加服务器实例名自定义与联系 URL#5718 #5872、管理员商店总览#5745 #5782、邀请新用户流程#5714 #5719 #5874、PoS Keypad 商品列表#5814 #5857 #5877与 BBQr PSBT 支持#5852。1.13.2 增加退款报告#5791。1.12.x.NET 8 与 BIP129 多签导入1.12.0 升级到 .NET 8#5479要求 Docker Engine 20.10.10Lightning 集成重构为可由插件扩展#5422同时为 Altcoins 迁移到插件做准备——升级后插件大概率会被禁用需要安装兼容 v1.12 的新版本。该版本还支持 BIP129 多签钱包导入#5389、Boltcard 与 Pull Payment 配对/重置#5419、插件安装/更新计划调度#5537。此外1.12.0 宣布结束对 PostgreSQL 11 的支持。1.11.x报告系统彻底重做与产品分类1.11.0 完成发票报告系统的全面改造#5095 #5155、PoS 购物车重新设计#5109 #5171、PoS 产品分类#5088 #5078、Checkout v2 支付成功音效#5085 #5113。1.11.5 为报告增加 payouts#5320并引入归档商店与应用能力#5296。1.10.x自定义角色与表单系统1.10.0 突破性地引入自定义角色除了默认的 Owner 与 Guest可创建新角色并调整 Owner/Guest 的权限#4940表单获得可视化编辑器#4968与多行输入#4942新增隐藏敏感信息设置#4966。角色体系对应 BTCPayServer/Roles.cs 与 Security 目录下的权限实现。1.10.0 还提示 webhook 交付数据因磁盘占用过大将定期清理超过两个月的数据自动删除#5005。1.8 – 1.9Generic Forms、Checkout v2 与零售预设1.8.0 推出 Generic Forms 表单系统#4561 #4668 #4697、地址标签#4594、管理员可创建/删除任意用户的 API Key#4680。1.9.0 增加零售场景的 checkout 预设#4756、Checkout v2 的 confetti 庆祝动效#4727、BIP-329 钱包事务导出#4799、付款证明展示#4782并默认对新商店启用 Checkout V2#4850。1.9.0 的破坏性变更以--sqlitefile或--mysql启动将失败除非处于迁移上下文新引入--deprecated标志临时允许 SQLite/MySQL 启动。1.6 – 1.7Dashboard、Payout Processors 与 Checkout v21.5.0 引入Dashboard 仪表盘#3530 #3629 #3631 #3654、Payout Processors#3476与自动审批#1851 #3682。1.6.0 增加仪表盘 Lightning 余额#3838、LNURL Withdraw 付款#3709、基于发票事件的参数化邮件#3611。1.7.0 引入 Checkout v2 作为可选功能#4157 #4276 #4345、客户表单收集邮箱与收货地址#4137、商店品牌选项#4131、Greenfield 商店汇率配置#3931与钱包对象 API#4274 #4297。1.7.4 改变了插件重启机制重启按钮改为直接终止进程交由 systemd 或 Docker 自动拉起这要求所有部署方式必须配置自动重启能力。1.0.5 – 1.0.6Pull Payments、Refunds 与 Greenfield 起步1.0.5.0 是 1.x 早期最重要的版本引入**通知Notifications、Pull Payments、Refunds退款**三大特性支持 BIP21 原生钱包跳转、Server Info Greenfield API、支付请求 Greenfield API、Cobo Vault / Wasabi 钱包文件导入、跨实现 Lightning 节点 Greenfield API、Tor Onion-Location HTTP 头。1.0.6.0 增加统一二维码链上 链下合一#2060、全新 webhook API#2058、实验性插件系统#2058并将发票状态Confirmed/Complete改名为Settled、Paid改名为ProcessingGreenfield 破坏性变更。1.0.6.5 加入输出描述符子集支持与 API Key/服务器 URL 二维码配对。1.0.4.0 则是 Payjoin 时代开端收款端商店 Payjoin 支持、发款端内部钱包 Payjoin、Coin Selection、双主题亮/暗checkout 与站点皮肤、钱包摄像头扫码、Greenfield 权限体系重构与 C# 客户端对应 BTCPayServer.Client 项目。六、贯穿各版本的主线脉络6.1 安全从 XSS 修补到 TOTP 绕过与主动利用漏洞Changelog 记录了长期的安全对抗史是运维人员评估升级紧迫性的第一手依据1.2.3三个 XSS 漏洞修复引入 CSP#2856 #28631.7.11 / 1.8.3 / 2.0.3持续的 XSS 与 HTML 注入修复1.9.0支持以--deprecated标志过渡 SQLite/MySQL2.0.2Nostr 与 Blink 插件用户被视为安全关键——未修复版本中拥有 Pull Payment 访问权的攻击者可无限制抽干 Lightning 钱包2.0.6针对特定链上配置的重复 payout 关键漏洞修复#6540 #65642.4.2/2.4.3被积极利用的漏洞 TOTP 绕过修复。仓库中 Security 目录含 GreenField 子目录、PermissionAuthorizationHandler、SetContextFilter 等与 Filters 目录CSP、X-Frame、Referrer 等响应头过滤器是这些安全措施在当前源码中的实现载体。6.2 数据库MySQL/SQLite → PostgreSQL 的坚定迁移从 1.7.1 标记 MySQL/SQLite 废弃、1.7.8 提供迁移路径docs/db-migration.md、1.9.0 默认禁止非迁移启动、2.0.0 移除依赖BTCPay 用数个版本完成了数据库统一。运维升级时应确认 BTCPayServer.Data/Migrations 对应的迁移在大型实例上会消耗数分钟且 docker-entrypoint.sh 与BTCPAY_环境变量体系见 Configuration需同步检查。6.3 运行时与工具链.NET 3.1 → .NET 6 → .NET 8 → .NET 101.4.0从 .NET 3.1 迁移到 .NET 6.0启用 C# 101.12.0升级 .NET 8Docker 引擎需 20.10.102.3.7首个 .NET 10 版本插件需同步迁移。每次运行时升级都伴随插件兼容性风险这也是 Changelog 反复提示升级后更新插件的原因。6.4 国际化与 RTL从 checkout 翻译到全 UI 本地化早期 1.0.4.x 就开始扩充 checkout 语言2.0.0 全面铺开界面本地化2.3.7 为发票 checkout 增加阿拉伯语、希伯来语、波斯语 RTL 支持#444 #72592.4.1 将 RTL 适配扩展到整个 UI 并修复 RTL 样式表加载。前端语言文件可在 wwwroot/locales 中查看。6.5 插件化从实验到系统化1.0.6.0 引入实验性插件系统1.6.11 将 PoS 与 Crowdfund 改为系统插件#39872.0.0 允许插件注册汇率提供商2.3.6 允许插件创建权限策略2.3.1 增加启动崩溃自动禁用插件保护。插件生态在仓库中占据极大比重Plugins 下包含 Altcoins、Bitpay、Crowdfund、Emails、Forms、Monetization、Multisig、NFC、PayButton、PointOfSale、Subscriptions、Webhooks 等二十余个子目录插件开发基础设施见 BTCPayServer.Abstractions/Contracts/IBTCPayServerPlugin.cs。七、升级实操如何用好这份 Changelog7.1 升级前的检查清单结合 Changelog 中反复出现的注意事项建议按如下顺序核对读取最高版本条目若最新版本标注 security release 或actively exploited应优先排期升级核对 Breaking changes2.4.2 的 Basic 认证默认关闭、2.2.0 的 Invoice Export 重命名、2.1.0 的 ZCash/Monero 插件化、2.0.0 的 API 变更、1.9.0 的 SQLite/MySQL 启动限制均属此列检查插件兼容性1.12.0、2.0.0、2.3.7 三个版本对插件生态影响最大升级后进入Manage Plugins页面确认插件状态与更新同步升级周边组件2.4.2 要求 NBXplorer 2.6.10、2.2.0 建议 NBXplorer 2.5.28、1.12.0 要求 Docker 20.10.10评估数据库迁移时间2.0.0 明确提示大型实例迁移需数分钟应选择低峰期操作。7.2 在仓库中验证每个版本声明Changelog 中的每个条目都能在源码中找到落点例如当前版本号见 Build/Version.csproj订阅 API 模型见 BTCPayServer.Client/Models/Subscriptions数据库迁移见 BTCPayServer.Data/Migrations 与 docs/db-migration.md权限与角色见 Security 与 Roles.cs测试验证Playwright UI 测试见 BTCPayServer.Tests/PlaywrightTests.cs核心单元测试见 BTCPayServer.Tests 下各*Tests.cs文件。7.3 长期维护建议将 Changelog 中标注security的版本视为升级硬门槛不要跳过关注Deprecations/Miscellaneous小节提前规划被移除功能如 1.10.0 的 webhook 交付数据自动清理、2.0.0 的 MySQL/SQLite的替代方案2.x 版本对 Linux、Docker、PostgreSQL 的组合依赖持续收紧升级前对照 Dockerfile、docker-entrypoint.sh 与 README.md 核对部署基线。结语从 1.0.4.0 的 Payjoin 与 Greenfield 起步到 2.4.3 的 TOTP 安全加固这份 Changelog 完整记录了一个开源支付处理器八年的进化史支付能力从单一链上收款扩展到 Lightning、LNURL、PayJoin、Pull Payments 与订阅架构从单体走向插件化数据库与运行时持续向现代化收敛国际化从 checkout 覆盖到整个管理界面。对自托管运维者而言它是最可靠的升级决策依据对开发者而言它是理解 BTCPay Server 当前源码结构BTCPayServer、BTCPayServer.Client、BTCPayServer.Data 三大工程的索引地图。【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考