Web3 交易系统
部署与运维

故障排查与维护运行手册

v0.6 发售排查从 8082/health/ready、9092/check 和页面底部连接状态开始;先核对本轮 dataset、链上合约、索引水位,再查 SQL outbox/job 与 RabbitMQ Ready/Unacked/.dead。暂时 SQL 故障应保留消息,禁止 purge 队列或删资格“修好”。倒计时结束但未释放,先检查确认块时间与 RPC;深重组冻结须保留证据并人工核查。启动与逐项排查见发售验收。以下保留模拟/既有链模式运维背景。

当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。

既有链模式恢复规则:未知广播先查原 hash/receipt 并重发原 raw,不新分配 nonce;深重组或历史 receipt 丢失保守停服务。PG 锁断线不得换连接继续发送;当前 RabbitMQ 至少一次靠任务唯一 ID 去重;Redis 限流失败拒绝,缓存查询可回源。当前配置见链部署手册,验证见v0.6 测试。

更新:2026-10-11。适用于单实例 Linux/systemd 或 Docker 模拟交易环境。排查从业务现象开始,数据库维护前停止唯一实例;涉及真实数据时保留原目录、备份及错误输出。配置、命令安装位置见部署手册,未知结果规则见接口指南。

1. 先确认进程与版本#

主机:systemctl status exchange、journalctl -u exchange -n 100 --no-pager;容器:docker compose -f deploy/compose.yaml ps 与 logs --tail=100 exchange。核对实际二进制/前端、数据路径、准确 Origin、CookieSecure、卷名和发布包 SHA256SUMS。现有旧 v0.3 包/verified 镜像属于所有权修复前,不自动代表当前源码。

curl --fail http://127.0.0.1:8080/health/live
curl --fail http://127.0.0.1:8080/health/ready
# 仅开启独立诊断监听时,主机直接部署可执行:
curl --fail http://127.0.0.1:9090/metrics

live 只表示能响应,ready 还要求 runtime 能受理;不证明投影零延迟、磁盘空间充足或身份库完全健康。冷启动恢复完成前通常尚未监听,连接拒绝不一定是崩溃。致命 journal/核心/投影故障触发监督退出,检查完整错误而非只重复重启。

2. 按现象定位#

现象 优先证据 下一步
启动 already in use 进程列表、Compose 同卷容器、数据实际路径 停第二写者;锁文件存在不是持锁证明,不删除文件绕过 flock
启动格式/摘要/序号/版本失败 原 stderr、程序版本、journal 完整性 保留权威输入,用兼容程序/可信备份核查,不跳过记录
首次注册返回失败,再注册邮箱冲突 身份已提交但资金/会话尚未完成 用同账号登录补齐保留键资金,核查原键;不删 auth 重建
401、重新启用仍不能使用旧 Cookie expires_at、disabled 与停用审计 重新登录;24h 不滑动续期,启用不复活删除的会话
403 CSRF/Origin 登录响应、浏览器 Origin、代理配置 获取当前 CSRF,访问 host 与 AllowedOrigin 一致,HTTPS 配 Secure
429 认证限流 auth 请求频率、直连 IP/代理拓扑 稍后重试;当前不信任任意 X-Forwarded-For,代理可能共享 IP
下单失败/超时/断网后不确定 原 key/body、当前身份/dataset、按键查询与 min_seq 保留 pending,原键确认;查不到不表示未受理
201 后余额或订单没变 processed_seq 与 projection_seq 带 min_seq 重读;不要因旧余额再次下单
OVERLOADED、inflight 长期接近满 queue 深度、三水位、阶段 sum/count/max、磁盘 区分 journal 慢、核心工作量、投影争用,不先扩大队列掩盖瓶颈
PROJECTION_LAG 持续 journal/core/projection 三水位、当前 dataset、日志 先确认不是恢复旧备份后的旧 min_seq;再看投影故障与磁盘
WS 反复断开 公共 REST、连接数、浏览器网络、反向代理升级配置 200 连接预算、写超时 2s、重连退避;完整历史用 REST 分页
用户列表翻页不含新用户 当前 cursor 与首屏上界 回首屏;当前遍历固定成员上界,状态仍是各页当前值
内存/磁盘持续增长 retained orders/dedupe、commands/视图大小、恢复时长 预算历史;无 TTL/截断/快照,不能擅删去重或日志
check 对账失败 原投影、报告、权威日志完整性 保持停机并保留证据;确认权威完整后 rebuild-views,再 check

