Bitcart 0.10.3.0 常用 CLI 命令与工具详解

目标：系统梳理 Bitcart 0.10.3.0 日常管理与开发涉及的五类命令行工具——bitcart-cli 守护进程控制台、bitcart-cli.sh 包装脚本、daemon JSON-RPC 直调、uv run just 源码任务集与 bitcart-docker 管理脚本，给出各工具的获取方式、用法与实测回显，全部命令均在 Ubuntu 22.04 服务器环境实测通过。

一、环境与版本说明

本文所有命令均在以下环境中实测执行（实测日期：2026-10-22）。CLI 工具类操作在部署 Bitcart 0.10.3.0 的服务器上进行，服务器环境沿用《Ubuntu 22.04 安装 Bitcart 0.10.3.0 指南》完成的核心部署（BTC daemon + API + worker + PostgreSQL + Redis，systemd 托管）；Docker Compose 编排形态相关的小节沿用《Bitcart 0.10.3.0 Docker Compose 部署指南》的环境。

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
Bitcart	0.10.3.0（2026-03-05 发布）
bitcart-cli（独立二进制）	1.6.1（2026-02-17 发布，Go 语言实现，官方最新稳定版，版本号取自 GitHub Releases）
BTC daemon 内核	Electrum 4.6.0b1（`bitcart-cli version` 实测值）
Python（uv 托管，实际运行）	3.12（由仓库 `requires-python >= 3.12` 约束）
uv	0.13.5
Docker（仅编排形态小节涉及）	29.9.2, build a82e528 / Compose v5.6.1

版本核对输出：

lsb_release -d; uv --version

实测输出：

Description:	Ubuntu 22.04.5 LTS
uv 0.13.5 (x86_64-unknown-linux-gnu)

二、CLI 工具全景与选型

Bitcart 的命令行工具不是一个单一程序，而是按使用场景分层的工具族。动手之前先建立全景认知，避免"用错工具"：

工具	形态	面向对象	作用边界	适用场景
bitcart-cli	独立二进制 / 编排内置	BTC daemon 等 RPC 服务	只能调用 daemon 的 JSON-RPC 方法	查询 daemon 同步状态、无钱包地址查询、调试 RPC
bitcart-cli.sh	编排仓库包装脚本	同上	透传参数给编排内置的 bitcart-cli	Docker Compose 部署形态下免安装直接用
curl（daemon JSON-RPC 直调）	系统自带	各币种 daemon RPC 端口	原始 HTTP 调用，任何 RPC 方法可达	脚本集成、无 CLI 环境下的最小依赖调用
uv run just	仓库任务集	Bitcart 源码仓库	面向源码开发（迁移/测试/静态检查/临时拉起服务）	二次开发、参与贡献、本地调试
bitcart-docker 管理脚本	编排仓库脚本集	整套编排服务	部署/启停/更新/备份恢复/改域名	Docker Compose 生产运维

关键解读：管理业务数据（发票、商店、钱包记录）走 Merchants API 或管理面板，不在本文工具族范围内；bitcart-cli 与 curl 直调的对象是 daemon（守护进程）这一层，它懂的是"链、地址、交易、钱包文件"，不懂"发票、商店"。两条主线容易混淆的根源见 3.7 节排障实录第一则。

下文按独立二进制形态（第三章）逐层展开，编排形态差异在第四章说明。

三、bitcart-cli：daemon 的 RPC 控制台

3.1 获取与安装

bitcart-cli 是 Go 语言编写的独立命令行工具，仓库为 github.com/bitcart/bitcart-cli，官方通过 GitHub Releases 发布各平台二进制。0.10.3.0 时代对应最新版 1.6.1（2026-02-17 发布，发布说明仅为 "Use go 1.26"，版本信息取自 releases 订阅源 https://github.com/bitcart/bitcart-cli/releases.atom，查询日期 2026-10-22）。

先通过 GitHub API 确认资产清单（网络受限环境为 curl 配置代理）：

curl -s https://api.github.com/repos/bitcart/bitcart-cli/releases/latest | grep -E '"tag_name"|browser_download_url' | head -6

