# 故障排查与维护运行手册

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

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

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


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

## 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 镜像属于所有权修复前，不自动代表当前源码。

```bash
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 时，可以只进入容器网络命名空间，仍使用宿主工具：

```bash
# 手工核对容器名；下方命令仅取本次运维容器的 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 和新主库。完整步骤及文件归属见[数据生命周期](data-lifecycle.md)。

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

## 6. 保存可复查记录

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

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


## Windows 一键入口排障

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

## v0.5 链故障操作

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