Bitcart 0.10.3.0 Docker Compose 部署指南

目标：使用 Bitcart 官方 bitcart-docker 编排仓库，在一台 Ubuntu 22.04 服务器上以 Docker Compose 方式完成 Bitcart 0.10.3.0 的一键部署、验证与日常运维（启动/停止/更新/备份/恢复），全部命令实测通过。

一、环境与版本说明

本文所有命令均在以下环境中实测执行（实测日期：2026-10-22）：

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
Bitcart	0.10.3.0（2026-03-05 发布，官方最新稳定版；编排仓库 bitcart-docker 跟踪 master，拉取 `stable` 标签组件镜像）
Docker	29.9.2, build a82e528
Docker Compose	v5.6.1
编排生成器	bitcart/docker-compose-generator:latest
部署形态	9 个服务容器：nginx + nginx-gen + backend(API) + worker + admin + store + database + redis + bitcoin daemon

版本核对输出：

docker --version
docker compose version

实测输出：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

二、部署架构与配置机制

2.1 组件架构

bitcart-docker 是官方编排仓库，setup.sh 读取环境变量后调用 bitcart/docker-compose-generator 镜像动态生成 docker-compose.yml（生成产物位于 compose/generated.yml），再用 Docker Compose 拉起整套服务：

容器	角色	内部端口
compose-nginx-1	反向代理，唯一对外入口	对外暴露 80/443
compose-nginx-gen-1	根据 Docker 事件自动刷新 nginx 配置	—
compose-backend-1	Merchants API	8000
compose-worker-1	后台任务与支付事件处理	9020
compose-admin-1	Admin 管理面板	4000
compose-store-1	Store 收银台	3000
compose-database-1	PostgreSQL	5432
compose-redis-1	Redis	6379
compose-bitcoin-1	BTC daemon（Electrum SPV）	5000

注意容器内部端口分配：admin 为 4000、store 为 3000，与源码手动部署时（admin 3000、store 4000）相反，排查时以 docker ps 实际输出为准。单域名模式下，外部统一从 nginx 进入：Store 在 /，Admin 在 /admin，API 在 /api。

2.2 配置变量机制

所有定制通过环境变量传给 setup.sh，生成时固化到 compose/generated.yml。修改配置的标准方式：重新 export 变量后再次执行 ./setup.sh（脚本幂等，实测重复执行会重新生成配置并滚动重启受影响的容器）。

常用环境变量（详见官方 bitcart-docker README 的 Configuration 章节）：

变量	说明	实测取值
`BITCART_HOST`	访问域名。生产环境填真实域名并配置 DNS A 记录；本地测试用 `.local` 结尾域名	`bitcart.local`
`BITCART_CRYPTOS`	启用的币种，逗号分隔（`btc,eth` 等），默认 `btc`	`btc`
`BITCART_REVERSEPROXY`	`nginx-https`（默认，自动申请 Let's Encrypt 证书）或 `nginx`（无 TLS）	`nginx`
`BITCART_ADDITIONAL_COMPONENTS`	附加组件，如 `tor`	未启用
`BTC_NETWORK`	币种网络（`mainnet`/`testnet`），每个币种同构：`<COIN>_NETWORK`	mainnet
`BTC_LIGHTNING`	闪电网络开关（BTC 系币种支持）：`<COIN>_LIGHTNING`	未启用
`BTC_DEBUG`	daemon 调试日志：`<COIN>_DEBUG`	未启用

三、部署步骤（实测）

3.1 安装 Docker

在全新的 Ubuntu 22.04 服务器上使用官方脚本安装 Docker：

curl -fsSL https://get.docker.com | bash
docker --version
docker compose version

实测输出：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

网络受限环境可为 Docker daemon 配置 HTTP 代理（/etc/docker/daemon.json 增加 "proxies": {"http-proxy": "http://<proxy>:<port>", "https-proxy": "http://<proxy>:<port>"} 后重启 docker），确保能拉取 Docker Hub 镜像。

3.2 克隆编排仓库并执行 setup

官方标准流程要求在 root shell 下执行（sudo su -，注意减号，用于加载完整环境）：

