10 分钟 Docker 部署 BTCPay Server从安装到跑通第一笔比特币收款的完整新手指南【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserverBTCPay Server 是一个免费、开源、可自托管的比特币收款平台让你在没有第三方中介、没有平台手续费的情况下接受 BTC 支付。本文带你完成 BTCPay Server 安装与入门的完整流程Docker 部署、初始化实例、跑通第一张发票收款。BTCPay Server 能解决什么问题独立开发者与小商家点对点直接收比特币资金不经过任何支付机构没有 KYC、没有提现费只付出链上网络手续费。重视资金控制权的商户非托管架构私钥完全由你保管服务器和数据库都在你自己的硬件上。需要完整收款体验的商店内置发票管理、付款请求、收银台Point of Sale、众筹等应用开箱即用。多店铺运营团队实例是多租户的一台 BTCPay Server 可以承载多个店铺并为每个店铺单独配置支付方式与权限。Lightning Network 用户原生支持 LND、Core LightningCLN、Eclair 三种节点链上收款与闪电收款可以并行。部署前准备系统、硬件与网络要求清单项目要求说明操作系统支持 Docker 的 Linux推荐 Ubuntu、WindowsWSL2、macOS容器化部署对发行版无特殊要求DockerDocker 引擎 Docker Compose v2用docker compose version确认CPU / 内存1 核 / 1GB 起步仅 BTCPay 自身若同机再跑 Bitcoin 全节点需按节点要求额外加配磁盘应用本体几十 MB 即可主网全节点需额外数百 GB 空间具体以比特币网络现状为准网络开放 1 个 Web 端口主网默认 23000testnet 默认 23001、regtest 默认 23002端口值来自仓库代码 BTCPayServer.Common/BTCPayNetwork.cs依赖服务1 个 PostgreSQL 数据库下文 compose 文件已包含随 BTCPay 一起启动你不需要在宿主机安装 .NET 运行时官方镜像已内置Dockerfile 基于mcr.microsoft.com/dotnet/aspnet构建数据目录固定在容器内的/datadir。一键 Docker 部署步骤4 步启动 BTCPay Server 第 1 步确认 Docker 环境docker version docker compose version预期结果两条命令都能打印出版本信息。若提示命令不存在先安装 Docker。第 2 步创建部署目录与 compose 文件mkdir -p ~/btcpay cd ~/btcpay cat docker-compose.yml EOF services: btcpayserver: image: btcpayserver/btcpayserver:latest container_name: btcpayserver restart: unless-stopped ports: - 23000:23000 environment: BTCPAY_POSTGRES: User IDpostgres;Passwordpostgres;Hostpostgres;Port5432;Databasebtcpay volumes: - btcpay_data:/datadir postgres: image: postgres:18 restart: unless-stopped environment: POSTGRES_PASSWORD: postgres POSTGRES_DB: btcpay volumes: - postgres_data:/var/lib/postgresql volumes: btcpay_data: postgres_data: EOF关键参数说明btcpayserver/btcpayserver:latest官方镜像即本仓库 Dockerfile 的构建产物生产环境请固定具体版本标签。/datadir容器内数据目录对应 Dockerfile 中的BTCPAY_DATADIR配置与日志都落在挂载卷里删容器不丢数据。BTCPAY_POSTGRESPostgreSQL 连接串。镜像启动入口 Docker/docker-entrypoint.sh 不转发命令行参数Docker 部署下所有配置项都以BTCPAY_前缀的环境变量形式传入前缀定义见 BTCPayServer/Configuration/DefaultConfiguration.cs。23000:23000主网默认端口。改用 testnet 练习时把BTCPAY_NETWORK设为testnet并映射 23001。第 3 步启动服务docker compose up -d第 4 步验证启动结果docker compose ps docker compose logs -f btcpayserver预期结果两个容器均为 running 状态日志走完数据库迁移后打印监听地址。首次启动耗时较长属于正常现象——它在执行数据库迁移机制说明见 docs/db-migration.md并生成默认配置文件。首次进入必做的 4 个设置账户、商店、钱包、发票 ✅访问入口浏览器打开http://你的服务器IP:23000。你接下来会看到 BTCPay 的登录/注册页新实例默认开放注册通过它创建第一个管理员账户账户体系建好后建议用disable-registration配置项关闭该入口。创建商店首次登录后仪表盘会显示待办清单第一步就是创建商店Store。商店是收款的组织单位后续所有发票、设置都挂在商店下面。生成钱包进入商店设置为商店生成钱包或连接你自己的 Bitcoin 节点。没有这一步BTCPay 无法监控链上到账。创建第一张发票打开商店的发票Invoices页面点击创建发票填入金额后提交。页面会给出一个 BTC 地址和二维码——用任意比特币钱包向该地址付款发票状态在确认后从 pending 变为 paid你的第一笔收款场景就此跑通。商店还内置 Point of Sale 收银台应用上图就是仓库中 POS 示例商店的商品页样式适合有在线卖货需求的场景。若不想花真实币测试把部署时BTCPAY_NETWORK设为testnet端口 23001用测试币走一遍同样的流程。BTCPay Server 新手配置速查4 个最关键的配置项配置项命令行形式作用定义位置数据库连接--postgres/ 环境变量BTCPAY_POSTGRESPostgreSQL 连接串必填BTCPayServer/Configuration/DefaultConfiguration.cs网络类型--networkmainnet / testnet / regtest决定默认端口 23000 / 23001 / 23002BTCPayServer.Common/BTCPayNetwork.cs数据目录环境变量BTCPAY_DATADIR镜像默认/datadir存放配置与日志配置文件为该目录下自动生成的settings.configDockerfile注册开关--disable-registration关闭新用户注册入口BTCPayServer/Configuration/DefaultConfiguration.cs完整开关清单可以用--help查看源码构建后运行 run.sh脚本入口为dotnet BTCPayServer.dll加上--help或直接阅读上表中的 DefaultConfiguration.cs。从源码构建则先安装 .NET SDK v10.0克隆仓库git clone https://gitcode.com/GitHub_Trending/bt/btcpayserver再按 README.md 的 Developing 章节操作。常见卡点排查3 个高频问题与解决方式 现象 1浏览器打不开页面提示连接被拒绝原因端口没映射出来或服务器防火墙 / 云安全组拦截了 23000 端口。解决运行docker compose ps确认存在23000-23000/tcp的映射在系统防火墙与安全组中放行该端口。若前面挂了反向代理把 X-Forwarded-Proto 设为 https对应开关xforwardedproto否则页面会因协议判断错误而异常。现象 2容器反复重启日志报数据库连接错误原因btcpayserver 先于 postgres 完成初始化时连接失败或BTCPAY_POSTGRES中的 Host / Port / Database / Password 与 compose 中 postgres 服务的定义不一致。解决docker compose logs btcpayserver查看具体报错逐项核对连接串字段是否与 postgres 服务完全一致确认 postgres 容器处于 running 状态后重新docker compose up -d。现象 3发票已创建但付款后状态长时间不变原因商店没有连接任何链上监控Bitcoin 节点 / NBXplorer或尚未生成钱包BTCPay 检测不到到账。解决回到仪表盘待办清单完成生成钱包或连接节点这一步暂无节点可用时改用 testnet 环境或仓库提供的cheatmode开关注入模拟支付完成验证开关列表见 BTCPayServer/Configuration/DefaultConfiguration.cs。结语与延伸阅读到这里你已经拥有一台可对外收款的自托管比特币支付平台后续按需接入 Lightning 节点即可覆盖小额快速收款场景。仓库内的这些文件值得常翻README.md功能总览与快速上手指引docs/db-migration.md数据库迁移机制说明docs/greenfield-authorization.mdGreenfield API 授权模型docs/greenfield-development.mdGreenfield API 开发说明Changelog.md版本变更记录Dockerfile 与 Docker/docker-entrypoint.sh官方镜像构建与启动逻辑【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
