# 故障排查

本文档记录常见运行问题和排查入口。

## 配置校验失败

DiAL 启动时会校验 YAML 配置。除动态键值表（`headers`、`env`、`variables`）外，未知字段会导致启动失败。

排查顺序：

1. 在 YAML 顶部添加 `# yaml-language-server: $schema=./probe-config.schema.json`。
2. 对照 [配置文件](configuration.md) 检查顶层结构和通用字段。
3. 对照 [Checker 参考](checkers/README.md) 检查 checker 专属字段。
4. 对照 [校验规则](expectations.md) 检查 expect 写法。

## 变量无法解析

变量解析优先级为 `variables -> process.env -> 默认值`。如果三者均不存在，配置校验会失败。

常见修复：

| 问题           | 修复                                |
| -------------- | ----------------------------------- | --------- |
| 环境变量未设置 | 设置环境变量或在 `variables` 中声明 |
| 希望允许空值   | 使用 `${key                         | }`        |
| 希望提供默认值 | 使用 `${key                         | default}` |
| 希望输出字面量 | 使用 `$${key}`                      |

## ICMP checker 无法运行

ICMP checker 依赖系统 `ping` 命令。

| 环境                | 处理                                   |
| ------------------- | -------------------------------------- |
| Alpine 或精简镜像   | 安装 `iputils-ping`                    |
| Docker 容器         | 运行容器时增加 `--cap-add=NET_RAW`     |
| Windows/macOS/Linux | 确认系统 `ping` 可执行且输出格式受支持 |

Docker 示例：

```bash
docker run --rm --cap-add=NET_RAW -p 3000:3000 -v dial-data:/data/dial dial:alpine
```

## CMD checker 找不到命令

官方 Docker 镜像不内置 `bun`、`node`、`curl`、`dig`、`psql`、`mysql`、`redis-cli` 等额外命令。需要这些命令时请使用派生镜像安装。

```dockerfile
FROM dial:alpine

USER root
RUN apk add --no-cache curl bind-tools postgresql-client
USER dial
```

## Docker 数据或日志丢失

推荐将数据卷挂载到 `/data/dial`，并在配置中使用该目录作为 storage dataDir。

```bash
docker run --rm -p 3000:3000 -v dial-data:/data/dial dial:alpine
```

容器示例配置位于 [`../../docker/probes.yaml`](../../docker/probes.yaml)。

## HTTP 或 LLM 证书问题

HTTP 和 LLM checker 支持 `ignoreSSL`。该选项适合内网、自签名证书或测试环境；生产环境应优先修复证书链。

## 正则规则被拒绝

`regex` 启动期会执行 ReDoS 风险检测。被拒绝时应改写为更明确、回溯风险更低的表达式。