sudo su -
git clone https://github.com/bitcart/bitcart-docker
cd bitcart-docker
export BITCART_HOST=bitcart.local
export BITCART_REVERSEPROXY=nginx
export BITCART_CRYPTOS=btc
./setup.sh

实测输出（关键节点摘录）：

Status: Downloaded newer image for bitcart/docker-compose-generator:latest
Host agent installed as systemd service bitcart-agent
Adding bitcart.service to systemd
Bitcart systemd configured in /etc/systemd/system/bitcart.service

Created symlink /etc/systemd/system/multi-user.target.wants/bitcart.service → /etc/systemd/system/bitcart.service.
Bitcart starting... this can take 5 to 10 minutes...
Bitcart started
 Container compose-admin-1 Running
 Container compose-store-1 Running
 Container compose-backend-1 Running
 Container compose-redis-1 Running
 Container compose-nginx-1 Running
 Container compose-database-1 Running
 Container compose-bitcoin-1 Running
 Container compose-worker-1 Running
 Container compose-nginx-gen-1 Running
Setup done.

setup 过程依次完成：拉取生成器镜像并生成 compose/generated.yml → 安装 bitcart-agent 主机代理服务 → 创建并启用 bitcart.service 系统服务 → 拉取各组件镜像 → 启动全部 9 个容器。

.local 域名说明：以 .local 结尾的 BITCART_HOST 是官方提供的免域名本地模式，仅本机可访问。本机访问需让 bitcart.local 解析到本机（在 /etc/hosts 加一行 127.0.0.1 bitcart.local），或像本文验证那样用 curl -H "Host: bitcart.local" http://127.0.0.1/ 指定 Host 头。生产环境请改用真实域名 + DNS A 记录 + 默认的 BITCART_REVERSEPROXY=nginx-https（自动签发与续期 Let's Encrypt 证书）。

3.3 检查服务状态

Bitcart 的系统服务是一个 oneshot 单元（RemainAfterExit=yes），通过 start.sh/stop.sh 管理整套容器：

systemctl is-active bitcart

实测输出：

active

bitcart.service 单元定义（自动生成于 /etc/systemd/system/bitcart.service）：

[Unit]
Description=Bitcart service
After=docker.service network-online.target
Requires=docker.service network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/bin/bash -c  '. "/etc/profile.d/bitcart-env.sh" && cd "/bitcart-docker" && ./start.sh'
ExecStop=/bin/bash -c   '. "/etc/profile.d/bitcart-env.sh" && cd "/bitcart-docker" && ./stop.sh'
ExecReload=/bin/bash -c '. "/etc/profile.d/bitcart-env.sh" && cd "/bitcart-docker" && ./stop.sh && ./start.sh'
[Install]
WantedBy=multi-user.target

查看全部容器状态（在 /bitcart-docker 目录下执行）：

cd /bitcart-docker
docker compose -f compose/generated.yml ps

实测输出：

compose-admin-1      running
compose-backend-1    running
compose-bitcoin-1    running
compose-database-1   running
compose-nginx-1      running
compose-nginx-gen-1  running
compose-redis-1      running
compose-store-1      running
compose-worker-1     running

3.4 验证 Web 端点

curl -s -o /dev/null -w "%{http_code}\n" -H "Host: bitcart.local" http://127.0.0.1/
curl -s -o /dev/null -w "%{http_code}\n" -H "Host: bitcart.local" -L http://127.0.0.1/admin
curl -s -H "Host: bitcart.local" http://127.0.0.1/api/cryptos

实测输出：

200
200
{"count":1,"next":null,"previous":null,"result":["btc"]}

三端含义：Store 收银台（/，200）、Admin 管理面板（/admin，登录页 200）、Merchants API（/api/cryptos，返回已启用币种列表）。生产环境用域名访问：https://<BITCART_HOST>/、https://<BITCART_HOST>/admin、https://<BITCART_HOST>/api。

四、日常运维命令（全部实测）

以下命令均在 /bitcart-docker 目录下以 root 执行。

4.1 停止与启动

./stop.sh

实测输出（尾部）——stop 脚本执行 docker compose down，容器与网络会被移除（数据保存在 Docker 卷中，不受影响）：

 Container compose-database-1 Removed
 Container compose-bitcoin-1 Removed
 Network compose_default Removing
 Network compose_default Removed

