当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。
v0.4新增独立链模式:云/容器/备份恢复手册,架构,本轮报告。本页原命令维护模拟系统,exchangectl不能用于链任务数据库。
更新:2026-10-11,适用 v0.3.0。单实例、单核心、模拟 ETH/USDT;云主机直接运行与 Docker 容器使用同版本后端/离线工具/前端。历史发布/容器/性能证据见v0.3 报告;当前源码的所有权修复与回归见测试完善报告。已有 v0.3 发布包与 verified 镜像属于修复前产物,尚未重新发布,不能直接当作当前源码。云实机需要用户提供服务器;本轮不声称已经上线。
1. 构建与发布产物#
需要 Go 1.26.9、Node 22、npm 与 Linux 构建环境。go.mod 固定最低补丁版本,Docker/CI 同步;SQLite 为 CGo-free,可静态构建。先安装锁定依赖,再检查/打包:
npm --prefix frontend ci go mod download bash scripts/verify.sh bash scripts/release.sh |
发布包 bin/releases/exchange-v0.3.0.tar.gz 包含 exchange、exchangectl、frontend/、deploy/、SHA256SUMS、build-info.json。后端二进制嵌入 OpenAPI;前端来自同版契约,不能混装。release 脚本拒绝覆盖既有目录,且当前不支持 --output 或输出目录环境覆盖;已有同版本目录时需在不携带旧 bin/releases 的独立源码副本中构建,保留旧产物与摘要供审阅。build-info 记录真实工具链/依赖、engine/schema/契约摘要,没有 Git 时 commit 为 null。远程 CI 文件已提供,但需把项目推送仓库才会运行。
当前架构不要求生成 Go 路由或拆成多服务;字段契约通过生成 TS 和真实响应验证。FULL 固定,不能用“性能开关”关闭同步耐久。
2. 配置与资源#
实际示例:exchange.env.example ↗、systemd ↗、Compose ↗、Caddy ↗。密码只放权限 0600 的环境文件,不复制测试管理员密码。
| 配置 | 默认/说明 |
|---|---|
| EXCHANGE_LISTEN_ADDR | 127.0.0.1:8080;容器 0.0.0.0:8080 |
| EXCHANGE_DATA_DIR | data;主机 /var/lib/exchange,容器 /data |
| EXCHANGE_FRONTEND_DIR | frontend/dist;发布包主机 frontend,容器 /app/frontend |
| EXCHANGE_ALLOWED_ORIGIN | 单个准确 Origin,如 https://trade.example.com;不得与访问地址混用 localhost/127.0.0.1 |
| EXCHANGE_COOKIE_SECURE | 默认 false;HTTPS 必须 true |
| EXCHANGE_ADMIN_EMAIL / PASSWORD | 首次初始化 ADMIN;无默认账号密码,重启不改已有密码,不提升 USER |
| EXCHANGE_LOCAL_ADMIN_NAME | 默认空;仅 Windows/明确回环本地模式启用账号别名与 8–72 字节初始化,云/容器不配置 |
| EXCHANGE_DIAGNOSTICS_ADDR | 空则关闭;非空必须 loopback IP,如 127.0.0.1:9090 |
| EXCHANGE_QUEUE_CAPACITY | 默认 1024,1–65536 |
| EXCHANGE_INFLIGHT_CAPACITY | 默认 2048,1–131072,直到投影提交才释放 |
| EXCHANGE_JOURNAL_BATCH_SIZE | 默认 64,1–4096,日志/投影最大批大小 |
| EXCHANGE_JOURNAL_BATCH_WAIT | 默认 1ms,0–1s,只用于日志聚批 |
| EXCHANGE_SHUTDOWN_TIMEOUT | 默认 60s,1s–5min,小于进程管理器强杀窗口 |
| EXCHANGE_HEALTH_URL | health 子命令目标,默认 http://127.0.0.1:8080/health/ready |
起步机器建议 Ubuntu 24.04、本地 SSD、2 vCPU/4GiB;这只是部署预算,不能由配置推算 TPS。实测工作区为 WSL,性能数据使用 Linux /tmp。SQLite 不放 NFS/共享对象存储,不能两个实例共享 /data;flock 是本机进程锁,不是跨主机 fencing。
3. 云服务器直接运行#
部署目录:发布 /opt/exchange/releases/v0.3.0,current 指向当前版本,环境 /etc/exchange/exchange.env,数据 /var/lib/exchange,备份 /var/backups/exchange。专用 exchange 用户无登录权限、非 root 运行。
以下命令在目标服务器由运维执行,域名和路径使用自己的实际值:
sudo useradd --system --home /var/lib/exchange --shell /usr/sbin/nologin exchange sudo install -d -o exchange -g exchange -m 0700 /var/lib/exchange /var/backups/exchange sudo install -d -m 0755 /opt/exchange/releases /etc/exchange # 将已校验发布目录复制到 /opt/exchange/releases/v0.3.0,再在该目录执行: sha256sum -c SHA256SUMS sudo ln -s /opt/exchange/releases/v0.3.0 /opt/exchange/current sudo install -m 0600 deploy/exchange.env.example /etc/exchange/exchange.env # 修改邮箱/密码/准确 Origin/路径。不要直接采用示例密码。 sudoedit /etc/exchange/exchange.env sudo install -m 0644 deploy/exchange.service /etc/systemd/system/exchange.service sudo systemctl daemon-reload sudo systemctl enable --now exchange curl --fail http://127.0.0.1:8080/health/ready sudo journalctl -u exchange -n 100 --no-pager |
环境中的 EXCHANGE_FRONTEND_DIR=/opt/exchange/current/frontend。只公开 443/必要的 80,SSH 仅运维来源;8080/9090 不公开。配置 Caddy 自动 TLS、准确 Origin 和 Secure Cookie,执行 caddy validate --config <实际配置> 后启用。需要 DNS/云安全组/实际证书可用条件;本轮没有这些外部资源,未执行。
无域名时可用 ssh -L 8080:127.0.0.1:8080 deploy@<server-address>;本地 HTTP 演示明确 CookieSecure=false 与对应 Origin,不能套用 HTTPS Cookie 配置。
4. 容器部署#
标准多阶段构建复制 api/backend/cmd,生成后端与运维工具、前端,运行层为 Debian bookworm-slim;离线 Dockerfile.runtime 使用 scratch。两者均以 UID/GID 10001 非 root 运行。运行目录 /data 持久卷;rootfs 只读,/tmp tmpfs。首个卷初始化由镜像目录 ownership 保证可写,bind mount 需要自行设置 10001 所有权。
# 真实管理员密码从安全环境提供。 export EXCHANGE_ADMIN_EMAIL='admin@example.com' read -rsp '管理员密码: ' EXCHANGE_ADMIN_PASSWORD export EXCHANGE_ADMIN_PASSWORD export EXCHANGE_ALLOWED_ORIGIN='http://127.0.0.1:8080' docker compose -f deploy/compose.yaml config --quiet docker compose -f deploy/compose.yaml up -d --build docker compose -f deploy/compose.yaml logs --tail=100 exchange |
在线构建仍取决于主机镜像源/Go/npm 网络。本环境用户配置的镜像源 DNS 失败,未擅改 Docker daemon;可用已验证本地产物构建运行镜像:
npm --prefix frontend run build CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server CGO_ENABLED=0 go build -trimpath -o bin/exchangectl ./cmd/exchangectl docker build -f Dockerfile.runtime -t exchange-demo:local . docker compose -f deploy/compose.yaml up -d --no-build |
scratch 镜像没有 shell/curl,HEALTHCHECK 使用 /app/exchange health。当前 diagnostics 在容器回环 9090,不映射公网;容器回环与宿主回环不同,宿主 curl 127.0.0.1:9090 不会自动进入容器。可用宿主受控工具通过 nsenter -t <容器PID> -n 采样,或已核验工具容器共享其网络命名空间;scratch 内不能 docker exec ... curl/sh。pprof 需受控诊断工具/方式,不为方便排错安装整套工具到生产镜像。docker logs 读取 JSON slog,Compose 限制日志大小、资源和停止宽限。Docker unhealthy 标记本身不会自动重启;致命运行时故障由应用监督退出。
升级保持原 volume 名称,禁止 down -v,不把 replicas 扩大为多个写者。镜像标签固定版本,生产可另外锁已验证 digest。当前在线 Go/Node 构建镜像使用补丁标签,Debian 运行层使用 bookworm-slim 系列标签,尚未在该网络环境验证/锁定 digest,不能把离线 runtime 构建成绩当成完整在线构建成绩。
5. 离线管理工具#
服务停机后使用同版 exchangectl;工具与服务共享 flock,服务运行时拒绝 check/backup/rebuild。例子中的备份目标和恢复目标必须不存在,不能覆盖旧数据。
# 新目录初始化;密码只来自 EXCHANGE_ADMIN_PASSWORD,不放参数。 ./exchangectl init-admin --data /var/lib/exchange --email admin@example.com # check 会补齐正常崩溃的落后投影,并与独立重放逐表对账。 ./exchangectl check --data /var/lib/exchange ./exchangectl backup --data /var/lib/exchange --backup /var/backups/exchange/20261011 # 恢复到新目录,原目录始终保留。 ./exchangectl restore --backup /var/backups/exchange/20261011 --data /var/lib/exchange-restored # 只重建可派生投影,保留原坏 views/WAL/SHM 到 views-preserved-时间戳。 ./exchangectl rebuild-views --data /var/lib/exchange |
systemd 路径需要 sudo -u exchange;初始化管理员时通过受控方式传入所需密码变量。systemd 的 EnvironmentFile 由管理器解析,不要直接 source 未经审阅的环境文件执行 shell 内容。check/backup/rebuild 均包含全历史重放和临时数据库,不是只读轻量命令,应预算停机时间、/tmp 空间和数据盘 staging 空间。backup 先校验/补投影、checkpoint 三库,再复制、fsync 并写 manifest;权限 0700/0600。manifest 含 dataset、engine、水位/数量/逐表摘要与数据库 SHA256。restore 先验证字节摘要/白名单,再拷贝/重放对账;不是防攻击签名,也不是在线备份。
auth.db 是权威身份/会话,不可按投影方式删除。journal.db 是权威输入,不能从 views 反推。checkpoint 不删应用 commands 历史。直接复制运行中的 .db 会遗漏 WAL,禁止这样做;云磁盘丢失仍依赖异机备份,RPO 是最近成功备份,不因 FULL 变为硬件故障 RPO=0。
容器停机维护示例:
docker compose -f deploy/compose.yaml stop exchange # Compose run 覆盖 entrypoint,只启动离线工具,挂载相同卷。 docker compose -f deploy/compose.yaml run --rm --no-deps --entrypoint /app/exchangectl exchange check --data /data docker compose -f deploy/compose.yaml run --rm --no-deps --entrypoint /app/exchangectl exchange backup --data /data --backup /data/backup-20261011 # 将备份复制到受限异机位置;卷内备份无法抵御整个磁盘损坏。 docker compose -f deploy/compose.yaml start exchange |
6. 升级、退出与回滚#
v0.3 前后端同版:users/audit 从数组改页对象,orders 仍 v0.2 页协议;旧库增加可重建审计/迁移标记,新日志 schema=1,旧 schema=0 可重放,engine_version=1 保持业务语义。升级前停唯一实例、完整备份、保留旧发布包;新程序对旧卷验证后才切换入口。
SIGTERM 主动关闭 WS、停止业务受理并排空,再等待 HTTP;投影整批成功才释放额度,最后关 DB/解锁。超时失败会记录并返回非零,已提交日志重启补齐。冷启动先完成恢复再监听 HTTP,因此准备期间通常连接拒绝;不能假称总有 ready=503 可查询。
回滚不能同时开新旧写者;先停止新接入保存最新日志。仅兼容界面/二进制时可切旧发布;恢复升级前备份可能抹掉备份后的已确认命令,必须先对账制定恢复方案。不要为“修好启动”删 journal/auth 或跳过不兼容记录。
7. 观测与部署验收#
独立诊断端口 /metrics 包括阶段累计/最大耗时、已提交/执行/投影水位、队列/在途、活动订单/保留订单/幂等数、堆/GC/goroutine。max 不是 p99;业务数据集序号只在同 dataset 比较。pprof 使用标准库,默认不公开。日志为外围 JSON slog,不输出密码/会话 token/完整 payload。
每次部署验证:ready 成功 → 注册/登录 → 双账户成交/撤单 → 管理操作 → 原键确认 → 关闭/重启会话和余额保留 → 停机备份恢复到新目录 → 独占锁拒绝第二写者。查看磁盘空间/历史增长、投影 lag、容量拒绝、堆内存;本版没有日志截断/去重 TTL/自动扩容。
可重复本地/容器验证:python3 scripts/e2e_check.py、python3 scripts/container_check.py;会启动本任务独立环境。容器脚本只保留自己的已停止容器/命名卷,并生成实际资源名称和证据。云端同样执行该验收顺序,服务器未提供时不能声明云实机通过。
8. 手册配套与证据保存#
离线步骤的文件边界与中断处理见数据生命周期,ready/401/403/未知结果/投影滞后排查见故障排查手册。服务器资源、DNS/TLS、镜像在线构建、真实断电、远程 CI 均按实际环境验收,文档示例不等于已经执行。
scripts/container_check.py 会构建固定的 verified 标签,并将结果写入既有 evidence-v0.3/container.json;重跑前先把旧证据与镜像摘要存到独立路径,避免覆盖历史结论。本次只审阅脚本注释与配置,未重跑容器、重新打包或部署。
Windows 本机启动路径#
双击项目根目录 run-windows.cmd,脚本在 bin/windows 构建原生 exe 与独立 Windows 前端依赖,data-windows 保留数据。本地管理员模式明确限制数值回环,不在本节云/systemd/Compose 配置启用。常规部署密码下限 12 字节仍保留。见Windows 指南与实际验证。
v0.5 链容器与云观测#
链模式采用独立镜像 exchange-web3:v0.5-local 和独立数据卷。升级前停机备份日志/投影/任务共同水位;SQLite/PG 任务显式迁移。Linux host 网络 Prometheus 可采集 127.0.0.1:9091,配置见 deploy/web3-prometheus.yml 和 web3-alerts.yml;不对外代理诊断端口。详细操作见链部署手册,云环境未实测。