BTCPay Server：自建比特币支付系统完全指南

1. 项目架构解析 📊

1.1 三步掌握核心目录结构

BTCPay Server采用模块化架构设计，核心代码组织清晰：

• BTCPayServer/Controllers/：处理HTTP请求的核心控制器，包含UIInvoiceController.cs等支付相关逻辑
• BTCPayServer/Services/：业务服务层，提供支付处理、汇率转换等核心功能
• BTCPayServer/Plugins/：扩展插件目录，支持Crowdfund、Subscriptions等增值功能

注意：所有业务逻辑通过依赖注入解耦，修改功能时只需关注对应模块，无需全局调整

1.2 避坑指南：环境依赖检查

部署前需确认系统满足：

• .NET 6.0+运行时环境
• PostgreSQL或SQLite数据库支持
• Docker Engine 20.10+（容器化部署）

执行以下命令快速检查环境：

dotnet --version && docker --version

2. 核心组件说明 🔧

2.1 支付处理引擎深度解析

BTCPay Server的支付核心由三层架构构成：

1. 协议层：位于BTCPayServer/Payments/，支持比特币、闪电网络等多种支付协议
2. 业务层：通过InvoiceService.cs实现订单生命周期管理
3. 存储层：使用Entity Framework Core与数据库交互

核心处理流程：创建订单→生成地址→监听区块链→确认支付→触发回调

2.2 插件生态系统使用指南

通过插件机制扩展系统功能：

1. 浏览Plugins/目录选择所需功能（如PointOfSale、Webhooks）
2. 修改BTCPayServer.csproj添加插件引用
3. 重启服务自动加载插件

注意：第三方插件需验证安全性，建议优先使用官方维护的插件

3. 个性化配置指南 ⚙️

3.1 五分钟环境部署

使用Docker快速启动服务：

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

访问http://localhost:23000完成初始化配置

3.2 配置项优先级规则

系统配置按以下顺序生效（优先级从高到低）：

1. 命令行参数（如--port 8080）
2. 环境变量（如BTCPAY_POSTGRES=connectionstring）
3. appsettings.Production.json配置文件
4. 内置默认配置

3.3 安全加固最佳实践

• 启用HTTPS：修改appsettings.json中Kestrel:Endpoints:HTTPS配置
• 限制访问来源：在Security/ServerPolicies.cs中配置IP白名单
• 定期更新：通过docker-compose pull获取安全补丁

注意：生产环境必须设置BTCPAY_SSL_CERTIFICATE_PATH指定SSL证书路径