docs: 重构文档体系

docs/user/troubleshooting.md

@@ -0,0 +1,73 @@
+# 故障排查
+
+本文档记录常见运行问题和排查入口。
+
+## 配置校验失败
+
+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 风险检测。被拒绝时应改写为更明确、回溯风险更低的表达式。