# 链模式云服务器、容器与恢复

当前消息队列已切换 RabbitMQ。v0.6 的 Windows 原生服务、WSL 中间件与发售入口见[验收手册](../04-testing/sale-acceptance.md)。下方 app 镜像为二级交易服务，未包含独立 saleserver；发售生产容器交付仍需单独设计。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

适用单链单relayer演示。原模拟部署见[部署手册](deployment.md)，其exchangectl只维护模拟三库，不能拿来清空/恢复chain任务。v0.5提供回环 /check 只读对账，不提供自动修复 CLI。公开测试网/云实例本轮未部署；下面是可审阅的运维方案，不是上线证明。

## Linux直接部署

在测试网预先部署相同版本Settlement与标准测试ERC20，核对chainID、token地址、18/6精度、relayer；JSON域格式见[开发配置](../03-development/web3-development.md)。只使用自有测试钱包，合约不能热换域。将测试Gas放relayer地址，使用受限环境文件保存key与DSN，不写进镜像、命令行参数或报告。

```bash
CGO_ENABLED=0 go build -trimpath -o bin/web3server ./cmd/web3server
npm --prefix frontend ci
npm --prefix frontend run build
```

上传同版二进制、frontend/dist和公开chain.json到 `/opt/exchange-web3`，建立专有用户和其可写 `/var/lib/exchange-web3`。环境文件权限0600，例如：

```text
WEB3_CONFIG=/opt/exchange-web3/chain.json
WEB3_DATA_DIR=/var/lib/exchange-web3
WEB3_FRONTEND_DIR=/opt/exchange-web3/frontend
WEB3_RPC_URL=https://YOUR_TESTNET_RPC
WEB3_LISTEN_ADDR=127.0.0.1:8081
WEB3_ALLOWED_ORIGIN=https://YOUR_DOMAIN
WEB3_DIAGNOSTICS_ADDR=127.0.0.1:9091
WEB3_RELAYER_KEY=YOUR_TEST_RELAYER_KEY
WEB3_POSTGRES_DSN=YOUR_RESTRICTED_PG_DSN
WEB3_REDIS_URL=YOUR_PRIVATE_REDIS_URL
WEB3_RABBITMQ_URL=amqps://USER:PASSWORD@YOUR_PRIVATE_RABBITMQ/VHOST
WEB3_RABBITMQ_QUEUE=exchange-settlements
```

占位文本必须替换；密码DSN需正确URL编码。受控TLS代理将准确公网Origin的请求转发到8081，防火墙只开放443/必要SSH。HTTP代码不信任X-Forwarded-For，代理模式所有请求可能按代理IP共享50/s窗口；上线前需设计可信代理身份策略，不能擅自打开任意头取IP。公开订单带钱包地址/签名，不公开模拟邮箱和私钥。

可使用 `deploy/web3.service`，按实际用户/路径安装systemd，再daemon-reload/start。先检查ready、合约配置、metrics、真实小额测试转移、取消和重启。RPC TLS、PG认证/权限、Redis/RabbitMQ私网ACL、备份异机保存均需在部署环境实施；compose开发单副本不替代生产集群。管理员key没有进入链交易授权；邮箱账户与钱包尚未绑定。

## Linux容器部署

运行镜像构建不下载基础层，scratch包含当前静态Go、页面与宿主公开CA根，UID10001。先构建：

```bash
bash scripts/build-web3-image.sh
export WEB3_DB_PASSWORD='replace-with-a-strong-secret'
export WEB3_CONFIG_FILE='/absolute/path/to/chain.json'
export WEB3_RPC_URL='https://YOUR_TESTNET_RPC'
read -rsp '测试relayer key: ' WEB3_RELAYER_KEY
export WEB3_RELAYER_KEY
export WEB3_ALLOWED_ORIGIN='https://YOUR_DOMAIN'
docker compose -f deploy/web3-compose.yaml config --quiet
docker compose -f deploy/web3-compose.yaml --profile app up -d
```

app 使用 Linux host network，连接宿主回环 16379/15432/5672。若改普通 bridge 网络，AMQP 主机应改为服务名 rabbitmq，PG/Redis 也需相应改址；RabbitMQ 没有 Kafka advertised.listeners 配置。本轮原生 Windows 与 WSL 中间件通过，Docker Desktop host 网络仍未验证。

PG/Redis/RabbitMQ配置可解析后启动，但depends_on不证明完全ready；app启动验证并在失败后由restart重试。初次PG空库由app建表，之后dataset绑定保持；旧PG卷不能和新chain数据卷随意组合。compose中inactive app用空key/默认路径，仅方便启动中间件，启用app前必须明确真实配置。health使用二进制 `health` 子命令，无需curl。命名卷存权威数据，read_only+tmpfs保存边界；停止宽限90s，日志建议由宿主管理轮转。

历史 v0.5 应用容器证据保留在原报告；v0.6 实际运行的是原生 Windows 应用与 WSL 的 PG/Redis/RabbitMQ 中间件容器，没有重新验证当前 app 镜像。在线 Dockerfile 多阶段构建与云镜像拉取另依赖网络，不沿用旧镜像摘要。

