企业官网建设流程全解析

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

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

BTCPay Server 是一个免费开源、可自托管的比特币支付处理器，让你不经过中间商、不交平台手续费地直接收取比特币。读完本文，你能拉取代码在本地跑起来、用 Docker 部署上线，并改掉端口、数据库等常见配置。

项目速览：自托管比特币支付处理器定位

• 解决什么问题：商户收比特币 + 私钥自持。非托管（密钥在你手里）、零平台抽成，只付矿工费，且一个实例可开多个店铺（多租户）。

• 目标用户：想自己收比特币的个人、小店和自托管爱好者，以及需要给客户提供支付能力的团队。

• 与同类产品的关键差异：BitPay 这类 SaaS 网关托管资金和密钥，BTCPay Server 完全跑在你自己的服务器上，且内置兼容 BitPay 的 Legacy API，迁移成本低。

功能细节以仓库根目录 README.md 为准，文档说明可看 docs/。

动手前：环境与依赖清单

验证命令：

dotnet --version

输出为 10.x 即可开工；不是的话先装 .NET 10 SDK，这是本项目最硬的门槛。

BTCPay Server 安装、启动与验证步骤 🚀

1. 拉取代码并构建

1. 克隆仓库：git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver

2. 进入目录后执行dotnet build btcpayserver.sln。首次会还原 NuGet 包，耗时几分钟，预期看到Build succeeded。

2. 最小配置，首次启动

3. 直接运行dotnet run --project BTCPayServer。首次启动会在数据目录自动生成一份带注释的配置文件模板（port、bind、postgres、btc.explorer.url等），不填也能以默认值启动。

4. 默认监听本地地址（常见为127.0.0.1:3300），实际端口以生成的配置文件为准。

3. 验证跑通

5. 控制台打印出Now listening on: http://...这一行，说明服务起来了，数据库迁移脚本也会自动执行。

6. 浏览器打开该地址，注册第一个账号（即服务器管理员），创建一个店铺——看到店铺设置页，整个链路就算通了。

7. 想确认支持哪些参数，随时跑./run.sh --help查看全部命令行选项（run.sh会调用BTCPayServer/bin/Release/publish/下的发布产物，所以需先dotnet publish）。

关键组件拆解：入口、配置、存储、测试

按"运行时先后顺序"看这五个位置，改哪、影响哪一目了然：

内置应用（Point of Sale、众筹、收款按钮等）全部以插件形式放在 BTCPayServer/Plugins/ 下。POS 收银台支持上传自己的商品图，例如：

BTCPay Server Docker 容器化部署与常见自定义

最短生产路径只有三步：

1. 仓库根目录执行docker build -t btcpay-server .，用的是根目录 Dockerfile，它先 SDK 构建、再拷进精简的 aspnet 运行镜像。

2. 启动容器时把宿主机目录挂载到容器/datadir（镜像内已设BTCPAY_DATADIR=/datadir），数据、配置、插件全在这个卷里。

3. 用BTCPAY_前缀的环境变量注入外部依赖，例如BTCPAY_POSTGRES（PostgreSQL 连接串）、BTCPAY_BTCEXPLORERURL（NBXplorer 地址）。完整参数名对照 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.0，8.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 dev，FAQ 见 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