USDB 区块浏览器与公共 RPC 接入服务。包含 Blockscout 集成、USDB 展示适配、受限 RPC gateway、 内置 Nginx，以及独立安装、备份、升级与发版工具。新安装默认连接同机 USDB 的 loopback RPC， 也支持独立机器上的私网 RPC 上游。
本工程从 buckyos/usdb 的 0b946e03c71f70e6dfe0bb1bc44d9e6b3ce803ec 迁出，来源路径记录在
MIGRATION.json。新版本使用本仓库的 vX.Y.Z，不要求创建节点 rN 或更新节点 release lock。
用户和运维人员从 Explorer handbook 开始，覆盖安装、局域网/公网接入、 检查结果、升级备份和排错。完整参数与部署细节见 部署参考。源码入口：
explorer/usdb-explorer --help
explorer/usdb-explorer setup --config /path/to/config.json --state-dir /path/to/deployment
explorer/usdb-explorer prepare --config /path/to/config.json --state-dir /path/to/deploymentusdb-public 保留为兼容命令。原有配置/部署 schema、默认 ~/.config/usdb-public、
~/.local/share/usdb-public、deployment ID 和数据库 volume 身份继续使用。
历史 usdb-public-v0.1.0 附件保留在原 USDB 仓库。
| 目录 | 内容 |
|---|---|
explorer/ |
部署控制、安装器、网络 catalog/contract、第三方镜像 lock |
frontend/ |
固定 Blockscout 源码上的 USDB 导航、网络概览和矿工证查询；独立构建与镜像发布 |
gateway/ |
独立 Go module：公共 RPC、浏览器 API，以及独立进程运行的可选水龙头 |
scripts/prepare_release.py |
本仓库的 annotated tag 准备工具 |
.github/workflows/ |
独立 CI、构建草稿、手动 Publish |
scripts/image_security.py |
固定 digest 的镜像扫描计划、证据校验与可选强制门禁 |
tests/ |
部署、安装、迁移、发布、网络契约和真实 Nginx 测试 |
docs/ |
用户与运维 handbook、网络接口、发布与迁移说明、历史验收记录 |
日常构建和测试不需要 USDB/go-ethereum/SourceDAO checkout。网络身份和 RPC 要求通过已提交的 契约文件关联固定 USDB commit；刷新流程见 网络契约。
Python 3.11+，Go 版本见 gateway/go.mod。完整 Python 验证需要本地 Docker，用于创建和清理
带随机名称的临时 Nginx 容器/网络：
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py'
cd gateway
go test -race ./...可选水龙头的账户、限额和一次性矿工补款命令见 水龙头手册。
容器验收使用 python3 tests/test_faucet_containers.py --image <gateway-test-image>，只连接隔离模拟链。
在干净且已推送的 main 上：
python3 scripts/prepare_release.py --version 0.2.1
python3 scripts/prepare_release.py --version 0.2.1 --create --push
# Wait for the tag build to succeed before publishing.
gh workflow run release-publish.yml --repo buckyos/usdb-explorer --ref v0.2.1先等待 tag build 成功，再手动 Publish；网页中在 Use workflow from 选择对应 tag，无需填写版本。
此流程适用于包含 tag 选择修复的新版本；已有 v0.2.0 的过渡方式及完整配置见
发布与迁移。普通开发 checkout 即使尚无 commit 也可生成明确标记
source_dirty 的本地测试包；发布只接受通过 tag 构建的干净源码。
版本变更使用 结构化 fragment 维护，规则沿用 USDB/go-ethereum。 打 tag 前会报告未分类提交；Build 生成变更 JSON、checksum、Markdown 和 Release 正文， Publish 从固定源码重验。工作流与兼容性比较见 变更记录管理。
测试网采用镜像安全 report-only 模式，并允许显式配置 public + HTTP 的 IP/端口预览或 HTTPS。漏洞及未完成验收状态
继续保留；扫描失败、digest/source 不符、证据损坏仍阻断发布。维护者可手工运行 strict 审查。
完整策略见 镜像安全与测试网发布。真实 archive、重组恢复、合约验证和
钱包广播仍需独立验收；原始结果见 历史验收记录。