实测输出（节选）：

  "tag_name": "1.6.1",
      "browser_download_url": "https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-darwin-aarch64"
      "browser_download_url": "https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-darwin-x86_64"
      "browser_download_url": "https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-freebsd-aarch64"
      "browser_download_url": "https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-freebsd-armv7"
      "browser_download_url": "https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-freebsd-i686"

Linux x86_64 平台对应的资产名为 bitcart-cli-linux-x86_64。下载并赋予执行权限：

mkdir -p /opt/bitcart-cli && cd /opt/bitcart-cli
curl -fL -o bitcart-cli https://github.com/bitcart/bitcart-cli/releases/download/1.6.1/bitcart-cli-linux-x86_64
chmod +x bitcart-cli
ls -lh bitcart-cli

实测输出：

  0     0    0     0    0     0      0      0 --:--:-- --:--:--     0
100 10.2M  100 10.2M    0     0  3793k      0  0:00:02  0:00:02 --:--:-- 5541k
-rwxr-xr-x 1 root root 11M Oct 22 18:03 bitcart-cli

验证版本：

./bitcart-cli --version

实测输出：

bitcart-cli version 1.6.1

提示：若希望全局可用，可将其软链到 PATH 内（ln -s /opt/bitcart-cli/bitcart-cli /usr/local/bin/bitcart-cli）。本文为清晰起见统一使用完整路径调用。

3.2 全局选项与连接参数

bitcart-cli 的定位是"从控制台调用 RPC 方法"（--help 自述 "Call RPC methods from console"）。查看完整帮助：

./bitcart-cli --help

实测输出：

NAME:
   bitcart-cli - Call RPC methods from console

USAGE:
   bitcart-cli method [args]

VERSION:
   1.6.1

COMMANDS:
   plugin  Manage plugins
   update  CLI update operations

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.
   --version, -v                 print the version

逐项说明关键选项：

选项	默认值	说明
`-c/--coin`	`btc`	目标币种。CLI 按币种推导 daemon 默认端口（BTC 为 5000、LTC 为 5001，端口表见《Bitcart 0.10.3.0 介绍与选型指南》），也可用 `-U` 显式覆盖
`-u/--user`	`electrum`	daemon RPC 的 Basic 认证用户名，与官方默认凭证一致
`-p/--password`	`electrumz`	daemon RPC 的 Basic 认证密码
`-U/--url`	无（按币种推导）	显式指定 daemon URL，优先级最高
`-w/--wallet`	无	指定要加载的钱包（钱包名或 xpub），调用钱包级 RPC 方法时必需
`-d/--diskless`	关闭	钱包仅加载到内存，不落盘；配合 xpub 使用可避免在服务器留下钱包文件
`--skip-update-check`	关闭	跳过每条命令执行前的 CLI 更新检查，内网环境建议加上以消除额外联网

每个选项都有同名环境变量（如 $BITCART_COIN），环境变量方式实测：

BITCART_COIN=btc ./bitcart-cli version

实测输出：

4.6.0b1

注意 version 这里返回的是 daemon（Electrum）的版本 而非 CLI 自身版本（CLI 自身版本用 --version 查看），二者不要混淆。

3.3 基础用法：调用 daemon RPC 方法

USAGE 行已经说明用法：bitcart-cli method [args]——方法名后直接跟参数。以最常用的 getinfo（daemon 概况）为例：

./bitcart-cli getinfo

实测输出：

{
  "auto_connect": true,
  "blockchain_height": 972640,
  "connected": true,
  "fee_estimates": {
    "10": 1000,
    "1008": 813,
    "144": 813,
    "2": 2255,
    "25": 852,
    "5": 1823
  },
  "network": "mainnet",
  "path": "/home/bitcart/.electrum",
  "server": "bitcoin.lu.ke",
  "server_height": 972640,
  "spv_nodes": 10,
  "synchronized": true,
  "total_wallets": 0,
  "version": "4.6.0b1"
}

