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

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

---

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

### 现象 1：`nl` 阶段出现 `DIVD ... BIG` 或 `NITER` 达到上限发散
- **原因**：初猜大气与当前网格点的真实 NLTE 大气物理状态相差过大，线性化半径无法收敛。
- **排查步骤**：
  1. 查看归档的 `conv.json`（节点端在 `DCTS_RESULT_DIR/<model_name>/conv.json`，服务端在 `DCTS_SEEDS_DIR/<model_name>/conv.json`）：
     ```bash
     cat data/seeds/<model_name>/conv.json
     ```
  2. 失败任务的各阶段输入/日志/收敛诊断（`<name>.<label>.5/.6/.err/.nst/.7`、`_chmax*.9`）经白名单归档到节点 `result_dir`，供排错；沙盒 `task_*` 在结算后清理。
  3. **解决方案**：确保服务端 `DCTS_SEEDS_DIR`（默认 `data/seeds`）下存有相近 $T_{\text{eff}}$ / $\log g$ 的已收敛 `.7` 种子。若 `tlusty_strategies` 含 `seed_step`，调度器会在失败回退时自动注入近邻种子重试（**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`
- **原因**：该节点的专属 node token 已失效或被重发覆盖（节点鉴权不依赖任何环境变量，而是使用审批时下发的专属 token）。
- **解决办法**：删除节点本地 `runtime/.node_token` 文件并重启节点进程，使其重新免凭据提交注册申请，等待管理员在 Dashboard 审批授权后获取新 token。

### 现象 2：任务长时间处于 `Running` 状态没有进展
- **原因**：Worker 节点在计算中途遭遇断电、内存溢出（OOM）或僵死进程卡死。
- **自动恢复**：Master 服务端后台线程会在超过 `DCTS_STALE_SEC`（默认 21600 秒 / 6 小时，约为单任务超时的 3 倍缓冲）后自动将 `claimed` 态任务重置为 `pending` 放回队列。
- **手动恢复**：若需立即重置挂起任务，最稳妥的方式是重启 `server`（启动恢复逻辑会处理卡死态）。若必须直接操作队列库，注意队列表的正确列名与状态：
  ```sql
  -- task_queue 表的状态列是 status，领用列是 claimed_by_node_id（非 assigned_node）；
  -- 领用中的任务是 status='claimed'（非 'running'）。
  UPDATE task_queue SET status='pending', claimed_by_node_id=NULL
   WHERE status='claimed';
  ```

### 现象 3：网络抖动或后端滚动重配下提示 `向服务端上报任务 ... 结果失败`
- **原因**：在较长时效（如1-2小时）的运算完结回传一瞬间，Server 恰遇热更重启或遭遇防火墙短暂会话剔除。
- **容灾机制**：Worker 内置了超强的 8 轮指数级自适应退避长跳上报防护（跨度可自 1s 到 60s 顺次延迟，支撑 2 分钟以上的长时断裂耐受窗口）；上报失败时产物仍会**尽力归档**到本地 `DCTS_RESULT_DIR/<model_name>/`（白名单保留科学产物），沙盒随后清理。若真正超出了总重试界限，可从 `result_dir/<model_name>/` 直接调出最终收敛物（`.7`/`.spec` 等）手工补录。

### 现象 4：Windows 节点重启后掉线（Docker Desktop 未自启）
- **原因**：Docker Desktop 是 GUI 程序，必须有所属用户的**交互桌面会话**才能启动引擎；重启后无人登录桌面时，即使配了 AutoStart 引擎也不会起来（节点小宝网络链路本身 Auto 自启，不受影响）。
- **解决办法**：经跳板 SSH 隧道转发 RDP 登录对应账户桌面，Docker 引擎随登录自启、`dcts-node` 容器靠 restart 策略自动恢复。完整拓扑、凭据、隧道命令与诊断速查见 **[remote_desktop_via_jump.md](remote_desktop_via_jump.md)**。

---

## 3. 日志与现场诊断

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

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

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