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

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

【免费下载链接】btcpayserverAccept 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，可部署在自己的服务器上确保数据安全

🔧 环境准备

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

环境兼容性检查表

基础依赖安装

操作提示：建议优先选择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（原生部署）。

关键配置项速查表：

高级配置

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

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