BTCPay Server 从零上手完整指南：自建比特币支付处理器实操

BTCPay Server 从零上手完整指南自建比特币支付处理器实操【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserverBTCPay Server 是一个免费开源、可自托管的比特币支付处理器让你不经过中间商、不交平台手续费地直接收取比特币。读完本文你能拉取代码在本地跑起来、用 Docker 部署上线并改掉端口、数据库等常见配置。项目速览自托管比特币支付处理器定位解决什么问题商户收比特币 私钥自持。非托管密钥在你手里、零平台抽成只付矿工费且一个实例可开多个店铺多租户。目标用户想自己收比特币的个人、小店和自托管爱好者以及需要给客户提供支付能力的团队。与同类产品的关键差异BitPay 这类 SaaS 网关托管资金和密钥BTCPay Server 完全跑在你自己的服务器上且内置兼容 BitPay 的 Legacy API迁移成本低。功能细节以仓库根目录 README.md 为准文档说明可看 docs/。动手前环境与依赖清单依赖要求是否必须.NET SDK10.0项目目标框架net10.0必须源码构建时Git任一较新版本必须Docker任一较新版本可选容器化部署时PostgreSQL通过连接串接入生产环境需要验证命令dotnet --version输出为 10.x 即可开工不是的话先装 .NET 10 SDK这是本项目最硬的门槛。BTCPay Server 安装、启动与验证步骤 1. 拉取代码并构建克隆仓库git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver进入目录后执行dotnet build btcpayserver.sln。首次会还原 NuGet 包耗时几分钟预期看到Build succeeded。2. 最小配置首次启动直接运行dotnet run --project BTCPayServer。首次启动会在数据目录自动生成一份带注释的配置文件模板port、bind、postgres、btc.explorer.url等不填也能以默认值启动。默认监听本地地址常见为127.0.0.1:3300实际端口以生成的配置文件为准。3. 验证跑通控制台打印出Now listening on: http://...这一行说明服务起来了数据库迁移脚本也会自动执行。浏览器打开该地址注册第一个账号即服务器管理员创建一个店铺——看到店铺设置页整个链路就算通了。想确认支持哪些参数随时跑./run.sh --help查看全部命令行选项run.sh会调用BTCPayServer/bin/Release/publish/下的发布产物所以需先dotnet publish。关键组件拆解入口、配置、存储、测试按运行时先后顺序看这五个位置改哪、影响哪一目了然组件一句话定位相对路径改它会发生什么程序入口加载配置、起 Kestrel、监听端口BTCPayServer/Program.cs插件启动崩溃会被自动禁用并写日志服务装配依赖注入与中间件管线BTCPayServer/Hosting/Startup.cs改错这里全站 500配置解析全部命令行参数与BTCPAY_前缀环境变量BTCPayServer/Configuration/DefaultConfiguration.cs在这里加参数名才能从命令行/环境变量传入数据层EF Core 模型与数据库迁移BTCPayServer.Data/Migrations/表结构变更必须新增迁移脚本测试套件集成测试 本地比特币测试网BTCPayServer.Tests/测试跑在 Docker testnet 里不是纯单元测试内置应用Point of Sale、众筹、收款按钮等全部以插件形式放在 BTCPayServer/Plugins/ 下。POS 收银台支持上传自己的商品图例如BTCPay Server Docker 容器化部署与常见自定义最短生产路径只有三步仓库根目录执行docker build -t btcpay-server .用的是根目录 Dockerfile它先 SDK 构建、再拷进精简的 aspnet 运行镜像。启动容器时把宿主机目录挂载到容器/datadir镜像内已设BTCPAY_DATADIR/datadir数据、配置、插件全在这个卷里。用BTCPAY_前缀的环境变量注入外部依赖例如BTCPAY_POSTGRESPostgreSQL 连接串、BTCPAY_BTCEXPLORERURLNBXplorer 地址。完整参数名对照 BTCPayServer/Configuration/DefaultConfiguration.cs。两个最高频的定制点换端口 / 换绑定地址改数据目录里生成配置文件的port与bind默认只绑本地对外要改成0.0.0.0并配反向代理或用环境变量BTCPAY_PORT。挂子路径想以/btcpay访问而不是根路径传--rootpath对应BTCPAY_ROOTPATH。POS 类应用的展示内容文案、商品图也都在店铺设置里改不需要碰代码BTCPay Server 常见坑与下一步⚠️坑一dotnet build报 TargetFramework 找不到解法装 .NET 10 SDK项目目标框架是net10.08.0/9.0 的 SDK 都不行。⚠️坑二./run.sh提示找不到BTCPayServer.dll解法先执行dotnet publish脚本固定从BTCPayServer/bin/Release/publish/找产物。⚠️坑三服务起来了外网访问不到解法默认bind是127.0.0.1改配置里的bind为0.0.0.0再用 Nginx/Caddy 反代并加 HTTPS。⚠️坑四测试环境卡死、容器起不来解法docker-compose down --volumes重置测试环境再up devFAQ 见 BTCPayServer.Tests/README.md。下一步在刚建好的店铺里填好 NBXplorer 连接串开出你的第一张真实发票。延伸阅读docs/db-migration.md、docs/greenfield-authorization.md、Changelog.md。【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考