./start.sh

实测输出（尾部）：

 Container compose-admin-1 Started
 Container compose-store-1 Started

重启等价命令：

./restart.sh

实测输出（尾部）：

 Container compose-worker-1 Started
 Container compose-admin-1 Started

4.2 更新到新版本

./update.sh

脚本默认先 git pull --force 更新编排仓库再滚动重建容器。网络受限环境跳过 git 拉取时用：

./update.sh --skip-git-pull

实测输出（尾部）——更新后 9 个容器全部 running：

 Container compose-admin-1 Started
 Container compose-worker-1 Started
 Container compose-store-1 Started
Total reclaimed space: 0B

其他参数：--agent-only（只更新主机代理）、--no-start（更新后不启动）、--keep-master-images（保留 master 标签镜像）。

4.3 备份

./backup.sh

脚本将数据库导出为 SQL、打包关键数据卷并压缩为 tar.zst，默认存入 backup_datadir Docker 卷。实测输出（尾部）：

Backed up to /var/lib/docker/volumes/backup_datadir/_data/20261022-174817-backup.tar.zst
Backup done.

查看备份产物：

docker run --rm -v backup_datadir:/data alpine ls -lh /data

实测输出：

-rw-r--r--    1 root     root       60.0K Oct 22 17:47 20261022-174756-backup.tar
-rw-r--r--    1 root     root       43.8K Oct 22 17:47 20261022-174756-database.sql
-rw-r--r--    1 root     root        8.4K Oct 22 17:48 20261022-174817-backup.tar.zst

常用参数与环境变量：--only-db（仅备份数据库）、--restart（备份前重启避免数据不一致）、BACKUP_PROVIDER（local 默认 / scp / s3）、BACKUP_ENCRYPTION=true（OpenSSL AES-256-CBC 加密，密钥存于 .deploy 文件）、BACKUP_NAME（归档名前缀）。

注意：实测环境首次执行 backup 时报 zstdmt: command not found，仅生成未压缩的 .tar 与 .sql；安装 zstd 包后重跑得到完整 .tar.zst 归档（见 6.1 节）。

4.4 恢复

restore.sh 从 tar.zst 备份归档恢复数据库与数据卷，参数为备份文件路径，恢复后自动重启服务：

docker run --rm -v backup_datadir:/data -v $(pwd):/out alpine cp /data/20261022-174817-backup.tar.zst /out/
./restore.sh ./20261022-174817-backup.tar.zst

实测输出（尾部）——容器全部拉起：

 Container compose-nginx-1 Started
 Container compose-nginx-gen-1 Started
 Container compose-store-1 Started
 Container compose-admin-1 Started
 Container compose-worker-1 Started

恢复后验证 API 正常：

curl -s -H "Host: bitcart.local" http://127.0.0.1/api/cryptos

实测输出：

{"count":1,"next":null,"previous":null,"result":["btc"]}

可选参数：--delete-backup（恢复后删除备份文件）、--encryption-key KEY（解密加密备份，缺省用 .deploy 文件中的密钥）。

4.5 命令行工具入口

编排仓库提供 bitcart-cli.sh，它包装了 worker 容器内的 bitcart-cli（Go 编写的 RPC 控制台工具），无需在宿主机单独安装：

./bitcart-cli.sh --help

实测输出：

NAME:
   bitcart-cli - Call RPC methods from console

USAGE:
   bitcart-cli method [args]

VERSION:
   docker

COMMANDS:
   plugin  Manage plugins

GLOBAL OPTIONS:
   --help, -h                    show help
   --wallet string, -w string    specify wallet [$BITCART_WALLET]
   --contract string             specify contract [$BITCART_CONTRACT]
   --address string              specify address (XMR-only) [$BITCART_ADDRESS]
   --diskless, -d                Load wallet in memory only [$BITCART_DISKLESS]
   --coin string, -c string      specify coin to use (default: "btc") [$BITCART_COIN]
   --user string, -u string      specify daemon user (default: "electrum") [$BITCART_LOGIN]
   --password string, -p string  specify daemon password (default: "electrumz") [$BITCART_PASSWORD]
   --url string, -U string       specify daemon URL (overrides defaults) [$BITCART_DAEMON_URL]
   --no-spec                     Disables spec fetching for better exceptions display [$BITCART_NO_SPEC]
   --github-api string           Change the default endpoint to GitHub API for retrieving updates (default: "https://api.github.com")
   --skip-update-check           Skip the check for updates check run before every command.

