bitcoin-cli.sh
btcpay-admin.sh
btcpay-clean.sh
btcpay-down.sh
btcpay-fragments
btcpay-host
btcpay-restart.sh
btcpay-routes
btcpay-setup.sh
btcpay-switch
btcpay-up.sh
btcpay-update.sh
changedomain.sh

export BTCPAY_API_KEY='<在服务器设置生成的 unrestricted API key>'

# 无效：参数被入口脚本丢弃
docker run btcpayserver/btcpayserver:2.4.5 --port=23102
# 有效：环境变量传参
docker run -e BTCPAY_PORT=23102 btcpayserver/btcpayserver:2.4.5
# 或覆盖入口直传参数
docker run --entrypoint dotnet btcpayserver/btcpayserver:2.4.5 BTCPayServer.dll --port=23102

bitcoin-cli.sh getblockchaininfo

{
  "chain": "regtest",
  "blocks": 103,
  "headers": 103,
  "bestblockhash": "7e2a98736602bda9c104e9cc5366f9567898403573913d9aa897c8e76aec17d5",
  "bits": "207fffff",
  "difficulty": 4.656542373906925e-10,
  "verificationprogress": 0.7734459937686521,
  "initialblockdownload": false
}

bitcoin-cli.sh -version

Bitcoin Core RPC client version v31.1.0
Copyright (C) 2009-2026 The Bitcoin Core developers

bitcoin-lncli.sh getinfo

Error response from daemon: No such container: btcpayserver_lnd_bitcoin

COOKIE=$(cat /var/lib/docker/volumes/generated_nbxplorer_datadir/_data/RegTest/.cookie)

curl -s http://127.0.0.1:32838/health

{
  "status": "Healthy",
  "results": {
    "NodesHealthCheck": {
      "status": "Healthy",
      "description": null,
      "data": {
        "BTC": "Ready"
      }
    }
  }
}

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:32838/v1/cryptos/btc/status
# 实测输出：401
COOKIE=$(cat /var/lib/docker/volumes/generated_nbxplorer_datadir/_data/RegTest/.cookie)
curl -s -u "$COOKIE" http://127.0.0.1:32838/v1/cryptos/btc/status

{"bitcoinStatus":{"blocks":103,"headers":103,"verificationProgress":0.7740503278760351,"isSynched":true,"incrementalRelayFee":0.1,"minRelayTxFee":0.1,"externalAddresses":[],"capabilities":{"canScanTxoutSet":true,"canSupportSegwit":true,"canSupportTaproot":true,"canSupportTransactionCheck":true}},"isFullySynched":true,"chainHeight":103,"syncHeight":103,"instanceName":"","networkType":"Regtest","cryptoCode":"BTC","supportedCryptoCodes":["BTC"],"version":"2.6.19.0"}

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/api/v1/users/me
# 实测输出：401
curl -s -H "Authorization: token ${BTCPAY_API_KEY}" http://127.0.0.1/api/v1/users/me

{"id":"7add6db5-a91b-4061-a2df-36e0fb309f88","email":"admin@example.com","name":null,"imageUrl":null,"emailConfirmed":false,"requiresEmailConfirmation":false,"approved":true,"requiresApproval":false,"roles":["ServerAdmin"],"invitationUrl":null,"created":1792690747,"disabled":false,"storeQuota":null,…}

curl -s http://127.0.0.1/api/v1/health; echo

{"synchronized":true}

curl -s -H "Authorization: token ${BTCPAY_API_KEY}" http://127.0.0.1/api/v1/stores

