trustbase-shop-init

📛 改名说明（2026-09-29）：原 @trustbase/shopxo-init 更名为 trustbase-shop-init。 ShopXO 已于 2026-09-22 全线下架，本安装器装的是「链节点 + 索引器 + 卖家后端」，与 ShopXO/PHP/MySQL/nginx 无关。 老包名已在 npm 标记 deprecated，老命令 shopxo-init 不再更新。

TrustBase 商家本地开店一键安装器。商家在自己电脑上运行:

npx trustbase-shop-init

本安装器是 npm 包, 本身就运行在 Node 上, 所以 npx 之前必须先有 Node.js >= 18。 全新云主机/裸机通常一条命令装好:

# Ubuntu / Debian: 装 Node 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

node -v          # 确认 >= 18 (建议 20 或 22)
npx trustbase-shop-init

• 为什么引导 22 而不是最新的 24: 本项目的原生模块 (better-sqlite3) 在 Node 24 上 没有预编译包、需要本机编译, 容易在商户机器上装失败; 20/22 LTS 有预编译包。doctor 对 >= 24 会给 ⚠️ 提示。
• RHEL / CentOS / Rocky / openSUSE: 用 NodeSource 对应发行版的脚本, 或从 https://nodejs.org/dist/ 下载 官方二进制 tarball 解到 /usr/local。
• Windows / macOS: 直接从 https://nodejs.org/en/download 装 LTS (Windows 建议 22)。
• 只想看一眼装完什么样, 不动手: npx trustbase-shop-init doctor。

自动完成 5 步:

1. 环境检测 (Node >= 18 + 平台支持矩阵)
2. 部署卖家后端 trustbase-seller-backend (含本地入驻页, 端口随机)
3. 安装链节点 @trustbaseai/trustchaind (canonical genesis sha256 校验 + 公共 peer 注入 + 启动同步; 端口随机, RPC 默认只绑回环)
4. 安装本地索引器 @trustbaseai/indexer (默认指本机节点; 无本机节点时指远程默认节点; 双栈监听)
5. 启动服务并自动打开 http://localhost:<随机端口>/onboard

新装的机器上不会出现 PHP / php-fpm / MariaDB / MySQL / nginx / ShopXO —— 商家机器终态 = 链节点 + 索引器 + 卖家后端 (ShopXO 退出方案 §4)。店铺界面由 SDK 的 PWA 提供 (尚未发布), 所以安装完没有店铺网页, 开店先走进驻页 (/onboard)。

链节点平台支持: linux x64/arm64 + windows x64 + darwin x64/arm64 (二进制随包, sha256 校验); 不支持的平台自动跳过链节点并明确提示 (索引器可指远程节点), 不阻断安装。 可用 --skip-chain-node / --skip-indexer 跳过, --trustchaind-tarball / --indexer-tarball 用本地包。

关于链节点同步: 新节点要用 blocksync 从创世一路追到链头, 这要求网络上区块历史连续。 只要中间有一段没有任何节点还留着块 (节点各自裁剪或掉队造成"空洞"), 就永远接不上 —— 而且不报任何错, 只是高度停在 0 一直空转, 很容易被当成"还在同步"。 doctor 的「网络可同步性」一项会实际探测公共节点的可提供区间, 直接告诉你能不能追、 断在哪个高度, 不会让你干等:

npx trustbase-shop-init doctor

追不上时的出路 (三条, 都得网络侧先支持, 本机改配置解决不了): ① 网络侧开 state sync ([statesync] enable = true 且 app 侧配 state-sync.snapshot-interval)； ② 网络侧提供一份可直接灌入的 snapshot；③ 恢复一个仍保有完整历史的节点并让它保持同步。

注意: 链节点同步与开店/收款无关。 收款走 SP 网关上链, 不依赖商户本机的链节点, 所以即使本机节点追不上, 入驻、下单、收款依然可用。

端口策略 (六端口, 见《一键安装与端口策略-2026-09-22》§3)

端口随机分配 (10000-60000, 安装时探测空闲, 六个互不相同) — 固定端口会被上游网络封锁 (2026-09-22 实测 8080 被家庭宽带上游按端口封禁, 随机端口直通), 同机第二个安装也不再撞端口。

