# 配置文件

DiAL 通过 YAML 配置文件定义运行参数和拨测目标。完整可运行示例参见 [`../../probes.example.yaml`](../../probes.example.yaml)。配置 JSON Schema 位于 [`../../probe-config.schema.json`](../../probe-config.schema.json)。

## 配置结构

```yaml
# yaml-language-server: $schema=./probe-config.schema.json

server:
  listen:
    host: "127.0.0.1"
    port: "${server_port}"
  storage:
    dataDir: "/tmp/probes_data"
    retention: "${retention}"
  logging:
    level: "${log_level|info}"
    file:
      path: "<dataDir>/logs/dial.log"

probes:
  execution:
    maxConcurrentChecks: "${max_checks}"

variables:
  server_port: 3000
  retention: "7d"
  max_checks: 20
  default_interval: "30s"
  default_timeout: "10s"

targets:
  - id: "baidu-home"
    name: "Baidu"
    type: http
    interval: "${default_interval}"
    timeout: "${default_timeout}"
    http:
      url: "https://www.baidu.com"
    expect:
      status: [200]
```

## server.listen

| 字段   | 说明     | 必填 | 默认值      |
| ------ | -------- | ---- | ----------- |
| `host` | 监听地址 | 否   | `127.0.0.1` |
| `port` | 监听端口 | 否   | `3000`      |

## server.storage

| 字段        | 说明                                                 | 必填 | 默认值   |
| ----------- | ---------------------------------------------------- | ---- | -------- |
| `dataDir`   | 数据目录，相对路径基于配置文件所在目录解析           | 否   | `./data` |
| `retention` | 历史数据保留时长，支持 `ms`、`s`、`m`、`h`、`d` 单位 | 否   | `7d`     |

## probes.execution

| 字段                  | 说明           | 必填 | 默认值 |
| --------------------- | -------------- | ---- | ------ |
| `maxConcurrentChecks` | 最大并发拨测数 | 否   | `20`   |

## server.logging

| 字段                                     | 说明                                           | 必填 | 默认值                    |
| ---------------------------------------- | ---------------------------------------------- | ---- | ------------------------- |
| `server.logging.level`                   | 全局日志等级，console 和 file 未指定时继承此值 | 否   | `info`                    |
| `server.logging.console.level`           | 控制台日志等级                                 | 否   | 继承 `level`              |
| `server.logging.file.level`              | 文件日志等级                                   | 否   | 继承 `level`              |
| `server.logging.file.path`               | 日志文件路径，相对路径基于配置文件目录解析     | 否   | `<dataDir>/logs/dial.log` |
| `server.logging.file.rotation.size`      | 按大小滚动，支持 `KB`、`MB`、`GB` 单位         | 否   | `50MB`                    |
| `server.logging.file.rotation.frequency` | 按时间滚动：`hourly`、`daily`、`weekly`        | 否   | `daily`                   |
| `server.logging.file.rotation.maxFiles`  | 保留的归档文件数量，不含活跃日志               | 否   | `14`                      |

日志等级支持：`trace`、`debug`、`info`、`warn`、`error`、`fatal`。

控制台始终输出 pretty 格式，文件始终输出 JSONL 格式并支持滚动。`rotation.size` 和 `rotation.frequency` 任一条件触发即滚动。

## 内置默认值

| 字段       | 默认值 | 约束                    |
| ---------- | ------ | ----------------------- |
| `interval` | `30s`  | 最小 `10s`              |
| `timeout`  | `10s`  | 必须小于等于 `interval` |

各 checker 专属默认值见 [Checker 参考](checkers/README.md)。

## variables

`variables` 是顶层动态键值表，key 必须符合 `[a-zA-Z_][a-zA-Z0-9_]*`，value 仅支持 string、number、boolean。`server`、`probes` 和 `targets` 中的字符串值可引用变量。

| 语法              | 说明                                       |
| ----------------- | ------------------------------------------ |
| `${key}`          | 引用 variables 或环境变量                  |
| `${key\|default}` | variables 和环境变量都不存在时使用默认值   |
| `${key\|}`        | variables 和环境变量都不存在时使用空字符串 |
| `$${key}`         | 转义输出字面量 `${key}`                    |

解析优先级为 `variables -> process.env -> 默认值`。三者均不存在时配置校验失败。字段值完整等于单个变量引用时会保留 number、boolean、string 类型；部分拼接时统一转为字符串。

变量替换作用于 `server`、`probes` 和 `targets`，不作用于 `variables` 段自身，且不会替换 `targets[].id` 和 `targets[].type` 字段；对象 key 不参与替换。

## 配置加载形态

配置加载内部区分三层形态：

| 形态              | 说明                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------- |
| Authoring Config  | 用户 YAML 可书写形态，允许变量引用和 expect 简写                                      |
| Normalized Config | `normalizeAuthoringConfig()` 完成变量替换、expect 简写展开并移除 `variables` 后的形态 |
| ResolvedConfig    | checker `resolve()` 补默认值并解析 duration、size、路径和运行期环境后的形态           |

根目录 `probe-config.schema.json` 面向 Authoring Config，因此 VSCode 校验会接受 `server.listen.port: "${server_port|3000}"`、`http.maxRedirects: "${MAX|5}"` 和 `expect.durationMs: 5000` 这类写法。

## targets 通用字段

| 字段          | 说明                                                                                 | 必填 | 默认值    |
| ------------- | ------------------------------------------------------------------------------------ | ---- | --------- |
| `id`          | 目标唯一标识，最长 30 字符，支持字母数字、下划线、连字符，不参与变量替换             | 是   | 无        |
| `name`        | 展示名称，最长 30 字符，支持变量替换，可省略或显式 null；前端展示时 null 回退到 `id` | 否   | 无        |
| `description` | 目标描述，最长 500 字符，支持变量替换，可省略或显式 null，允许空字符串               | 否   | 无        |
| `type`        | 目标类型：`http`、`cmd`、`db`、`tcp`、`udp`、`dns`、`icmp`、`llm`、`ws`              | 是   | 无        |
| `group`       | 分组名称                                                                             | 否   | `default` |
| `interval`    | 拨测间隔，最小 `10s`                                                                 | 否   | `30s`     |
| `timeout`     | 超时时间，必须小于等于 `interval`                                                    | 否   | `10s`     |

## Checker 专属配置

每个 target 必须根据 `type` 配置对应的 checker 专属字段。详情见 [Checker 参考](checkers/README.md)。

## 校验规则

`expect` 字段按 checker 类型不同而变化。通用断言模型见 [校验规则](expectations.md)。