## 停机、备份、恢复与升级

先停接入和应用，保存日志/投影/任务、配置与二进制摘要；PG 一致性 dump 并记录 RabbitMQ 队列名、Ready/Unacked、outbox 与任务共同水位。RabbitMQ 没有 group/topic/offset 恢复协议。跨库备份必须协调停机；Redis 只重建本 dataset 的缓存键，不能清别的系统。

恢复到独立目录、恢复同域任务库，不覆盖原坏库。核对 raw/hash/nonce、最终块锚点、outbox 发布标记、RabbitMQ 待确认消息及 SQL inbox/任务和链上 settled/filled；不能只看本地 applied_seq 一致。只恢复 SQLite 日志但丢已发送 raw 交易可能错误分配新 nonce；任务数据库落后或消息丢失须停机人工对账，当前没有自动修复 CLI。重建 views 仅可在完整任务权威保存且停机时进行，不删除 tasks 或 journal。

升级签名域、合约、资产或schema需要新域迁移设计；v0.5提供同域旧任务schema 1→2兼容迁移、投影索引表初始化；不提供跨合约或签名域迁移。模拟恢复CLI对本模式不适用。旧链模式状态不兼容就拒绝启动，禁止删metadata绕过。测试网更换RPC可保留同链数据，但先验证历史receipt和块hash；Anvil每次重建历史必须用新业务目录和新PG数据库。

## 故障排查与观测

`/health/live`只表示HTTP存活，ready说明运行时及致命worker边界尚可；它不是Redis/RabbitMQ/链端到端延迟SLO。`WEB3_DIAGNOSTICS_ADDR`开启请求总/拒绝、请求耗时 histogram、索引高度与落后块数、未终结任务和最老年龄、outbox积压、对账差异/lag、采样失败及worker错误。pending包含已广播任务；详情查 `/api/web3/tasks/{id}`。直方图可估计请求p95/p99，不代表链最终性耗时。未提供Grafana dashboard。

RPC异常：保留任务，先按hash查receipt；不得改nonce重建转账。BROADCAST长期停留：核对Gas、nonce占用、授权、deadline和节点mempool；当前不自动提价替换。PG锁连接丢失：发送停下，确认旧进程死亡后再启动；会话锁不是自动主备。坏RabbitMQ消息：保存该消息/域与来源，人工隔离；不绕过验证。深重组或最终receipt丢失：服务保守停止，核对多个可信节点与历史，人工对账，不删除锚点继续跑。

## v0.5 回环监控与迁移操作

采样启动时执行一次，之后每30秒执行，失败时 sample_failed=1 并保留旧 gauge。/check 是一次全量只读检查：differences 表示稳定冲突，lag 表示异步分发/确认/索引/取消扫描尚未追平。它不查钱包储备，也不自动补发交易。采样可能因10秒预算不足失败；规模扩大时要独立对账角色和增量策略，不把失败指标忽略。

Linux host网络下可启动独立 Prometheus，避免普通 bridge 容器不能访问宿主回环：

```bash
docker run -d --name exchange-web3-prometheus --network host \
  -v "$PWD/deploy/web3-prometheus.yml:/etc/prometheus/prometheus.yml:ro" \
  -v "$PWD/deploy/web3-alerts.yml:/etc/prometheus/web3-alerts.yml:ro" \
  quay.io/prometheus/prometheus:v3.2.1 --config.file=/etc/prometheus/prometheus.yml \
  --web.listen-address=127.0.0.1:9090
```

版本固定便于复现，部署前仍须扫描镜像。打开回环9090查看规则；默认只评估告警，要实际通知需要另配置 Alertmanager 及收件渠道，本项目不自动给任何人发送消息。阈值为教学值：持续对账差异、最老任务>120秒、索引落后>64块、采样陈旧/失败、错误增量与outbox积压；公共链调整为实际 SLO。/check 不映射到公网。

升级需完整停机备份同域 SQLite/PG 任务库，再以 v0.5 启动。PG迁移在获取专用owner后进行，SQLite受应用目录锁保护。schema未知拒绝启动，旧时间不补造；索引可重建、任务raw不可重建。验收看历史分页、任务详情、/check追平与sample_failed=0；若失败保留新旧证据，不使用旧二进制直接写新任务库。

独立读池：日志/投影的 WAL 读取与唯一写连接分开，每读池1连接；SQLite读池query_only，PG任务Reader独立1连接，owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令，避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本，需要超时和后续增量策略。

告警配置校验：项目根执行 `docker run --rm --entrypoint /bin/promtool -v "$PWD/deploy:/etc/prometheus:ro" quay.io/prometheus/prometheus:v3.2.1 test rules /etc/prometheus/web3-alerts-test.yml`，预期 SUCCESS；配置另用 `check config /etc/prometheus/web3-prometheus.yml`。指标输出包含 HELP/TYPE，使用 `docker run --rm -i --entrypoint /bin/promtool quay.io/prometheus/prometheus:v3.2.1 check metrics < 保存的metrics.txt` 检查实际格式。规则评估测试不向外发送消息。
