DCTS/docs/troubleshooting.md

DCTS 故障排查与 FAQ (Troubleshooting & FAQs)

汇集 DCTS 计算过程中的常见故障、物理发散问题排查方法及节点恢复指南。

---

1. 物理计算发散排查 (TLUSTY Divergence)

现象 1：nl 阶段出现 DIVD ... BIG 或 NITER 达到上限发散

• 原因：初猜大气与当前网格点的真实 NLTE 大气物理状态相差过大，线性化半径无法收敛。
• 排查步骤：
  1. 查看节点运行目录中的 fort.6 或 conv.json：

     cat results/<model_name>/conv.json
     

  2. 检查 coldfail 现场保存：冷启动失败后，系统会自动保存过程数据到 <model>.coldfail/。
  3. 解决方案：确保 Master 的 results/ 目录下存有相近 T_{\text{eff}} / \log g 的已收敛 .7 大气文件。系统将在下次重试时自动触发 Seed-Stepping 种子步进算法。

现象 2：lte 阶段报错或瞬间终止

• 原因：输入的物理参数超出了灰色大气基本假设或基础原子数据（原子能级/光致电离截面）损坏缺失。
• 排查步骤：
  1. 验证 data/ 目录中的 ATO / ISO 数据文件是否齐全。
  2. 检查 gen_input5 生成的参数中 TEFF 是否小于 10000K 或大于 120000K。

---

2. 节点与网络故障 (Node & Network Issues)

现象 1：Worker 节点提示 Unauthorized: Invalid or missing authentication token

• 原因：Master 服务端启用了 API Auth Token，但 Worker 的配置文件或环境变量中未配置匹配的 auth_token。
• 解决办法：在 Worker 的 .env 中加入 DCTS_AUTH_TOKEN=<your_secret_token>。

现象 2：任务长时间处于 Running 状态没有进展

• 原因：Worker 节点在计算中途遭遇断电、内存溢出（OOM）或僵死进程卡死。
• 自动恢复：Master 服务端后台线程会在超过 DCTS_STALE_SEC（默认 30 分钟）后自动将该任务标记为 pending 重新放回队列。
• 手动恢复：若需立即重置挂起任务，可直接重启 server 或使用 SQL：

  UPDATE task_queue SET status='pending', assigned_node=NULL WHERE status='running';
  

现象 3：网络抖动或后端滚动重配下提示 向服务端上报任务 ... 结果失败

• 原因：在较长时效（如1-2小时）的运算完结回传一瞬间，Server 恰遇热更重启或遭遇防火墙短暂会话剔除。
• 容灾机制：Worker 内置了超强的 8 轮指数级自适应退避长跳上报防护（跨度可自 1s 到 60s 顺次延迟，支撑 2 分钟以上的长时断裂耐受窗口）；若由于连天硬件故障真正超出了总重试界限，亦可在本地非清理型数据栈（data/work/task_{uuid}）的目录直接调出本套算法终极收敛物并执行手工打标还原。

---

3. 日志与现场诊断

日志控制通过 RUST_LOG 环境变量配置：

# 查看服务端调试级别日志
RUST_LOG=info,server=debug ./target/release/server

# 查看节点端详细网络与子进程调用日志
RUST_LOG=info,node=debug,common=trace ./target/release/node