企业官网建设流程全解析

10 分钟 Docker 部署 BTCPay Server：从安装到跑通第一笔比特币收款的完整新手指南

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

BTCPay Server 是一个免费、开源、可自托管的比特币收款平台，让你在没有第三方中介、没有平台手续费的情况下接受 BTC 支付。本文带你完成 BTCPay Server 安装与入门的完整流程：Docker 部署、初始化实例、跑通第一张发票收款。

BTCPay Server 能解决什么问题

• 独立开发者与小商家：点对点直接收比特币，资金不经过任何支付机构，没有 KYC、没有提现费，只付出链上网络手续费。
• 重视资金控制权的商户：非托管架构，私钥完全由你保管，服务器和数据库都在你自己的硬件上。
• 需要完整收款体验的商店：内置发票管理、付款请求、收银台（Point of Sale）、众筹等应用，开箱即用。
• 多店铺运营团队：实例是多租户的，一台 BTCPay Server 可以承载多个店铺，并为每个店铺单独配置支付方式与权限。
• Lightning Network 用户：原生支持 LND、Core Lightning（CLN）、Eclair 三种节点，链上收款与闪电收款可以并行。

部署前准备：系统、硬件与网络要求清单

你不需要在宿主机安装 .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 ID=postgres;Password=postgres;Host=postgres;Port=5432;Database=btcpay" 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_POSTGRES：PostgreSQL 连接串。镜像启动入口 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 个设置：账户、商店、钱包、发票 ✅

1. 访问入口：浏览器打开http://你的服务器IP:23000。你接下来会看到 BTCPay 的登录/注册页，新实例默认开放注册，通过它创建第一个管理员账户；账户体系建好后，建议用disable-registration配置项关闭该入口。
2. 创建商店：首次登录后仪表盘会显示待办清单，第一步就是创建商店（Store）。商店是收款的组织单位，后续所有发票、设置都挂在商店下面。
3. 生成钱包：进入商店设置，为商店生成钱包（或连接你自己的 Bitcoin 节点）。没有这一步，BTCPay 无法监控链上到账。
4. 创建第一张发票：打开商店的发票（Invoices）页面，点击创建发票，填入金额后提交。页面会给出一个 BTC 地址和二维码——用任意比特币钱包向该地址付款，发票状态在确认后从 pending 变为 paid，你的第一笔收款场景就此跑通。

商店还内置 Point of Sale 收银台应用，上图就是仓库中 POS 示例商店的商品页样式，适合有在线卖货需求的场景。若不想花真实币测试，把部署时BTCPAY_NETWORK设为testnet（端口 23001），用测试币走一遍同样的流程。

BTCPay Server 新手配置速查：4 个最关键的配置项

完整开关清单可以用--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.md：Greenfield API 授权模型
• docs/greenfield-development.md：Greenfield 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