BTCPay Server 安装与使用全指南：从核心功能到生产部署

【免费下载链接】btcpayserver Accept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor. 【免费下载链接】btcpayserver 项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver

BTCPay 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 个钱包管理界面

BTCPay Server 品牌标识 图 1：BTCPay Server 品牌标识，绿色与黄色几何图形构成的"BTC"字母组合

二、环境准备：构建生产级运行环境

2.1 验证系统兼容性：3项核心检查

  1. 验证操作系统：确认使用 Ubuntu 20.04+ 或 Debian 11+，通过 lsb_release -a 检查版本
  2. 检查 Docker 环境：执行 docker --version 确保 Docker 20.10+ 已安装
  3. 验证 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 源码构建与启动：开发模式

  1. 克隆代码仓库：git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver
  2. 进入项目目录：cd btcpayserver/BTCPayServer
  3. 还原依赖包：dotnet restore
  4. 启动开发服务器：dotnet run --launch-profile "https"
  5. 访问系统：打开浏览器访问 https://localhost:44301

3.2 容器化部署：生产模式

  1. 配置环境变量：创建 .env 文件设置 BTCPAY_HOST=yourdomain.com
  2. 启动服务栈：docker-compose -f docker-compose.yml up -d
  3. 初始化管理员账户：访问 https://yourdomain.com 完成注册
  4. 配置域名解析：将域名 A 记录指向服务器 IP 地址
  5. 启用 HTTPS：运行 ./btcpay-setup.sh 配置 Let's Encrypt 证书

小贴士：生产环境建议设置防火墙，仅开放 80/443 端口，通过 ufw allow 443/tcp 配置

验证标准：服务启动后，访问 /api/v1/health 应返回 {"status":"Healthy"} JSON 响应

四、深度配置：场景化参数矩阵

4.1 开发环境配置：本地测试优化

参数类别 关键配置项 推荐值 配置文件路径
数据库 ConnectionStrings__Postgres Host=localhost;Port=5432;Database=btcpay-dev appsettings.Development.json
日志级别 Logging__LogLevel__Default Debug appsettings.Development.json
闪电网络 Lightning__Clightning__Enabled true appsettings.json

配置步骤：

  1. 复制模板文件：cp appsettings.json appsettings.Development.json
  2. 修改数据库连接字符串
  3. 启用开发特性：设置 "ExperimentalFeatures": true

4.2 生产环境配置：安全与性能优化

核心配置文件：BTCPayServer/Configuration/BTCPayServerOptions.cs

  1. 配置数据库连接：
"ConnectionStrings": {
  "Postgres": "Host=db;Port=5432;Username=postgres;Password=securepassword;Database=btcpay"
}
  1. 设置域名与端口：
"Server": {
  "Domain": "pay.yourdomain.com",
  "Port": 443,
  "UseHttps": true
}
  1. 配置缓存策略：
"Cache": {
  "Redis": "redis:6379",
  "CacheDuration": "00:30:00"
}

4.3 容器部署配置：Docker 环境变量

通过 .env 文件设置关键参数：

# 基础设置
BTCPAY_HOST=pay.example.com
REVERSEPROXY_HTTP_PORT=80
REVERSEPROXY_HTTPS_PORT=443

# 高级选项
BITCOIN_NETWORK=mainnet
NBXPLORER_PORT=24444
LIGHTNING_ALIAS=MyBTCPayServer

验证标准：修改配置后，通过 docker-compose logs -f btcpayserver 查看日志，确认无 ERROR 级别日志输出

五、功能验证：核心业务流程测试

5.1 创建测试发票：完整支付流程

  1. 登录管理后台，导航至 Stores → New Store 创建商店
  2. 进入 Invoices → Create Invoice，填写测试订单信息
  3. 选择支付方式（比特币链上/闪电网络）
  4. 使用比特币钱包扫描生成的二维码
  5. 确认支付成功：系统显示"Payment Received"状态

5.2 API 集成测试：使用 Greenfield API

  1. 创建 API 密钥：Account → API Keys → Generate New
  2. 调用创建发票 API：
curl -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"}'
  1. 验证响应：应返回包含 id 和 checkoutLink 的 JSON 数据

验证标准：发票创建后 30 秒内可在区块链浏览器中查询到交易信息，系统状态更新为"Confirmed"

BTCPay Server 启动界面 图 2：BTCPay Server 启动界面，中央为绿色与黄色构成的品牌标志

六、常见问题解决：故障排查指南

6.1 服务启动失败：日志诊断流程

  1. 检查容器日志：docker-compose logs btcpayserver
  2. 验证数据库连接：docker exec -it btcpayserver_db psql -U postgres
  3. 检查端口占用：netstat -tulpn | grep 443

6.2 支付确认延迟：区块链同步问题

  1. 检查区块同步状态：访问 /serverinfo 查看区块高度
  2. 验证 NBXplorer 连接：docker-compose logs nbxplorer
  3. 调整同步参数：修改 NBXplorer__SyncMode 为 "Full"

验证标准：所有服务重启后，系统应在 5 分钟内完成区块链初始同步，可通过 /api/v1/explorer/blocks 接口确认最新区块高度

通过以上步骤，你已完成 BTCPay Server 的完整部署与配置。系统支持持续扩展，可通过插件系统添加更多加密货币支持或集成第三方服务。如需进一步定制，可查阅 docs/ 目录下的高级配置指南。

【免费下载链接】btcpayserver Accept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor. 【免费下载链接】btcpayserver 项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

OpenClaw部署和使用心得

avatar 龙虾开发者社区
cover

我把OpenCode连上了微信ClawBot

avatar 龙虾开发者社区

AI 龙虾 | 对学习工作的影响和未来前瞻

AI 龙虾（OpenClaw）是能自主操控设备、完成全流程任务的 AI 智能体，核心是 “动口即执行”，正从工具升级为数字生产力单元，深刻重塑学习与工作模式。

avatar 龙虾开发者社区