BTCPay Server 安装与使用全指南从核心功能到生产部署【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserverBTCPay Server 是一款免费开源的自托管比特币支付处理器支持无需第三方中介的点对点交易处理。本指南将帮助你从功能理解到环境配置快速构建安全可靠的比特币支付系统。一、核心功能解析理解支付系统架构1.1 支付协议处理核心BTCPayServer/Controllers 模块Controllers 目录包含 50 个 API 控制器是系统对外提供服务的核心入口。其中UIInvoiceController处理发票创建、支付状态更新等核心业务逻辑GreenField 子目录提供 33 个 RESTful API 端点支持第三方系统集成UILightningNodeInfoController管理闪电网络节点信息查询与状态监控小贴士通过grep -r HttpPost BTCPayServer/Controllers可快速定位所有支付相关 API 端点1.2 区块链交互层BTCPayServer/Services 模块该模块实现与比特币网络的核心交互包含NBXplorerConnectionFactory建立与区块链浏览器的连接LightningClientFactoryService管理闪电网络客户端实例WalletRepository处理钱包地址生成与资金管理验证标准通过list_code_definition_names工具可查看该目录下 20 个服务类定义确保核心服务类如InvoiceService、WalletService存在1.3 前端交互界面BTCPayServer/Views 模块包含 200 个 Razor 视图文件实现响应式用户界面UIInvoice 子目录提供 12 个发票相关页面模板Shared 目录包含 43 个公共组件导航栏、页脚、表单控件等UIWallets 目录提供 21 个钱包管理界面图 1BTCPay Server 品牌标识绿色与黄色几何图形构成的BTC字母组合二、环境准备构建生产级运行环境2.1 验证系统兼容性3项核心检查验证操作系统确认使用Ubuntu 20.04或Debian 11通过lsb_release -a检查版本检查 Docker 环境执行docker --version确保 Docker 20.10 已安装验证 Git 工具链运行git --version确认 Git 2.20 可用2.2 安装核心依赖2种部署模式选择开发环境本地测试# 安装 .NET SDK 6.0 sudo apt-get update sudo apt-get install -y dotnet-sdk-6.0 # 安装 Node.js (前端资源构建) curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - sudo apt-get install -y nodejs生产环境服务器部署# 使用 Docker Compose 一键部署依赖 git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver cd btcpayserver docker-compose up -d验证标准开发环境下运行dotnet --list-sdks应显示 6.0.x 版本生产环境下docker ps应显示btcpayserver容器状态为Up三、快速启动5分钟部署支付系统3.1 源码构建与启动开发模式克隆代码仓库git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver进入项目目录cd btcpayserver/BTCPayServer还原依赖包dotnet restore启动开发服务器dotnet run --launch-profile https访问系统打开浏览器访问https://localhost:443013.2 容器化部署生产模式配置环境变量创建.env文件设置BTCPAY_HOSTyourdomain.com启动服务栈docker-compose -f docker-compose.yml up -d初始化管理员账户访问https://yourdomain.com完成注册配置域名解析将域名 A 记录指向服务器 IP 地址启用 HTTPS运行./btcpay-setup.sh配置 Lets Encrypt 证书小贴士生产环境建议设置防火墙仅开放 80/443 端口通过ufw allow 443/tcp配置验证标准服务启动后访问/api/v1/health应返回{status:Healthy}JSON 响应四、深度配置场景化参数矩阵4.1 开发环境配置本地测试优化参数类别关键配置项推荐值配置文件路径数据库ConnectionStrings__PostgresHostlocalhost;Port5432;Databasebtcpay-devappsettings.Development.json日志级别Logging__LogLevel__DefaultDebugappsettings.Development.json闪电网络Lightning__Clightning__Enabledtrueappsettings.json配置步骤复制模板文件cp appsettings.json appsettings.Development.json修改数据库连接字符串启用开发特性设置ExperimentalFeatures: true4.2 生产环境配置安全与性能优化核心配置文件BTCPayServer/Configuration/BTCPayServerOptions.cs配置数据库连接ConnectionStrings: { Postgres: Hostdb;Port5432;Usernamepostgres;Passwordsecurepassword;Databasebtcpay }设置域名与端口Server: { Domain: pay.yourdomain.com, Port: 443, UseHttps: true }配置缓存策略Cache: { Redis: redis:6379, CacheDuration: 00:30:00 }4.3 容器部署配置Docker 环境变量通过.env文件设置关键参数# 基础设置 BTCPAY_HOSTpay.example.com REVERSEPROXY_HTTP_PORT80 REVERSEPROXY_HTTPS_PORT443 # 高级选项 BITCOIN_NETWORKmainnet NBXPLORER_PORT24444 LIGHTNING_ALIASMyBTCPayServer验证标准修改配置后通过docker-compose logs -f btcpayserver查看日志确认无ERROR级别日志输出五、功能验证核心业务流程测试5.1 创建测试发票完整支付流程登录管理后台导航至Stores → New Store创建商店进入Invoices → Create Invoice填写测试订单信息选择支付方式比特币链上/闪电网络使用比特币钱包扫描生成的二维码确认支付成功系统显示Payment Received状态5.2 API 集成测试使用 Greenfield API创建 API 密钥Account → API Keys → Generate New调用创建发票 APIcurl -X POST https://yourdomain.com/api/v1/stores/{storeId}/invoices \ -H Authorization: token {apiKey} \ -H Content-Type: application/json \ -d {amount: 0.001, currency: BTC}验证响应应返回包含id和checkoutLink的 JSON 数据验证标准发票创建后 30 秒内可在区块链浏览器中查询到交易信息系统状态更新为Confirmed图 2BTCPay Server 启动界面中央为绿色与黄色构成的品牌标志六、常见问题解决故障排查指南6.1 服务启动失败日志诊断流程检查容器日志docker-compose logs btcpayserver验证数据库连接docker exec -it btcpayserver_db psql -U postgres检查端口占用netstat -tulpn | grep 4436.2 支付确认延迟区块链同步问题检查区块同步状态访问/serverinfo查看区块高度验证 NBXplorer 连接docker-compose logs nbxplorer调整同步参数修改NBXplorer__SyncMode为Full验证标准所有服务重启后系统应在 5 分钟内完成区块链初始同步可通过/api/v1/explorer/blocks接口确认最新区块高度通过以上步骤你已完成 BTCPay Server 的完整部署与配置。系统支持持续扩展可通过插件系统添加更多加密货币支持或集成第三方服务。如需进一步定制可查阅docs/目录下的高级配置指南。【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考