逐项解读关键字段：connected 与 synchronized 同时为 true 表示 daemon 已连上 Electrum 服务器且 SPV 头同步完成（部署后管理面板出现"未同步"告警时，可用此命令核实真实状态）；blockchain_height 与 server_height 一致说明本地区块头已追平远端；spv_nodes 为 10 表示当前连接的 SPV 服务器数量；total_wallets 为 0 表示 daemon 尚未加载任何钱包（全新部署的正常状态）。

不记得有哪些方法时，调用 help 方法获取 daemon 支持的完整方法清单：

./bitcart-cli help

实测输出（节选，实测首尾）：

[
  "add_hold_invoice",
  "add_peer",
  "add_request",
  "addtransaction",
  "broadcast",
  "bumpfee",
  "cancel_hold_invoice",
  "check_hold_invoice",
  "close_wallet",
  "convert_currency",
  "create",
  "createmultisig",
  "createnewaddress",
  "decode_invoice",
  "getaddressbalance",
  "getaddresshistory",
  "getinfo",
  "help",
  "list_wallets",
  "onchain_history",
  "payto",
  "paytomany",
  "restore",
  "setconfig",
  "signmessage",
  "signtransaction",
  "stop",
  "validateaddress",
  "version",
  "wait_for_sync"
]

清单覆盖比特币全量操作（地址、交易、闪电网络通道、多签、消息签名等）。给 help 传入方法名可查看单个方法的参数说明：

./bitcart-cli help getaddressbalance

实测输出：

usage: bitcart-cli getaddressbalance address

Return the balance of any address. Note: This is a walletless server query,
results are not checked by SPV.

positional arguments:
  address  Bitcoin address

3.4 常用 RPC 方法实测

查询任意地址余额（钱包无关的服务器查询）：

./bitcart-cli getaddressbalance bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

实测输出：

{
  "confirmed": "3.92748892",
  "unconfirmed": "0"
}

地址格式校验：

./bitcart-cli validateaddress bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

实测输出：

true

查看 daemon 已加载的钱包列表：

./bitcart-cli list_wallets

实测输出：

[]

带参数调用的方法：以 getconfig 为例，不带参数调用会返回参数缺失错误：

./bitcart-cli getconfig

实测输出：

{
  "code": -32603,
  "message": "TypeError: Commands.getconfig() missing 1 required positional argument: 'key'"
}

补上 key 参数查询一个不存在的配置项：

./bitcart-cli getconfig check_gossip

实测输出：

NoConfigKeyError: No config key found

汇率换算（daemon 默认关闭法币汇率模块）：

./bitcart-cli convert_currency 1 BTC USD

实测输出：

{
  "code": -32603,
  "message": "electrum.util.UserFacingException: FX is disabled. To enable, run: 'electrum setconfig use_exchange_rate true'"
}

错误信息本身给出了开启方式（setconfig use_exchange_rate true）。注意：Bitcart 商家的法币换算由 Merchants API 层完成（默认经 CoinGecko），daemon 层的 FX 模块默认关闭属正常状态，不建议为 CLI 体验单独开启。

3.5 钱包级方法：--wallet + --diskless

onchain_history、getbalance 这类钱包级方法需要先加载钱包。bitcart-cli 通过 --wallet 传入钱包标识（钱包名或 xpub）。本文演示采用"随机生成的一次性测试 xpub + --diskless 内存加载"方式：xpub 是公开钥信息，不构成资金风险；--diskless 保证不在服务器留下钱包文件。

先生成一个测试用 xpub（利用仓库虚拟环境内的 Electrum 库，随机根种子生成，输出仅为公开钥）：

cd /opt/bitcart/bitcart
.venv/bin/python3 -c "from electrum.bip32 import BIP32Node; from os import urandom; print(BIP32Node.from_rootseed(urandom(32), xtype=\"standard\").to_xpub())"

实测输出：

xpub661MyMwAqRbcGb3trNjcb8XwVkHkL8hkPDBBkaqz4LGFZ7FwQexi6GQWNY8qHW5kXqL8y8AHm5z9yamrENwPHUhf27qceknscHJSDN1Y8SE

用该 xpub 加载钱包（--diskless）并查询余额：

