DiAL/README.md

# DiAL

<p align="center">
  <strong>轻量级多类型拨测监控工具</strong>
</p>

<p align="center">
  基于 Bun + TypeScript 构建 · YAML 配置驱动 · 内置 Dashboard
</p>

---

DiAL 是一个自托管的拨测监控工具，支持 **HTTP**、**命令行**、**数据库**、**TCP**、**UDP**、**Ping** 和 **LLM** 多种拨测类型。通过 YAML 配置文件定义拨测目标，后端定时并发执行拨测并将结果持久化到本地 SQLite，前端 Dashboard 展示各目标的实时状态、可用率和耗时趋势。

**功能亮点：**

- 多种拨测类型：HTTP（GET/POST/PUT 等）、Cmd（命令行执行）、DB（PostgreSQL/MySQL/SQLite）、TCP（端口可达性 + Banner 探测）、UDP（自定义 payload 请求-响应）、Ping（ICMP 存活、延迟、丢包率）、LLM（大模型服务应用层健康检查）
- 丰富的校验规则：状态码、响应头、JSONPath、CSS 选择器、XPath、正则匹配、数值比较等
- 响应式 Dashboard：实时状态、可用率统计、耗时趋势图、手动/自动刷新
- 多主题支持：系统、明亮、黑暗三种主题模式
- 零外部依赖：数据存储使用 SQLite，无需额外数据库服务

## 快速开始