当前 credit 目标查询异常也映射 USER_NOT_FOUND,updateUser 存储/业务拒绝统一映射 USER_UPDATE_REJECTED;单凭这些 HTTP 码不能断言数据库一定健康,需结合服务日志和其他认证查询。手册不把统一映射推成不存在错误的精确诊断。

3. 指标怎样解读#

exchange_journal_seq/core_seq/projection_seq 独立原子采样,不是事务快照;lag 取非负值。持久化水位先进、核心不动可能是核心/结果背压,核心先进、投影不动可能是存储/查询争用。队列和在途也只反映抓取瞬间,不能从单个采样推定长期瓶颈。

stage 的 seconds_sum/count 可算该阶段平均耗时,max 为自启动以来最大值,均不是 p99。journal/projection 计时按批,core 按命令;阶段计时不含所有排队/网络等待。恢复时间启动时固定;进程重启计数重置。固定文本指标无高基数身份标签,不含 HTTP 延迟直方图或告警平台。

core 指标由唯一调用者发布规模副本,抓取不读取核心树/账户。分析 CPU/heap 可从独立 loopback pprof 获取,但只在受控环境采样;业务端 /metrics、/debug/ 返回 404。

4. 容器诊断#

scratch 镜像没有 shell/curl;docker exec <容器> /app/exchange health 是支持的健康检查。容器 127.0.0.1:9090 不等于宿主回环。Linux 宿主具备 nsenter/curl 时,可以只进入容器网络命名空间,仍使用宿主工具:

# 手工核对容器名;下方命令仅取本次运维容器的 PID。
exchange_diag_container='替换为实际服务容器名'
exchange_diag_pid=$(docker inspect --format '{{.State.Pid}}' "$exchange_diag_container")
sudo nsenter -t "$exchange_diag_pid" -n curl --fail http://127.0.0.1:9090/metrics

示例需替换容器名且容器正在运行;它不是本轮云实机执行证据。也可用经过核验的工具容器共享服务网络命名空间,不为调试把诊断端口绑定公网。Docker unhealthy 标记不自动重启;应用致命故障退出才触发既有重启策略。

5. 维护失败与资源预算#

check/backup/restore 都含全历史重放与临时库,rebuild-views 还在原数据盘建 staging。先检查磁盘空间、/tmp 容量、文件属主/权限和唯一服务状态。systemd 环境文件由管理器解析;不要直接 source 未审阅文件。CLI 失败返回非零,JSON 成功报告和 manifest 才作为完成证据。

备份/恢复目标不存在才继续;backup 中断目录不能当完成备份,restore 失败不要切换服务目录。rebuild 替换涉及多文件 rename,中断先保留 views-preserved 与仍存在的 staging,避免混配旧 WAL/SHM 和新主库。完整步骤及文件归属见数据生命周期。

SIGTERM 取消采样、关闭 WS、停止 runtime 受理并排空,再等待 HTTP/后台结束,最后关 DB;默认关闭 60s、Compose 强杀宽限 90s。关闭超时不等于未提交命令丢失,重启仍从日志恢复并确认原键。不要同时启动恢复程序和旧服务。

6. 保存可复查记录#

记录现象/时间、程序与契约版本、数据路径/dataset、三水位、资源配置、脱敏错误日志、复现步骤、维护 JSON/manifest 和所用备份。不得记录密码、Cookie、CSRF 或完整敏感 payload。没有 Git 时用独立源码 SHA256 与构建信息,不编造提交号。

测试与性能使用独立目录和输出路径;容器脚本固定 verified 标签与 container.json 会覆盖该位置,重跑先保留旧证据与镜像摘要。原始证据不因新注释而更新,最新验证口径见文档报告和测试手册。云实机、物理断电、完整弱网与长期容量仍需对应环境验证。

Windows 一键入口排障#

启动窗口保留构建/服务错误;缺依赖与端口冲突在初始化之前拒绝。默认 data-windows 独立于原 data,已有管理员仍不自动重置密码;别名只在 EXCHANGE_LOCAL_ADMIN_NAME 的回环模式有效。Windows npm 专属依赖在 bin/windows/frontend,Linux/WSL node_modules 不受影响。步骤见Windows 指南,不要为解决编译 exe 占用强杀其他服务。

v0.5 链故障操作#

先 GET 回环 /check,再按 difference 与 lag 定位日志/投影、任务终态和事件。/metrics 的 sample_failed=1 时原 gauge 是旧数据,不能宣告健康。深重组停止后保留全部库和块锚点,人工核查可信节点。迁移失败事务回滚,不删 metadata;不可将备份任务库与另一 dataset 的日志拼接。

— 本篇阅读完毕 —
来源:Web3 交易系统 / docs / 05-deployment/operations-runbook.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