BTCPay Server 安装与使用指南

1. 核心功能解析

1.1 项目核心模块速览

BTCPay Server 是一个开源的比特币支付处理器，采用模块化架构设计，主要包含以下核心组件：

• 支付处理模块：支持比特币及多种 altcoin 支付，提供闪电网络和链上交易处理能力
• 商店管理系统：允许创建和管理多个商店，配置不同的支付方式和费率
• 用户认证与授权：基于角色的访问控制，支持多用户协作管理
• 报表与分析：提供交易历史、收入统计等财务数据可视化功能
• 插件生态：支持通过插件扩展功能，如 POS 系统、订阅服务、邮件通知等

1.2 部署决策树

选择适合的部署方式取决于您的技术背景和使用场景：

• 源码部署：适合开发者或需要深度定制的场景，需手动配置依赖环境
• 容器部署：适合快速启动和生产环境使用，通过 Docker 容器化简化部署流程
• 混合部署：结合两者优势，核心服务容器化，自定义组件源码编译

⚠️ 注意：生产环境建议使用容器部署以确保环境一致性和安全性，同时便于版本管理和更新。

2. 环境配置

2.1 系统要求

最低配置：

• CPU：双核处理器
• 内存：4GB RAM
• 存储：20GB 可用空间
• 操作系统：Linux (推荐 Ubuntu 20.04+)、Windows 10/Server 2019 或 macOS 10.15+

推荐配置：

• CPU：四核处理器
• 内存：8GB RAM
• 存储：100GB SSD
• 网络：稳定的互联网连接，建议固定 IP 地址

2.2 依赖项安装

📌 基础依赖安装

# Ubuntu/Debian 系统
sudo apt update && sudo apt install -y git curl wget apt-transport-https

# CentOS/RHEL 系统
sudo dnf install -y git curl wget

验证方法：运行 git --version 和 curl --version 确认命令可正常执行

3. 实战操作

3.1 系统部署双路径

3.1.1 源码部署：三步启动法

📌 步骤一：获取源码

git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver
cd btcpayserver

验证方法：检查目录下是否存在 btcpayserver.sln 文件

📌 步骤二：配置环境

# 安装 .NET SDK
curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --version 6.0.413

# 配置环境变量
export PATH="$HOME/.dotnet:$PATH"

验证方法：运行 dotnet --version 应显示 6.0.x 版本号

📌 步骤三：启动服务

cd BTCPayServer
dotnet run --urls=http://0.0.0.0:8080

验证方法：打开浏览器访问 http://localhost:8080，应看到 BTCPay Server 欢迎页面

3.1.2 容器部署：一键启动方案

📌 快速启动命令

git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver
cd btcpayserver
docker-compose up -d

验证方法：运行 docker ps 检查容器状态，确认 btcpayserver 容器正在运行

3.2 初始配置：配置黄金法则

3.2.1 基本设置

首次访问系统后，需完成以下关键配置：

1. 创建管理员账户（使用强密码，至少 12 位包含大小写字母、数字和特殊符号）
2. 配置域名（推荐使用 HTTPS，可通过 Let's Encrypt 获取免费证书）
3. 设置数据库（生产环境建议使用 PostgreSQL，而非默认的 SQLite）

⚠️ 注意：生产环境需设置独立数据库密码，并定期备份数据库文件

3.2.2 配置示例卡片

数据库配置（appsettings.json）：

"ConnectionStrings": {
  "Postgres": "Host=db;Port=5432;Database=btcpay;Username=btcpayuser;Password=your_strong_password"
}

• 推荐值：使用 PostgreSQL 13+ 版本
• 安全阈值：密码长度至少 16 位，包含大小写字母、数字和特殊符号

4. 进阶技巧

4.1 生产环境优化建议

📌 优化一：启用 HTTPS

# 使用 Certbot 获取免费 SSL 证书
sudo certbot --nginx -d yourdomain.com

验证方法：访问 https://yourdomain.com，浏览器应显示安全锁图标

📌 优化二：配置自动备份

# 创建备份脚本
cat > backup-btcpay.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/var/backups/btcpay"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p $BACKUP_DIR
docker exec btcpayserver_postgres_1 pg_dump -U btcpayuser btcpay > $BACKUP_DIR/btcpay-$TIMESTAMP.sql
EOF

# 添加执行权限并设置定时任务
chmod +x backup-btcpay.sh
crontab -e
# 添加: 0 2 * * * /path/to/backup-btcpay.sh

验证方法：检查 /var/backups/btcpay 目录是否生成备份文件

📌 优化三：启用监控

# 安装 Prometheus 和 Grafana
docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

验证方法：访问 http://localhost:3000 登录 Grafana，默认用户名/密码为 admin/admin

4.2 功能扩展指南

BTCPay Server 支持通过插件扩展功能，以下是常用插件的安装方法：

4.2.1 POS 系统插件

# 进入插件目录
cd BTCPayServer/Plugins/PointOfSale

# 编译插件
dotnet build

使用方法：在管理界面中启用 POS 插件，创建产品目录并生成销售点页面

4.2.2 订阅服务插件

# 安装订阅插件
cd BTCPayServer/Plugins/Subscriptions
dotnet build

使用方法：在商店设置中启用订阅功能，创建订阅计划并生成订阅按钮代码

4.3 常见问题诊断

4.3.1 服务无法启动

• 检查日志：tail -f BTCPayServer/logs/btcpay.log
• 常见原因：端口被占用（默认 8080），可通过 --urls 参数修改端口
• 解决方案：dotnet run --urls=http://0.0.0.0:8081

4.3.2 支付无法处理

• 检查节点连接：在管理界面的"服务器设置"中确认比特币节点连接状态
• 常见原因：节点未同步或网络连接问题
• 解决方案：确保节点已完成同步，检查防火墙设置

BTCPay Server 标志，代表项目的核心品牌标识

通过以上指南，您应该能够成功部署和使用 BTCPay Server。根据您的具体需求，可以进一步探索高级功能和插件生态，定制适合您业务的支付解决方案。