[{"id":"9m64kg2ibfNzLAdA3hRAYpRfcG9xLUm6KLFDKoR7cSe1","name":"Doc Store","website":null,"brandColor":null,"applyBrandColorToBackend":false,"logoUrl":null,"cssUrl":null,"paymentSoundUrl":null,"supportUrl":null,"invoiceExpiration":900,"displayExpirationTimer":300,"refundBOLT11Expiration":30,"monitoringExpiration":86400,"speedPolicy":"MediumSpeed",…}

Usage:
------

Install BTCPay on this server
This script must be run as root on a Linux host

    -i : Run install and start BTCPay Server
    --install-only: Run install only
    --docker-unavailable: Allow install-only setup to continue without Docker; automatic Docker installation may still be attempted
    --no-startup-register: Do not register BTCPayServer to start via systemctl or upstart
    --no-systemd-reload: Do not reload systemd configuration

This script will:

* Install Docker
* Install Docker-Compose
* Setup BTCPay settings
* Make sure it starts at reboot via upstart or systemd
* Add BTCPay utilities in /usr/local/bin
* Start BTCPay

You can run again this script if you desire to change your configuration.

btcpay-down.sh

 Container generated_btcpayserver_1 Removed
 Container btcpayserver_bitcoind Removed
 Container generated_postgres_1 Stopped
 Container generated_postgres_1 Removing
 Container generated_postgres_1 Removed
 Network generated_default Removing
 Network generated_default Removed

btcpay-up.sh

 Container generated_btcpayserver_1 Starting
 Container generated_nbxplorer_1 Starting
 Container generated_btcpayserver_1 Started
 Container generated_nbxplorer_1 Started

curl -s --max-time 10 http://127.0.0.1/api/v1/health; echo
# 实测输出：{"synchronized":true}

btcpay-clean.sh

Total reclaimed space: 0B

Usage: btcpay-backup.sh [--migrate]

Default: back up for disaster recovery, omit Bitcoin LND data/graph, and restart BTCPay.
Recover LND channels by importing channel.backup (SCB); peers will be asked to close them.

--migrate: include Bitcoin LND data/graph and leave all BTCPay Docker Compose containers stopped.
Use this snapshot only while the source remains stopped to migrate with open channels.
Do not restart the source before or after starting the destination.

Outputs: backup.tar.gz[.gpg], or backup-migrate.tar.gz[.gpg] with --migrate.

ℹ️ Dumping Postgres database …
✅ Postgres database dump done.

ℹ️ Stopping BTCPay Server …

ℹ️ Archiving files in /var/lib/docker …
✅ Archive done.

ℹ️ Restarting BTCPay Server …

ℹ️ Cleaning up …

✅ Backup done => /var/lib/docker/volumes/backup_datadir/_data/backup.tar.gz

ls -la /var/lib/docker/volumes/backup_datadir/_data/backup.tar.gz
tar -tzf /var/lib/docker/volumes/backup_datadir/_data/backup.tar.gz | head -8

-rw------- 1 root root 63681 Oct 23 02:37 backup.tar.gz
postgres.sql.gz
btcpay-backup-mode
volumes/generated_bitcoin_datadir/
volumes/generated_bitcoin_wallet_datadir/
volumes/generated_btcpay_datadir/
volumes/generated_btcpay_datadir/_data/RegTest/settings.config
volumes/generated_btcpay_pluginsdir/

ℹ️ Cleaning restore directory /var/lib/docker/volumes/backup_datadir/_data/restore …

ℹ️ Extracting files in /var/lib/docker/volumes/backup_datadir/_data/restore …
✅ Extraction done.

🚨 The destination secrets path already exists. Remove it before restoring this backup.
ℹ️ Restore files were retained in /var/lib/docker/volumes/backup_datadir/_data/restore for diagnosis.

mv /root/btcpayserver-docker/secrets /root/btcpayserver-docker/secrets.pre-restore
/root/btcpayserver-docker/btcpay-restore.sh /var/lib/docker/volumes/backup_datadir/_data/backup.tar.gz

✅ Volume restore done.

ℹ️ Restoring Postgres database …
✅ Postgres database restore done.

ℹ️ Restarting BTCPay Server …

ℹ️ Cleaning up …

✅ Restore done

curl -s --max-time 10 http://127.0.0.1/api/v1/health; echo
# 实测输出：{"synchronized":true}

btcpay-teardown.sh
# 实测输出：
This script must be sourced ". btcpay-teardown.sh"

Usage: ./btcpay-admin.sh [command]

Commands:
         disable-multifactor <email>
         set-user-admin <email>
         reset-server-policy

btcpay-fragments show

{"excludedFragments":[],"additionalFragments":[],"effectiveFragments":["bitcoin","btcpay-host","btcpayserver","btcpayserver-noreverseproxy","nbxplorer","opt-mempoolfullrbf","postgres"],"availableFragments":["beldex","bitcoin","bitcoin-clightning","bitcoin-lnd","bitcoincore","btcpay-host","btcpayserver","btcpayserver-nginx",…}

btcpay-routes show

{"error":"BTCPAYGEN_REVERSEPROXY must be nginx"}

Usage: btcpay-switch <command> [options] <target>

Commands:
  node default|bitcoincore                 Switch the Bitcoin node implementation.
  ln [--yes] clightning|lnd|phoenixd|none Switch the Lightning implementation.
  help                                     Show this help.

The domain must be a valid domain name without a protocol.

Usage: btcpay-host <command> [arguments]

Commands:
  env                   Return deployment metadata and supported host commands as JSON.
  help                  Show this help.
  showauthorizedkeys    Return authorized SSH public keys as JSON.
  setauthorizedkeys     Replace authorized SSH public keys with argument 1.
  changedomain <domain> Change the BTCPay Server domain.
  update                Update BTCPay Server.
  clean                 Clean unused host resources.
  restart               Restart BTCPay Server and related services.