| 端口 (tb-ports.json) | 谁用 | 默认绑定 | |---|---|---| | backend_port | 卖家后端 / 入驻页 (管理面) | :: (双栈) + IP_WHITELIST 锁回环 | | indexer_port | 索引器 HTTP + WS (/ws/indexer 买家查询面) | :: (双栈, 买家面) | | chain_p2p_port | 链节点 P2P listen | [::] (以出站为主) | | chain_rpc_port | 链节点 RPC (config.toml [rpc] laddr) | 127.0.0.1 | | chain_lcd_port | 链节点 LCD/API (app.toml [api] address) | 127.0.0.1 | | chain_grpc_port | 链节点 gRPC (app.toml [grpc] address) | 127.0.0.1 |

• 端口记录在安装目录根部的 tb-ports.json (doctor/fix/backup/restore/uninstall 都读它; backup 打包它, restore 换机沿用原端口, 被占用时明确提示而不静默改);
• 索引器没有独立 WS 端口, 也不写 ws-port.json (那是 standalone 入口 index.js 的行为, 生产入口 run-unified.js 是同一端口按路径分流; 见 PWA 设计 §6.1.1)。老安装的 tb-ports.json 里 如果还有 indexer_ws_port 字段, 读到时忽略并提示"该字段已废弃", 不报错;
• 链节点 rpc/lcd/grpc 默认只绑 127.0.0.1; 需要对外时 fix --chain-rpc-public 显式打开 (会打印风险提示), 打开后这些端口在 0.0.0.0 全网可达, 请自行加防火墙;
• 改链节点端口 = 显式动作 + 重启节点 (CometBFT 不支持热改): fix --randomize-chain-ports 重新抽签四个端口、写配置并重启; 安装器绝不会在运行中偷偷改端口;
• 老安装: 没有链端口记录时按旧常量 (26656/26657/1317/9090) 处理并说明, 不自动改老机器的端口; doctor 会把 config 里的实际值写回 tb-ports.json 记录, 保证"记录 = 现状";
• 验证者保护: 改链端口前会查链上验证者集, 若本机 consensus 公钥在其中 → 拒绝改端口并提示 "验证者端口变更要人工协调 (改配置 + 同步各节点 persistent_peers + 逐台重启)"; 查不到链时 fail closed (宁可不改); 安装器只写本机 chain-node/home 里的配置, 从不碰别人的 --home。

创世文件 (genesis): 包内优先 + sha256

genesis 是"创世真相", 不该依赖一个可能下线的下载域名 (2026-09-22 实测那两个镜像 URL 都已 404)。 所以 canonical genesis 随安装包分发: assets/genesis-trustchain-1.json (556 KB, 已进 package.json 的 files 白名单)。

取用顺序 (只信哈希, 不信来源):

| 顺序 | 来源 | 校验失败时 | |---|---|---| | 1 (主路径) | 包内副本 assets/genesis-trustchain-1.json | 直接拒绝安装 — 包本身坏了, 不该"降级硬装" | | 2 | 本地缓存 <安装目录>/cache/genesis-trustchain-1.json | 跳过并说明 (本地半成品, 可重取) | | 3 (仅兜底) | 远端镜像 (GENESIS_URLS, 可用 --genesis-url 覆盖) | 换下一个地址; 全部不行才报错 |

• 三步都过内置 sha256 (GENESIS_SHA256, 与包内文件同一来源的真值, 不是两份);
• 安装输出会写明用的是哪一份 + 校验结果, 例如 genesis 来源: 包内副本 (…, 543.1 KB) — sha256 校验通过 + 未访问远端 (远端镜像只是兜底); 远端挂了只是 warn, 不影响安装;
• 报错文案区分"包损坏"与"远端被改"(前者让你重新取包, 后者丢弃该镜像);
• 拿到包内/远端副本后会顺带写入安装目录 cache/, 下次 fix/重装可离线复用;
• doctor 有一项 创世文件: 节点正在用的 chain-node/home/config/genesis.json 的 sha256 == 内置 canonical 值; 不一致给 ❌ 并提示 fix (会用包内副本重写 + 重启节点); 该项同时打印包内副本状态与远端镜像的当前状态 (例如 远端镜像(仅兜底): trustbase.ployq.com=404, 43.143.70.90:29443=404)。