**前置条件：** [Bun](https://bun.sh/) >= 1.0

Ping checker 依赖系统 `ping` 命令。精简容器镜像需额外安装，例如 Alpine 可安装 `iputils-ping`。

```bash
# 克隆仓库
git clone https://github.com/your-org/DiAL.git
cd DiAL

# 安装依赖
bun install

# 复制示例配置并按需修改
cp probes.example.yaml probes.yaml

# 启动开发服务器
bun run dev probes.yaml
```

`bun run dev` 会同时启动 Vite 开发服务器（`http://127.0.0.1:5173`）和 API 服务器（`http://127.0.0.1:3000`），访问前端地址即可使用 Dashboard。

## 生产部署

```bash
# 构建
bun run build

# 运行
./dist/dial-server ./probes.yaml
```

构建产物为独立可执行文件，只需一个 YAML 配置文件即可运行。

## 配置文件

程序通过 YAML 配置文件定义所有运行参数，完整示例参见 [`probes.example.yaml`](probes.example.yaml)。

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

server:
  host: "127.0.0.1"
  port: 3000
  dataDir: "/tmp/probes_data"

runtime:
  maxConcurrentChecks: 20
  retention: "7d"

variables:
  env_name: "生产"
  base_url: "https://api.example.com"
  api_token: "Bearer demo-token"
  sqlite_url: "sqlite:///path/to/db.sqlite"

defaults:
  interval: "30s"
  timeout: "10s"
  http:
    maxBodyBytes: "10MB"
  cmd:
    maxOutputBytes: "1MB"

targets:
  - id: "baidu-home"
    name: "Baidu"
    type: http
    http:
      url: "https://www.baidu.com"
    expect:
      status: [200]
      durationMs:
        lte: 10000

  - id: "json-api"
    name: "${env_name} JSON API 示例"
    type: http
    http:
      url: "${base_url}/json"
      headers:
        Authorization: "${api_token|Bearer fallback-token}"
    expect:
      status: [200]
      headers:
        Content-Type:
          contains: "application/json"
      body:
        - json:
            path: "$.slideshow.title"
            equals: "Sample Slide Show"

  - id: "bun-script"
    name: "Bun 脚本检查"
    type: cmd
    cmd:
      exec: "bun"
      args: ["-e", "console.log('ok')"]
    expect:
      exitCode: [0]
      stdout:
        - contains: "ok"

  - id: "sqlite-active-users"
    name: "SQLite 数据库检查"
    type: db
    db:
      url: "${sqlite_url}"
      query: "SELECT COUNT(*) as cnt FROM users WHERE status = 'active'"
    expect:
      durationMs:
        lte: 5000
      rowCount: { gte: 1 }
      rows:
        - cnt: { gte: 0 }

  - id: "redis-port"
    name: "Redis 端口可达"
    type: tcp
    tcp:
      host: "127.0.0.1"
      port: 6379
    expect:
      durationMs:
        lte: 3000

  - id: "udp-heartbeat"
    name: "UDP 心跳检测"
    type: udp
    udp:
      host: "127.0.0.1"
      port: 9000
      payload: "PING"
    expect:
      response:
        - contains: "PONG"
      durationMs:
        lte: 100

  - id: "gateway-ping"
    name: "网关 ICMP 可达"
    type: ping
    ping:
      host: "10.0.0.1"
      count: 3
      packetSize: 56
    expect:
      alive: true
      packetLossPercent:
        lte: 10
      avgLatencyMs:
        lte: 100
      maxLatencyMs:
        lte: 300
      durationMs:
        lte: 5000
```

### 配置说明

#### server — 服务配置（均可省略，使用默认值）

| 字段      | 说明                                       | 默认值      |
| --------- | ------------------------------------------ | ----------- |
| `host`    | 监听地址                                   | `127.0.0.1` |
| `port`    | 监听端口                                   | `3000`      |
| `dataDir` | 数据目录，相对路径基于配置文件所在目录解析 | `./data`    |

#### runtime — 运行时配置

| 字段                  | 说明                                             | 默认值 |
| --------------------- | ------------------------------------------------ | ------ |
| `maxConcurrentChecks` | 最大并发拨测数                                   | `20`   |
| `retention`           | 历史数据保留时长，支持 `ms`/`s`/`m`/`h`/`d` 单位 | `7d`   |

#### defaults — 全局默认值（均可省略）

| 字段                 | 说明                                               | 默认值  |
| -------------------- | -------------------------------------------------- | ------- |
| `interval`           | 拨测间隔                                           | `30s`   |
| `timeout`            | 超时时间                                           | `10s`   |
| `http.maxBodyBytes`  | 响应体最大字节数                                   | `100MB` |
| `http.headers`       | 默认请求头（target 中的 headers 会合并覆盖同名头） | —       |
| `cmd.maxOutputBytes` | 输出最大字节数                                     | `100MB` |
| `cmd.cwd`            | 默认工作目录（相对于配置文件所在目录）             | `.`     |

#### variables — 配置变量（可省略）

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

- `${key}`：引用 variables 或环境变量
- `${key|default}`：变量和环境变量都不存在时使用默认值，第一个 `|` 后的内容为默认值
- `$${key}`：转义输出字面量 `${key}`

解析优先级为 `variables -> process.env -> 默认值`。字段值完整等于单个变量引用时会保留 number/boolean/string 类型；部分拼接时统一转为字符串。变量替换仅作用于 `targets`，且不会替换 `id` 和 `type` 字段。

#### targets — 拨测目标列表（必填）

每个 target 的通用字段：

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

**HTTP 类型** (`type: http`)

| 字段                | 说明                                    |
| ------------------- | --------------------------------------- |
| `http.url`          | 目标 URL                                |
| `http.method`       | HTTP 方法（覆盖 defaults）              |
| `http.headers`      | 请求头（与 defaults.http.headers 合并） |
| `http.body`         | 请求体                                  |
| `http.ignoreSSL`    | 忽略 HTTPS 证书校验，默认 `false`       |
| `http.maxRedirects` | 最大重定向跟随次数，默认 `0`（不跟随）  |

**Cmd 类型** (`type: cmd`)

| 字段       | 说明                                   |
| ---------- | -------------------------------------- |
| `cmd.exec` | 可执行文件名或路径                     |
| `cmd.args` | 命令行参数列表                         |
| `cmd.env`  | 环境变量覆盖（继承进程环境变量并合并） |
| `cmd.cwd`  | 工作目录（相对于配置文件所在目录）     |

**DB 类型** (`type: db`)

| 字段       | 说明                                                          |
| ---------- | ------------------------------------------------------------- |
| `db.url`   | 数据库连接字符串，支持 `postgres://`、`mysql://`、`sqlite://` |
| `db.query` | SQL 查询语句（不配置时仅测试连接）                            |

**TCP 类型** (`type: tcp`)

| 字段                    | 说明                                                    |
| ----------------------- | ------------------------------------------------------- |
| `tcp.host`              | 目标主机地址                                            |
| `tcp.port`              | 目标端口（1-65535）                                     |
| `tcp.readBanner`        | 是否读取服务端 banner，默认 `false`                     |
| `tcp.bannerReadTimeout` | banner 读取超时（毫秒），默认 `2000`                    |
| `tcp.maxBannerBytes`    | banner 最大字节数，支持 `KB`/`MB`/`GB` 单位，默认 `4KB` |

**Ping 类型** (`type: ping`)

| 字段              | 说明                                |
| ----------------- | ----------------------------------- |
| `ping.host`       | 目标主机地址                        |
| `ping.count`      | ICMP 包数量，默认 `3`，范围 `1-100` |
| `ping.packetSize` | ICMP 包大小（bytes），默认 `56`     |

Ping checker 通过系统 `ping` 命令执行 ICMP 探测，支持 Linux、macOS 和 Windows 输出解析。

**LLM 类型** (`type: llm`)

| 字段                  | 说明                                                        |
| --------------------- | ----------------------------------------------------------- |
| `llm.provider`        | 模型提供方：`openai`、`openai-responses`、`anthropic`       |
| `llm.url`             | API base URL                                                |
| `llm.model`           | 模型名称                                                    |
| `llm.prompt`          | 单轮 prompt                                                 |
| `llm.mode`            | 调用模式：`http`（默认，非流式）或 `stream`（流式）         |
| `llm.key`             | API key（默认空字符串，支持 `${VAR}` 变量替换）             |
| `llm.authToken`       | Bearer token（仅 `anthropic` provider，与 `key` 互斥）      |
| `llm.headers`         | 附加请求头（与 `defaults.llm.headers` 合并）                |
| `llm.ignoreSSL`       | 忽略 HTTPS 证书校验，默认 `false`                           |
| `llm.options`         | 生成选项（与 `defaults.llm.options` 合并）                  |
| `llm.providerOptions` | Provider 专属选项（与 `defaults.llm.providerOptions` 合并） |

`llm.options` 支持 `maxOutputTokens`（默认 `16`）、`temperature`（默认 `0`）、`topP`、`topK`、`presencePenalty`、`frequencyPenalty`、`stopSequences`、`seed`。

`defaults.llm` 支持 `mode`、`headers`、`ignoreSSL`、`options`、`providerOptions`，不支持 `provider`、`url`、`model`、`key`、`authToken`、`prompt`。

#### expect — 期望校验

| 字段                | 适用类型 | 说明                                                                   |
| ------------------- | -------- | ---------------------------------------------------------------------- |
| `status`            | HTTP/LLM | 可接受的状态码列表，支持精确码和范围（如 `"2xx"`）；默认 `[200]`       |
| `exitCode`          | Cmd      | 可接受的退出码列表；未指定时默认 `[0]`                                 |
| `headers`           | HTTP/LLM | 响应头校验，使用动态键名和 `KeyValueExpect`                            |
| `durationMs`        | 全部     | 完整执行耗时校验，使用 `ValueMatcher`，如 `{ lte: 1000 }`              |
| `output`            | LLM      | 模型输出校验，使用 `ContentRules` 数组                                 |
| `finishReason`      | LLM      | finish reason 校验，使用 `ValueMatcher`                                |
| `rawFinishReason`   | LLM      | 原始 finish reason 校验，使用 `ValueMatcher`                           |
| `usage`             | LLM      | Token usage 校验（`inputTokens`/`outputTokens`/`totalTokens` matcher） |
| `stream`            | LLM      | 流式断言（`completed`、`firstTokenMs` matcher，仅 `mode: stream`）     |
| `body`              | HTTP     | 响应体校验，使用 `ContentRules` 数组                                   |
| `stdout` / `stderr` | Cmd      | 输出校验，使用 `ContentRules` 数组                                     |
| `rowCount`          | DB       | 查询返回行数校验，使用 `ValueMatcher`                                  |
| `rows`              | DB       | 查询结果逐行校验，数组内每行为列名到 `KeyValueExpect` 的映射           |
| `result`            | DB       | 完整查询结果 `{ rows, rowCount }` 校验，使用 `ContentRules` 数组       |
| `connected`         | TCP      | 期望连接结果，`true`（默认）可达或 `false` 期望不可达                  |
| `banner`            | TCP      | Banner 内容校验，使用 `ContentRules` 数组，需开启 `tcp.readBanner`     |
| `responded`         | UDP      | 期望是否收到响应，默认 `true`                                          |
| `response`          | UDP      | 响应内容校验，使用 `ContentRules` 数组                                 |
| `responseSize`      | UDP      | 响应字节数校验，使用 `ValueMatcher`                                    |
| `sourceHost`        | UDP      | 响应来源地址校验，使用 `ValueMatcher`                                  |
| `sourcePort`        | UDP      | 响应来源端口校验，使用 `ValueMatcher`                                  |
| `alive`             | Ping     | 期望主机可达性，默认 `true`                                            |
| `packetLossPercent` | Ping     | 丢包率百分比校验，范围 `0-100`，使用 `ValueMatcher`                    |
| `avgLatencyMs`      | Ping     | 平均延迟校验，使用 `ValueMatcher`                                      |
| `maxLatencyMs`      | Ping     | 最大单次延迟校验，使用 `ValueMatcher`                                  |

**ContentRules 校验项**（`body`、`stdout`、`stderr`、`banner`、`response`、`output`、`result` 均使用数组）：

- `contains` — 响应体包含指定文本
- `regex` — 正则匹配（启动期会拒绝存在 ReDoS 风险的模式）
- `json` — JSONPath 提取值比较（`path` 必填，如 `$.slideshow.title`）
- `css` — CSS 选择器提取 HTML 元素（`selector` 必填，`attr` 可选提取属性）
- `xpath` — XPath 提取 XML/HTML 节点（`path` 必填，如 `/html/body/h1/text()`）

**ValueMatcher 字段**：`equals`、`contains`、`regex`、`empty`、`exists`、`gte`、`lte`、`gt`、`lt`。`equals` 支持 JSON 深度相等；`regex` 固定使用无 flags 正则；提取器未配置 matcher 时等价于 `exists: true`。

旧字段 `maxDurationMs`、`maxPacketLoss`、`maxAvgLatencyMs`、`maxMaxLatencyMs` 和旧正则字段 `match` 已移除，请分别改用 `durationMs`、Ping matcher 字段和 `regex`。

**大小说明**：`maxBodyBytes` 和 `maxOutputBytes` 支持 `KB`、`MB`、`GB` 单位，也可直接使用数字。

**时长格式**：`500ms`、`30s`、`5m`、`2h`、`7d`

**JSON Schema**：仓库根目录导出 `probe-config.schema.json`，在 YAML 文件顶部添加 `# yaml-language-server: $schema=./probe-config.schema.json` 即可在编辑器中获得提示和校验。

> **注意：** 配置校验在启动时执行，非法配置会阻止启动并输出错误信息。除动态键值表（`headers`、`env`、`variables`）外，未知字段会导致启动失败，请使用 YAML 注释。

## 目标状态判定

采用单层判定模型：

- **UP** = 拨测结果符合 expect 规则
- **DOWN** = 拨测结果不符合 expect 规则

执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 DOWN，通过 `failure.kind` 区分原因（`"error"` vs `"mismatch"`）。

## 开发

```bash
bun run check   # schema:check + typecheck + lint + test
bun run verify  # check + build
```

开发相关文档（项目结构、构建、测试、代码规范等）请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。

## License

MIT