v0.6 已新增发售入口和 RabbitMQ;完整运行按手动验收,当前边界见进度。下文交易 dev 命令只启动二级市场;发售使用 run-sale-windows.cmd 同时启动两个服务。
当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。
适用 v0.5 独立钱包模式,原模拟模式运行方式见项目README。本模式不使用管理员账户余额,注册/登录功能继续保留在模拟服务。范围、状态和权威见v0.5架构。
从干净依赖开始#
需要Go 1.26.9、Node22+、npm、浏览器;下面命令在项目根目录执行。只连接本次Anvil,首次下载需要网络。标准代理不可用时可单条命令指定 GOPROXY=https://goproxy.cn,direct,不改全局设置。
go mod download npm --prefix contracts ci npm --prefix contracts run compile npm --prefix frontend ci npm --prefix frontend run build npm --prefix contracts run dev |
访问 http://127.0.0.1:8081/?mode=web3 。脚本部署MockWETH、MockUSDT、Settlement;生成 bin/web3-dev/config.json,每次新建时间戳数据目录,不覆盖旧数据。Ctrl+C停止本次Go/Anvil子进程。端口8545/8081须空闲。每次Anvil新历史,旧数据不能复用,即使地址与chainID相同;数据库任务域还含dataset。
钱包增加本地RPC http://127.0.0.1:8545、链ID31337。仅导入 contracts/scripts/local.mjs 中公开Anvil测试key对应账户1和2;账户0专供relayer。这三个key属于公开fixture,不可用于公共链真实资产。两个测试钱包各有10MockWETH与100000MockUSDT,部署脚本已授权合约;页面授权按钮可重新授权。用不同钱包卖2WETH@100、买3WETH@105:先见pending2,再见filled2,实际支付200USDT;剩余1WETH买单可链上撤销。
Windows双击 run-web3-windows.cmd。脚本在 bin/windows-web3 安装独立平台依赖并构建页面,避免使用WSL的node_modules;原 run-windows.cmd 的pinkode管理员与data-windows保持独立。新脚本本轮未在Windows原生环境实测。
连接真实开发中间件#
先设置开发数据库密码,再启动指定compose的三个服务(不会创建应用容器)。开发端口均向回环绑定。
export WEB3_DB_PASSWORD='local-web3-password' docker compose -f deploy/web3-compose.yaml up -d redis postgres rabbitmq export WEB3_REDIS_URL='redis://127.0.0.1:16379' export WEB3_POSTGRES_DSN='postgres://exchange:local-web3-password@127.0.0.1:15432/exchange?sslmode=disable' export WEB3_RABBITMQ_URL='127.0.0.1:5672' npm --prefix contracts run dev |
这里密码仅演示;云部署必须另设。第一次库可为空;第二次本地dev重建Anvil与dataset时,创建新的PG数据库并改DSN,保留原库作恢复证据,不能删任务表来绕过域检查。未配置中间件时显式本地模式用独立SQLite任务、直接outbox分发、无Redis共享限流;配置了但故障会拒绝启动。
改代码的顺序#
- 修改业务约束时先列出四项数量守恒、重试/取消/未知广播影响,更新设计和用例。
- 合约改动先跑compile/test;修改签名字段时Go TypedData、Solidity TYPEHASH、前端和契约一起更新,换新合约及数据域。
- Engine只接收确定命令;新RPC/SQL/密码学放外围。修改Apply后对重放和兼容做判断,不隐式解释旧日志。
- API先改
api/web3-openapi.json,执行npm --prefix frontend run web3:generate,不要手改生成TS。补真实响应校验。 - 运行
bash scripts/test.sh web3,再常规verify和真实中间件用例,按最终证据更新文档。
阅读路径:types→engine→store→tasks/middleware→chain→index/history/reconcile/observability→http→cmd/web3server→Web3App/Web3History→Settlement。新函数和关键字段均需中文注释,解释单位、所有者、恢复及错误边界;测试注释说明证明点,脚本注释说明资源隔离与清理。
配置#
| 环境变量 | 默认/含义 |
|---|---|
| WEB3_CONFIG | bin/web3-dev/config.json:公开链域,必须与合约getter一致 |
| WEB3_DATA_DIR | data-web3:不可复用模拟目录 |
| WEB3_RPC_URL | http://127.0.0.1:8545 |
| WEB3_RELAYER_KEY | 必填,与config relayer相符,只来自受限环境 |
| WEB3_LISTEN_ADDR / WEB3_ALLOWED_ORIGIN | 127.0.0.1:8081 / 对应http Origin |
| WEB3_FRONTEND_DIR | frontend/dist |
| WEB3_DIAGNOSTICS_ADDR | 空关闭;仅允许数值回环,例如127.0.0.1:9091 |
| WEB3_POSTGRES_DSN | 空为显式SQLite任务;非空PG权威 |
| WEB3_REDIS_URL | 空关闭Redis;非空缓存与共享限流 |
| WEB3_RABBITMQ_URL / WEB3_RABBITMQ_QUEUE | AMQP URL;空为显式本地直连;默认队列前缀 exchange-settlements,追加 dataset |
配置confirmations在JSON中为1–128,默认fixture2;修改域或确认策略拒绝复用日志。固定inflight/历史/响应预算见架构;没有声称自动调参或全市场扩容。
v0.5 历史、对账和升级#
钱包页面底部“交易记录”支持四种类型、25条翻页、当前钱包筛选和任务详情。trades 只列 CONFIRMED 意图,刷新首屏才能收录刚确认的旧意图;翻页过程对象状态仍可能变化。
export WEB3_DIAGNOSTICS_ADDR=127.0.0.1:9091 npm --prefix contracts run dev # 另一个终端: curl http://127.0.0.1:9091/check curl http://127.0.0.1:9091/metrics curl 'http://127.0.0.1:8081/api/web3/history/orders?limit=25' |
已有同域 v0.4 数据升级前停机备份,不删库。任务 schema 2 事务迁移并赋 version=0,不改旧 raw/hash/nonce;历史没有记录的时间仍为0。chain-views 补索引表,从创世开始补拉已确认块,索引未追平先显示 lag。日志 schema 与 Domain JSON 不变,确认策略/合约变更仍须新域方案。新结构运行后回退旧二进制会遗漏版本维护,禁止直接回退;恢复停机备份并先人工核对已广播交易。
独立读池:日志/投影的 WAL 读取与唯一写连接分开,每读池1连接;SQLite读池query_only,PG任务Reader独立1连接,owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令,避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本,需要超时和后续增量策略。