BTCPay Server 开源项目安装与使用全指南

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

BTCPay Server 是一款免费、开源且自托管的比特币支付处理器，允许商家直接接受比特币支付而无需第三方中介。本指南将从核心功能解析到实际部署配置，帮助你全面掌握这个强大工具的安装与使用。

🚀 核心功能概览

BTCPay Server 作为去中心化支付解决方案，提供了以下关键能力：

• 无中介支付处理：直接对接比特币网络，无需支付网关或第三方服务
• 多商店管理：支持创建多个独立商店，分别配置支付规则和通知方式
• 丰富的支付方式：支持比特币链上交易、闪电网络（Lightning Network）等多种支付渠道
• 自定义集成：通过 API 和 Webhook 轻松与现有电商系统或自定义应用集成
• 开源与自托管：完全透明的代码base，可部署在自己的服务器上确保数据安全

🔧 环境准备

在开始部署前，请确保你的环境满足以下要求：

环境兼容性检查表

环境要求	最低配置	推荐配置
操作系统	Ubuntu 20.04 LTS	Ubuntu 22.04 LTS
CPU	2核	4核
内存	4GB RAM	8GB RAM
存储	20GB SSD	100GB SSD
网络	稳定互联网连接	静态IP + 域名
依赖	Docker 20.10+ / .NET 6.0 SDK	Docker Compose v2+

基础依赖安装

操作提示：建议优先选择Docker容器化部署，可大幅简化环境配置过程

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装Docker (容器化部署必需)
sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker

# 或安装.NET SDK (原生部署必需)
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt install -y dotnet-sdk-6.0

📦 分步部署指南

1. 获取项目代码

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

2. 选择部署方式

方式一：Docker容器化部署 (推荐)

# 复制环境配置模板
cp .env.example .env

# 编辑配置文件 (至少设置BTCPAY_HOST)
nano .env

# 启动服务
docker-compose up -d

方式二：原生.NET部署

# 进入主应用目录
cd BTCPayServer

# 还原依赖包
dotnet restore

# 构建项目
dotnet build -c Release

# 运行应用
dotnet run --no-build -c Release --urls=http://0.0.0.0:8080

操作提示：容器化部署适合生产环境，原生部署适合开发和调试。首次部署建议使用Docker方式。

⚙️ 配置详解

BTCPay Server的配置系统设计灵活，支持基础设置到高级定制的全场景需求。

基础配置

核心配置文件位于项目根目录的.env（Docker部署）或appsettings.json（原生部署）。

关键配置项速查表：

配置项	默认值	说明	安全建议
BTCPAY_HOST	未设置	服务器域名或IP	生产环境必须使用HTTPS域名
PORT	80	HTTP端口	生产环境应改为非标准端口
HTTPS_PORT	443	HTTPS端口	保持默认，通过反向代理转发
DATABASE_URL	sqlite:///data/btcpayserver.db	数据库连接串	生产环境建议使用PostgreSQL
BTCPAYGEN_CRYPTO1	btc	启用的加密货币	仅启用实际需要的货币

高级配置

通过修改appsettings.json可以实现更精细的控制：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "BTCPayServer": "Debug"  // 调试时设为Debug，生产环境改为Information
    }
  },
  "Lightning": {
    "Enabled": true,
    "Clightning": {
      "Enabled": false
    },
    "Lnd": {
      "Enabled": true,
      "ConnectionString": "type=lnd-rest;server=http://lnd:8080/;macaroonfilepath=/data/lnd/admin.macaroon"
    }
  }
}

安全配置

1. 启用HTTPS：生产环境必须配置SSL证书

   # 使用Let's Encrypt获取免费证书
   sudo apt install certbot
   sudo certbot certonly --standalone -d yourdomain.com
   

2. 设置强密码策略：编辑appsettings.json

   "Authentication": {
     "PasswordPolicy": {
       "RequiredLength": 12,
       "RequireNonAlphanumeric": true,
       "RequireUppercase": true,
       "RequireLowercase": true,
       "RequireDigit": true
     }
   }
   

3. 配置防火墙：只开放必要端口

   sudo ufw allow 22/tcp  # SSH
   sudo ufw allow 443/tcp # HTTPS
   sudo ufw enable
   

版本差异说明：v2.x相比v1.x的配置变化

• 配置文件结构优化，分离了环境特定配置
• 新增BTCPAYGEN_ADDITIONAL_FRAGMENTS支持模块化配置
• 加密货币配置从硬编码改为动态加载

🛠️ 常见问题解决

1. 服务启动失败

症状：Docker部署后容器反复重启 排查步骤：

# 查看容器日志
docker logs btcpayserver_btcpayserver_1

# 常见原因及解决：
# - 端口冲突：修改.env中的PORT和HTTPS_PORT
# - 权限问题：确保数据目录权限正确
# - 配置错误：检查BTCPAY_HOST是否正确设置

2. 无法连接到数据库

解决方法：

• SQLite：确保数据目录可写 chmod -R 775 ./data
• PostgreSQL：检查连接字符串格式 postgresql://user:password@host:port/dbname

3. 闪电网络连接问题

操作提示：这里需要特别注意， Lightning节点需要足够的同步和通道才能正常工作

# 检查LND节点状态
docker exec -it btcpayserver_lnd_1 lncli getinfo

# 确保节点已同步且有足够的通道余额

📚 官方资源导航

• 项目文档：docs/
• 配置示例：BTCPayServer/Configuration/
• API文档：通过部署后的/swagger路径访问
• 社区支持：项目提供的讨论论坛和Issue跟踪系统
• 更新日志：Changelog.md

BTCPay Server作为持续发展的开源项目，建议定期查看更新日志以获取新功能和安全更新信息。通过自托管部署，你可以完全掌控支付流程，同时为比特币生态系统的去中心化发展做出贡献。

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