卖家私钥: 口令加密落盘 (WP2a, 2026-09-23)

原则: 商家机器上不留私钥明文。助记词/私钥只以口令加密的密钥库形式落盘 (seller-backend/tb-keyring/keystore.json, 0600), 加密用 SDK 的 @trustbase/account (keystore v1: Argon2id + AES-256-GCM, 明文头做 AAD) —— 安装器不自创加密格式。

| 事项 | 做法 | |---|---| | 口令从哪来 | 交互输入为主 (隐藏回显, 输两次); 强度必须过 estimatePasswordStrength (评分 ≥ 3 + 非黑名单), 不够就重来 | | 非交互模式 | --keyring-passphrase-file <文件> 或环境变量 TRUSTBASE_KEYRING_PASSPHRASE; 两者都会大声警告"明文口令放文件 = 锁和钥匙放一起, 仅限自动化/测试" | | 口令绝不落盘 | 不写 .env、不写任何配置; 解锁时才输入。忘了口令 → 用纸密钥恢复 | | 助记词 | 建库前走抄写门 (pickTranscriptionIndices/checkTranscription, 3 词回填, 3 次不过就中止); 明文助记词不落盘 | | 纸密钥 | print-key 会先解锁 keystore 再生成打印页 (0600), 打完请自行删除 (doctor 会把残留的 paper-key-*.html 报成明文) | | 老机器 | npx trustbase-shop-init migrate-keyring --dir <目录>: 扫明文 (mnemonic.txt / CLI keyring / .env 变量) → 先备份到 backup/keyring-pre-encrypt-<时间戳>/ (0700/0600) → 加密 → 解锁回算地址必须与迁移前一致 → 一致才删明文; 不一致就保留明文并报错 (宁可不迁移也不丢身份) | | 自检 | doctor 的「私钥明文落盘」项: 扫 mnemonic.txt、CLI keyring 明文后端、.env 里的 *_MNEMONIC、paper-key-*.html、迁移前的明文备份 —— 命中即 ❌ 并逐条给修复指引 |

@trustbase/account 目前未发布到 npm(SDK monorepo 内私有), 过渡期三选一: npm i @trustbase/account(发布后) / --account-pkg <路径> / TRUSTBASE_ACCOUNT_PKG=<路径>。 没有它就不生成任何私钥材料(也绝不退回明文) —— 由 doctor 提示。

⚠️ 已知过渡缺口: 卖家后端 (core/chain-signer.js / core/chain-seller-identity.js) 目前只认 tb-keyring/mnemonic.txt 与 CLI keyring, 所以迁移后它的上链写操作会失败, 直到后端改为 "读 keystore + 启动时解锁"。改造接口说明见交付报告 (由后端 lane 落地)。

远程访问 / 买家可达