./bitcart-cli --wallet xpub661MyMwAqRbcGb3trNjcb8XwVkHkL8hkPDBBkaqz4LGFZ7FwQexi6GQWNY8qHW5kXqL8y8AHm5z9yamrENwPHUhf27qceknscHJSDN1Y8SE --diskless getbalance

实测输出：

{
  "confirmed": "0"
}

全新 xpub 无历史余额，返回 0 属预期。获取一个未使用的新收款地址：

./bitcart-cli --wallet xpub661MyMwAqRbcGb3trNjcb8XwVkHkL8hkPDBBkaqz4LGFZ7FwQexi6GQWNY8qHW5kXqL8y8AHm5z9yamrENwPHUhf27qceknscHJSDN1Y8SE --diskless getunusedaddress

实测输出：

1DzEtVB1XZFrtRarAVydV8ZszPWzXr7QKy

查询该钱包链上历史：

./bitcart-cli --wallet xpub661MyMwAqRbcGb3trNjcb8XwVkHkL8hkPDBBkaqz4LGFZ7FwQexi6GQWNY8qHW5kXqL8y8AHm5z9yamrENwPHUhf27qceknscHJSDN1Y8SE --diskless onchain_history

实测输出：

[]

验证"内存加载不落盘"：加载期间或之后再次查看 daemon 钱包列表：

./bitcart-cli list_wallets

实测输出：

[]

list_wallets 仍为空，证明 --diskless 钱包未持久化到 ~/.electrum/wallets 目录。

⚠️ 安全提示：生产环境不要在命令行明文传入正式钱包的 xpub（会进入 shell 历史）；应优先通过管理面板或 API 创建钱包。本文的测试 xpub 仅供演示，请勿向上述示例地址转入任何资产。

3.6 内置子命令：update 与 plugin

除 RPC 方法外，CLI 自带两组内置子命令。

update：CLI 自更新：

./bitcart-cli update --help

实测输出：

NAME:
   bitcart-cli update - CLI update operations

USAGE:
   bitcart-cli update [command [command options]]

COMMANDS:
   check    Check if there are any updates available
   install  Update the tool to the latest version

./bitcart-cli update check

实测输出：

Already up-to-date.

plugin：插件开发辅助：

./bitcart-cli plugin --help

实测输出：

NAME:
   bitcart-cli plugin - Manage plugins

USAGE:
   bitcart-cli plugin [command [command options]]

COMMANDS:
   init       Create a new plugin
   install    Install a plugin
   uninstall  Uninstall a plugin
   validate   Validate plugin manifest and common checks
   package    Package plugin from its directory

其中 validate 用于校验插件清单文件是否符合官方规范，默认使用官方 schema：

./bitcart-cli plugin validate --help

实测输出：

NAME:
   bitcart-cli plugin validate - Validate plugin manifest and common checks

USAGE:
   bitcart-cli plugin validate <path>

OPTIONS:
   --schema string  Supply custom schema URL (default: "https://bitcart.ai/schemas/plugin/1.3.0/plugin.schema.json")

3.7 常见报错与排查

以下是实测中踩到的典型报错，均可复现。

报错一：调用 SDK 层方法报 ProcedureNotFoundError：

./bitcart-cli balance
./bitcart-cli getwalletinfo

实测输出：

ProcedureNotFoundError: Procedure not found
ProcedureNotFoundError: Procedure not found

原因：balance、getwalletinfo 是 bitcart-sdk（Python 库）在 daemon RPC 之上封装出的方法，daemon 原生 RPC 并不存在这两个过程。bitcart-cli 直连 daemon，因此查不到。等价需求改用：daemon 层用 getbalance（需加载钱包）与 list_wallets，SDK 层（业务程序内）才有 balance/getwalletinfo。这是"daemon 方法面"与"SDK 方法面"的边界问题，排错时先确认方法属于哪一层。

报错二：密码错误返回 Unauthorized：

./bitcart-cli -p wrongpass getinfo

实测输出：

{
  "code": -32600,
  "message": "Unauthorized"
}

原因：daemon RPC 启用了 Basic 认证，凭证不对时所有请求被拒。官方默认凭证为 electrum:electrumz，且仅监听 127.0.0.1:5000（不对公网开放），若曾用 BITCART_LOGIN/BITCART_PASSWORD 类参数改过凭证，CLI 调用时需同步传入。

