BTCPay Server 快速上手：免费自托管比特币支付处理器的安装、启动与配置完全指南
【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver
BTCPay Server 是一个免费、开源、自托管的比特币支付处理器，让你在没有手续费、没有中间商、没有 KYC 的情况下直接接收比特币，并支持闪电网络。这篇文章带你认识项目结构、把第一个实例跑起来，并给出一份可直接照抄的配置速查表。
快速认识项目
BTCPay Server 本质上是一个多租户的比特币收款后台：你创建门店（Store），生成发票（Invoice），买家直接链上付款，系统自动确认到账状态。它适合两类人——想自己收比特币的商家，以及想学习「发票管理 + 全节点钱包 + 闪电网络」这套完整链上业务逻辑的开发者。核心卖点就一句话：私钥完全掌握在你自己手里，非托管。
目录速览：导航地图 🗂️
仓库根目录是一个 .NET 多项目解决方案（btcpayserver.sln），几个关键位置如下：
| 目录/文件 | 承担什么职责 | 你该关心什么 |
|---|---|---|
| BTCPayServer/ | 主程序：控制器、服务、支付处理、插件系统、前端视图 | 入口Program.cs就在这里 |
| BTCPayServer.Data/ | 数据库模型与 EF Core 迁移脚本 | 表结构、PostgreSQL 迁移 |
| BTCPayServer.Client/ | Greenfield API 的 .NET 客户端封装 | 想用代码调 API 看这里 |
| BTCPayServer.Abstractions/ | 插件扩展点的接口定义 | 开发插件前必读 |
| BTCPayServer.Rating/ | 汇率源实现 | 法币换算逻辑 |
| BTCPayServer.Tests/ | 集成测试与开发用 docker-compose | 本地开发环境怎么搭 |
| Dockerfile、Docker/ | 容器镜像构建与容器入口脚本 | 生产部署的参考实现 |
| run.sh、run.ps1 | 本地一键运行脚本 | Linux 用 run.sh，Windows 用 run.ps1 |
| docs/ | 仓库内的专题文档（如数据库迁移） | 完整官方文档在 BTCPay Server 官网的 Documentation 栏目 |
三步跑起来你的第一个实例 🚀
前置条件：按 Dockerfile 与 README 的说明，你需要 .NET SDK 10.0、一个 PostgreSQL 数据库（SQLite/MySQL 后端已停止支持，启动时会直接报错），以及一个 NBXplorer 实例来监听链上交易。
第一步，构建。run.sh的实现在 run.sh：它只是进入BTCPayServer/bin/Release/publish/然后执行dotnet BTCPayServer.dll。所以你需要先发布一份产物到这个路径：
dotnet publish BTCPayServer/BTCPayServer.csproj -c Release -o BTCPayServer/bin/Release/publish第二步，启动。先用./run.sh --help看全部命令行参数，然后带上必填项启动：
./run.sh --postgres="Host=localhost;Port=5432;Database=btcpay;Username=...;Password=..." --btcexplorerurl=http://localhost:32838第三步，验证。BTCPayServer/Program.cs 在启动成功后会打印Now listening on: http://...，浏览器打开该地址即可访问后台。配置缺失（比如没给--postgres）时，控制台会抛出明确的Configuration error提示，照提示补参数即可。
配置体系速查表 ⚙️
BTCPay Server 的配置有三个来源，按「命令行参数 > 环境变量 > 配置文件」的优先级取用：
| 配置位置 | 对应环境 | 典型用途 |
|---|---|---|
命令行参数（./run.sh --xxx） | 任意 | 最高优先级，临时覆盖最方便 |
BTCPAY_前缀环境变量（如BTCPAY_POSTGRES、BTCPAY_DATADIR） | 容器部署最常用 | Dockerfile 里就是靠ENV BTCPAY_DATADIR=/datadir指定数据目录 |
| 数据目录下的配置文件 | 常驻运行 | 首次启动自动生成带注释的模板，涵盖network、port、bind、postgres、btc.explorer.url、btc.lightning等项 |
appsettings.dev.json | 仅 DEBUG 构建 | 开发期补充配置，见Program.cs |
常用参数速查：-n | --network切换 mainnet/testnet/regtest；--rootpath改 URL 根路径；--btcexplorerurl指向 NBXplorer；--btclightning接入 c-lightning 或 Charge；--debuglog+--debugloglevel开滚动日志；--disable-registration（默认 true）控制是否允许注册新用户。全部参数清单直接跑./run.sh --help就能看到，定义在 BTCPayServer/Configuration/DefaultConfiguration.cs。
新手避坑与下一步 💡
- 别再用 SQLite/MySQL：指定
SQLITEFILE或MYSQL会直接抛ConfigException，提示按 docs/db-migration.md 迁移到 Postgres；老实例可加--deprecated强行启动。 - cheatmode 只能用于测试网：
--cheatmode在 mainnet 下会被拒绝启动。 - run.sh 找不到 dll：如果你没执行过 publish 就运行 run.sh，会报文件不存在——它要求产物在
BTCPayServer/bin/Release/publish/。 - 下一步：想搭完整开发环境（含 regtest 测试链），看 BTCPayServer.Tests/README.md；想写插件，从
BTCPayServer.Abstractions/的扩展接口和 docs/greenfield-development.md 入手。
【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