完整用法见《Bitcart 0.10.3.0 常用 CLI 命令与工具详解》。

五、数据持久化说明

Bitcart 的持久数据全部存放于 Docker 卷（docker volume ls 可见），容器重建/升级不丢数据：

卷	内容
`bitcart_datadir`	数据库与组件关键数据（备份脚本打包对象）
`backup_datadir`	备份归档存放处
`compose_` 前缀各卷	postgres 数据、redis 数据、daemon 钱包数据（如 bitcoin 的 `.electrum`）等

数据安全建议：定期执行 ./backup.sh 并将 backup_datadir 卷内容同步到异地（或直接配置 BACKUP_PROVIDER=scp/s3 自动上传）；.deploy 文件包含备份加密密钥与部署凭据，务必与备份一同妥善保管，且不要提交到代码仓库。

六、常见问题与排障实录

6.1 backup 报 zstdmt: command not found

现象：./backup.sh 输出数据库导出成功后报错：

./backup.sh: line 121: zstdmt: command not found

结果只生成未压缩的 .tar 与 -database.sql，没有最终的 .tar.zst 归档。

原因：zstdmt 是 zstd 的多线程压缩入口，Ubuntu 22.04 默认未安装 zstd。

处置：

apt install -y zstd
./backup.sh

实测输出：

Backed up to /var/lib/docker/volumes/backup_datadir/_data/20261022-174817-backup.tar.zst
Backup done.

6.2 嵌套/受限存储环境启动失败：overlay 挂载 invalid argument

现象：在 Docker-in-Docker 类嵌套环境（或 storage driver 配置异常的主机）中执行 ./setup.sh，组件容器创建失败，报错包含 failed to mount ... invalid argument，docker info 显示 Storage Driver 为 containerd snapshotter 的 overlayfs。

原因：此类环境不允许在 overlay 文件系统之上再叠加 overlay。

处置：将存储驱动切换为兼容性最好的 vfs（牺牲性能换兼容，仅建议在无法使用 overlay2 的环境使用）：

/etc/docker/daemon.json：

{
  "storage-driver": "vfs",
  "features": { "containerd-snapshotter": false }
}

systemctl restart docker
cd /bitcart-docker
./setup.sh

实测确认 docker info | grep "Storage Driver" 显示 vfs 后，setup 全流程成功。

提示：普通物理服务器或标准虚拟机安装 Docker 后默认即 overlay2，无需做任何改动，本条仅适用于特殊嵌套/受限场景。

6.3 本机无法通过 bitcart.local 访问

现象：./setup.sh 完成后，本机浏览器访问 http://bitcart.local/ 无响应。

原因：.local 域名不会自动配置 DNS，需要本机解析支持；生产域名则要求 DNS A 记录已指向服务器。

处置：本机测试在 /etc/hosts 增加 127.0.0.1 bitcart.local，或按 3.4 节用 curl -H "Host: bitcart.local" http://127.0.0.1/ 验证；生产环境将 BITCART_HOST 设为真实域名并确保 DNS 生效后重新 ./setup.sh。

6.4 修改币种/域名等配置不生效

原因：配置在生成阶段固化进 compose/generated.yml，直接改该生成文件无效（文件头注明 DO NOT EDIT）。

处置：重新 export 环境变量后重跑 ./setup.sh，例如启用 testnet：

export BTC_NETWORK=testnet
./setup.sh

脚本幂等，会重新生成配置并滚动重建受影响容器。

七、下一步

了解组件定位与选型依据：《Bitcart 0.10.3.0 介绍与选型指南》（/post/yKeVQmbN4Q6d）
源码手动部署路线：《Bitcart 0.10.3.0 Ubuntu 22.04 安装指南》（/post/9HkLvzFW4ZKO）
全部配置参数与生产配置模板：《Bitcart 0.10.3.0 配置参数详解》
命令行工具与日常运维：《Bitcart 0.10.3.0 常用 CLI 命令与工具详解》