lanyuanxiaoyao
714b635aef
- 合并 DEVELOPMENT.md 至 docs/development/README.md - 合并 CONTRIBUTING.md 至 docs/development/checker.md - 合并 build-release.md 至 release.md - 合并 testing-quality.md 内容至各专题文档 - 合并 status-model.md 至 expectations.md - 新增 docs/user/README.md 用户入口 - 简化 docs/README.md 文档路由 - 各专题文档新增适用场景和更新触发条件 - 更新 openspec/config.yaml 文档规则
2.5 KiB
2.5 KiB
故障排查
本文档记录常见运行问题和排查入口。
配置校验失败
DiAL 启动时会校验 YAML 配置。除动态键值表（headers、env、variables）外，未知字段会导致启动失败。
排查顺序：
- 在 YAML 顶部添加
# yaml-language-server: $schema=./probe-config.schema.json。 - 对照 配置文件 检查顶层结构和通用字段。
- 对照 Checker 参考 检查 checker 专属字段。
- 对照 校验规则 检查 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 示例：
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 等额外命令。需要这些命令时请使用派生镜像安装。
FROM dial:alpine
USER root
RUN apk add --no-cache curl bind-tools postgresql-client
USER dial
Docker 数据或日志丢失
推荐将数据卷挂载到 /data/dial，并在配置中使用该目录作为 storage dataDir。
docker run --rm -p 3000:3000 -v dial-data:/data/dial dial:alpine
容器示例配置位于 ../../docker/probes.yaml。
HTTP 或 LLM 证书问题
HTTP 和 LLM checker 支持 ignoreSSL。该选项适合内网、自签名证书或测试环境；生产环境应优先修复证书链。
正则规则被拒绝
regex 启动期会执行 ReDoS 风险检测。被拒绝时应改写为更明确、回溯风险更低的表达式。