• 卖家后端是管理面, 默认锁本机 (IP_WHITELIST=127.0.0.1,::1, 远程访问一律 403 — 这是应用层白名单, 不是端口不通);
• 要放开: npx trustbase-shop-init fix --allow-cidr 192.168.1.0/24 (可重复传; IPv6 前缀同样写法; 0.0.0.0/0 全开只在你显式传它时生效) —— --allow-cidr 只管管理面, 不影响买家面;
• 索引器 :indexer_port 是买家侧的只读门: 默认双栈监听, 故意不做鉴权 (要收紧靠每 IP 限速 + 单连接并发上限), 不要锁到 127.0.0.1;
• ⚠️ 索引器 0.5.0 的现状: 同一个进程还挂着 /api/* 写操作面, 所以安装器给索引器 .env 写了 REQUIRE_API_KEY_FOR_LAN=true (与卖家后端一致), 避免"开买家面 = 顺手把管理面也放开给 LAN"。 等 SDK 的只读索引器拆出来后再重新评估这条。

常用参数

| 参数 | 说明 | |---|---| | --dir <路径> | 安装目录 (默认 <当前目录>/trustbase-shop) | | --skip-backend / --skip-chain-node / --skip-indexer | 跳过某一步 (仅 install) | | --trustchaind-tarball / --indexer-tarball | 用本地/测试 tarball 装 (调试用) | | --chain-rpc <地址> | 上游服务节点地址 (默认内置公共节点, 仅 install) | | --genesis-url <地址> | 覆盖 genesis 远端兜底镜像 (可重复传; 只在包内副本与缓存都不可用时才会用到) | | --chain-rpc-public | 把本机链节点 rpc/lcd/grpc 绑到 0.0.0.0 (默认只绑回环; 有风险, 会打印提示) | | --randomize-chain-ports | 显式换链节点四个端口并重启节点 (仅 fix; 验证者会被拒绝) | | --dry-run | 只打印计划不做修改 (目前用于 uninstall: 列出"会停哪些 pid + 判据") | | --port-backend <端口> | 入驻页端口 (默认随机; 指定后冲突会报错) | | --allow-cidr <网段> | 追加后端 IP 白名单 (可重复传; 只管管理面) | | --yes | 全默认值不询问 | | --no-start / --no-open | 不启动服务 / 不打开浏览器 | | --help | 完整帮助 |

已废弃参数 (保留名字只为不炸老脚本, 传了会被忽略并打印一行提示): --skip-env-check、--skip-db、--db-host/--db-port/--db-user/--db-pass/--db-name、 --admin-user/--admin-pass、--port-shop —— 这些都属于 ShopXO (PHP + MySQL) 时代。

体检与修复

装完后环境出问题 (电脑重启后端没起 / 误删文件 / 改了端口) 时:

# 体检: 逐项检查, 输出 ✅/⚠️/❌ + 修复建议, 有失败项退出码 1
npx trustbase-shop-init doctor

# 自动修复: 先体检, 修能修的 (重建配置/重装依赖/重启服务/补 genesis+peers), 修完再体检
npx trustbase-shop-init fix

# 显式改链节点端口/绑定 (会重启节点; 只在你自己要求时发生)
npx trustbase-shop-init fix --randomize-chain-ports
npx trustbase-shop-init fix --chain-rpc-public

doctor 项 (新装形态): 操作系统、Node 版本、卖家后端文件/原生模块/.env、 后端进程与 /health + /onboard、卖家身份一致性 (入驻页身份 vs 上链签名 key)、 链节点 (运行/同步高度)、链节点端口 (config.toml/app.toml 的值 vs tb-ports.json 记录 vs 实际监听 ss, 逐项比对)、 链节点暴露面 (rpc/lcd/grpc 是否被绑到 0.0.0.0, 给警告不算失败)、 索引器 (/healthz)、索引器监听面 (买家面是否真的可达 + 管理面是否被放宽)、 索引器 WS 查询面 (对该索引器端口的 /ws/indexer 做一次真实 upgrade 握手, 期望 101)、磁盘空间。 云服务器上另给安全组提示 (买家面/管理面/链端口的放行建议)。

fix 能自动修: 重装后端依赖、rebuild 原生模块、补写后端配置、拉起后端/链节点/索引器、补 genesis 与 peers。 修不了的 (Node 版本不对、磁盘不足) 会打印明确的手动指引。

备份 / 恢复 / 纸质密钥 / 卸载

# 备份: 打包配置/后端数据/卖家密钥/链节点配置/索引器数据, 输出到安装目录上一级
npx trustbase-shop-init backup

# 恢复: 新机器上从备份包恢复 (新装形态的备份不再下载 ShopXO、不建库), 恢复后自动体检
npx trustbase-shop-init restore trustbase-backup-20260921-103000.tar.gz

# 打印纸质密钥页 (助记词+地址+二维码, 自动弹打印对话框); 未完成入驻会拒绝打印
npx trustbase-shop-init print-key

# 先看卸载计划 (推荐先跑这个: 列出会停哪些 pid + 判据, 什么都不动)
npx trustbase-shop-init uninstall --dry-run

# 彻底卸载: 三重安全闸门, 默认保留卖家密钥, --destroy-keys 才销毁
npx trustbase-shop-init uninstall

backup 生成 trustbase-backup-时间戳.tar.gz, 内含 manifest.json (逐文件 sha256 校验)。 ⚠️ 备份包含卖家私钥, 必须离线存放; 包本身未加密 (零依赖限制), 建议自行用 7-Zip/VeraCrypt 加密。 新装形态没有数据库, 所以不再有 mysqldump 那一段 (老 ShopXO 安装的备份仍会导出数据库)。

restore 先校验 manifest 每个文件的 sha256, 再恢复; 目标已有安装时需 --yes 确认覆盖; 结束时强制跑一遍 doctor。注意: 恢复的是数据与配置, 链节点/索引器/后端的程序本体由 restore 内的部署步骤 或重跑 install 装好 (链节点平台不支持时需另行处理)。

老安装 (legacy ShopXO) 的维护

已有 ShopXO 的老机器 (例如 .215 的 /root/tb-test) 不受本次下架影响: doctor / fix / backup / restore / uninstall 里与 ShopXO/PHP/MySQL/nginx 相关的代码路径保留并标 legacy, 只有在安装目录里存在 shopxo/ 时才生效 (新装不再经过这些路径):

• doctor 仍检查 PHP/MySQL 依赖、shopxo/ 与插件完整性、.env 凭据与建库导入、install.lock、后台入口随机化、 runtime 可写、店铺后台账号是否仍是模板默认密码、php -S 测试服务;
• fix 仍能重建 .env/install.lock、重导数据、重随机后台入口、改后台密码、拉起 php -S;
• backup/restore/uninstall 仍处理 shopxo/、商品图、数据库 dump 与整库删除;
• 老机器端口不会被自动改: 没有链端口记录就按旧常量 (26656/26657/1317/9090) 处理并说明, 只把 config.toml 里的实际值写回 tb-ports.json 记录 (记录 = 现状)。

uninstall 只停"属于本安装目录"的进程

老实现按端口兜底杀进程 (lsof -ti :26657), 而 26657 是全局常量 → 2026-09-22 在 .215 实测: 对任一目录跑 uninstall 会连带杀掉别的安装的链节点 + 后端 + 索引器 (含用户正在验收的 /root/tb-test)。 现在改成:

1. 候选 = 本目录 pid 文件 + 本目录 tb-ports.json 里记的端口上监听的进程;
2. 每个候选都做归属判定 (/proc/<pid>/cwd 是否在安装目录内 / cmdline 是否含安装目录 / 链节点 --home 是否等于 <安装目录>/chain-node/home) —— 不属于的只打印"跳过原因", 不杀;
3. systemd unit 同样加闸: ExecStart 不指向本目录就不停不删;
4. uninstall --dry-run 先打印"将会停止哪些 pid + 判据"和"看到但不会动哪些 pid + 原因", 什么都不做。

下架时间线: 2026-09-22 店面即刻下架 (.215: index.php → 410, 根路径 302 到买家入口, 先 dump 数据库) → 安装器同步下架 (本 README 描述的改动)。

平台要求

• Ubuntu 24.04 LTS (推荐, 含轻量云服务器, 2C2G 即可) / 22.04 LTS (可用) / Windows 10+ / macOS 13+
• 低于 Ubuntu 22.04 的系统会被拒绝 (不做向下兼容)
• Node.js >= 18 (推荐 20/22 LTS, 原生模块有预编译包)
• 不需要 PHP / MySQL / nginx (ShopXO 已下架)

零运行时依赖, 全部使用 Node 内置模块 (仅 vendor 了一个 MIT 单文件 QR 库用于纸质密钥页)。 解压使用系统自带 tar (Windows 10+ 自带)。

改名记录 (2026-09-29 已执行)

原名 @trustbase/shopxo-init → 现名 trustbase-shop-init（bin 命令 shopxo-init → shop-init）。 原因：ShopXO 已于 2026-09-22 全线下架，安装器自当日起装的就是「链节点 + 索引器 + 卖家后端」，包名名不副实。 旧包名在 npm 已 deprecate 并指向本包；老安装目录里的 shopxo/ legacy 检测与 shopxo-trustbase-fork.tar.gz 归档名保持不变（维护老安装的能力不受影响）。

License: MIT