报错三：切换未启用的币种连接被拒：

./bitcart-cli --coin ltc getinfo

实测输出：

Error: rpc call getinfo() on http://localhost:5001: Post "http://localhost:5001": dial tcp [::1]:5001: connect: connection refused

原因：--coin ltc 让 CLI 转向 LTC daemon 的默认端口 5001，但本机只部署了 BTC daemon（BITCART_CRYPTOS=btc），5001 端口无服务监听。属正常现象：先按《Bitcart 0.10.3.0 Ubuntu 22.04 安装指南》为对应币种补充部署（uv sync 追加币种分组并拉起对应 daemon），再使用该币种。

报错四：未加载钱包就调用钱包级方法：

./bitcart-cli onchain_history

实测输出：

WalletNotLoadedError: Wallet not loaded. No xpub was provided and this function requires wallet

原因：钱包级方法必须配合 --wallet（钱包名或 xpub），报错文本已给出明确指引。

报错五：查询 daemon 不存在的配置项：

./bitcart-cli getconfig check_gossip

实测输出：

NoConfigKeyError: No config key found

原因：check_gossip 是闪电网络相关配置项，未启用闪电网络时该键不存在。Bitcart 自身的配置参数（BITCART_*、BTC_* 系列）属于 API/编排层的环境变量，不归 daemon 的 getconfig 管——后者管的是 Electrum 自身配置。两套配置体系的关系见《Bitcart 0.10.3.0 配置参数详解》。

四、bitcart-cli.sh：Docker Compose 形态的包装入口

采用《Bitcart 0.10.3.0 Docker Compose 部署指南》所述官方编排部署时，无需单独下载二进制：编排仓库自带 bitcart-cli.sh 包装脚本，执行时等价于"进入 worker 服务执行其内置的 bitcart-cli 并透传全部参数"：

cd bitcart-docker
./bitcart-cli.sh --help

实测输出（完整回显见该指南 4.5 节）：

NAME:
   bitcart-cli - Call RPC methods from console

USAGE:
   bitcart-cli method [args]

VERSION:
   docker

COMMANDS:
   plugin  Manage plugins

与独立二进制形态的实测差异：

差异点	独立二进制	编排内置版
版本号	`1.6.1`	`docker`（随编排组件构建发布，非独立版本号）
内置子命令	`plugin`、`update`	仅 `plugin`（编排环境内自更新无意义）
全局选项	全量（含 `--contract`、`--address` 等）	同全量
默认连接目标	本机 daemon 端口（如 5000）	编排内部网络的 daemon 服务

除入口与版本号外，RPC 方法调用方式完全一致，第三章的全部用法（含 --wallet/--diskless）在编排形态下同样适用。

五、daemon JSON-RPC 直调（curl）

bitcart-cli 本质上是 daemon JSON-RPC 接口的命令行客户端。任何有 curl 的环境都可以直接调用，不需要安装任何 Bitcart 组件——这是做监控脚本、健康检查时的最小依赖方案。

daemon 的 RPC 端口监听在 127.0.0.1:5000（BTC），启用 HTTP Basic 认证（默认凭证 electrum:electrumz），协议为 JSON-RPC 2.0。以 getinfo 为例：

curl -s -X POST http://127.0.0.1:5000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(printf "electrum:electrumz" | base64)" \
  -d '{"jsonrpc":"2.0","id":0,"method":"getinfo","params":[]}'

实测输出：

{"jsonrpc": "2.0", "result": {"network": "mainnet", "path": "/home/bitcart/.electrum", "server": "bitcoin.lu.ke", "blockchain_height": 972640, "server_height": 972640, "spv_nodes": 10, "connected": true, "auto_connect": true, "version": "4.6.0b1", "fee_estimates": {"1008": 813, "144": 813, "25": 852, "10": 1000, "5": 1823, "2": 2255}, "synchronized": true, "total_wallets": 0}, "id": 0}

与 bitcart-cli 调用同一方法返回的数据完全一致（对照 3.3 节），证实 CLI 只是 RPC 的封装。

