> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trylaunchkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 自带（BYO）沙箱 Runtime 的常见问题：现象、原因与解决方法

请先在 worker 主机执行其自带的诊断命令：

```bash theme={null}
launchkit-worker doctor
```

## 桥接模式

| 现象                                                              | 可能原因                                                                         | 解决方法                                                                                  |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `doctor` 云端连通性检查失败                                              | worker 主机到 `https://api.trylaunchkit.ai` 的出站流量被阻断，或 `LAUNCHKIT_API_URL` 配置有误 | 允许 worker 主机对外访问 HTTPS；检查 URL 拼写无误且协议为 `https://`                                     |
| `doctor` 报告密钥无效或未授权                                             | 密钥已吊销，或 `LAUNCHKIT_RUNTIME_ID` 与密钥对应的 runtime 不匹配                            | 对照 LaunchKit 对接人提供的两个值逐一核对；该密钥仅对其所属 runtime 有效                                        |
| 守护进程立即退出，且 systemd 不会重启                                         | **HTTP 426**：worker 版本低于该 runtime 的版本下限                                      | 安装 LaunchKit 对接人提供的新 wheel，然后执行 `systemctl restart launchkit-worker`                  |
| `doctor` 报时钟偏差警告或失败                                             | 主机时钟漂移超过 30 秒（警告）或 300 秒（失败）                                                 | 修复 worker 主机的 NTP 同步                                                                  |
| `doctor` 沙箱平台连通性检查失败                                            | `E2B_DOMAIN`/`E2B_API_URL` 配置错误、沙箱平台不可用，或私有 CA 导致的 TLS 失败                    | 检查沙箱平台变量；若使用私有 CA，请设置 `SSL_CERT_FILE`（见[兼容性](/zh/runtimes/compatibility)）             |
| `doctor --probe` 暂停检查失败                                         | 沙箱平台不支持 pause-with-disk-parity（CubeSandbox 低于 v0.5.0）                        | 升级沙箱平台后重新执行探测                                                                         |
| `doctor --probe` 快照检查失败，或 runtime 显示 `snapshot probe failed` 错误 | 沙箱平台不支持快照/派生（CubeSandbox 低于 v0.5.1），或 worker wheel 低于 0.5.0                  | 将沙箱平台升级到 >= v0.5.1、worker wheel 升级到 >= 0.5.0，重新执行 `doctor --probe`，然后请对接人重新探测 runtime |
| LaunchKit 中 runtime 显示 worker 离线                                | 守护进程未运行，或出站流量中断                                                              | 在 worker 主机执行 `systemctl status launchkit-worker` 和 `journalctl -u launchkit-worker`  |
| 主机故障转移后操作被报告为不确定                                                | 新主机缺少重投递操作的结果日志（此为安全行为，并非缺陷）                                                 | 故障转移后预期出现一次，属正常情况；将结果日志保存在持久化存储上，同主机重启时可干净恢复                                          |

## 直连模式

| 现象                             | 可能原因                          | 解决方法                                                      |
| ------------------------------ | ----------------------------- | --------------------------------------------------------- |
| runtime 卡在 `needs_credentials` | 尚未录入 API 密钥                   | 将密钥交给 LaunchKit 对接人，由对方录入                                 |
| 运行一段时间后变为 `error`              | LaunchKit 云无法访问沙箱平台，或平台侧轮换过密钥 | 检查沙箱平台可用性与 IP 白名单；若密钥已变更，请重新录入并重新执行探测                     |
| CubeSandbox 探测报认证错误            | 密钥校验已启用，但密钥并非 E2B 格式          | 请对接人在 runtime 上关闭密钥校验（见[兼容性](/zh/runtimes/compatibility)） |

## 仍未解决

请将 `doctor` 的完整输出发送给 LaunchKit 对接人；如涉及守护进程问题，请一并附上 `journalctl -u launchkit-worker` 的末尾日志。两者均不包含你沙箱平台的 API 密钥。