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，可部署在自己的服务器上确保数据安全
🔧 环境准备
在开始部署前，请确保你的环境满足以下要求：
环境兼容性检查表
| 环境要求 | 最低配置 | 推荐配置 |
|---|---|---|
| 操作系统 | 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 btcpayserver2. 选择部署方式
方式一：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" } } }安全配置
启用HTTPS：生产环境必须配置SSL证书
# 使用Let's Encrypt获取免费证书 sudo apt install certbot sudo certbot certonly --standalone -d yourdomain.com设置强密码策略：编辑
appsettings.json"Authentication": { "PasswordPolicy": { "RequiredLength": 12, "RequireNonAlphanumeric": true, "RequireUppercase": true, "RequireLowercase": true, "RequireDigit": true } }配置防火墙：只开放必要端口
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