要点说明：

method 填 daemon 方法名，params 为参数数组；带参调用示例："method": "getaddressbalance", "params": ["bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"]；
认证串格式为 Basic base64(用户名:密码)，凭证错误时返回 {"code": -32600, "message": "Unauthorized"}；
各币种端口不同（BTC 5000、LTC 5001、ETH 5002 等，全表见《Bitcart 0.10.3.0 介绍与选型指南》），只监听本机回环地址，远程调用需先自行建立加密隧道，不要把端口暴露到公网；
SDK 与业务程序建议使用 bitcart-sdk（WebSocket 事件推送、自动重连），curl 直调适合一次性检查与轻量轮询。

六、uv run just：源码开发任务集

以上工具面向"运行中的 Bitcart"。若从事二次开发或问题定位，Bitcart 源码仓库内置了一套 just 任务集（justfile 定义，rust-just 作为 Python 依赖随 uv sync 装入虚拟环境，无需全局安装 just）。

查看任务清单：

cd /opt/bitcart/bitcart
uv run --no-dev just --list

实测输出：

Available recipes:
    [BTC setup]
    bitcoind             # start bitcoind
    fulcrum              # start fulcrum
    mainnet              # start electrum mainnet daemon
    regtest              # start electrum regtest daemon
    regtestln            # start electrum regtest daemon (lightning node)
    testnet              # start electrum testnet daemon

    [CI]
    ci *args             # run ci checks
    ci-lint              # run ci checks (without tests)

    [Database]
    db-migrate           # run alembic upgrade
    db-migration MESSAGE # create new migration
    db-rollback          # run alembic downgrade

    [Linting]
    lint                 # run linters with autofix
    lint-check           # run linters (check only)
    lint-types           # run type checking

    [Services]
    daemon coin          # run coin daemons
    dev-api              # run api service
    prod-api             # run api service in production
    prod-api-up          # run migrations and start api service in production
    worker               # run worker service

    [Testing]
    functional *args     # run functional tests
    test *args           # run tests

任务分组解读：

分组	代表任务	用途
Services	`dev-api`、`prod-api`、`worker`、`daemon btc`	手工拉起各服务进程（前台运行，便于看日志调试）；`prod-api-up` 先迁移再启动生产 API
Database	`db-migrate`、`db-rollback`、`db-migration "MSG"`	数据库迁移三件套：升级、回滚一代、生成新迁移脚本
BTC setup	`regtest`、`testnet`、`mainnet`	以指定网络参数前台启动 BTC daemon（regtest 任务还会自动清理旧数据并指向本地 fulcrum）
Linting / CI	`lint`、`lint-check`、`lint-types`、`ci`	ruff 格式化/检查 + mypy 类型检查，提交前自检
Testing	`test`、`functional`	单元测试与功能测试（后者需本地 bitcoind/fulcrum 引导）

实测一个幂等的数据库任务（迁移已到最新版时重复执行安全）：

uv run --no-dev just db-migrate

实测输出：

alembic upgrade head
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.

注意事项：

uv run 的语义是"先同步依赖再执行命令"。不带 --no-dev 时会把开发依赖（ruff、mypy、pytest 等 71 个包）一并装入虚拟环境——实测首次执行 uv run just --list（无 --no-dev）即出现 Installed 71 packages in 48ms。生产服务器上建议统一加 --no-dev，保持运行环境干净；

uv sync 不保留旧状态：手工部署时用过的 --group btc --group otel 等分组参数在同步后不会保留，重新同步必须带全所需分组（见安装指南 3.5 节）；

这些任务以前台方式启动服务（如 just dev-api），会占用当前终端；systemd 托管的生产服务请用安装指南 3.9 节的方式管理，勿混用两套启动方式。

七、bitcart-docker 管理脚本汇总

Docker Compose 形态的整套生命周期操作由编排仓库根目录的脚本集承担，各脚本用途如下（均以 ./<脚本名> 方式在编排仓库目录内执行）：

脚本	用途	备注
setup.sh	一键部署/重新配置整套服务（读取环境变量生成编排配置并启动）	每次修改配置后重新执行即可生效
start.sh / stop.sh / restart.sh	启动 / 停止 / 重启整套服务	—
update.sh	更新到新版本（支持 `--skip-git-pull` 跳过仓库拉取）	—
backup.sh / restore.sh	备份全部数据卷 / 从备份恢复（生成时间戳命名的压缩包）	依赖 zstd，实测排障见该指南 6.1 节
changedomain.sh	变更访问域名（替换域名并滚动重启受影响服务）	参数不带 `http(s)://` 前缀
admin.sh	向 worker 服务下发服务器策略更新指令	—
cleanup.sh	清理编排仓库构建产生的无用本地资源	—
build.sh	从源码构建服务组件（面向自构建场景）	—
bitcart-cli.sh	透传调用内置 bitcart-cli	见本文第四章
helpers.sh / load_env.sh	内部公共函数库，不单独执行	—

其中 setup、启停、更新、备份、恢复五个高频脚本的完整实测过程（含命令与回显）已在《Bitcart 0.10.3.0 Docker Compose 部署指南》第四章逐节验证，本文不重复展开，运维操作请以该指南为准。

八、常见问题与排障实录

Q1：bitcart-cli balance 明明是"查余额"，为什么报 ProcedureNotFoundError？

balance 是 bitcart-sdk 暴露给业务代码的方法，daemon 原生 RPC 里没有它。分层记忆法：daemon 层方法看 bitcart-cli help 的清单（getbalance、onchain_history 等），SDK 层方法查 bitcart-sdk 文档（balance、getwalletinfo 等）。详见 3.7 节报错一。

Q2：CLI 报 Unauthorized，但管理面板一切正常？

管理面板走的是 Merchants API（8000 端口）认证体系，daemon RPC（5000 端口）是另一套独立凭证（默认 electrum:electrumz）。二者不共享账号体系。用 -p 传对 daemon 密码即可；若按 3.2 节改过默认凭证，记得同步更新。

Q3：--coin ltc 报 connection refused？

CLI 只是按端口找服务（LTC 对应 5001），机器上没部署该币种 daemon 自然拒绝连接。先补部署再调用，见 3.7 节报错三。

Q4：想让 CLI 连接远程服务器上的 daemon？

用 -U/--url 显式指定 daemon URL（优先级高于按币种推导的默认值）。但注意 daemon 默认只监听 127.0.0.1，远程访问需要先在远端改监听地址并在两端做好认证与加密（隧道），安全责任自担；更推荐的做法是在目标服务器本地执行 CLI 或直调 RPC。

Q5：--diskless 和普通 --wallet <钱包名> 的区别？

--diskless 只把钱包加载进内存，服务器磁盘上不产生钱包文件，适合一次性查询（如本文的测试 xpub 演示）；--wallet <钱包名> 加载 daemon 钱包目录里已存在的钱包文件，适合对长期驻留钱包的持续操作。验证手段见 3.5 节末尾（list_wallets 始终为空）。

Q6：执行 uv run just 时自动下载了一堆包，正常吗？

正常但需留意：uv run 会先做依赖同步。缺 --no-dev 时连开发依赖一起装（实测 71 个包）。生产服务器加 --no-dev；开发机两种皆可。见第六章注意事项。

Q7：脚本集里没找到"查看服务状态"的脚本？

编排形态的服务状态检查命令（systemctl status bitcart 与各服务状态核对）在《Bitcart 0.10.3.0 Docker Compose 部署指南》3.3 节有完整实测，不属于独立脚本；脚本集聚焦"变更类"操作（部署、启停、更新、备份），状态检查属于日常巡检命令。

九、下一步

需要从零搭起本文所依赖的服务器环境：见《Bitcart 0.10.3.0 Ubuntu 22.04 安装指南》或《Bitcart 0.10.3.0 Docker Compose 部署指南》；
需要理解各配置参数（含 CLI 相关的监听地址、凭证、币种开关）：见《Bitcart 0.10.3.0 配置参数详解》；
需要了解 Bitcart 架构与组件边界（daemon 与 API 的职责划分）：见《Bitcart 0.10.3.0 介绍与选型指南》。